1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
|
.\"
.Dd $Mdocdate$
.Dt mdoc 3
.Os
.\"
.Sh NAME
.Nm mdoc_alloc ,
.Nm mdoc_parseln ,
.Nm mdoc_endparse ,
.Nm mdoc_node ,
.Nm mdoc_meta ,
.Nm mdoc_free
.Nd mdoc macro compiler library
.\"
.Sh SYNOPSIS
.Fd #include <mdoc.h>
.Vt extern const char * const * mdoc_macronames;
.Vt extern const char * const * mdoc_argnames;
.Ft "struct mdoc *"
.Fn mdoc_alloc "void *data" "const struct mdoc_cb *cb"
.Ft void
.Fn mdoc_free "struct mdoc *mdoc"
.Ft int
.Fn mdoc_parseln "struct mdoc *mdoc" "int line" "char *buf"
.Ft "const struct mdoc_node *"
.Fn mdoc_node "struct mdoc *mdoc"
.Ft "const struct mdoc_meta *"
.Fn mdoc_meta "struct mdoc *mdoc"
.Ft int
.Fn mdoc_endparse "struct mdoc *mdoc"
.\"
.Sh DESCRIPTION
The
.Nm mdoc
library parses lines of mdoc-macro text into an abstract syntax tree.
In general, applications initiate a parsing sequence with
.Fn mdoc_alloc ,
parse each line in a document with
.Fn mdoc_parseln ,
close the parsing session with
.Fn mdoc_endparse ,
operate over the syntax tree returned by
.Fn mdoc_node
and
.Fn mdoc_meta ,
then free all allocated memory with
.Fn mdoc_free .
See the
.Sx EXAMPLES
section for a full example.
.Pp
.\" Function descriptions.
Function descriptions follow:
.Bl -ohang -offset indent
.It Fn mdoc_alloc
Allocates a parsing structure. The
.Fa data
pointer is passed to callbacks in
.Fa cb ,
which are documented further in the header file. Returns NULL on
failure. If non-NULL, the pointer must be freed with
.Fn mdoc_free .
.It Fn mdoc_free
Free all resources of a parser. The pointer is no longer valid after
invocation.
.It Fn mdoc_parseln
Parse a nil-terminated line of input. This line should not contain the
trailing newline. Returns 0 on failure, 1 on success. The input buffer
.Fa buf
is modified by this function.
.It Fn mdoc_endparse
Signals that the parse is complete. Note that if
.Fn mdoc_endparse
is called subsequent to
.Fn mdoc_node ,
the resulting tree is incomplete. Returns 0 on failure, 1 on success.
.It Fn mdoc_node
Returns the first node of the parse. Note that if
.Fn mdoc_parseln
or
.Fn mdoc_endparse
return 0, the tree will be incomplete.
.It Fn mdoc_meta
Returns the document's parsed meta-data. If this information has not
yet been supplied or
.Fn mdoc_parseln
or
.Fn mdoc_endparse
return 0, the data will be incomplete.
.El
.Pp
.\" Variable descriptions.
The following variables are also defined:
.Bl -ohang -offset indent
.It Va mdoc_macronames
An array of string-ified token names.
.It Va mdoc_argnames
An array of string-ified token argument names.
.El
.Pp
.Nm
is
.Ud
.\"
.Sh EXAMPLES
The following example reads lines from stdin and parses them, operating
on the finished parse tree with
.Fn parsed .
Note that, if the last line of the file isn't newline-terminated, this
will truncate the file's last character (see
.Xr fgetln 3 ) .
Further, this example does not error-check nor free memory upon failure.
.Bd -literal
struct mdoc *mdoc;
struct mdoc_node *node;
char *buf;
size_t len;
int line;
line = 1;
mdoc = mdoc_alloc(NULL, NULL);
while ((buf = fgetln(fp, &len))) {
buf[len - 1] = '\\0';
if ( ! mdoc_parseln(mdoc, line, buf))
errx(1, "mdoc_parseln");
line++;
}
if ( ! mdoc_endparse(mdoc))
errx(1, "mdoc_endparse");
if (NULL == (node = mdoc_node(mdoc)))
errx(1, "mdoc_node");
parsed(mdoc, node);
mdoc_free(mdoc);
.Ed
.\"
.Sh SEE ALSO
.Xr mdoc 7 ,
.Xr mdoc.samples 7 ,
.Xr groff 1 ,
.Xr mdocml 1
.\"
.\"
.Sh AUTHORS
The
.Nm
utility was written by
.An Kristaps Dzonsons Aq kristaps@kth.se .
.\"
.\"
.Sh BUGS
Bugs, un-implemented macros and incompabilities are documented in this
section. The baseline for determining whether macro parsing is
.Qq incompatible
is the default
.Xr groff 1
system bundled with
.Ox .
.Pp
Un-implemented: the
.Sq \&Xc
and
.Sq \&Xo
macros aren't handled when used to span lines for the
.Sq \&It
macro. Such usage is specifically discouraged in
.Xr mdoc.samples 7 .
.Pp
Bugs: when
.Sq \&It \-column
is invoked, whitespace is not stripped around
.Sq \&Ta
or tab-character separators.
.Pp
Incompatible: the
.Sq \&At
macro only accepts a single parameter. Furthermore, several macros
.Pf ( Sq \&Pp ,
.Sq \&It ,
and possibly others) accept multiple arguments with a warning.
.Pp
Incompatible: only those macros specified by
.Xr mdoc.samples 7
and
.Xr mdoc 7
for
.Ox
are supported; support for
.Nx
and other BSD systems is in progress.
|
