1126bf76484821b90aba9df985a96a1d54dfda47
[dragonfly.git] / usr.bin / mandoc / mdoc.h
1 /*      $Id: mdoc.h,v 1.15 2009/10/27 21:40:07 schwarze Exp $ */
2 /*
3  * Copyright (c) 2008, 2009 Kristaps Dzonsons <kristaps@kth.se>
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  * This library implements a validating scanner/parser for ``mdoc'' roff
22  * macro documents, a.k.a. BSD manual page documents.  The mdoc.c file
23  * drives the parser, while macro.c describes the macro ontologies.
24  * validate.c pre- and post-validates parsed macros, and action.c
25  * performs actions on parsed and validated macros.
26  */
27
28 /* What follows is a list of ALL possible macros. */
29
30 #define MDOC_Ap          0
31 #define MDOC_Dd          1
32 #define MDOC_Dt          2
33 #define MDOC_Os          3
34 #define MDOC_Sh          4
35 #define MDOC_Ss          5
36 #define MDOC_Pp          6
37 #define MDOC_D1          7
38 #define MDOC_Dl          8
39 #define MDOC_Bd          9
40 #define MDOC_Ed          10
41 #define MDOC_Bl          11
42 #define MDOC_El          12
43 #define MDOC_It          13
44 #define MDOC_Ad          14
45 #define MDOC_An          15
46 #define MDOC_Ar          16
47 #define MDOC_Cd          17
48 #define MDOC_Cm          18
49 #define MDOC_Dv          19
50 #define MDOC_Er          20
51 #define MDOC_Ev          21
52 #define MDOC_Ex          22
53 #define MDOC_Fa          23
54 #define MDOC_Fd          24
55 #define MDOC_Fl          25
56 #define MDOC_Fn          26
57 #define MDOC_Ft          27
58 #define MDOC_Ic          28
59 #define MDOC_In          29
60 #define MDOC_Li          30
61 #define MDOC_Nd          31
62 #define MDOC_Nm          32
63 #define MDOC_Op          33
64 #define MDOC_Ot          34
65 #define MDOC_Pa          35
66 #define MDOC_Rv          36
67 #define MDOC_St          37
68 #define MDOC_Va          38
69 #define MDOC_Vt          39
70 #define MDOC_Xr          40
71 #define MDOC__A          41
72 #define MDOC__B          42
73 #define MDOC__D          43
74 #define MDOC__I          44
75 #define MDOC__J          45
76 #define MDOC__N          46
77 #define MDOC__O          47
78 #define MDOC__P          48
79 #define MDOC__R          49
80 #define MDOC__T          50
81 #define MDOC__V          51
82 #define MDOC_Ac          52
83 #define MDOC_Ao          53
84 #define MDOC_Aq          54
85 #define MDOC_At          55
86 #define MDOC_Bc          56
87 #define MDOC_Bf          57
88 #define MDOC_Bo          58
89 #define MDOC_Bq          59
90 #define MDOC_Bsx         60
91 #define MDOC_Bx          61
92 #define MDOC_Db          62
93 #define MDOC_Dc          63
94 #define MDOC_Do          64
95 #define MDOC_Dq          65
96 #define MDOC_Ec          66
97 #define MDOC_Ef          67
98 #define MDOC_Em          68
99 #define MDOC_Eo          69
100 #define MDOC_Fx          70
101 #define MDOC_Ms          71
102 #define MDOC_No          72
103 #define MDOC_Ns          73
104 #define MDOC_Nx          74
105 #define MDOC_Ox          75
106 #define MDOC_Pc          76
107 #define MDOC_Pf          77
108 #define MDOC_Po          78
109 #define MDOC_Pq          79
110 #define MDOC_Qc          80
111 #define MDOC_Ql          81
112 #define MDOC_Qo          82
113 #define MDOC_Qq          83
114 #define MDOC_Re          84
115 #define MDOC_Rs          85
116 #define MDOC_Sc          86
117 #define MDOC_So          87
118 #define MDOC_Sq          88
119 #define MDOC_Sm          89
120 #define MDOC_Sx          90
121 #define MDOC_Sy          91
122 #define MDOC_Tn          92
123 #define MDOC_Ux          93
124 #define MDOC_Xc          94
125 #define MDOC_Xo          95
126 #define MDOC_Fo          96
127 #define MDOC_Fc          97
128 #define MDOC_Oo          98
129 #define MDOC_Oc          99
130 #define MDOC_Bk          100
131 #define MDOC_Ek          101
132 #define MDOC_Bt          102
133 #define MDOC_Hf          103
134 #define MDOC_Fr          104
135 #define MDOC_Ud          105
136 #define MDOC_Lb          106
137 #define MDOC_Lp          107
138 #define MDOC_Lk          108
139 #define MDOC_Mt          109
140 #define MDOC_Brq         110
141 #define MDOC_Bro         111
142 #define MDOC_Brc         112
143 #define MDOC__C          113
144 #define MDOC_Es          114
145 #define MDOC_En          115
146 #define MDOC_Dx          116
147 #define MDOC__Q          117
148 #define MDOC_br          118
149 #define MDOC_sp          119
150 #define MDOC__U          120
151 #define MDOC_MAX         121
152
153 /* What follows is a list of ALL possible macro arguments. */
154
155 #define MDOC_Split       0
156 #define MDOC_Nosplit     1
157 #define MDOC_Ragged      2
158 #define MDOC_Unfilled    3
159 #define MDOC_Literal     4
160 #define MDOC_File        5
161 #define MDOC_Offset      6
162 #define MDOC_Bullet      7
163 #define MDOC_Dash        8
164 #define MDOC_Hyphen      9
165 #define MDOC_Item        10
166 #define MDOC_Enum        11
167 #define MDOC_Tag         12
168 #define MDOC_Diag        13
169 #define MDOC_Hang        14
170 #define MDOC_Ohang       15
171 #define MDOC_Inset       16
172 #define MDOC_Column      17
173 #define MDOC_Width       18
174 #define MDOC_Compact     19
175 #define MDOC_Std         20
176 #define MDOC_Filled      21
177 #define MDOC_Words       22
178 #define MDOC_Emphasis    23
179 #define MDOC_Symbolic    24
180 #define MDOC_Nested      25
181 #define MDOC_Centred     26
182 #define MDOC_ARG_MAX     27
183
184 /* Type of a syntax node. */
185 enum    mdoc_type {
186         MDOC_TEXT,
187         MDOC_ELEM,
188         MDOC_HEAD,
189         MDOC_TAIL,
190         MDOC_BODY,
191         MDOC_BLOCK,
192         MDOC_ROOT
193 };
194
195 /* Section (named/unnamed) of `Sh'. */
196 enum    mdoc_sec {
197         SEC_NONE,               /* No section, yet. */
198         SEC_NAME,
199         SEC_LIBRARY,
200         SEC_SYNOPSIS,
201         SEC_DESCRIPTION,
202         SEC_IMPLEMENTATION,
203         SEC_EXIT_STATUS,
204         SEC_RETURN_VALUES,
205         SEC_ENVIRONMENT,
206         SEC_FILES,
207         SEC_EXAMPLES,
208         SEC_DIAGNOSTICS,
209         SEC_COMPATIBILITY,
210         SEC_ERRORS,
211         SEC_SEE_ALSO,
212         SEC_STANDARDS,
213         SEC_HISTORY,
214         SEC_AUTHORS,
215         SEC_CAVEATS,
216         SEC_BUGS,
217         SEC_SECURITY,
218         SEC_CUSTOM              /* User-defined. */
219 };
220
221 /* Information from prologue. */
222 struct  mdoc_meta {
223         int               msec;
224         char             *vol;
225         char             *arch;
226         time_t            date;
227         char             *title;
228         char             *os;
229         char             *name;
230 };
231
232 /* An argument to a macro (multiple values = `It -column'). */
233 struct  mdoc_argv {
234         int               arg;
235         int               line;
236         int               pos;
237         size_t            sz;
238         char            **value;
239 };
240
241 struct  mdoc_arg {
242         size_t            argc;
243         struct mdoc_argv *argv;
244         unsigned int      refcnt;
245 };
246
247 /* Node in AST. */
248 struct  mdoc_node {
249         struct mdoc_node *parent;
250         struct mdoc_node *child;
251         struct mdoc_node *next;
252         struct mdoc_node *prev;
253         int               nchild;
254         int               line;
255         int               pos;
256         int               tok;
257         int               flags;
258 #define MDOC_VALID       (1 << 0)
259 #define MDOC_ACTED       (1 << 1)
260         enum mdoc_type    type;
261         enum mdoc_sec     sec;
262
263         struct mdoc_arg  *args;         /* BLOCK/ELEM */
264         struct mdoc_node *head;         /* BLOCK */
265         struct mdoc_node *body;         /* BLOCK */
266         struct mdoc_node *tail;         /* BLOCK */
267         char             *string;       /* TEXT */
268 };
269
270 #define MDOC_IGN_SCOPE   (1 << 0) /* Ignore scope violations. */
271 #define MDOC_IGN_ESCAPE  (1 << 1) /* Ignore bad escape sequences. */
272 #define MDOC_IGN_MACRO   (1 << 2) /* Ignore unknown macros. */
273 #define MDOC_IGN_CHARS   (1 << 3) /* Ignore disallowed chars. */
274
275 /* Call-backs for parse messages. */
276
277 struct  mdoc_cb {
278         int     (*mdoc_err)(void *, int, int, const char *);
279         int     (*mdoc_warn)(void *, int, int, const char *);
280 };
281
282 /* See mdoc.3 for documentation. */
283
284 extern  const char *const *mdoc_macronames;
285 extern  const char *const *mdoc_argnames;
286
287 __BEGIN_DECLS
288
289 struct  mdoc;
290
291 /* See mdoc.3 for documentation. */
292
293 void              mdoc_free(struct mdoc *);
294 struct  mdoc     *mdoc_alloc(void *, int, const struct mdoc_cb *);
295 int               mdoc_reset(struct mdoc *);
296 int               mdoc_parseln(struct mdoc *, int, char *buf);
297 const struct mdoc_node *mdoc_node(const struct mdoc *);
298 const struct mdoc_meta *mdoc_meta(const struct mdoc *);
299 int               mdoc_endparse(struct mdoc *);
300
301 __END_DECLS
302
303 #endif /*!MDOC_H*/