+++ /dev/null
-/************************************************************************
- ************************************************************************
- FAUST compiler
- Copyright (C) 2009 GRAME, Centre National de Creation Musicale
- ---------------------------------------------------------------------
- This program is free software; you can redistribute it and/or modify
- it under the terms of the GNU General Public License as published by
- the Free Software Foundation; either version 2 of the License, or
- (at your option) any later version.
-
- This program is distributed in the hope that it will be useful,
- but WITHOUT ANY WARRANTY; without even the implied warranty of
- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
- GNU General Public License for more details.
-
- You should have received a copy of the GNU General Public License
- along with this program; if not, write to the Free Software
- Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
- ************************************************************************
- ************************************************************************/
-
-
-
-/*****************************************************************************
- ******************************************************************************
-
-
- The Documentator Language
-
-
- ******************************************************************************
- *****************************************************************************/
-
-
-/**
- * @file doc.cpp
- * @author Karim Barkati and Yann Orlarey
- * @version 1.0
- * @date 2009
- * @brief Implementation of documentation trees support and printing.
- */
-
-#include <stdio.h>
-#include <string.h>
-#include <errno.h>
-#include <sys/stat.h>
-#include <time.h>
-#include <algorithm>
-#include <functional>
-
-#include <iostream>
-#include <fstream>
-#include <sstream>
-
-#include <map>
-#include <string>
-#include <vector>
-
-#include "ppbox.hh"
-#include "prim2.hh"
-#include "doc.hh"
-#include "eval.hh"
-#include "errormsg.hh"
-#include "doc_Text.hh"
-#include "sigprint.hh"
-#include "propagate.hh"
-#include "enrobage.hh"
-#include "drawschema.hh"
-#include "names.hh"
-#include "simplify.hh"
-#include "privatise.hh"
-#include "recursivness.hh"
-#include "sourcereader.hh"
-#include "lateq.hh"
-#include "doc_compile.hh"
-#include "doc_lang.hh"
-#include "doc_notice.hh"
-#include "doc_autodoc.hh"
-#include "compatibility.hh"
-
-
-
-#define MAXIDCHARS 5 ///< max numbers (characters) to represent ids (e.g. for directories).
-
-using namespace std ;
-
-
-/*****************************************************************************
- Globals and prototyping
- *****************************************************************************/
-
-extern Tree gExpandedDefList;
-extern map<Tree, set<Tree> > gMetaDataSet;
-extern map<string, string> gDocMetadatasStringMap;
-extern map<string, string> gDocMathStringMap;
-extern bool gDetailsSwitch;
-extern bool gStripDocSwitch;
-extern string gFaustDirectory;
-extern string gFaustSuperDirectory;
-extern string gFaustSuperSuperDirectory;
-extern string gMasterDocument;
-extern string gMasterName;
-extern SourceReader gReader;
-
-extern string gDocName; ///< Contains the filename for out documentation.
-static const char* gDocDevSuffix; ///< ".tex" (or .??? - used to choose output device).
-static string gCurrentDir; ///< Room to save current directory name.
-static const string gLatexheaderfilename = "latexheader.tex";
-
-vector<Tree> gDocVector; ///< Contains <mdoc> parsed trees: DOCTXT, DOCEQN, DOCDGM.
-
-static struct tm gCompilationDate;
-
-bool gLstDependenciesSwitch = true; ///< mdoc listing management.
-bool gLstMdocTagsSwitch = true; ///< mdoc listing management.
-bool gLstDistributedSwitch = true; ///< mdoc listing management.
-
-enum { langEN, langFR, langIT };
-string gDocLang;
-
-/* Printing functions */
-static void printlatexheader(istream& latexheader, const string& faustversion, ostream& docout);
-static void printfaustlistings(ostream& docout);
-static void printfaustlisting(string& path, ostream& docout);
-static void printlatexfooter(ostream& docout);
-static void printdoccontent(const char* svgTopDir, const vector<Tree>& docVector, const string& faustversion, ostream& docout);
-static void printfaustdocstamp(const string& faustversion, ostream& docout);
-static void printDocEqn(Lateq* ltq, ostream& docout);
-static void printDocDgm(const Tree expr, const char* svgTopDir, ostream& docout, int i);
-static void printDocMetadata(const Tree expr, ostream& docout);
-
-/* Primary sub-functions for <equation> handling */
-static void prepareDocEqns( const vector<Tree>& docBoxes, vector<Lateq*>& docCompiledEqnsVector ); ///< Caller function.
-static void collectDocEqns( const vector<Tree>& docBoxes, vector<Tree>& eqBoxes ); ///< step 0. Feed a vector.
-static void mapEvalDocEqn( const vector<Tree>& eqBoxes, const Tree& env, vector<Tree>& evalEqBoxes ); ///< step 1. Evaluate boxes.
-static void mapGetEqName( const vector<Tree>& evalEqBoxes, vector<string>& eqNames ); ///< step 2. Get boxes name.
-static void calcEqnsNicknames( const vector<string>& eqNames, vector<string>& eqNicknames ); ///< step 3. Calculate nicknames.
-static void mapPrepareEqSig( const vector<Tree>& evalEqBoxes, vector<int>& eqInputs, vector<int>& eqOutputs, vector<Tree>& eqSigs ); ///< step 4&5. Propagate and prepare signals.
-static void mapSetSigNickname( const vector<string>& eqNicknames, const vector<int>& eqInputs, const vector<Tree>& eqSigs ); ///< step 6. Set signals nicknames.
-static void collectEqSigs( const vector<Tree>& eqSigs, Tree& superEqList ); ///< step 7. Collect all signals in a superlist.
-static void annotateSuperList( DocCompiler* DC, Tree superEqList ); ///< step 8. Annotate superlist.
-//static void calcAndSetLtqNames( Tree superEqList ); ///< step 9.
-static void mapCompileDocEqnSigs( const vector<Tree>& eqSigs, const vector<int>& eqInputs, const vector<int>& eqOutputs, DocCompiler* DC, vector<Lateq*>& docCompiledEqnsVector ); ///< step 10. Compile equations.
-
-/* Secondary sub-functions for <equation> handling */
-static string calcNumberedName(const char* base, int i);
-static void getBoxInputsAndOutputs(const Tree t, int& numInputs, int& numOutputs);
-static string calcDocEqnInitial(const string s);
-
-/* Notice related functions */
-static void initCompilationDate();
-static struct tm* getCompilationDate();
-
-/* Files functions */
-static int cholddir ();
-static int mkchdir(const char* dirname);
-static int makedir(const char* dirname);
-static void getCurrentDir();
-static istream* openArchFile (const string& filename);
-static char* legalFileName(const Tree t, int n, char* dst);
-static string rmExternalDoubleQuotes(const string& s);
-static void copyFaustSources(const char* projname, const vector<string>& pathnames);
-vector<string>& docCodeSlicer(const string& faustfile, vector<string>& codeSlices);
-static void printdocCodeSlices(const string& code, ostream& docout);
-static bool doesFileBeginWithCode(const string& faustfile);
-
-//static void declareAutoDoc();
-
-
-
-/*****************************************************************************
- Types of Documentation Elements
- *****************************************************************************/
-
-Sym DOCTXT = symbol ("DocTxt");
-Tree docTxt(const char* name) { return tree( DOCTXT, tree(symbol(name)) ); }
-bool isDocTxt(Tree t) { return t->node() == Node(DOCTXT); }
-bool isDocTxt(Tree t0, const char** str)
-{
- Tree t1; Sym s;
- if ( isTree(t0, DOCTXT, t1) && isSym(t1->node(), &s) ) {
- *str = name(s);
- return true;
- } else {
- return false;
- }
-}
-
-Sym DOCEQN = symbol ("DocEqn");
-Tree docEqn(Tree x) { return tree(DOCEQN, x); }
-bool isDocEqn(Tree t, Tree& x) { return isTree(t, DOCEQN, x); }
-
-Sym DOCDGM = symbol ("DocDgm");
-Tree docDgm(Tree x) { return tree(DOCDGM, x); }
-bool isDocDgm(Tree t, Tree& x) { return isTree(t, DOCDGM, x); }
-
-Sym DOCNTC = symbol ("DocNtc");
-Tree docNtc() { return tree(DOCNTC); }
-bool isDocNtc(Tree t) { return isTree(t, DOCNTC); }
-
-Sym DOCLST = symbol ("DocLst");
-Tree docLst() { return tree(DOCLST); }
-bool isDocLst(Tree t) { return isTree(t, DOCLST); }
-
-Sym DOCMTD = symbol ("DocMtd");
-Tree docMtd(Tree x) { return tree(DOCMTD, x); }
-bool isDocMtd(Tree t, Tree& x) { return isTree(t, DOCMTD, x); }
-
-//string getDocTxt(Tree t) { return hd(t)->branch(0); }
-
-
-
-/*****************************************************************************
- Main Printing Function for the Documentation
- *****************************************************************************/
-
-
-/**
- * @brief The entry point to generate faust doc files.
- *
- * The entry point to generate the output LaTeX file, stored in the directory "<projname>-math/".
- * This file eventually references images for diagrams, generated in SVG subdirectories.
- * The device system was adapted from drawSchema's device system.
- *
- * @param[in] projname Basename of the new doc directory ("*-math").
- * @param[in] docdev The doc device; only ".tex" is supported for the moment.
- * @param[in] faustversion The current version of this Faust compiler.
- */
-void printDoc(const char* projname, const char* docdev, const char* faustversion)
-{
- gDocDevSuffix = docdev;
-
- /** File stuff : create doc directories and a tex file. */
- //cerr << "Documentator : printDoc : gFaustDirectory = '" << gFaustDirectory << "'" << endl;
- //cerr << "Documentator : printDoc : gFaustSuperDirectory = '" << gFaustSuperDirectory << "'" << endl;
- //cerr << "Documentator : printDoc : gFaustSuperSuperDirectory = '" << gFaustSuperSuperDirectory << "'" << endl;
- //cerr << "Documentator : printDoc : gCurrentDir = '" << gCurrentDir << "'" << endl;
-
- makedir(projname); // create a top directory to store files
-
- string svgTopDir = subst("$0/svg", projname);
- makedir(svgTopDir.c_str()); // create a directory to store svg-* subdirectories.
-
- string cppdir = subst("$0/cpp", projname);
- makedir(cppdir.c_str()); // create a cpp directory.
-
- string pdfdir = subst("$0/pdf", projname);
- makedir(pdfdir.c_str()); // create a pdf directory.
-
- /* Copy all Faust source files into an 'src' sub-directory. */
- vector<string> pathnames = gReader.listSrcFiles();
- copyFaustSources(projname, pathnames);
-
- string texdir = subst("$0/tex", projname);
- mkchdir(texdir.c_str()); // create a directory and move into.
-
- /** Create THE mathdoc tex file. */
- ofstream docout(subst("$0.$1", gDocName, docdev).c_str());
- cholddir(); // return to current directory
-
- /** Init and load translation file. */
- loadTranslationFile(gDocLang);
-
- /** Simulate a default doc if no <mdoc> tag detected. */
- if (gDocVector.empty()) { declareAutoDoc(); }
-
- /** Printing stuff : in the '.tex' ouptut file, eventually including SVG files. */
- printfaustdocstamp(faustversion, docout); ///< Faust version and compilation date (comment).
- istream* latexheader = openArchFile(gLatexheaderfilename);
- printlatexheader(*latexheader, faustversion, docout); ///< Static LaTeX header (packages and setup).
- printdoccontent(svgTopDir.c_str(), gDocVector, faustversion, docout); ///< Generate math contents (main stuff!).
- printlatexfooter(docout); ///< Static LaTeX footer.
-}
-
-
-
-/*****************************************************************************
- LaTeX basic printing functions of the Documentation
- *****************************************************************************/
-
-/**
- * Print a static LaTeX header.
- *
- * @param[in] latexheader The file containing the static part of the LaTeX header.
- * @param[in] faustversion The current version of this Faust compiler.
- * @param[out] docout The LaTeX output file to print into.
- */
-static void printlatexheader(istream& latexheader, const string& faustversion, ostream& docout)
-{
- string s;
- while(getline(latexheader, s)) docout << s << endl;
-
- /** Specific LaTeX macros for Faust */
- docout << "\\newcommand{\\faustfilename}{" << gMasterDocument << "}" << endl;
- docout << "\\newcommand{\\faustdocdir}{" << gMasterName << "-mdoc}" << endl;
- docout << "\\newcommand{\\faustprogname}{" << gMasterName << "}" << endl;
- docout << "\\newcommand{\\faustversion}{" << faustversion << "}" << endl;
- char datebuf [150];
- strftime (datebuf, 150, "%B %d, %Y", getCompilationDate());
- docout << "\\newcommand{\\faustdocdate}{" << datebuf << "}" << endl;
-
- docout << endl << "\\begin{document}" << endl;
-}
-
-
-/**
- * @Brief Print a metadata set.
- *
- * Each metadata is a set, in order to handle multiple items,
- * like multiple authors, even if most of metadatas have
- * unique items.
- *
- * @param[in] expr Parsed metadata keyname, as boxes tree.
- * @param[out] docout The output file to print into.
- */
-static void printDocMetadata(const Tree expr, ostream& docout)
-{
- if (gMetaDataSet.count(expr)) {
- string sep = "";
- set<Tree> mset = gMetaDataSet[expr];
-
- for (set<Tree>::iterator j = mset.begin(); j != mset.end(); j++) {
- docout << sep << rmExternalDoubleQuotes(tree2str(*j));
- sep = ", ";
- }
- }
-}
-
-
-/**
- * Print listings of each Faust code ".dsp" files,
- * calling the 'printfaustlisting' function.
- *
- * @param[out] docout The LaTeX output file to print into.
- */
-static void printfaustlistings(ostream& docout)
-{
- if (gLstDependenciesSwitch) {
- vector<string> pathnames = gReader.listSrcFiles();
- for (unsigned int i=0; i< pathnames.size(); i++) {
- printfaustlisting(pathnames[i], docout);
- }
- } else {
- printfaustlisting(gMasterDocument, docout);
- }
-}
-
-
-/**
- * Print a listing of the Faust code, in a LaTeX "listing" environment.
- * Strip content of <mdoc> tags.
- *
- * @param[in] faustfile The source file containing the Faust code.
- * @param[out] docout The LaTeX output file to print into.
- */
-static void printfaustlisting(string& faustfile, ostream& docout)
-{
- string s;
- ifstream src;
-
- //cerr << "Documentator : printfaustlisting : Opening file '" << faustfile << "'" << endl;
- src.open(faustfile.c_str(), ifstream::in);
-
- docout << endl << "\\bigskip\\bigskip" << endl;
- docout << "\\begin{lstlisting}[caption=\\texttt{" << filebasename(faustfile.c_str()) << "}]" << endl;
-
- bool isInsideDoc = false;
-
- if (faustfile != "" && src.good()) {
- while(getline(src, s)) { /** We suppose there's only one <mdoc> tag per line. */
- size_t foundopendoc = s.find("<mdoc>");
- if (foundopendoc != string::npos && gStripDocSwitch) isInsideDoc = true;
-
- if (isInsideDoc == false)
- docout << s << endl;
-
- size_t foundclosedoc = s.find("</mdoc>");
- if (foundclosedoc != string::npos && gStripDocSwitch) isInsideDoc = false;
- }
- } else {
- cerr << "ERROR : can't open faust source file " << faustfile << endl;
- exit(1);
- }
-
- docout << "\\end{lstlisting}" << endl << endl;
-}
-
-
-/**
- * Print the static LaTeX footer.
- *
- * @param[out] docout The LaTeX output file to print into.
- */
-static void printlatexfooter(ostream& docout)
-{
- docout << endl << "\\end{document}" << endl << endl;
-}
-
-
-/**
- * Print a "doc stamp" in the LaTeX document :
- * - the Faust version,
- * - the date of doc compilation,
- * - faust's web site URL.
- *
- * @param[in] faustversion The current version of this Faust compiler.
- * @param[out] docout The LaTeX output file to print into.
- */
-static void printfaustdocstamp(const string& faustversion, ostream& docout)
-{
- char datebuf [150];
- strftime (datebuf, 150, "%c", getCompilationDate());
-
- docout << "%% This documentation was generated with Faust version " << faustversion << endl;
- docout << "%% " << datebuf << endl;
- docout << "%% http://faust.grame.fr" << endl << endl;
-}
-
-
-
-/*****************************************************************************
- Main loop : launches prepare, evaluate, and print functions
- *****************************************************************************/
-
-/**
- * @brief Main documentator loop.
- *
- * First loop on gDocVector, which contains the faust <mdoc> trees.
- * Second loop for each of these <mdoc> trees, which contain parsed input expressions of 3 types :
- * DOCEQN for <equation> tags, DOCDGM for <diagram> tags, and DOCTXT for direct LaTeX text (no tag).
- * - DOCTXT expressions printing is trivial.
- * - DOCDGM expressions printing calls 'printDocDgm' to generate SVG files and print LaTeX "figure" code.
- * - DOCEQN expressions printing calls 'printDocEqn' after an important preparing work
- * has been done by 'prepareDocEqns'.
- *
- * @param[in] projname Basename of the new doc directory ("*-math").
- * @param[in] docVector Contains all <mdoc> parsed content (as boxes).
- * @param[in] faustversion The current version of this Faust compiler.
- * @param[out] docout The output file to print into.
- **/
-static void printdoccontent(const char* svgTopDir, const vector<Tree>& docVector, const string& faustversion, ostream& docout)
-{
- //cerr << endl << "Documentator : printdoccontent : " << docVector.size() << " <mdoc> tags read." << endl;
-
- /** Equations need to be prepared (named and compiled) before printing. */
- vector<Lateq*> docCompiledEqnsVector;
- prepareDocEqns( docVector, docCompiledEqnsVector ); ///< Quite a lot of stuff there.
- vector<Lateq*>::iterator eqn_it = docCompiledEqnsVector.begin();
-
- int dgmIndex = 1; ///< For diagram directories numbering.
-
- vector<string> docMasterCodeMap;
- docMasterCodeMap = docCodeSlicer(gMasterDocument, docMasterCodeMap);
-
- vector<Tree>::const_iterator doc;
- vector<string>::const_iterator code;
- code = docMasterCodeMap.begin();
-
- if(doesFileBeginWithCode(gMasterDocument) && (! docMasterCodeMap.empty()) && gLstDistributedSwitch ) {
- printdocCodeSlices(*code, docout);
- code++;
- }
-
- /** First level printing loop, on docVector. */
- for (doc=docVector.begin(); doc<docVector.end(); doc++, code++) {
-
- Tree L = reverse(*doc);
- //cerr << "Entering into <mdoc> parsing..." << endl;
-
- /** Second level printing loop, on each <mdoc>. */
- while (isList(L)) {
- Tree expr;
- if ( isDocEqn(hd(L), expr) ) { ///< After equations are well prepared and named.
- printDocEqn(*eqn_it++, docout);
- }
- else if ( isDocDgm(hd(L), expr) ) {
- printDocDgm(expr, svgTopDir, docout, dgmIndex++);
- }
- else if ( isDocMtd(hd(L), expr) ) {
- printDocMetadata(expr, docout);
- }
- else if ( isDocTxt(hd(L)) ) {
- docout << *hd(L)->branch(0); // Directly print registered doc text.
- }
- else if ( isDocNtc(hd(L)) ) {
- printDocNotice(faustversion, docout);
- }
- else if ( isDocLst(hd(L)) ) {
- printfaustlistings(docout);
- }
- else {
- cerr << "ERROR : " << *hd(L) << " is not a valid documentation type." << endl;
- }
- L = tl(L);
- }
- //cerr << " ...end of <mdoc> parsing." << endl;
-
- if ( code != docMasterCodeMap.end() && gLstDistributedSwitch ) {
- printdocCodeSlices(*code, docout);
- }
- }
-}
-
-
-
-/*****************************************************************************
- Primary sub-functions for <equation> handling
- *****************************************************************************/
-
-/**
- * @brief Caller function for all steps of doc equations preparation.
- *
- * Note : many of the functions called put their result into their last argument
- * in a "source / destination" manner,
- * the "destination" being declared before the function call.
- *
- * @param[in] docBoxes The <mdoc> boxes to collect and prepare.
- * @param[out] docCompiledEqnsVector The place to store compiled equations.
- */
-static void prepareDocEqns(const vector<Tree>& docBoxes, vector<Lateq*>& docCompiledEqnsVector)
-{
- vector<Tree> eqBoxes; collectDocEqns( docBoxes, eqBoxes ); ///< step 0. Feed a vector.
-
- if(! eqBoxes.empty() ) {
- vector<Tree> evalEqBoxes; mapEvalDocEqn( eqBoxes, gExpandedDefList, evalEqBoxes ); ///< step 1. Evaluate boxes.
- vector<string> eqNames; mapGetEqName( evalEqBoxes, eqNames ); ///< step 2. Get boxes name.
- vector<string> eqNicknames; calcEqnsNicknames( eqNames, eqNicknames ); ///< step 3. Calculate nicknames.
-
- vector<int> eqInputs;
- vector<int> eqOutputs;
- vector<Tree> eqSigs; mapPrepareEqSig( evalEqBoxes, eqInputs, eqOutputs, eqSigs ); ///< step 4&5. Propagate and prepare signals.
- mapSetSigNickname( eqNicknames, eqInputs, eqSigs ); ///< step 6. Set signals nicknames.
- Tree superEqList; collectEqSigs( eqSigs, superEqList ); ///< step 7. Collect all signals in a superlist.
-
- DocCompiler* DC = new DocCompiler(0, 0);
- annotateSuperList( DC, superEqList ); ///< step 8. Annotate superEqList.
- //calcAndSetLtqNames( superEqList ); ///< step 9. (directly in 10.)
- mapCompileDocEqnSigs( eqSigs, eqInputs, eqOutputs, DC, docCompiledEqnsVector ); ///< step 10. Compile every signal.
- }
-}
-
-
-/**
- * #0. Collect every <equation> found in all <mdoc> faust comments.
- *
- * @param[in] docBoxes The <mdoc> boxes to filter.
- * @param[out] eqBoxes The place to store only <equation> boxes.
- */
-static void collectDocEqns(const vector<Tree>& docBoxes, vector<Tree>& eqBoxes)
-{
- int nbdoceqn = 0;
-
- for (vector<Tree>::const_iterator doc=docBoxes.begin(); doc<docBoxes.end(); doc++) {
- Tree L = reverse(*doc);
- Tree expr;
- while (isList(L)) {
- if ( isDocEqn(hd(L), expr) ) {
- eqBoxes.push_back(expr);
- nbdoceqn++;
- }
- L = tl(L);
- }
- }
- //cerr << "Documentator : collectDocEqns : " << nbdoceqn << " <equation> tags found." << endl;
-}
-
-
-/**
- * #1. Evaluate every doc <equation> (evaluation replaces abstractions by symbolic boxes).
- *
- * @param[in] eqBoxes The boxes to evaluate.
- * @param[in] env The environment for the evaluation.
- * @param[out] evalEqBoxes The place to store evaluated equations boxes.
- */
-static void mapEvalDocEqn(const vector<Tree>& eqBoxes, const Tree& env, vector<Tree>& evalEqBoxes)
-{
- //cerr << "###\n# Documentator : mapEvalDocEqn" << endl;
-
- for ( vector<Tree>::const_iterator eq=eqBoxes.begin(); eq < eqBoxes.end(); eq++)
- {
- evalEqBoxes.push_back(evaldocexpr( *eq, env ));
- }
- //cerr << "Documentator : end of mapEvalDocEqn\n---" << endl;
-}
-
-
-/**
- * #2. Get name if exists, else create one, and store it.
- *
- * @param[in] evalEqBoxes Evaluated box trees, eventually containing an equation name.
- * @param[out] eqNames The place to store equations names.
- */
-static void mapGetEqName(const vector<Tree>& evalEqBoxes, vector<string>& eqNames)
-{
- //cerr << "###\n# Documentator : mapGetEqName" << endl;
-
- int i = 1;
- for( vector<Tree>::const_iterator eq = evalEqBoxes.begin(); eq < evalEqBoxes.end(); eq++, i++ ) {
- Tree id;
- string s;
- int n,m; getBoxType(*eq, &n, &m); // eq name only for bd without inputs
- if ( n==0 && getDefNameProperty(*eq, id) ) {
- s = tree2str(id);
- }
- else {
- s = calcNumberedName("doceqn-", i);
- }
- eqNames.push_back( s ) ;
- }
- //cerr << "Documentator : end of mapGetEqName\n---" << endl;
-}
-
-
-/**
- * #3. Calculate a nickname for each equation and store it.
- *
- * @param[in] eqNames Equations names to parse.
- * @param[out] eqNicknames The place to store calculated nicknames.
- *
- * @todo Should check unicity : check whether several names share the same initial,
- * or else capture consonants for example.
- */
-static void calcEqnsNicknames(const vector<string>& eqNames, vector<string>& eqNicknames)
-{
- //cerr << "###\n# Documentator : calcEqnsNicknames" << endl;
-
- vector<string> v;
-
- for( vector<string>::const_iterator eq = eqNames.begin(); eq < eqNames.end(); eq++ ) {
- string init = calcDocEqnInitial(*eq);
- v.push_back(init);
- /** Check duplicates */
-// for( vector<string>::iterator it = v.begin(); it < v.end()-1; ++it ) {
-// if (init == *it) {
-// //cerr << "!! Warning Documentator : calcEqnsNicknames : duplicates \"" << init << "\"" << endl;
-// }
-// }
- eqNicknames.push_back(init);
- }
-
-// for( vector<string>::const_iterator eq = eqNames.begin(); eq < eqNames.end(); eq++ ) {
-// int c = 0;
-// c = count_if(eqNames.begin(), eqNames.end(), bind2nd(equal_to<string>(), *eq));
-// if (c > 0) {
-// cerr << "- Duplicate nickname !! " << *eq << endl;
-// } else {
-// cerr << "(no duplicate) " << *eq << endl;
-// }
-// }
-
- //cerr << "Documentator : end of calcEqnsNicknames\n---" << endl;
-}
-
-
-/**
- * #4&5. Propagate and prepare every doc <equation>.
- *
- * Call boxPropagateSig, deBruijn2Sym, simplify, and privatise.
- *
- * @param[in] evalEqBoxes Equations boxes to propagate as signals.
- * @param[out] eqSigs The place to store prepared signals.
- */
-static void mapPrepareEqSig(const vector<Tree>& evalEqBoxes, vector<int>& eqInputs, vector<int>& eqOutputs, vector<Tree>& eqSigs)
-{
- //cerr << "###\n# Documentator : mapPrepareEqSig" << endl;
-
- for( vector<Tree>::const_iterator eq = evalEqBoxes.begin(); eq < evalEqBoxes.end(); eq++ ) {
-
- int numInputs, numOutputs;
- getBoxInputsAndOutputs(*eq, numInputs, numOutputs);
- //cerr << numInputs <<" ins and " << numOutputs <<" outs" << endl;
- eqInputs.push_back(numInputs);
- eqOutputs.push_back(numOutputs);
-
- Tree lsig1 = boxPropagateSig( nil, *eq , makeSigInputList(numInputs) );
- //cerr << "output signals are : " << endl; printSignal(lsig1, stderr);
-
- Tree lsig2 = deBruijn2Sym(lsig1); ///< Convert debruijn recursion into symbolic recursion
- Tree lsig3 = simplify(lsig2); ///< Simplify by executing every computable operation
- //Tree lsig4 = privatise(lsig3); ///< Un-share tables with multiple writers
- Tree lsig4 = docTableConvertion(lsig3); ///< convert regular tables into special doctables
- ///< (regular tables are difficult to translate to equations)
-
- eqSigs.push_back(lsig4);
- }
- //cerr << "Documentator : end of mapPrepareEqSig\n---" << endl;
-}
-
-
-/**
- * #6. Set signals nicknames.
- *
- * Do nothing for the moment !
- * @param[in] eqNicknames Contains previously calculated nicknames.
- * @param[out] eqSigs The signals to tag with a NICKNAMEPROPERTY.
- */
-static void mapSetSigNickname(const vector<string>& eqNicknames, const vector<int>& eqInputs, const vector<Tree>& eqSigs)
-{
- //cerr << "###\n# Documentator : mapSetSigNickname" << endl;
-
-// Do nothing for the moment...
-// for( unsigned int i=0; i < eqSigs.size(); i++ ) {
-// if (eqInputs[i] == 0) // Only "generators" should be finally named with user equation (nick)name.
-// setSigListNickName(eqSigs[i], eqNicknames[i]);
-// }
- //cerr << "Documentator : end of mapSetSigNickname\n---" << endl;
-}
-
-
-/**
- * #7. Collect each prepared list of signals to construct a super list.
- *
- * @param[in] eqSigs Contains well-prepared and nicknamed signals.
- * @param[out] superEqList The root where to 'cons' signals all together.
- */
-static void collectEqSigs(const vector<Tree>& eqSigs, Tree& superEqList)
-{
- //cerr << "###\n# Documentator : collectEqSigs" << endl;
-
- superEqList = nil;
-
- for( vector<Tree>::const_iterator it = eqSigs.begin(); it < eqSigs.end(); ++it ) {
- superEqList = cons( *it, superEqList );
- }
- //printSignal(superEqList, stdout, 0);
-
- //cerr << endl << "Documentator : end of collectEqSigs\n---" << endl;
-}
-
-
-/**
- * #8. Annotate superEqList (to find candidate signals to be named later).
- *
- * @param[in] DC The signals compiler.
- * @param[out] superEqList The super equations signal tree to annotate.
- */
-static void annotateSuperList(DocCompiler* DC, Tree superEqList)
-{
- DC->annotate(superEqList);
-}
-
-
-///**
-// * #9. Calculated and set lateq (LaTeX equation) names.
-// * Note : Transfered into mapCompileDocEqnSigs (DocCompiler::compileMultiSignal).
-// */
-//static void calcAndSetLtqNames(Tree superEqList)
-//{
-//
-//}
-
-
-/**
- * #10. Name and compile prepared doc <equation> signals.
- *
- * @param[in] eqSigs Contains well-prepared and nicknamed signals.
- * @param[in] DC The signals compiler.
- * @param[out] docCompiledEqnsVector The place to store each compiled Lateq* object.
- */
-static void mapCompileDocEqnSigs(const vector<Tree>& eqSigs, const vector<int>& eqInputs, const vector<int>& eqOutputs, DocCompiler* DC, vector<Lateq*>& docCompiledEqnsVector)
-{
- //cerr << "###\n# Documentator : mapCompileDocEqnSigs" << endl;
-
- for( unsigned int i=0; i < eqSigs.size(); i++ ) {
-
- // docCompiledEqnsVector.push_back( DC->compileMultiSignal(*it, 0) );
- docCompiledEqnsVector.push_back( DC->compileLateq(eqSigs[i], new Lateq(eqInputs[i], eqOutputs[i])) );
- }
-
- //cerr << "Documentator : end of mapCompileDocEqnSigs\n---" << endl;
-}
-
-
-
-/*****************************************************************************
- Secondary sub-functions for <equation> handling
- *****************************************************************************/
-
-
-/**
- * Calculate an appropriate nickname for equations,
- * from previous names.
- *
- * @param The string to parse.
- * @return Essentially returns the initial character,
- * except "Y" for "process", and "Z" for unnamed equations.
- */
-static string calcDocEqnInitial(const string s)
-{
- string nn;
- if(s == "process")
- nn = "Y";
- else if (s.substr(0,6) == "doceqn")
- nn = "Z";
- else
- nn += toupper(s[0]);
- return nn;
-}
-
-
-/**
- * Just get the number of inputs and the number of outputs of a box.
- *
- * @param[in] t The box tree to get inputs and outputs from.
- * @param[out] numInputs The place to store the number of inputs.
- * @param[out] numOutputs The place to store the number of outputs.
- */
-static void getBoxInputsAndOutputs(const Tree t, int& numInputs, int& numOutputs)
-{
- if (!getBoxType(t, &numInputs, &numOutputs)) {
- cerr << "ERROR during the evaluation of t : " << boxpp(t) << endl;
- exit(1);
- }
- //cerr << "Documentator : " << numInputs <<" inputs and " << numOutputs <<" outputs for box : " << boxpp(t) << endl;
-}
-
-
-/**
- * Print doc equations, following the Lateq::println method.
- *
- * @param[in] ltq The object containing compiled LaTeX code of equations.
- * @param[out] docout The output file to print into.
- */
-static void printDocEqn(Lateq* ltq, ostream& docout)
-{
- ltq->println(docout);
- //cerr << "Documentator : printDocEqn : "; ltq->println(cerr); cerr << endl;
-}
-
-
-/*****************************************************************************
- Sub-function for <diagram> handling
- *****************************************************************************/
-
-/**
- * @brief Doc diagrams handling.
- *
- * Three steps :
- * 1. evaluate expression
- * 2. call svg drawing in the appropriate directory
- * 3. print latex figure code with the appropriate directory reference
- *
- * @param[in] expr Parsed input expression, as boxes tree.
- * @param[in] svgTopDir Basename of the new doc directory ("*-math/svg").
- * @param[out] docout The output file to print into.
- */
-static void printDocDgm(const Tree expr, const char* svgTopDir, ostream& docout, int i)
-{
- /** 1. Evaluate expression. */
- Tree docdgm = evaldocexpr(expr, gExpandedDefList);
- if (gErrorCount > 0) {
- cerr << "Total of " << gErrorCount << " errors during evaluation of : diagram docdgm = " << boxpp(docdgm) << ";\n";
- exit(1);
- }
-
- /**
- * 2. Draw the diagram after its evaluation, in SVG.
- * Warning : pdflatex can't directly include SVG files !
- */
- char dgmid[MAXIDCHARS+1];
- sprintf(dgmid, "%02d", i);
- string thisdgmdir = subst("$0/svg-$1", svgTopDir, dgmid);
- //cerr << "Documentator : printDocDgm : drawSchema in '" << gCurrentDir << "/" << thisdgmdir << "'" << endl;
-
- drawSchema( docdgm, thisdgmdir.c_str(), "svg" );
-
- /** 3. Print LaTeX figure code. */
- char temp[1024];
- const string dgmfilename = legalFileName(docdgm, 1024, temp);
- //docout << "figure \\ref{figure" << i << "}";
- docout << "\\begin{figure}[ht!]" << endl;
- docout << "\t\\centering" << endl;
- docout << "\t\\includegraphics[width=\\textwidth]{" << subst("../svg/svg-$0/", dgmid) << dgmfilename << "}" << endl;
- docout << "\t\\caption{" << gDocMathStringMap["dgmcaption"] << " \\texttt{" << dgmfilename << "}}" << endl;
- docout << "\t\\label{figure" << i << "}" << endl;
- docout << "\\end{figure}" << endl << endl;
-
- /** 4. Warn about naming interferences (in the notice). */
- gDocNoticeFlagMap["nameconflicts"] = true;
- gDocNoticeFlagMap["svgdir"] = true;
-}
-
-
-
-/*****************************************************************************
- Other sub-functions
- *****************************************************************************/
-
-
-/**
- * Slice faust code between "mdoc" sections.
- *
- * @param[in] faustfile Name of the input faust file to parse.
- * @param[in] codeSlices The place to store code "slices".
- */
-vector<string>& docCodeSlicer(const string& faustfile, vector<string>& codeSlices)
-{
- string s;
- ifstream src;
- src.open(faustfile.c_str(), ifstream::in);
- string tmp = "";
-
- bool isInsideDoc = false;
-
- if (faustfile != "" && src.good()) {
- while(getline(src, s)) { /** Caution: we suppose there's only one <mdoc> tag per line! */
- size_t foundopendoc = s.find("<mdoc>");
-
- if (foundopendoc != string::npos) {
- if (isInsideDoc == false) { /** A change has come. ;) */
- if (! tmp.empty() ) {
- codeSlices.push_back(tmp); }
- tmp = "";
- }
- isInsideDoc = true;
- }
-
- if (isInsideDoc == false) {
- tmp += s + '\n';
- }
-
- size_t foundclosedoc = s.find("</mdoc>");
- if (foundclosedoc != string::npos) isInsideDoc = false;
- }
- } else {
- cerr << "ERROR : can't open faust source file " << faustfile << endl;
- exit(1);
- }
- return codeSlices;
-}
-
-
-/**
- * Print faust code inside a listing environment.
- *
- * @param[in] code Faust code as a string (may contain '\n' characters).
- * @param[out] docout The output file to print into.
- */
-static void printdocCodeSlices(const string& code, ostream& docout)
-{
- if ( ! code.empty() ) {
- docout << endl << "\\begin{lstlisting}[numbers=none, frame=none, basicstyle=\\small\\ttfamily, backgroundcolor=\\color{yobg}]" << endl;
- docout << code << endl;
- docout << "\\end{lstlisting}" << endl << endl;
- }
-}
-
-
-/**
- * Test whether a file does begin with some faust code or not.
- *
- * @param[in] faustfile Name of the input faust file to parse.
- */
-static bool doesFileBeginWithCode(const string& faustfile)
-{
- string s;
- ifstream src;
- src.open(faustfile.c_str(), ifstream::in);
-
- if (faustfile != "" && src.good()) {
- getline(src, s);
- size_t foundopendoc = s.find("<mdoc>");
- if(int(foundopendoc)==0) {
- return false;
- } else {
- return true;
- }
- } else {
- cerr << "ERROR : can't open faust source file " << faustfile << endl;
- exit(1);
- }
-}
-
-
-
-//------------------------ dealing with files -------------------------
-
-
-/**
- * Create a new directory in the current one.
- */
-static int makedir(const char* dirname)
-{
- char buffer[FAUST_PATH_MAX];
- gCurrentDir = getcwd (buffer, FAUST_PATH_MAX);
-
- if ( gCurrentDir.c_str() != 0) {
- int status = mkdir(dirname, S_IRWXU | S_IRWXG | S_IROTH | S_IXOTH);
- if (status == 0 || errno == EEXIST) {
- return 0;
- }
- }
- perror("makedir");
- exit(errno);
-}
-
-
-/**
- * Create a new directory in the current one,
- * then 'cd' into this new directory.
- *
- * @remark
- * The current directory is saved to be later restaured.
- */
-static int mkchdir(const char* dirname)
-{
- char buffer[FAUST_PATH_MAX];
- gCurrentDir = getcwd (buffer, FAUST_PATH_MAX);
-
- if ( gCurrentDir.c_str() != 0) {
- int status = mkdir(dirname, S_IRWXU | S_IRWXG | S_IROTH | S_IXOTH);
- if (status == 0 || errno == EEXIST) {
- if (chdir(dirname) == 0) {
- return 0;
- }
- }
- }
- perror("mkchdir");
- exit(errno);
-}
-
-
-/**
- * Switch back to the previously stored current directory
- */
-static int cholddir ()
-{
- if (chdir(gCurrentDir.c_str()) == 0) {
- return 0;
- } else {
- perror("cholddir");
- exit(errno);
- }
-}
-
-
-/**
- * Get current directory and store it in gCurrentDir.
- */
-static void getCurrentDir ()
-{
- char buffer[FAUST_PATH_MAX];
- gCurrentDir = getcwd (buffer, FAUST_PATH_MAX);
-}
-
-
-/**
- * Open architecture file.
- */
-static istream* openArchFile (const string& filename)
-{
- istream* file;
- getCurrentDir(); // Save the current directory.
- //cerr << "Documentator : openArchFile : Opening input file '" << filename << "'" << endl;
- if ( (file = open_arch_stream(filename.c_str())) ) {
- //cerr << "Documentator : openArchFile : Opening '" << filename << "'" << endl;
- } else {
- cerr << "ERROR : can't open architecture file " << filename << endl;
- exit(1);
- }
- cholddir(); // Return to current directory.
- return file;
-}
-
-
-/**
- * Transform the definition name property of tree <t> into a
- * legal file name. The resulting file name is stored in
- * <dst> a table of at least <n> chars. Returns the <dst> pointer
- * for convenience.
- */
-static char* legalFileName(const Tree t, int n, char* dst)
-{
- Tree id;
- int i=0;
- if (getDefNameProperty(t, id)) {
- const char* src = tree2str(id);
- for (i=0; isalnum(src[i]) && i<16; i++) {
- dst[i] = src[i];
- }
- }
- dst[i] = 0;
- if (strcmp(dst, "process") != 0) {
- // if it is not process add the hex address to make the name unique
- snprintf(&dst[i], n-i, "-%p", t);
- }
- return dst;
-}
-
-/**
- * Simply concat a string with a number in a "%03d" format.
- * The number has MAXIDCHARS characters.
- **/
-static string calcNumberedName(const char* base, int i)
-{
- char nb[MAXIDCHARS+1];
- sprintf(nb, "%03d", i);
- return subst("$0$1", base, nb);
-}
-
-/**
- * Remove the leading and trailing double quotes of a string
- * (but not those in the middle of the string)
- */
-static string rmExternalDoubleQuotes(const string& s)
-{
- size_t i = s.find_first_not_of("\"");
- size_t j = s.find_last_not_of("\"");
-
- if ( (i != string::npos) & (j != string::npos) ) {
- return s.substr(i, 1+j-i);
- } else {
- return "";
- }
-}
-
-
-/**
- * Copy all Faust source files into an 'src' subdirectory.
- *
- * @param[in] projname Basename of the new doc directory ("*-math").
- * @param[in] pathnames The paths list of the source files to copy.
- */
-static void copyFaustSources(const char* projname, const vector<string>& pathnames)
-{
- string srcdir = subst("$0/src", projname);
- //cerr << "Documentator : copyFaustSources : Creating directory '" << srcdir << "'" << endl;
- makedir(srcdir.c_str()); // create a directory.
-
- for (unsigned int i=0; i< pathnames.size(); i++) {
- ifstream src;
- ofstream dst;
- string faustfile = pathnames[i];
- string copy = subst("$0/$1", srcdir, filebasename(faustfile.c_str()));
- //cerr << "Documentator : copyFaustSources : Opening input file '" << faustfile << "'" << endl;
- //cerr << "Documentator : copyFaustSources : Opening output file '" << copy << "'" << endl;
- src.open(faustfile.c_str(), ifstream::in);
- dst.open(copy.c_str(), ofstream::out);
- string s;
- while ( getline(src,s) ) dst << s << endl;
- }
-}
-
-
-//------------------------ date managment -------------------------
-
-
-static void initCompilationDate()
-{
- time_t now;
-
- time(&now);
- gCompilationDate = *localtime(&now);
-}
-
-static struct tm* getCompilationDate()
-{
- initCompilationDate();
- return &gCompilationDate;
-}
-
projects / Faustine.git / blobdiff