projects / Faustine.git / blob
? search:


00c956eafe8b50428cd8fdff2d43f1a953b60ff4
[Faustine.git] / interpretor / faust-0.9.47mr3 / compiler / documentator / doc.cpp
1 /************************************************************************
2 ************************************************************************
3 FAUST compiler
4 Copyright (C) 2009 GRAME, Centre National de Creation Musicale
5 ---------------------------------------------------------------------
6 This program is free software; you can redistribute it and/or modify
7 it under the terms of the GNU General Public License as published by
8 the Free Software Foundation; either version 2 of the License, or
9 (at your option) any later version.
10
11 This program is distributed in the hope that it will be useful,
12 but WITHOUT ANY WARRANTY; without even the implied warranty of
13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
14 GNU General Public License for more details.
15
16 You should have received a copy of the GNU General Public License
17 along with this program; if not, write to the Free Software
18 Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
19 ************************************************************************
20 ************************************************************************/
21
22
23
24 /*****************************************************************************
25 ******************************************************************************
26
27
28 The Documentator Language
29
30
31 ******************************************************************************
32 *****************************************************************************/
33
34
35 /**
36 * @file doc.cpp
37 * @author Karim Barkati and Yann Orlarey
38 * @version 1.0
39 * @date 2009
40 * @brief Implementation of documentation trees support and printing.
41 */
42
43 #include <stdio.h>
44 #include <string.h>
45 #include <errno.h>
46 #include <sys/stat.h>
47 #include <time.h>
48 #include <algorithm>
49 #include <functional>
50
51 #include <iostream>
52 #include <fstream>
53 #include <sstream>
54
55 #include <map>
56 #include <string>
57 #include <vector>
58
59 #include "ppbox.hh"
60 #include "prim2.hh"
61 #include "doc.hh"
62 #include "eval.hh"
63 #include "errormsg.hh"
64 #include "doc_Text.hh"
65 #include "sigprint.hh"
66 #include "propagate.hh"
67 #include "enrobage.hh"
68 #include "drawschema.hh"
69 #include "names.hh"
70 #include "simplify.hh"
71 #include "privatise.hh"
72 #include "recursivness.hh"
73 #include "sourcereader.hh"
74 #include "lateq.hh"
75 #include "doc_compile.hh"
76 #include "doc_lang.hh"
77 #include "doc_notice.hh"
78 #include "doc_autodoc.hh"
79 #include "compatibility.hh"
80
81
82
83 #define MAXIDCHARS 5 ///< max numbers (characters) to represent ids (e.g. for directories).
84
85 using namespace std ;
86
87
88 /*****************************************************************************
89 Globals and prototyping
90 *****************************************************************************/
91
92 extern Tree gExpandedDefList;
93 extern map<Tree, set<Tree> > gMetaDataSet;
94 extern map<string, string> gDocMetadatasStringMap;
95 extern map<string, string> gDocMathStringMap;
96 extern bool gDetailsSwitch;
97 extern bool gStripDocSwitch;
98 extern string gFaustDirectory;
99 extern string gFaustSuperDirectory;
100 extern string gFaustSuperSuperDirectory;
101 extern string gMasterDocument;
102 extern string gMasterName;
103 extern SourceReader gReader;
104
105 extern string gDocName; ///< Contains the filename for out documentation.
106 static const char* gDocDevSuffix; ///< ".tex" (or .??? - used to choose output device).
107 static string gCurrentDir; ///< Room to save current directory name.
108 static const string gLatexheaderfilename = "latexheader.tex";
109
110 vector<Tree> gDocVector; ///< Contains <mdoc> parsed trees: DOCTXT, DOCEQN, DOCDGM.
111
112 static struct tm gCompilationDate;
113
114 bool gLstDependenciesSwitch = true; ///< mdoc listing management.
115 bool gLstMdocTagsSwitch = true; ///< mdoc listing management.
116 bool gLstDistributedSwitch = true; ///< mdoc listing management.
117
118 enum { langEN, langFR, langIT };
119 string gDocLang;
120
121 /* Printing functions */
122 static void printlatexheader(istream& latexheader, const string& faustversion, ostream& docout);
123 static void printfaustlistings(ostream& docout);
124 static void printfaustlisting(string& path, ostream& docout);
125 static void printlatexfooter(ostream& docout);
126 static void printdoccontent(const char* svgTopDir, const vector<Tree>& docVector, const string& faustversion, ostream& docout);
127 static void printfaustdocstamp(const string& faustversion, ostream& docout);
128 static void printDocEqn(Lateq* ltq, ostream& docout);
129 static void printDocDgm(const Tree expr, const char* svgTopDir, ostream& docout, int i);
130 static void printDocMetadata(const Tree expr, ostream& docout);
131
132 /* Primary sub-functions for <equation> handling */
133 static void prepareDocEqns( const vector<Tree>& docBoxes, vector<Lateq*>& docCompiledEqnsVector ); ///< Caller function.
134 static void collectDocEqns( const vector<Tree>& docBoxes, vector<Tree>& eqBoxes ); ///< step 0. Feed a vector.
135 static void mapEvalDocEqn( const vector<Tree>& eqBoxes, const Tree& env, vector<Tree>& evalEqBoxes ); ///< step 1. Evaluate boxes.
136 static void mapGetEqName( const vector<Tree>& evalEqBoxes, vector<string>& eqNames ); ///< step 2. Get boxes name.
137 static void calcEqnsNicknames( const vector<string>& eqNames, vector<string>& eqNicknames ); ///< step 3. Calculate nicknames.
138 static void mapPrepareEqSig( const vector<Tree>& evalEqBoxes, vector<int>& eqInputs, vector<int>& eqOutputs, vector<Tree>& eqSigs ); ///< step 4&5. Propagate and prepare signals.
139 static void mapSetSigNickname( const vector<string>& eqNicknames, const vector<int>& eqInputs, const vector<Tree>& eqSigs ); ///< step 6. Set signals nicknames.
140 static void collectEqSigs( const vector<Tree>& eqSigs, Tree& superEqList ); ///< step 7. Collect all signals in a superlist.
141 static void annotateSuperList( DocCompiler* DC, Tree superEqList ); ///< step 8. Annotate superlist.
142 //static void calcAndSetLtqNames( Tree superEqList ); ///< step 9.
143 static void mapCompileDocEqnSigs( const vector<Tree>& eqSigs, const vector<int>& eqInputs, const vector<int>& eqOutputs, DocCompiler* DC, vector<Lateq*>& docCompiledEqnsVector ); ///< step 10. Compile equations.
144
145 /* Secondary sub-functions for <equation> handling */
146 static string calcNumberedName(const char* base, int i);
147 static void getBoxInputsAndOutputs(const Tree t, int& numInputs, int& numOutputs);
148 static string calcDocEqnInitial(const string s);
149
150 /* Notice related functions */
151 static void initCompilationDate();
152 static struct tm* getCompilationDate();
153
154 /* Files functions */
155 static int cholddir ();
156 static int mkchdir(const char* dirname);
157 static int makedir(const char* dirname);
158 static void getCurrentDir();
159 static istream* openArchFile (const string& filename);
160 static char* legalFileName(const Tree t, int n, char* dst);
161 static string rmExternalDoubleQuotes(const string& s);
162 static void copyFaustSources(const char* projname, const vector<string>& pathnames);
163 vector<string>& docCodeSlicer(const string& faustfile, vector<string>& codeSlices);
164 static void printdocCodeSlices(const string& code, ostream& docout);
165 static bool doesFileBeginWithCode(const string& faustfile);
166
167 //static void declareAutoDoc();
168
169
170
171 /*****************************************************************************
172 Types of Documentation Elements
173 *****************************************************************************/
174
175 Sym DOCTXT = symbol ("DocTxt");
176 Tree docTxt(const char* name) { return tree( DOCTXT, tree(symbol(name)) ); }
177 bool isDocTxt(Tree t) { return t->node() == Node(DOCTXT); }
178 bool isDocTxt(Tree t0, const char** str)
179 {
180 Tree t1; Sym s;
181 if ( isTree(t0, DOCTXT, t1) && isSym(t1->node(), &s) ) {
182 *str = name(s);
183 return true;
184 } else {
185 return false;
186 }
187 }
188
189 Sym DOCEQN = symbol ("DocEqn");
190 Tree docEqn(Tree x) { return tree(DOCEQN, x); }
191 bool isDocEqn(Tree t, Tree& x) { return isTree(t, DOCEQN, x); }
192
193 Sym DOCDGM = symbol ("DocDgm");
194 Tree docDgm(Tree x) { return tree(DOCDGM, x); }
195 bool isDocDgm(Tree t, Tree& x) { return isTree(t, DOCDGM, x); }
196
197 Sym DOCNTC = symbol ("DocNtc");
198 Tree docNtc() { return tree(DOCNTC); }
199 bool isDocNtc(Tree t) { return isTree(t, DOCNTC); }
200
201 Sym DOCLST = symbol ("DocLst");
202 Tree docLst() { return tree(DOCLST); }
203 bool isDocLst(Tree t) { return isTree(t, DOCLST); }
204
205 Sym DOCMTD = symbol ("DocMtd");
206 Tree docMtd(Tree x) { return tree(DOCMTD, x); }
207 bool isDocMtd(Tree t, Tree& x) { return isTree(t, DOCMTD, x); }
208
209 //string getDocTxt(Tree t) { return hd(t)->branch(0); }
210
211
212
213 /*****************************************************************************
214 Main Printing Function for the Documentation
215 *****************************************************************************/
216
217
218 /**
219 * @brief The entry point to generate faust doc files.
220 *
221 * The entry point to generate the output LaTeX file, stored in the directory "<projname>-math/".
222 * This file eventually references images for diagrams, generated in SVG subdirectories.
223 * The device system was adapted from drawSchema's device system.
224 *
225 * @param[in] projname Basename of the new doc directory ("*-math").
226 * @param[in] docdev The doc device; only ".tex" is supported for the moment.
227 * @param[in] faustversion The current version of this Faust compiler.
228 */
229 void printDoc(const char* projname, const char* docdev, const char* faustversion)
230 {
231 gDocDevSuffix = docdev;
232
233 /** File stuff : create doc directories and a tex file. */
234 //cerr << "Documentator : printDoc : gFaustDirectory = '" << gFaustDirectory << "'" << endl;
235 //cerr << "Documentator : printDoc : gFaustSuperDirectory = '" << gFaustSuperDirectory << "'" << endl;
236 //cerr << "Documentator : printDoc : gFaustSuperSuperDirectory = '" << gFaustSuperSuperDirectory << "'" << endl;
237 //cerr << "Documentator : printDoc : gCurrentDir = '" << gCurrentDir << "'" << endl;
238
239 makedir(projname); // create a top directory to store files
240
241 string svgTopDir = subst("$0/svg", projname);
242 makedir(svgTopDir.c_str()); // create a directory to store svg-* subdirectories.
243
244 string cppdir = subst("$0/cpp", projname);
245 makedir(cppdir.c_str()); // create a cpp directory.
246
247 string pdfdir = subst("$0/pdf", projname);
248 makedir(pdfdir.c_str()); // create a pdf directory.
249
250 /* Copy all Faust source files into an 'src' sub-directory. */
251 vector<string> pathnames = gReader.listSrcFiles();
252 copyFaustSources(projname, pathnames);
253
254 string texdir = subst("$0/tex", projname);
255 mkchdir(texdir.c_str()); // create a directory and move into.
256
257 /** Create THE mathdoc tex file. */
258 ofstream docout(subst("$0.$1", gDocName, docdev).c_str());
259 cholddir(); // return to current directory
260
261 /** Init and load translation file. */
262 loadTranslationFile(gDocLang);
263
264 /** Simulate a default doc if no <mdoc> tag detected. */
265 if (gDocVector.empty()) { declareAutoDoc(); }
266
267 /** Printing stuff : in the '.tex' ouptut file, eventually including SVG files. */
268 printfaustdocstamp(faustversion, docout); ///< Faust version and compilation date (comment).
269 istream* latexheader = openArchFile(gLatexheaderfilename);
270 printlatexheader(*latexheader, faustversion, docout); ///< Static LaTeX header (packages and setup).
271 printdoccontent(svgTopDir.c_str(), gDocVector, faustversion, docout); ///< Generate math contents (main stuff!).
272 printlatexfooter(docout); ///< Static LaTeX footer.
273 }
274
275
276
277 /*****************************************************************************
278 LaTeX basic printing functions of the Documentation
279 *****************************************************************************/
280
281 /**
282 * Print a static LaTeX header.
283 *
284 * @param[in] latexheader The file containing the static part of the LaTeX header.
285 * @param[in] faustversion The current version of this Faust compiler.
286 * @param[out] docout The LaTeX output file to print into.
287 */
288 static void printlatexheader(istream& latexheader, const string& faustversion, ostream& docout)
289 {
290 string s;
291 while(getline(latexheader, s)) docout << s << endl;
292
293 /** Specific LaTeX macros for Faust */
294 docout << "\\newcommand{\\faustfilename}{" << gMasterDocument << "}" << endl;
295 docout << "\\newcommand{\\faustdocdir}{" << gMasterName << "-mdoc}" << endl;
296 docout << "\\newcommand{\\faustprogname}{" << gMasterName << "}" << endl;
297 docout << "\\newcommand{\\faustversion}{" << faustversion << "}" << endl;
298 char datebuf [150];
299 strftime (datebuf, 150, "%B %d, %Y", getCompilationDate());
300 docout << "\\newcommand{\\faustdocdate}{" << datebuf << "}" << endl;
301
302 docout << endl << "\\begin{document}" << endl;
303 }
304
305
306 /**
307 * @Brief Print a metadata set.
308 *
309 * Each metadata is a set, in order to handle multiple items,
310 * like multiple authors, even if most of metadatas have
311 * unique items.
312 *
313 * @param[in] expr Parsed metadata keyname, as boxes tree.
314 * @param[out] docout The output file to print into.
315 */
316 static void printDocMetadata(const Tree expr, ostream& docout)
317 {
318 if (gMetaDataSet.count(expr)) {
319 string sep = "";
320 set<Tree> mset = gMetaDataSet[expr];
321
322 for (set<Tree>::iterator j = mset.begin(); j != mset.end(); j++) {
323 docout << sep << rmExternalDoubleQuotes(tree2str(*j));
324 sep = ", ";
325 }
326 }
327 }
328
329
330 /**
331 * Print listings of each Faust code ".dsp" files,
332 * calling the 'printfaustlisting' function.
333 *
334 * @param[out] docout The LaTeX output file to print into.
335 */
336 static void printfaustlistings(ostream& docout)
337 {
338 if (gLstDependenciesSwitch) {
339 vector<string> pathnames = gReader.listSrcFiles();
340 for (unsigned int i=0; i< pathnames.size(); i++) {
341 printfaustlisting(pathnames[i], docout);
342 }
343 } else {
344 printfaustlisting(gMasterDocument, docout);
345 }
346 }
347
348
349 /**
350 * Print a listing of the Faust code, in a LaTeX "listing" environment.
351 * Strip content of <mdoc> tags.
352 *
353 * @param[in] faustfile The source file containing the Faust code.
354 * @param[out] docout The LaTeX output file to print into.
355 */
356 static void printfaustlisting(string& faustfile, ostream& docout)
357 {
358 string s;
359 ifstream src;
360
361 //cerr << "Documentator : printfaustlisting : Opening file '" << faustfile << "'" << endl;
362 src.open(faustfile.c_str(), ifstream::in);
363
364 docout << endl << "\\bigskip\\bigskip" << endl;
365 docout << "\\begin{lstlisting}[caption=\\texttt{" << filebasename(faustfile.c_str()) << "}]" << endl;
366
367 bool isInsideDoc = false;
368
369 if (faustfile != "" && src.good()) {
370 while(getline(src, s)) { /** We suppose there's only one <mdoc> tag per line. */
371 size_t foundopendoc = s.find("<mdoc>");
372 if (foundopendoc != string::npos && gStripDocSwitch) isInsideDoc = true;
373
374 if (isInsideDoc == false)
375 docout << s << endl;
376
377 size_t foundclosedoc = s.find("</mdoc>");
378 if (foundclosedoc != string::npos && gStripDocSwitch) isInsideDoc = false;
379 }
380 } else {
381 cerr << "ERROR : can't open faust source file " << faustfile << endl;
382 exit(1);
383 }
384
385 docout << "\\end{lstlisting}" << endl << endl;
386 }
387
388
389 /**
390 * Print the static LaTeX footer.
391 *
392 * @param[out] docout The LaTeX output file to print into.
393 */
394 static void printlatexfooter(ostream& docout)
395 {
396 docout << endl << "\\end{document}" << endl << endl;
397 }
398
399
400 /**
401 * Print a "doc stamp" in the LaTeX document :
402 * - the Faust version,
403 * - the date of doc compilation,
404 * - faust's web site URL.
405 *
406 * @param[in] faustversion The current version of this Faust compiler.
407 * @param[out] docout The LaTeX output file to print into.
408 */
409 static void printfaustdocstamp(const string& faustversion, ostream& docout)
410 {
411 char datebuf [150];
412 strftime (datebuf, 150, "%c", getCompilationDate());
413
414 docout << "%% This documentation was generated with Faust version " << faustversion << endl;
415 docout << "%% " << datebuf << endl;
416 docout << "%% http://faust.grame.fr" << endl << endl;
417 }
418
419
420
421 /*****************************************************************************
422 Main loop : launches prepare, evaluate, and print functions
423 *****************************************************************************/
424
425 /**
426 * @brief Main documentator loop.
427 *
428 * First loop on gDocVector, which contains the faust <mdoc> trees.
429 * Second loop for each of these <mdoc> trees, which contain parsed input expressions of 3 types :
430 * DOCEQN for <equation> tags, DOCDGM for <diagram> tags, and DOCTXT for direct LaTeX text (no tag).
431 * - DOCTXT expressions printing is trivial.
432 * - DOCDGM expressions printing calls 'printDocDgm' to generate SVG files and print LaTeX "figure" code.
433 * - DOCEQN expressions printing calls 'printDocEqn' after an important preparing work
434 * has been done by 'prepareDocEqns'.
435 *
436 * @param[in] projname Basename of the new doc directory ("*-math").
437 * @param[in] docVector Contains all <mdoc> parsed content (as boxes).
438 * @param[in] faustversion The current version of this Faust compiler.
439 * @param[out] docout The output file to print into.
440 **/
441 static void printdoccontent(const char* svgTopDir, const vector<Tree>& docVector, const string& faustversion, ostream& docout)
442 {
443 //cerr << endl << "Documentator : printdoccontent : " << docVector.size() << " <mdoc> tags read." << endl;
444
445 /** Equations need to be prepared (named and compiled) before printing. */
446 vector<Lateq*> docCompiledEqnsVector;
447 prepareDocEqns( docVector, docCompiledEqnsVector ); ///< Quite a lot of stuff there.
448 vector<Lateq*>::iterator eqn_it = docCompiledEqnsVector.begin();
449
450 int dgmIndex = 1; ///< For diagram directories numbering.
451
452 vector<string> docMasterCodeMap;
453 docMasterCodeMap = docCodeSlicer(gMasterDocument, docMasterCodeMap);
454
455 vector<Tree>::const_iterator doc;
456 vector<string>::const_iterator code;
457 code = docMasterCodeMap.begin();
458
459 if(doesFileBeginWithCode(gMasterDocument) && (! docMasterCodeMap.empty()) && gLstDistributedSwitch ) {
460 printdocCodeSlices(*code, docout);
461 code++;
462 }
463
464 /** First level printing loop, on docVector. */
465 for (doc=docVector.begin(); doc<docVector.end(); doc++, code++) {
466
467 Tree L = reverse(*doc);
468 //cerr << "Entering into <mdoc> parsing..." << endl;
469
470 /** Second level printing loop, on each <mdoc>. */
471 while (isList(L)) {
472 Tree expr;
473 if ( isDocEqn(hd(L), expr) ) { ///< After equations are well prepared and named.
474 printDocEqn(*eqn_it++, docout);
475 }
476 else if ( isDocDgm(hd(L), expr) ) {
477 printDocDgm(expr, svgTopDir, docout, dgmIndex++);
478 }
479 else if ( isDocMtd(hd(L), expr) ) {
480 printDocMetadata(expr, docout);
481 }
482 else if ( isDocTxt(hd(L)) ) {
483 docout << *hd(L)->branch(0); // Directly print registered doc text.
484 }
485 else if ( isDocNtc(hd(L)) ) {
486 printDocNotice(faustversion, docout);
487 }
488 else if ( isDocLst(hd(L)) ) {
489 printfaustlistings(docout);
490 }
491 else {
492 cerr << "ERROR : " << *hd(L) << " is not a valid documentation type." << endl;
493 }
494 L = tl(L);
495 }
496 //cerr << " ...end of <mdoc> parsing." << endl;
497
498 if ( code != docMasterCodeMap.end() && gLstDistributedSwitch ) {
499 printdocCodeSlices(*code, docout);
500 }
501 }
502 }
503
504
505
506 /*****************************************************************************
507 Primary sub-functions for <equation> handling
508 *****************************************************************************/
509
510 /**
511 * @brief Caller function for all steps of doc equations preparation.
512 *
513 * Note : many of the functions called put their result into their last argument
514 * in a "source / destination" manner,
515 * the "destination" being declared before the function call.
516 *
517 * @param[in] docBoxes The <mdoc> boxes to collect and prepare.
518 * @param[out] docCompiledEqnsVector The place to store compiled equations.
519 */
520 static void prepareDocEqns(const vector<Tree>& docBoxes, vector<Lateq*>& docCompiledEqnsVector)
521 {
522 vector<Tree> eqBoxes; collectDocEqns( docBoxes, eqBoxes ); ///< step 0. Feed a vector.
523
524 if(! eqBoxes.empty() ) {
525 vector<Tree> evalEqBoxes; mapEvalDocEqn( eqBoxes, gExpandedDefList, evalEqBoxes ); ///< step 1. Evaluate boxes.
526 vector<string> eqNames; mapGetEqName( evalEqBoxes, eqNames ); ///< step 2. Get boxes name.
527 vector<string> eqNicknames; calcEqnsNicknames( eqNames, eqNicknames ); ///< step 3. Calculate nicknames.
528
529 vector<int> eqInputs;
530 vector<int> eqOutputs;
531 vector<Tree> eqSigs; mapPrepareEqSig( evalEqBoxes, eqInputs, eqOutputs, eqSigs ); ///< step 4&5. Propagate and prepare signals.
532 mapSetSigNickname( eqNicknames, eqInputs, eqSigs ); ///< step 6. Set signals nicknames.
533 Tree superEqList; collectEqSigs( eqSigs, superEqList ); ///< step 7. Collect all signals in a superlist.
534
535 DocCompiler* DC = new DocCompiler(0, 0);
536 annotateSuperList( DC, superEqList ); ///< step 8. Annotate superEqList.
537 //calcAndSetLtqNames( superEqList ); ///< step 9. (directly in 10.)
538 mapCompileDocEqnSigs( eqSigs, eqInputs, eqOutputs, DC, docCompiledEqnsVector ); ///< step 10. Compile every signal.
539 }
540 }
541
542
543 /**
544 * #0. Collect every <equation> found in all <mdoc> faust comments.
545 *
546 * @param[in] docBoxes The <mdoc> boxes to filter.
547 * @param[out] eqBoxes The place to store only <equation> boxes.
548 */
549 static void collectDocEqns(const vector<Tree>& docBoxes, vector<Tree>& eqBoxes)
550 {
551 int nbdoceqn = 0;
552
553 for (vector<Tree>::const_iterator doc=docBoxes.begin(); doc<docBoxes.end(); doc++) {
554 Tree L = reverse(*doc);
555 Tree expr;
556 while (isList(L)) {
557 if ( isDocEqn(hd(L), expr) ) {
558 eqBoxes.push_back(expr);
559 nbdoceqn++;
560 }
561 L = tl(L);
562 }
563 }
564 //cerr << "Documentator : collectDocEqns : " << nbdoceqn << " <equation> tags found." << endl;
565 }
566
567
568 /**
569 * #1. Evaluate every doc <equation> (evaluation replaces abstractions by symbolic boxes).
570 *
571 * @param[in] eqBoxes The boxes to evaluate.
572 * @param[in] env The environment for the evaluation.
573 * @param[out] evalEqBoxes The place to store evaluated equations boxes.
574 */
575 static void mapEvalDocEqn(const vector<Tree>& eqBoxes, const Tree& env, vector<Tree>& evalEqBoxes)
576 {
577 //cerr << "###\n# Documentator : mapEvalDocEqn" << endl;
578
579 for ( vector<Tree>::const_iterator eq=eqBoxes.begin(); eq < eqBoxes.end(); eq++)
580 {
581 evalEqBoxes.push_back(evaldocexpr( *eq, env ));
582 }
583 //cerr << "Documentator : end of mapEvalDocEqn\n---" << endl;
584 }
585
586
587 /**
588 * #2. Get name if exists, else create one, and store it.
589 *
590 * @param[in] evalEqBoxes Evaluated box trees, eventually containing an equation name.
591 * @param[out] eqNames The place to store equations names.
592 */
593 static void mapGetEqName(const vector<Tree>& evalEqBoxes, vector<string>& eqNames)
594 {
595 //cerr << "###\n# Documentator : mapGetEqName" << endl;
596
597 int i = 1;
598 for( vector<Tree>::const_iterator eq = evalEqBoxes.begin(); eq < evalEqBoxes.end(); eq++, i++ ) {
599 Tree id;
600 string s;
601 int n,m; getBoxType(*eq, &n, &m); // eq name only for bd without inputs
602 if ( n==0 && getDefNameProperty(*eq, id) ) {
603 s = tree2str(id);
604 }
605 else {
606 s = calcNumberedName("doceqn-", i);
607 }
608 eqNames.push_back( s ) ;
609 }
610 //cerr << "Documentator : end of mapGetEqName\n---" << endl;
611 }
612
613
614 /**
615 * #3. Calculate a nickname for each equation and store it.
616 *
617 * @param[in] eqNames Equations names to parse.
618 * @param[out] eqNicknames The place to store calculated nicknames.
619 *
620 * @todo Should check unicity : check whether several names share the same initial,
621 * or else capture consonants for example.
622 */
623 static void calcEqnsNicknames(const vector<string>& eqNames, vector<string>& eqNicknames)
624 {
625 //cerr << "###\n# Documentator : calcEqnsNicknames" << endl;
626
627 vector<string> v;
628
629 for( vector<string>::const_iterator eq = eqNames.begin(); eq < eqNames.end(); eq++ ) {
630 string init = calcDocEqnInitial(*eq);
631 v.push_back(init);
632 /** Check duplicates */
633 // for( vector<string>::iterator it = v.begin(); it < v.end()-1; ++it ) {
634 // if (init == *it) {
635 // //cerr << "!! Warning Documentator : calcEqnsNicknames : duplicates \"" << init << "\"" << endl;
636 // }
637 // }
638 eqNicknames.push_back(init);
639 }
640
641 // for( vector<string>::const_iterator eq = eqNames.begin(); eq < eqNames.end(); eq++ ) {
642 // int c = 0;
643 // c = count_if(eqNames.begin(), eqNames.end(), bind2nd(equal_to<string>(), *eq));
644 // if (c > 0) {
645 // cerr << "- Duplicate nickname !! " << *eq << endl;
646 // } else {
647 // cerr << "(no duplicate) " << *eq << endl;
648 // }
649 // }
650
651 //cerr << "Documentator : end of calcEqnsNicknames\n---" << endl;
652 }
653
654
655 /**
656 * #4&5. Propagate and prepare every doc <equation>.
657 *
658 * Call boxPropagateSig, deBruijn2Sym, simplify, and privatise.
659 *
660 * @param[in] evalEqBoxes Equations boxes to propagate as signals.
661 * @param[out] eqSigs The place to store prepared signals.
662 */
663 static void mapPrepareEqSig(const vector<Tree>& evalEqBoxes, vector<int>& eqInputs, vector<int>& eqOutputs, vector<Tree>& eqSigs)
664 {
665 //cerr << "###\n# Documentator : mapPrepareEqSig" << endl;
666
667 for( vector<Tree>::const_iterator eq = evalEqBoxes.begin(); eq < evalEqBoxes.end(); eq++ ) {
668
669 int numInputs, numOutputs;
670 getBoxInputsAndOutputs(*eq, numInputs, numOutputs);
671 //cerr << numInputs <<" ins and " << numOutputs <<" outs" << endl;
672 eqInputs.push_back(numInputs);
673 eqOutputs.push_back(numOutputs);
674
675 Tree lsig1 = boxPropagateSig( nil, *eq , makeSigInputList(numInputs) );
676 //cerr << "output signals are : " << endl; printSignal(lsig1, stderr);
677
678 Tree lsig2 = deBruijn2Sym(lsig1); ///< Convert debruijn recursion into symbolic recursion
679 Tree lsig3 = simplify(lsig2); ///< Simplify by executing every computable operation
680 //Tree lsig4 = privatise(lsig3); ///< Un-share tables with multiple writers
681 Tree lsig4 = docTableConvertion(lsig3); ///< convert regular tables into special doctables
682 ///< (regular tables are difficult to translate to equations)
683
684 eqSigs.push_back(lsig4);
685 }
686 //cerr << "Documentator : end of mapPrepareEqSig\n---" << endl;
687 }
688
689
690 /**
691 * #6. Set signals nicknames.
692 *
693 * Do nothing for the moment !
694 * @param[in] eqNicknames Contains previously calculated nicknames.
695 * @param[out] eqSigs The signals to tag with a NICKNAMEPROPERTY.
696 */
697 static void mapSetSigNickname(const vector<string>& eqNicknames, const vector<int>& eqInputs, const vector<Tree>& eqSigs)
698 {
699 //cerr << "###\n# Documentator : mapSetSigNickname" << endl;
700
701 // Do nothing for the moment...
702 // for( unsigned int i=0; i < eqSigs.size(); i++ ) {
703 // if (eqInputs[i] == 0) // Only "generators" should be finally named with user equation (nick)name.
704 // setSigListNickName(eqSigs[i], eqNicknames[i]);
705 // }
706 //cerr << "Documentator : end of mapSetSigNickname\n---" << endl;
707 }
708
709
710 /**
711 * #7. Collect each prepared list of signals to construct a super list.
712 *
713 * @param[in] eqSigs Contains well-prepared and nicknamed signals.
714 * @param[out] superEqList The root where to 'cons' signals all together.
715 */
716 static void collectEqSigs(const vector<Tree>& eqSigs, Tree& superEqList)
717 {
718 //cerr << "###\n# Documentator : collectEqSigs" << endl;
719
720 superEqList = nil;
721
722 for( vector<Tree>::const_iterator it = eqSigs.begin(); it < eqSigs.end(); ++it ) {
723 superEqList = cons( *it, superEqList );
724 }
725 //printSignal(superEqList, stdout, 0);
726
727 //cerr << endl << "Documentator : end of collectEqSigs\n---" << endl;
728 }
729
730
731 /**
732 * #8. Annotate superEqList (to find candidate signals to be named later).
733 *
734 * @param[in] DC The signals compiler.
735 * @param[out] superEqList The super equations signal tree to annotate.
736 */
737 static void annotateSuperList(DocCompiler* DC, Tree superEqList)
738 {
739 DC->annotate(superEqList);
740 }
741
742
743 ///**
744 // * #9. Calculated and set lateq (LaTeX equation) names.
745 // * Note : Transfered into mapCompileDocEqnSigs (DocCompiler::compileMultiSignal).
746 // */
747 //static void calcAndSetLtqNames(Tree superEqList)
748 //{
749 //
750 //}
751
752
753 /**
754 * #10. Name and compile prepared doc <equation> signals.
755 *
756 * @param[in] eqSigs Contains well-prepared and nicknamed signals.
757 * @param[in] DC The signals compiler.
758 * @param[out] docCompiledEqnsVector The place to store each compiled Lateq* object.
759 */
760 static void mapCompileDocEqnSigs(const vector<Tree>& eqSigs, const vector<int>& eqInputs, const vector<int>& eqOutputs, DocCompiler* DC, vector<Lateq*>& docCompiledEqnsVector)
761 {
762 //cerr << "###\n# Documentator : mapCompileDocEqnSigs" << endl;
763
764 for( unsigned int i=0; i < eqSigs.size(); i++ ) {
765
766 // docCompiledEqnsVector.push_back( DC->compileMultiSignal(*it, 0) );
767 docCompiledEqnsVector.push_back( DC->compileLateq(eqSigs[i], new Lateq(eqInputs[i], eqOutputs[i])) );
768 }
769
770 //cerr << "Documentator : end of mapCompileDocEqnSigs\n---" << endl;
771 }
772
773
774
775 /*****************************************************************************
776 Secondary sub-functions for <equation> handling
777 *****************************************************************************/
778
779
780 /**
781 * Calculate an appropriate nickname for equations,
782 * from previous names.
783 *
784 * @param The string to parse.
785 * @return Essentially returns the initial character,
786 * except "Y" for "process", and "Z" for unnamed equations.
787 */
788 static string calcDocEqnInitial(const string s)
789 {
790 string nn;
791 if(s == "process")
792 nn = "Y";
793 else if (s.substr(0,6) == "doceqn")
794 nn = "Z";
795 else
796 nn += toupper(s[0]);
797 return nn;
798 }
799
800
801 /**
802 * Just get the number of inputs and the number of outputs of a box.
803 *
804 * @param[in] t The box tree to get inputs and outputs from.
805 * @param[out] numInputs The place to store the number of inputs.
806 * @param[out] numOutputs The place to store the number of outputs.
807 */
808 static void getBoxInputsAndOutputs(const Tree t, int& numInputs, int& numOutputs)
809 {
810 if (!getBoxType(t, &numInputs, &numOutputs)) {
811 cerr << "ERROR during the evaluation of t : " << boxpp(t) << endl;
812 exit(1);
813 }
814 //cerr << "Documentator : " << numInputs <<" inputs and " << numOutputs <<" outputs for box : " << boxpp(t) << endl;
815 }
816
817
818 /**
819 * Print doc equations, following the Lateq::println method.
820 *
821 * @param[in] ltq The object containing compiled LaTeX code of equations.
822 * @param[out] docout The output file to print into.
823 */
824 static void printDocEqn(Lateq* ltq, ostream& docout)
825 {
826 ltq->println(docout);
827 //cerr << "Documentator : printDocEqn : "; ltq->println(cerr); cerr << endl;
828 }
829
830
831 /*****************************************************************************
832 Sub-function for <diagram> handling
833 *****************************************************************************/
834
835 /**
836 * @brief Doc diagrams handling.
837 *
838 * Three steps :
839 * 1. evaluate expression
840 * 2. call svg drawing in the appropriate directory
841 * 3. print latex figure code with the appropriate directory reference
842 *
843 * @param[in] expr Parsed input expression, as boxes tree.
844 * @param[in] svgTopDir Basename of the new doc directory ("*-math/svg").
845 * @param[out] docout The output file to print into.
846 */
847 static void printDocDgm(const Tree expr, const char* svgTopDir, ostream& docout, int i)
848 {
849 /** 1. Evaluate expression. */
850 Tree docdgm = evaldocexpr(expr, gExpandedDefList);
851 if (gErrorCount > 0) {
852 cerr << "Total of " << gErrorCount << " errors during evaluation of : diagram docdgm = " << boxpp(docdgm) << ";\n";
853 exit(1);
854 }
855
856 /**
857 * 2. Draw the diagram after its evaluation, in SVG.
858 * Warning : pdflatex can't directly include SVG files !
859 */
860 char dgmid[MAXIDCHARS+1];
861 sprintf(dgmid, "%02d", i);
862 string thisdgmdir = subst("$0/svg-$1", svgTopDir, dgmid);
863 //cerr << "Documentator : printDocDgm : drawSchema in '" << gCurrentDir << "/" << thisdgmdir << "'" << endl;
864
865 drawSchema( docdgm, thisdgmdir.c_str(), "svg" );
866
867 /** 3. Print LaTeX figure code. */
868 char temp[1024];
869 const string dgmfilename = legalFileName(docdgm, 1024, temp);
870 //docout << "figure \\ref{figure" << i << "}";
871 docout << "\\begin{figure}[ht!]" << endl;
872 docout << "\t\\centering" << endl;
873 docout << "\t\\includegraphics[width=\\textwidth]{" << subst("../svg/svg-$0/", dgmid) << dgmfilename << "}" << endl;
874 docout << "\t\\caption{" << gDocMathStringMap["dgmcaption"] << " \\texttt{" << dgmfilename << "}}" << endl;
875 docout << "\t\\label{figure" << i << "}" << endl;
876 docout << "\\end{figure}" << endl << endl;
877
878 /** 4. Warn about naming interferences (in the notice). */
879 gDocNoticeFlagMap["nameconflicts"] = true;
880 gDocNoticeFlagMap["svgdir"] = true;
881 }
882
883
884
885 /*****************************************************************************
886 Other sub-functions
887 *****************************************************************************/
888
889
890 /**
891 * Slice faust code between "mdoc" sections.
892 *
893 * @param[in] faustfile Name of the input faust file to parse.
894 * @param[in] codeSlices The place to store code "slices".
895 */
896 vector<string>& docCodeSlicer(const string& faustfile, vector<string>& codeSlices)
897 {
898 string s;
899 ifstream src;
900 src.open(faustfile.c_str(), ifstream::in);
901 string tmp = "";
902
903 bool isInsideDoc = false;
904
905 if (faustfile != "" && src.good()) {
906 while(getline(src, s)) { /** Caution: we suppose there's only one <mdoc> tag per line! */
907 size_t foundopendoc = s.find("<mdoc>");
908
909 if (foundopendoc != string::npos) {
910 if (isInsideDoc == false) { /** A change has come. ;) */
911 if (! tmp.empty() ) {
912 codeSlices.push_back(tmp); }
913 tmp = "";
914 }
915 isInsideDoc = true;
916 }
917
918 if (isInsideDoc == false) {
919 tmp += s + '\n';
920 }
921
922 size_t foundclosedoc = s.find("</mdoc>");
923 if (foundclosedoc != string::npos) isInsideDoc = false;
924 }
925 } else {
926 cerr << "ERROR : can't open faust source file " << faustfile << endl;
927 exit(1);
928 }
929 return codeSlices;
930 }
931
932
933 /**
934 * Print faust code inside a listing environment.
935 *
936 * @param[in] code Faust code as a string (may contain '\n' characters).
937 * @param[out] docout The output file to print into.
938 */
939 static void printdocCodeSlices(const string& code, ostream& docout)
940 {
941 if ( ! code.empty() ) {
942 docout << endl << "\\begin{lstlisting}[numbers=none, frame=none, basicstyle=\\small\\ttfamily, backgroundcolor=\\color{yobg}]" << endl;
943 docout << code << endl;
944 docout << "\\end{lstlisting}" << endl << endl;
945 }
946 }
947
948
949 /**
950 * Test whether a file does begin with some faust code or not.
951 *
952 * @param[in] faustfile Name of the input faust file to parse.
953 */
954 static bool doesFileBeginWithCode(const string& faustfile)
955 {
956 string s;
957 ifstream src;
958 src.open(faustfile.c_str(), ifstream::in);
959
960 if (faustfile != "" && src.good()) {
961 getline(src, s);
962 size_t foundopendoc = s.find("<mdoc>");
963 if(int(foundopendoc)==0) {
964 return false;
965 } else {
966 return true;
967 }
968 } else {
969 cerr << "ERROR : can't open faust source file " << faustfile << endl;
970 exit(1);
971 }
972 }
973
974
975
976 //------------------------ dealing with files -------------------------
977
978
979 /**
980 * Create a new directory in the current one.
981 */
982 static int makedir(const char* dirname)
983 {
984 char buffer[FAUST_PATH_MAX];
985 gCurrentDir = getcwd (buffer, FAUST_PATH_MAX);
986
987 if ( gCurrentDir.c_str() != 0) {
988 int status = mkdir(dirname, S_IRWXU | S_IRWXG | S_IROTH | S_IXOTH);
989 if (status == 0 || errno == EEXIST) {
990 return 0;
991 }
992 }
993 perror("makedir");
994 exit(errno);
995 }
996
997
998 /**
999 * Create a new directory in the current one,
1000 * then 'cd' into this new directory.
1001 *
1002 * @remark
1003 * The current directory is saved to be later restaured.
1004 */
1005 static int mkchdir(const char* dirname)
1006 {
1007 char buffer[FAUST_PATH_MAX];
1008 gCurrentDir = getcwd (buffer, FAUST_PATH_MAX);
1009
1010 if ( gCurrentDir.c_str() != 0) {
1011 int status = mkdir(dirname, S_IRWXU | S_IRWXG | S_IROTH | S_IXOTH);
1012 if (status == 0 || errno == EEXIST) {
1013 if (chdir(dirname) == 0) {
1014 return 0;
1015 }
1016 }
1017 }
1018 perror("mkchdir");
1019 exit(errno);
1020 }
1021
1022
1023 /**
1024 * Switch back to the previously stored current directory
1025 */
1026 static int cholddir ()
1027 {
1028 if (chdir(gCurrentDir.c_str()) == 0) {
1029 return 0;
1030 } else {
1031 perror("cholddir");
1032 exit(errno);
1033 }
1034 }
1035
1036
1037 /**
1038 * Get current directory and store it in gCurrentDir.
1039 */
1040 static void getCurrentDir ()
1041 {
1042 char buffer[FAUST_PATH_MAX];
1043 gCurrentDir = getcwd (buffer, FAUST_PATH_MAX);
1044 }
1045
1046
1047 /**
1048 * Open architecture file.
1049 */
1050 static istream* openArchFile (const string& filename)
1051 {
1052 istream* file;
1053 getCurrentDir(); // Save the current directory.
1054 //cerr << "Documentator : openArchFile : Opening input file '" << filename << "'" << endl;
1055 if ( (file = open_arch_stream(filename.c_str())) ) {
1056 //cerr << "Documentator : openArchFile : Opening '" << filename << "'" << endl;
1057 } else {
1058 cerr << "ERROR : can't open architecture file " << filename << endl;
1059 exit(1);
1060 }
1061 cholddir(); // Return to current directory.
1062 return file;
1063 }
1064
1065
1066 /**
1067 * Transform the definition name property of tree <t> into a
1068 * legal file name. The resulting file name is stored in
1069 * <dst> a table of at least <n> chars. Returns the <dst> pointer
1070 * for convenience.
1071 */
1072 static char* legalFileName(const Tree t, int n, char* dst)
1073 {
1074 Tree id;
1075 int i=0;
1076 if (getDefNameProperty(t, id)) {
1077 const char* src = tree2str(id);
1078 for (i=0; isalnum(src[i]) && i<16; i++) {
1079 dst[i] = src[i];
1080 }
1081 }
1082 dst[i] = 0;
1083 if (strcmp(dst, "process") != 0) {
1084 // if it is not process add the hex address to make the name unique
1085 snprintf(&dst[i], n-i, "-%p", t);
1086 }
1087 return dst;
1088 }
1089
1090 /**
1091 * Simply concat a string with a number in a "%03d" format.
1092 * The number has MAXIDCHARS characters.
1093 **/
1094 static string calcNumberedName(const char* base, int i)
1095 {
1096 char nb[MAXIDCHARS+1];
1097 sprintf(nb, "%03d", i);
1098 return subst("$0$1", base, nb);
1099 }
1100
1101 /**
1102 * Remove the leading and trailing double quotes of a string
1103 * (but not those in the middle of the string)
1104 */
1105 static string rmExternalDoubleQuotes(const string& s)
1106 {
1107 size_t i = s.find_first_not_of("\"");
1108 size_t j = s.find_last_not_of("\"");
1109
1110 if ( (i != string::npos) & (j != string::npos) ) {
1111 return s.substr(i, 1+j-i);
1112 } else {
1113 return "";
1114 }
1115 }
1116
1117
1118 /**
1119 * Copy all Faust source files into an 'src' subdirectory.
1120 *
1121 * @param[in] projname Basename of the new doc directory ("*-math").
1122 * @param[in] pathnames The paths list of the source files to copy.
1123 */
1124 static void copyFaustSources(const char* projname, const vector<string>& pathnames)
1125 {
1126 string srcdir = subst("$0/src", projname);
1127 //cerr << "Documentator : copyFaustSources : Creating directory '" << srcdir << "'" << endl;
1128 makedir(srcdir.c_str()); // create a directory.
1129
1130 for (unsigned int i=0; i< pathnames.size(); i++) {
1131 ifstream src;
1132 ofstream dst;
1133 string faustfile = pathnames[i];
1134 string copy = subst("$0/$1", srcdir, filebasename(faustfile.c_str()));
1135 //cerr << "Documentator : copyFaustSources : Opening input file '" << faustfile << "'" << endl;
1136 //cerr << "Documentator : copyFaustSources : Opening output file '" << copy << "'" << endl;
1137 src.open(faustfile.c_str(), ifstream::in);
1138 dst.open(copy.c_str(), ofstream::out);
1139 string s;
1140 while ( getline(src,s) ) dst << s << endl;
1141 }
1142 }
1143
1144
1145 //------------------------ date managment -------------------------
1146
1147
1148 static void initCompilationDate()
1149 {
1150 time_t now;
1151
1152 time(&now);
1153 gCompilationDate = *localtime(&now);
1154 }
1155
1156 static struct tm* getCompilationDate()
1157 {
1158 initCompilationDate();
1159 return &gCompilationDate;
1160 }
1161
An OCaml-based interpreter for Faust and its vector extension