1 .\" $Id: mdoc.3,v 1.39 2010/05/25 21:46:48 kristaps Exp $
3 .\" Copyright (c) 2009-2010 Kristaps Dzonsons <kristaps@bsd.lv>
5 .\" Permission to use, copy, modify, and distribute this software for any
6 .\" purpose with or without fee is hereby granted, provided that the above
7 .\" copyright notice and this permission notice appear in all copies.
9 .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
10 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
11 .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
12 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
13 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
14 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
15 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
17 .Dd $Mdocdate: May 25 2010 $
29 .Nd mdoc macro compiler library
33 .Vt extern const char * const * mdoc_macronames;
34 .Vt extern const char * const * mdoc_argnames;
36 .Fn mdoc_alloc "void *data" "int pflags" "mandocmsg msgs"
38 .Fn mdoc_endparse "struct mdoc *mdoc"
40 .Fn mdoc_free "struct mdoc *mdoc"
41 .Ft "const struct mdoc_meta *"
42 .Fn mdoc_meta "const struct mdoc *mdoc"
43 .Ft "const struct mdoc_node *"
44 .Fn mdoc_node "const struct mdoc *mdoc"
46 .Fn mdoc_parseln "struct mdoc *mdoc" "int line" "char *buf"
48 .Fn mdoc_reset "struct mdoc *mdoc"
52 library parses lines of
55 into an abstract syntax tree (AST).
57 In general, applications initiate a parsing sequence with
59 parse each line in a document with
61 close the parsing session with
63 operate over the syntax tree returned by
67 then free all allocated memory with
71 function may be used in order to reset the parser for another input
75 section for a simple example.
77 This section further defines the
82 available to programmers.
84 .Sx Abstract Syntax Tree
85 section documents the output tree.
91 may use the following types:
94 An opaque type defined in
96 Its values are only used privately within the library.
97 .It Vt struct mdoc_node
102 .Sx Abstract Syntax Tree
105 A function callback type defined in
109 Function descriptions follow:
112 Allocates a parsing structure.
115 pointer is passed to callbacks in
117 which are documented further in the header file.
120 arguments are defined in
122 Returns NULL on failure.
123 If non-NULL, the pointer must be freed with
126 Reset the parser for another parse routine.
129 behaves as if invoked for the first time.
130 If it returns 0, memory could not be allocated.
132 Free all resources of a parser.
133 The pointer is no longer valid after invocation.
135 Parse a nil-terminated line of input.
136 This line should not contain the trailing newline.
137 Returns 0 on failure, 1 on success.
140 is modified by this function.
142 Signals that the parse is complete.
145 is called subsequent to
147 the resulting tree is incomplete.
148 Returns 0 on failure, 1 on success.
150 Returns the first node of the parse.
155 return 0, the tree will be incomplete.
157 Returns the document's parsed meta-data.
158 If this information has not yet been supplied or
162 return 0, the data will be incomplete.
165 The following variables are also defined:
167 .It Va mdoc_macronames
168 An array of string-ified token names.
170 An array of string-ified token argument names.
172 .Ss Abstract Syntax Tree
175 functions produce an abstract syntax tree (AST) describing input in a
177 It may be reviewed at any time with
179 however, if called before
185 fail, it may be incomplete.
187 This AST is governed by the ontological
190 and derives its terminology accordingly.
192 elements described in
194 are described simply as
197 The AST is composed of
199 nodes with block, head, body, element, root and text types as declared
203 Each node also provides its parse point (the
208 fields), its position in the tree (the
214 fields) and some type-specific data.
216 The tree itself is arranged according to the following normal form,
217 where capitalised non-terminals represent nodes.
219 .Bl -tag -width "ELEMENTXX" -compact
223 \(<- BLOCK | ELEMENT | TEXT
225 \(<- (HEAD [TEXT])+ [BODY [TEXT]] [TAIL [TEXT]]
227 \(<- BODY [TEXT] [TAIL [TEXT]]
237 \(<- [[:printable:],0x1e]*
240 Of note are the TEXT nodes following the HEAD, BODY and TAIL nodes of
241 the BLOCK production.
242 These refer to punctuation marks.
243 Furthermore, although a TEXT node will generally have a non-zero-length
244 string, in the specific case of
245 .Sq \&.Bd \-literal ,
246 an empty line will produce a zero-length string.
248 The following example reads lines from stdin and parses them, operating
249 on the finished parse tree with
251 This example does not error-check nor free memory upon failure.
252 .Bd -literal -offset indent
254 const struct mdoc_node *node;
260 mdoc = mdoc_alloc(NULL, 0, NULL);
264 while ((len = getline(&buf, &alloc_len, stdin)) >= 0) {
265 if (len && buflen[len - 1] = '\en')
266 buf[len - 1] = '\e0';
267 if ( ! mdoc_parseln(mdoc, line, buf))
268 errx(1, "mdoc_parseln");
272 if ( ! mdoc_endparse(mdoc))
273 errx(1, "mdoc_endparse");
274 if (NULL == (node = mdoc_node(mdoc)))
275 errx(1, "mdoc_node");
283 in the source archive for a rigorous reference.
290 library was written by
291 .An Kristaps Dzonsons Aq kristaps@bsd.lv .