Import mdocml-1.10.9
[dragonfly.git] / contrib / mdocml / mdoc.h
CommitLineData
80387638
SW
1/* $Id: mdoc.h,v 1.114 2011/01/01 12:18:37 kristaps Exp $ */
2/*
3 * Copyright (c) 2008, 2009, 2010 Kristaps Dzonsons <kristaps@bsd.lv>
4 *
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.
8 *
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.
16 */
17#ifndef MDOC_H
18#define MDOC_H
19
20/*
21 * What follows is a list of ALL possible macros.
22 */
23enum mdoct {
24 MDOC_Ap = 0,
25 MDOC_Dd,
26 MDOC_Dt,
27 MDOC_Os,
28 MDOC_Sh,
29 MDOC_Ss,
30 MDOC_Pp,
31 MDOC_D1,
32 MDOC_Dl,
33 MDOC_Bd,
34 MDOC_Ed,
35 MDOC_Bl,
36 MDOC_El,
37 MDOC_It,
38 MDOC_Ad,
39 MDOC_An,
40 MDOC_Ar,
41 MDOC_Cd,
42 MDOC_Cm,
43 MDOC_Dv,
44 MDOC_Er,
45 MDOC_Ev,
46 MDOC_Ex,
47 MDOC_Fa,
48 MDOC_Fd,
49 MDOC_Fl,
50 MDOC_Fn,
51 MDOC_Ft,
52 MDOC_Ic,
53 MDOC_In,
54 MDOC_Li,
55 MDOC_Nd,
56 MDOC_Nm,
57 MDOC_Op,
58 MDOC_Ot,
59 MDOC_Pa,
60 MDOC_Rv,
61 MDOC_St,
62 MDOC_Va,
63 MDOC_Vt,
64 MDOC_Xr,
65 MDOC__A,
66 MDOC__B,
67 MDOC__D,
68 MDOC__I,
69 MDOC__J,
70 MDOC__N,
71 MDOC__O,
72 MDOC__P,
73 MDOC__R,
74 MDOC__T,
75 MDOC__V,
76 MDOC_Ac,
77 MDOC_Ao,
78 MDOC_Aq,
79 MDOC_At,
80 MDOC_Bc,
81 MDOC_Bf,
82 MDOC_Bo,
83 MDOC_Bq,
84 MDOC_Bsx,
85 MDOC_Bx,
86 MDOC_Db,
87 MDOC_Dc,
88 MDOC_Do,
89 MDOC_Dq,
90 MDOC_Ec,
91 MDOC_Ef,
92 MDOC_Em,
93 MDOC_Eo,
94 MDOC_Fx,
95 MDOC_Ms,
96 MDOC_No,
97 MDOC_Ns,
98 MDOC_Nx,
99 MDOC_Ox,
100 MDOC_Pc,
101 MDOC_Pf,
102 MDOC_Po,
103 MDOC_Pq,
104 MDOC_Qc,
105 MDOC_Ql,
106 MDOC_Qo,
107 MDOC_Qq,
108 MDOC_Re,
109 MDOC_Rs,
110 MDOC_Sc,
111 MDOC_So,
112 MDOC_Sq,
113 MDOC_Sm,
114 MDOC_Sx,
115 MDOC_Sy,
116 MDOC_Tn,
117 MDOC_Ux,
118 MDOC_Xc,
119 MDOC_Xo,
120 MDOC_Fo,
121 MDOC_Fc,
122 MDOC_Oo,
123 MDOC_Oc,
124 MDOC_Bk,
125 MDOC_Ek,
126 MDOC_Bt,
127 MDOC_Hf,
128 MDOC_Fr,
129 MDOC_Ud,
130 MDOC_Lb,
131 MDOC_Lp,
132 MDOC_Lk,
133 MDOC_Mt,
134 MDOC_Brq,
135 MDOC_Bro,
136 MDOC_Brc,
137 MDOC__C,
138 MDOC_Es,
139 MDOC_En,
140 MDOC_Dx,
141 MDOC__Q,
142 MDOC_br,
143 MDOC_sp,
144 MDOC__U,
145 MDOC_Ta,
146 MDOC_MAX
147};
148
149/*
150 * What follows is a list of ALL possible macro arguments.
151 */
152enum mdocargt {
153 MDOC_Split,
154 MDOC_Nosplit,
155 MDOC_Ragged,
156 MDOC_Unfilled,
157 MDOC_Literal,
158 MDOC_File,
159 MDOC_Offset,
160 MDOC_Bullet,
161 MDOC_Dash,
162 MDOC_Hyphen,
163 MDOC_Item,
164 MDOC_Enum,
165 MDOC_Tag,
166 MDOC_Diag,
167 MDOC_Hang,
168 MDOC_Ohang,
169 MDOC_Inset,
170 MDOC_Column,
171 MDOC_Width,
172 MDOC_Compact,
173 MDOC_Std,
174 MDOC_Filled,
175 MDOC_Words,
176 MDOC_Emphasis,
177 MDOC_Symbolic,
178 MDOC_Nested,
179 MDOC_Centred,
180 MDOC_ARG_MAX
181};
182
183/*
184 * Type of a syntax node.
185 */
186enum mdoc_type {
187 MDOC_TEXT,
188 MDOC_ELEM,
189 MDOC_HEAD,
190 MDOC_TAIL,
191 MDOC_BODY,
192 MDOC_BLOCK,
193 MDOC_TBL,
194 MDOC_ROOT
195};
196
197/*
198 * Section (named/unnamed) of `Sh'. Note that these appear in the
199 * conventional order imposed by mdoc.7.
200 */
201enum mdoc_sec {
202 SEC_NONE = 0, /* No section, yet. */
203 SEC_NAME,
204 SEC_LIBRARY,
205 SEC_SYNOPSIS,
206 SEC_DESCRIPTION,
207 SEC_IMPLEMENTATION,
208 SEC_RETURN_VALUES,
209 SEC_ENVIRONMENT,
210 SEC_FILES,
211 SEC_EXIT_STATUS,
212 SEC_EXAMPLES,
213 SEC_DIAGNOSTICS,
214 SEC_COMPATIBILITY,
215 SEC_ERRORS,
216 SEC_SEE_ALSO,
217 SEC_STANDARDS,
218 SEC_HISTORY,
219 SEC_AUTHORS,
220 SEC_CAVEATS,
221 SEC_BUGS,
222 SEC_SECURITY,
223 SEC_CUSTOM, /* User-defined. */
224 SEC__MAX
225};
226
227/*
228 * Information from prologue.
229 */
230struct mdoc_meta {
231 char *msec; /* `Dt' section (1, 3p, etc.) */
232 char *vol; /* `Dt' volume (implied) */
233 char *arch; /* `Dt' arch (i386, etc.) */
234 time_t date; /* `Dd' normalised date */
235 char *title; /* `Dt' title (FOO, etc.) */
236 char *os; /* `Os' system (OpenBSD, etc.) */
237 char *name; /* leading `Nm' name */
238};
239
240/*
241 * An argument to a macro (multiple values = `-column xxx yyy').
242 */
243struct mdoc_argv {
244 enum mdocargt arg; /* type of argument */
245 int line;
246 int pos;
247 size_t sz; /* elements in "value" */
248 char **value; /* argument strings */
249};
250
251/*
252 * Reference-counted macro arguments. These are refcounted because
253 * blocks have multiple instances of the same arguments spread across
254 * the HEAD, BODY, TAIL, and BLOCK node types.
255 */
256struct mdoc_arg {
257 size_t argc;
258 struct mdoc_argv *argv;
259 unsigned int refcnt;
260};
261
262/*
263 * Indicates that a BODY's formatting has ended, but the scope is still
264 * open. Used for syntax-broken blocks.
265 */
266enum mdoc_endbody {
267 ENDBODY_NOT = 0,
268 ENDBODY_SPACE, /* is broken: append a space */
269 ENDBODY_NOSPACE /* is broken: don't append a space */
270};
271
272/*
273 * Normalised `Bl' list type.
274 */
275enum mdoc_list {
276 LIST__NONE = 0,
277 LIST_bullet,
278 LIST_column,
279 LIST_dash,
280 LIST_diag,
281 LIST_enum,
282 LIST_hang,
283 LIST_hyphen,
284 LIST_inset,
285 LIST_item,
286 LIST_ohang,
287 LIST_tag,
288 LIST_MAX
289};
290
291/*
292 * Normalised `Bd' display type.
293 */
294enum mdoc_disp {
295 DISP__NONE = 0,
296 DISP_centred,
297 DISP_ragged,
298 DISP_unfilled,
299 DISP_filled,
300 DISP_literal
301};
302
303/*
304 * Normalised `An' splitting argument.
305 */
306enum mdoc_auth {
307 AUTH__NONE = 0,
308 AUTH_split,
309 AUTH_nosplit
310};
311
312/*
313 * Normalised `Bf' font type.
314 */
315enum mdoc_font {
316 FONT__NONE = 0,
317 FONT_Em,
318 FONT_Li,
319 FONT_Sy
320};
321
322/*
323 * Normalised arguments for `Bd'.
324 */
325struct mdoc_bd {
326 const char *offs; /* -offset */
327 enum mdoc_disp type; /* -ragged, etc. */
328 int comp; /* -compact */
329};
330
331/*
332 * Normalised arguments for `Bl'.
333 */
334struct mdoc_bl {
335 const char *width; /* -width */
336 const char *offs; /* -offset */
337 enum mdoc_list type; /* -tag, -enum, etc. */
338 int comp; /* -compact */
339 size_t ncols; /* -column arg count */
340 const char **cols; /* -column val ptr */
341};
342
343/*
344 * Normalised arguments for `Bf'.
345 */
346struct mdoc_bf {
347 enum mdoc_font font; /* font */
348};
349
350/*
351 * Normalised arguments for `An'.
352 */
353struct mdoc_an {
354 enum mdoc_auth auth; /* -split, etc. */
355};
356
357struct mdoc_rs {
358 struct mdoc_node *child_J; /* pointer to %J */
359};
360
361/*
362 * Consists of normalised node arguments. These should be used instead
363 * of iterating through the mdoc_arg pointers of a node: defaults are
364 * provided, etc.
365 */
366union mdoc_data {
367 struct mdoc_an An;
368 struct mdoc_bd Bd;
369 struct mdoc_bf Bf;
370 struct mdoc_bl Bl;
371 struct mdoc_rs Rs;
372};
373
374/*
375 * Single node in tree-linked AST.
376 */
377struct mdoc_node {
378 struct mdoc_node *parent; /* parent AST node */
379 struct mdoc_node *child; /* first child AST node */
380 struct mdoc_node *last; /* last child AST node */
381 struct mdoc_node *next; /* sibling AST node */
382 struct mdoc_node *prev; /* prior sibling AST node */
383 int nchild; /* number children */
384 int line; /* parse line */
385 int pos; /* parse column */
386 enum mdoct tok; /* tok or MDOC__MAX if none */
387 int flags;
388#define MDOC_VALID (1 << 0) /* has been validated */
389#define MDOC_EOS (1 << 2) /* at sentence boundary */
390#define MDOC_LINE (1 << 3) /* first macro/text on line */
391#define MDOC_SYNPRETTY (1 << 4) /* SYNOPSIS-style formatting */
392#define MDOC_ENDED (1 << 5) /* rendering has been ended */
393 enum mdoc_type type; /* AST node type */
394 enum mdoc_sec sec; /* current named section */
395 union mdoc_data *norm; /* normalised args */
396 /* FIXME: these can be union'd to shave a few bytes. */
397 struct mdoc_arg *args; /* BLOCK/ELEM */
398 struct mdoc_node *pending; /* BLOCK */
399 struct mdoc_node *head; /* BLOCK */
400 struct mdoc_node *body; /* BLOCK */
401 struct mdoc_node *tail; /* BLOCK */
402 char *string; /* TEXT */
403 const struct tbl_span *span; /* TBL */
404 enum mdoc_endbody end; /* BODY */
405};
406
407/*
408 * Names of macros. Index is enum mdoct. Indexing into this returns
409 * the normalised name, e.g., mdoc_macronames[MDOC_Sh] -> "Sh".
410 */
411extern const char *const *mdoc_macronames;
412
413/*
414 * Names of macro args. Index is enum mdocargt. Indexing into this
415 * returns the normalised name, e.g., mdoc_argnames[MDOC_File] ->
416 * "file".
417 */
418extern const char *const *mdoc_argnames;
419
420__BEGIN_DECLS
421
422struct mdoc;
423
424void mdoc_free(struct mdoc *);
425struct mdoc *mdoc_alloc(struct regset *, void *, mandocmsg);
426void mdoc_reset(struct mdoc *);
427int mdoc_parseln(struct mdoc *, int, char *, int);
428const struct mdoc_node *mdoc_node(const struct mdoc *);
429const struct mdoc_meta *mdoc_meta(const struct mdoc *);
430int mdoc_endparse(struct mdoc *);
431int mdoc_addspan(struct mdoc *,
432 const struct tbl_span *);
433
434__END_DECLS
435
436#endif /*!MDOC_H*/