Write the text from the lexer to the OutputRange, and expand any macro in it..
Expand a macro, and write the result to an OutputRange.
Parses macros (or params) declaration list until the lexer is empty.
Parses macros files, usually with extension .ddoc.
The set of ddoc's predefined macros.
import std.conv : text; import ddoc.lexer : Lexer; // Ddoc has some hardwired macros, which will be automatically searched. // List here: dlang.org/ddoc.html auto l1 = Lexer(`A simple $(B Hello $(I world))`); immutable r1 = expand(l1, null); assert(r1 == `A simple <b>Hello <i>world</i></b>`, r1); // Example on how to parse ddoc file / macros sections. KeyValuePair[] pairs; auto lm2 = Lexer(`GREETINGS = Hello $(B $0) IDENTITY = $0`); // Acts as we are parsing a ddoc file. assert(parseKeyValuePair(lm2, pairs)); // parseKeyValuePair parses up to the first invalid token, or until // a section is reached. It returns false on parsing failure. assert(lm2.empty, lm2.front.text); assert(pairs.length == 2, text("Expected length 2, got: ", pairs.length)); string[string] m2; foreach (kv; pairs) m2[kv[0]] = kv[1]; // Macros are not expanded until the final call site. // This allow for forward reference of macro and recursive macros. assert(m2.get(`GREETINGS`, null) == `Hello $(B $0)`, m2.get(`GREETINGS`, null)); assert(m2.get(`IDENTITY`, null) == `$0`, m2.get(`IDENTITY`, null)); // There are some more specialized functions in this module, such as // expandMacro which expects the lexer to be placed on a macro, and // will consume the input (unlike expand, which exhaust a copy). auto l2 = Lexer(`$(GREETINGS $(IDENTITY John Doe))`); immutable r2 = expand(l2, m2); assert(r2 == `Hello <b>John Doe</b>`, r2); // Note that the expansions are not processed recursively. // Hence, it's possible to have DDOC-formatted code inside DDOC. auto l3 = Lexer(`This $(DOLLAR)(MACRO) do not expand recursively.`); immutable r3 = expand(l3, null); immutable e3 = `This $(MACRO) do not expand recursively.`; assert(e3 == r3, r3);
© 2014 Economic Modeling Specialists, Intl.
Functions to work with DDOC macros.
Provide functionalities to perform various macro-related operations, including: - Expand a text, with expand. - Expand a macro, with expandMacro; - Parse macro files (.ddoc), with parseMacrosFile; - Parse a "Macros:" section, with parseKeyValuePair; To work with embedded documentation ('.dd' files), see ddoc.standalone.
Most functions provide two interfaces. One takes an OutputRange to write to, and the other one is a convenience wrapper around it, which returns a string. It uses an std.array.Appender as the output range.
Most functions take a 'macros' parameter. The user is not required to pass the standard D macros in it if he wants HTML output, the same macros that are hardwired into DDOC are hardwired into libddoc (B, I, D_CODE, etc...).
Note: The code can contains embedded code, which will be highlighted by macros substitution (see corresponding DDOC macros). However, the substitution is *NOT* performed by this module, you should call ddoc.highlight.highlight first. If you forget to do so, libddoc will consider this as a developper mistake, and will kindly inform you with an assertion error.