9c22c3364099b135535f8a91ebde7528aece03f1
[dragonfly.git] / contrib / mdocml / mdoc.h
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  */
23 enum    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  */
152 enum    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  */
186 enum    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  */
201 enum    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  */
230 struct  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  */
243 struct  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  */
256 struct  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  */
266 enum    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  */
275 enum    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  */
294 enum    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  */
306 enum    mdoc_auth {
307         AUTH__NONE = 0,
308         AUTH_split,
309         AUTH_nosplit
310 };
311
312 /*
313  * Normalised `Bf' font type.
314  */
315 enum    mdoc_font {
316         FONT__NONE = 0,
317         FONT_Em,
318         FONT_Li,
319         FONT_Sy
320 };
321
322 /*
323  * Normalised arguments for `Bd'.
324  */
325 struct  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  */
334 struct  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  */
346 struct  mdoc_bf {
347         enum mdoc_font    font; /* font */
348 };
349
350 /*
351  * Normalised arguments for `An'.
352  */
353 struct  mdoc_an {
354         enum mdoc_auth    auth; /* -split, etc. */
355 };
356
357 struct  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  */
366 union   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  */
377 struct  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  */
411 extern  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  */
418 extern  const char *const *mdoc_argnames;
419
420 __BEGIN_DECLS
421
422 struct  mdoc;
423
424 void              mdoc_free(struct mdoc *);
425 struct  mdoc     *mdoc_alloc(struct regset *, void *, mandocmsg);
426 void              mdoc_reset(struct mdoc *);
427 int               mdoc_parseln(struct mdoc *, int, char *, int);
428 const struct mdoc_node *mdoc_node(const struct mdoc *);
429 const struct mdoc_meta *mdoc_meta(const struct mdoc *);
430 int               mdoc_endparse(struct mdoc *);
431 int               mdoc_addspan(struct mdoc *,
432                         const struct tbl_span *);
433
434 __END_DECLS
435
436 #endif /*!MDOC_H*/