1 .\" $Id: man.3,v 1.29 2011/01/03 11:31:26 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: January 3 2011 $
29 .Nd man macro compiler library
33 .Vt extern const char * const * man_macronames;
37 .Fa "const struct tbl_span *span"
41 .Fa "struct regset *regs"
46 .Fn man_endparse "struct man *man"
48 .Fn man_free "struct man *man"
49 .Ft "const struct man_meta *"
50 .Fn man_meta "const struct man *man"
51 .Ft "const struct man_node *"
52 .Fn man_node "const struct man *man"
60 .Fn man_reset "struct man *man"
64 library parses lines of
66 input into an abstract syntax tree (AST).
68 In general, applications initiate a parsing sequence with
70 parse each line in a document with
72 close the parsing session with
74 operate over the syntax tree returned by
78 then free all allocated memory with
82 function may be used in order to reset the parser for another input
85 Beyond the full set of macros defined in
89 library also accepts the following macro:
91 .Bl -tag -width Ds -compact
94 Handled as a current-scope line macro.
100 Its values are only used privately within the library.
101 .It Vt struct man_node
104 .Sx Abstract Syntax Tree
113 return 0, calls to any function but
117 will raise an assertion.
120 Add a table span to the parsing stream.
121 Returns 0 on failure, 1 on success.
123 Allocates a parsing structure.
128 Always returns a valid pointer.
129 The pointer must be freed with
132 Reset the parser for another parse routine.
135 behaves as if invoked for the first time.
137 Free all resources of a parser.
138 The pointer is no longer valid after invocation.
140 Parse a nil-terminated line of input.
141 This line should not contain the trailing newline.
142 Returns 0 on failure, 1 on success.
145 is modified by this function.
147 Signals that the parse is complete.
148 Returns 0 on failure, 1 on success.
150 Returns the first node of the parse.
152 Returns the document's parsed meta-data.
155 The following variables are also defined:
157 .It Va man_macronames
158 An array of string-ified token names.
160 .Ss Abstract Syntax Tree
163 functions produce an abstract syntax tree (AST) describing input in a
165 It may be reviewed at any time with
167 however, if called before
173 fail, it may be incomplete.
175 This AST is governed by the ontological rules dictated in
177 and derives its terminology accordingly.
179 The AST is composed of
181 nodes with element, root and text types as declared by the
184 Each node also provides its parse point (the
189 fields), its position in the tree (the
195 fields) and some type-specific data.
197 The tree itself is arranged according to the following normal form,
198 where capitalised non-terminals represent nodes.
200 .Bl -tag -width "ELEMENTXX" -compact
204 \(<- ELEMENT | TEXT | BLOCK
217 The only elements capable of nesting other elements are those with
218 next-lint scope as documented in
221 The following example reads lines from stdin and parses them, operating
222 on the finished parse tree with
224 This example does not error-check nor free memory upon failure.
225 .Bd -literal -offset indent
228 struct man_node *node;
233 bzero(®s, sizeof(struct regset));
235 man = man_alloc(®s, NULL, NULL);
239 while ((len = getline(&buf, &alloc_len, stdin)) >= 0) {
240 if (len && buflen[len - 1] = '\en')
241 buf[len - 1] = '\e0';
242 if ( ! man_parseln(man, line, buf))
243 errx(1, "man_parseln");
249 if ( ! man_endparse(man))
250 errx(1, "man_endparse");
251 if (NULL == (node = man_node(man)))
258 To compile this, execute
260 .Dl % cc main.c libman.a libmandoc.a
271 library was written by
272 .An Kristaps Dzonsons Aq kristaps@bsd.lv .