mdoc.h

   1 /*      $Id: mdoc.h,v 1.57 2009/06/10 20:18:43 kristaps 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 #include <time.h>
  21
  22 /*
  23  * This library implements a validating scanner/parser for ``mdoc'' roff
  24  * macro documents, a.k.a. BSD manual page documents.  The mdoc.c file
  25  * drives the parser, while macro.c describes the macro ontologies.
  26  * validate.c pre- and post-validates parsed macros, and action.c
  27  * performs actions on parsed and validated macros.
  28  */
  29
  30 /* What follows is a list of ALL possible macros. */
  31
  32 #define MDOC___          0
  33 #define MDOC_Dd          1
  34 #define MDOC_Dt          2
  35 #define MDOC_Os          3
  36 #define MDOC_Sh          4
  37 #define MDOC_Ss          5
  38 #define MDOC_Pp          6
  39 #define MDOC_D1          7
  40 #define MDOC_Dl          8
  41 #define MDOC_Bd          9
  42 #define MDOC_Ed          10
  43 #define MDOC_Bl          11
  44 #define MDOC_El          12
  45 #define MDOC_It          13
  46 #define MDOC_Ad          14
  47 #define MDOC_An          15
  48 #define MDOC_Ar          16
  49 #define MDOC_Cd          17
  50 #define MDOC_Cm          18
  51 #define MDOC_Dv          19
  52 #define MDOC_Er          20
  53 #define MDOC_Ev          21
  54 #define MDOC_Ex          22
  55 #define MDOC_Fa          23
  56 #define MDOC_Fd          24
  57 #define MDOC_Fl          25
  58 #define MDOC_Fn          26
  59 #define MDOC_Ft          27
  60 #define MDOC_Ic          28
  61 #define MDOC_In          29
  62 #define MDOC_Li          30
  63 #define MDOC_Nd          31
  64 #define MDOC_Nm          32
  65 #define MDOC_Op          33
  66 #define MDOC_Ot          34
  67 #define MDOC_Pa          35
  68 #define MDOC_Rv          36
  69 #define MDOC_St          37
  70 #define MDOC_Va          38
  71 #define MDOC_Vt          39
  72 #define MDOC_Xr          40
  73 #define MDOC__A          41
  74 #define MDOC__B          42
  75 #define MDOC__D          43
  76 #define MDOC__I          44
  77 #define MDOC__J          45
  78 #define MDOC__N          46
  79 #define MDOC__O          47
  80 #define MDOC__P          48
  81 #define MDOC__R          49
  82 #define MDOC__T          50
  83 #define MDOC__V          51
  84 #define MDOC_Ac          52
  85 #define MDOC_Ao          53
  86 #define MDOC_Aq          54
  87 #define MDOC_At          55
  88 #define MDOC_Bc          56
  89 #define MDOC_Bf          57
  90 #define MDOC_Bo          58
  91 #define MDOC_Bq          59
  92 #define MDOC_Bsx         60
  93 #define MDOC_Bx          61
  94 #define MDOC_Db          62
  95 #define MDOC_Dc          63
  96 #define MDOC_Do          64
  97 #define MDOC_Dq          65
  98 #define MDOC_Ec          66
  99 #define MDOC_Ef          67
 100 #define MDOC_Em          68
 101 #define MDOC_Eo          69
 102 #define MDOC_Fx          70
 103 #define MDOC_Ms          71
 104 #define MDOC_No          72
 105 #define MDOC_Ns          73
 106 #define MDOC_Nx          74
 107 #define MDOC_Ox          75
 108 #define MDOC_Pc          76
 109 #define MDOC_Pf          77
 110 #define MDOC_Po          78
 111 #define MDOC_Pq          79
 112 #define MDOC_Qc          80
 113 #define MDOC_Ql          81
 114 #define MDOC_Qo          82
 115 #define MDOC_Qq          83
 116 #define MDOC_Re          84
 117 #define MDOC_Rs          85
 118 #define MDOC_Sc          86
 119 #define MDOC_So          87
 120 #define MDOC_Sq          88
 121 #define MDOC_Sm          89
 122 #define MDOC_Sx          90
 123 #define MDOC_Sy          91
 124 #define MDOC_Tn          92
 125 #define MDOC_Ux          93
 126 #define MDOC_Xc          94
 127 #define MDOC_Xo          95
 128 #define MDOC_Fo          96
 129 #define MDOC_Fc          97
 130 #define MDOC_Oo          98
 131 #define MDOC_Oc          99
 132 #define MDOC_Bk          100
 133 #define MDOC_Ek          101
 134 #define MDOC_Bt          102
 135 #define MDOC_Hf          103
 136 #define MDOC_Fr          104
 137 #define MDOC_Ud          105
 138 #define MDOC_Lb          106
 139 #define MDOC_Ap          107
 140 #define MDOC_Lp          108
 141 #define MDOC_Lk          109
 142 #define MDOC_Mt          110
 143 #define MDOC_Brq         111
 144 #define MDOC_Bro         112
 145 #define MDOC_Brc         113
 146 #define MDOC__C          114
 147 #define MDOC_Es          115
 148 #define MDOC_En          116
 149 #define MDOC_Dx          117
 150 #define MDOC__Q          118
 151 #define MDOC_MAX         119
 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_ARG_MAX     26
 182
 183 /* Warnings are either syntax or groff-compatibility. */
 184 enum    mdoc_warn {
 185         WARN_SYNTAX,
 186         WARN_COMPAT
 187 };
 188
 189 /* Type of a syntax node. */
 190 enum    mdoc_type {
 191         MDOC_TEXT,
 192         MDOC_ELEM,
 193         MDOC_HEAD,
 194         MDOC_TAIL,
 195         MDOC_BODY,
 196         MDOC_BLOCK,
 197         MDOC_ROOT
 198 };
 199
 200 /* Section (named/unnamed) of `Sh'. */
 201 enum    mdoc_sec {
 202         SEC_PROLOGUE            = 0,
 203         SEC_BODY                = 1,
 204         SEC_NAME                = 2,
 205         SEC_LIBRARY             = 3,
 206         SEC_SYNOPSIS            = 4,
 207         SEC_DESCRIPTION         = 5,
 208         SEC_IMPLEMENTATION      = 6,
 209         SEC_RETURN_VALUES       = 7,
 210         SEC_ENVIRONMENT         = 8,
 211         SEC_FILES               = 9,
 212         SEC_EXAMPLES            = 10,
 213         SEC_DIAGNOSTICS         = 11,
 214         SEC_COMPATIBILITY       = 12,
 215         SEC_ERRORS              = 13,
 216         SEC_SEE_ALSO            = 14,
 217         SEC_STANDARDS           = 15,
 218         SEC_HISTORY             = 16,
 219         SEC_AUTHORS             = 17,
 220         SEC_CAVEATS             = 18,
 221         SEC_BUGS                = 19,
 222         SEC_CUSTOM
 223 };
 224
 225 /* Information from prologue. */
 226 struct  mdoc_meta {
 227         int               msec;
 228         char             *vol;
 229         char             *arch;
 230         time_t            date;
 231         char             *title;
 232         char             *os;
 233         char             *name;
 234 };
 235
 236 /* An argument to a macro (multiple values = `It -column'). */
 237 struct  mdoc_argv {
 238         int               arg;
 239         int               line;
 240         int               pos;
 241         size_t            sz;
 242         char            **value;
 243 };
 244
 245 struct  mdoc_arg {
 246         size_t            argc;
 247         struct mdoc_argv *argv;
 248         unsigned int      refcnt;
 249 };
 250
 251 /* Node in AST. */
 252 struct  mdoc_node {
 253         struct mdoc_node *parent;
 254         struct mdoc_node *child;
 255         struct mdoc_node *next;
 256         struct mdoc_node *prev;
 257         int               line;
 258         int               pos;
 259         int               tok;
 260         int               flags;
 261 #define MDOC_VALID       (1 << 0)
 262 #define MDOC_ACTED       (1 << 1)
 263         enum mdoc_type    type;
 264         enum mdoc_sec     sec;
 265
 266         /* FIXME: union/struct this with #defines. */
 267         struct mdoc_arg  *args;         /* BLOCK/ELEM */
 268         struct mdoc_node *head;         /* BLOCK */
 269         struct mdoc_node *body;         /* BLOCK */
 270         struct mdoc_node *tail;         /* BLOCK */
 271         char             *string;       /* TEXT */
 272 };
 273
 274 #define MDOC_IGN_SCOPE   (1 << 0) /* Ignore scope violations. */
 275 #define MDOC_IGN_ESCAPE  (1 << 1) /* Ignore bad escape sequences. */
 276 #define MDOC_IGN_MACRO   (1 << 2) /* Ignore unknown macros. */
 277 #define MDOC_IGN_CHARS   (1 << 3) /* Ignore disallowed chars. */
 278
 279 /* Call-backs for parse messages. */
 280 struct  mdoc_cb {
 281         void    (*mdoc_msg)(void *, int, int, const char *);
 282         int     (*mdoc_err)(void *, int, int, const char *);
 283         int     (*mdoc_warn)(void *, int, int,
 284                         enum mdoc_warn, const char *);
 285 };
 286
 287 /* Global table of macro names (`Bd', `Ed', etc.). */
 288 extern  const char *const *mdoc_macronames;
 289
 290 /* Global table of argument names (`column', `tag', etc.). */
 291 extern  const char *const *mdoc_argnames;
 292
 293 __BEGIN_DECLS
 294
 295 struct  mdoc;
 296
 297 /* Free memory allocated with mdoc_alloc. */
 298 void              mdoc_free(struct mdoc *);
 299
 300 /* Allocate a new parser instance. */
 301 struct  mdoc     *mdoc_alloc(void *, int, const struct mdoc_cb *);
 302
 303 /* Gets system ready for another parse. */
 304 int               mdoc_reset(struct mdoc *);
 305
 306 /* Parse a single line in a stream (boolean retval). */
 307 int               mdoc_parseln(struct mdoc *, int, char *buf);
 308
 309 /* Get result first node (after mdoc_endparse!). */
 310 const struct mdoc_node *mdoc_node(const struct mdoc *);
 311
 312 /* Get result meta-information (after mdoc_endparse!). */
 313 const struct mdoc_meta *mdoc_meta(const struct mdoc *);
 314
 315 /* Signal end of parse sequence (boolean retval). */
 316 int               mdoc_endparse(struct mdoc *);
 317
 318 /* The following are utility functions. */
 319
 320 const char       *mdoc_a2att(const char *);
 321 const char       *mdoc_a2lib(const char *);
 322 const char       *mdoc_a2st(const char *);
 323
 324 __END_DECLS
 325
 326 #endif /*!MDOC_H*/