ddoc.macros

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.

Members

Functions

expand
void expand(Lexer input, in string[string] macros, O output)
string expand(Lexer input, string[string] macros)

Write the text from the lexer to the OutputRange, and expand any macro in it..

expandMacro
void expandMacro(ref Lexer input, in string[string] macros, O output)
string expandMacro(ref Lexer input, in string[string] macros)

Expand a macro, and write the result to an OutputRange.

parseKeyValuePair
bool parseKeyValuePair(ref Lexer lexer, ref KeyValuePair[] pairs)

Parses macros (or params) declaration list until the lexer is empty.

parseMacrosFile
string[string] parseMacrosFile(R paths)

Parses macros files, usually with extension .ddoc.

stripWhitespace
size_t stripWhitespace(ref Lexer lexer)

Variables

DEFAULT_MACROS
string[string] DEFAULT_MACROS;

The set of ddoc's predefined macros.

Examples

1 import std.conv : text;
2 import ddoc.lexer : Lexer;
3 
4 // Ddoc has some hardwired macros, which will be automatically searched.
5 // List here: dlang.org/ddoc.html
6 auto l1 = Lexer(`A simple $(B Hello $(I world))`);
7 immutable r1 = expand(l1, null);
8 assert(r1 == `A simple <b>Hello <i>world</i></b>`, r1);
9 
10 // Example on how to parse ddoc file / macros sections.
11 KeyValuePair[] pairs;
12 auto lm2 = Lexer(`GREETINGS  =  Hello $(B $0)
13 		  IDENTITY = $0`);
14 // Acts as we are parsing a ddoc file.
15 assert(parseKeyValuePair(lm2, pairs));
16 // parseKeyValuePair parses up to the first invalid token, or until
17 // a section is reached. It returns false on parsing failure.
18 assert(lm2.empty, lm2.front.text);
19 assert(pairs.length == 2, text("Expected length 2, got: ", pairs.length));
20 string[string] m2;
21 foreach (kv; pairs)
22 	m2[kv[0]] = kv[1];
23 // Macros are not expanded until the final call site.
24 // This allow for forward reference of macro and recursive macros.
25 assert(m2.get(`GREETINGS`, null) == `Hello $(B $0)`, m2.get(`GREETINGS`, null));
26 assert(m2.get(`IDENTITY`, null) == `$0`, m2.get(`IDENTITY`, null));
27 
28 // There are some more specialized functions in this module, such as
29 // expandMacro which expects the lexer to be placed on a macro, and
30 // will consume the input (unlike expand, which exhaust a copy).
31 auto l2 = Lexer(`$(GREETINGS $(IDENTITY John Doe))`);
32 immutable r2 = expand(l2, m2);
33 assert(r2 == `Hello <b>John Doe</b>`, r2);
34 
35 // Note that the expansions are not processed recursively.
36 // Hence, it's possible to have DDOC-formatted code inside DDOC.
37 auto l3 = Lexer(`This $(DOLLAR)(MACRO) do not expand recursively.`);
38 immutable r3 = expand(l3, null);
39 immutable e3 = `This $(MACRO) do not expand recursively.`;
40 assert(e3 == r3, r3);

Meta

Authors

Brian Schott, Mathias 'Geod24' Lang