mdoc.h

   1 /*      $Id: mdoc.h,v 1.90 2010/06/19 20:46:28 kristaps Exp $ */
   2 /*
   3  * Copyright (c) 2008, 2009 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  * 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 enum    mdoct {
  31         MDOC_Ap = 0,
  32         MDOC_Dd,
  33         MDOC_Dt,
  34         MDOC_Os,
  35         MDOC_Sh,
  36         MDOC_Ss,
  37         MDOC_Pp,
  38         MDOC_D1,
  39         MDOC_Dl,
  40         MDOC_Bd,
  41         MDOC_Ed,
  42         MDOC_Bl,
  43         MDOC_El,
  44         MDOC_It,
  45         MDOC_Ad,
  46         MDOC_An,
  47         MDOC_Ar,
  48         MDOC_Cd,
  49         MDOC_Cm,
  50         MDOC_Dv,
  51         MDOC_Er,
  52         MDOC_Ev,
  53         MDOC_Ex,
  54         MDOC_Fa,
  55         MDOC_Fd,
  56         MDOC_Fl,
  57         MDOC_Fn,
  58         MDOC_Ft,
  59         MDOC_Ic,
  60         MDOC_In,
  61         MDOC_Li,
  62         MDOC_Nd,
  63         MDOC_Nm,
  64         MDOC_Op,
  65         MDOC_Ot,
  66         MDOC_Pa,
  67         MDOC_Rv,
  68         MDOC_St,
  69         MDOC_Va,
  70         MDOC_Vt,
  71         MDOC_Xr,
  72         MDOC__A,
  73         MDOC__B,
  74         MDOC__D,
  75         MDOC__I,
  76         MDOC__J,
  77         MDOC__N,
  78         MDOC__O,
  79         MDOC__P,
  80         MDOC__R,
  81         MDOC__T,
  82         MDOC__V,
  83         MDOC_Ac,
  84         MDOC_Ao,
  85         MDOC_Aq,
  86         MDOC_At,
  87         MDOC_Bc,
  88         MDOC_Bf,
  89         MDOC_Bo,
  90         MDOC_Bq,
  91         MDOC_Bsx,
  92         MDOC_Bx,
  93         MDOC_Db,
  94         MDOC_Dc,
  95         MDOC_Do,
  96         MDOC_Dq,
  97         MDOC_Ec,
  98         MDOC_Ef,
  99         MDOC_Em,
 100         MDOC_Eo,
 101         MDOC_Fx,
 102         MDOC_Ms,
 103         MDOC_No,
 104         MDOC_Ns,
 105         MDOC_Nx,
 106         MDOC_Ox,
 107         MDOC_Pc,
 108         MDOC_Pf,
 109         MDOC_Po,
 110         MDOC_Pq,
 111         MDOC_Qc,
 112         MDOC_Ql,
 113         MDOC_Qo,
 114         MDOC_Qq,
 115         MDOC_Re,
 116         MDOC_Rs,
 117         MDOC_Sc,
 118         MDOC_So,
 119         MDOC_Sq,
 120         MDOC_Sm,
 121         MDOC_Sx,
 122         MDOC_Sy,
 123         MDOC_Tn,
 124         MDOC_Ux,
 125         MDOC_Xc,
 126         MDOC_Xo,
 127         MDOC_Fo,
 128         MDOC_Fc,
 129         MDOC_Oo,
 130         MDOC_Oc,
 131         MDOC_Bk,
 132         MDOC_Ek,
 133         MDOC_Bt,
 134         MDOC_Hf,
 135         MDOC_Fr,
 136         MDOC_Ud,
 137         MDOC_Lb,
 138         MDOC_Lp,
 139         MDOC_Lk,
 140         MDOC_Mt,
 141         MDOC_Brq,
 142         MDOC_Bro,
 143         MDOC_Brc,
 144         MDOC__C,
 145         MDOC_Es,
 146         MDOC_En,
 147         MDOC_Dx,
 148         MDOC__Q,
 149         MDOC_br,
 150         MDOC_sp,
 151         MDOC__U,
 152         MDOC_Ta,
 153         MDOC_MAX
 154 };
 155
 156 /* What follows is a list of ALL possible macro arguments. */
 157
 158 #define MDOC_Split       0
 159 #define MDOC_Nosplit     1
 160 #define MDOC_Ragged      2
 161 #define MDOC_Unfilled    3
 162 #define MDOC_Literal     4
 163 #define MDOC_File        5
 164 #define MDOC_Offset      6
 165 #define MDOC_Bullet      7
 166 #define MDOC_Dash        8
 167 #define MDOC_Hyphen      9
 168 #define MDOC_Item        10
 169 #define MDOC_Enum        11
 170 #define MDOC_Tag         12
 171 #define MDOC_Diag        13
 172 #define MDOC_Hang        14
 173 #define MDOC_Ohang       15
 174 #define MDOC_Inset       16
 175 #define MDOC_Column      17
 176 #define MDOC_Width       18
 177 #define MDOC_Compact     19
 178 #define MDOC_Std         20
 179 #define MDOC_Filled      21
 180 #define MDOC_Words       22
 181 #define MDOC_Emphasis    23
 182 #define MDOC_Symbolic    24
 183 #define MDOC_Nested      25
 184 #define MDOC_Centred     26
 185 #define MDOC_ARG_MAX     27
 186
 187 /* Type of a syntax node. */
 188 enum    mdoc_type {
 189         MDOC_TEXT,
 190         MDOC_ELEM,
 191         MDOC_HEAD,
 192         MDOC_TAIL,
 193         MDOC_BODY,
 194         MDOC_BLOCK,
 195         MDOC_ROOT
 196 };
 197
 198 /* Section (named/unnamed) of `Sh'. */
 199 enum    mdoc_sec {
 200         SEC_NONE,               /* No section, yet. */
 201         SEC_NAME,
 202         SEC_LIBRARY,
 203         SEC_SYNOPSIS,
 204         SEC_DESCRIPTION,
 205         SEC_IMPLEMENTATION,
 206         SEC_RETURN_VALUES,
 207         SEC_ENVIRONMENT,
 208         SEC_FILES,
 209         SEC_EXIT_STATUS,
 210         SEC_EXAMPLES,
 211         SEC_DIAGNOSTICS,
 212         SEC_COMPATIBILITY,
 213         SEC_ERRORS,
 214         SEC_SEE_ALSO,
 215         SEC_STANDARDS,
 216         SEC_HISTORY,
 217         SEC_AUTHORS,
 218         SEC_CAVEATS,
 219         SEC_BUGS,
 220         SEC_SECURITY,
 221         SEC_CUSTOM,             /* User-defined. */
 222         SEC__MAX
 223 };
 224
 225 /* Information from prologue. */
 226 struct  mdoc_meta {
 227         char             *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 enum    mdoc_list {
 252         LIST__NONE = 0,
 253         LIST_bullet,
 254         LIST_column,
 255         LIST_dash,
 256         LIST_diag,
 257         LIST_enum,
 258         LIST_hang,
 259         LIST_hyphen,
 260         LIST_inset,
 261         LIST_item,
 262         LIST_ohang,
 263         LIST_tag
 264 };
 265
 266 enum    mdoc_disp {
 267         DISP__NONE = 0,
 268         DISP_centred,
 269         DISP_ragged,
 270         DISP_unfilled,
 271         DISP_filled,
 272         DISP_literal
 273 };
 274
 275 struct  mdoc_bd {
 276         const char       *offs; /* -offset */
 277         enum mdoc_disp    type; /* -ragged, etc. */
 278         int               comp; /* -compact */
 279 };
 280
 281 struct  mdoc_bl {
 282         const char       *width; /* -width */
 283         const char       *offs; /* -offset */
 284         enum mdoc_list    type; /* -tag, -enum, etc. */
 285         int               comp; /* -compact */
 286 };
 287
 288 /* Node in AST. */
 289 struct  mdoc_node {
 290         struct mdoc_node *parent; /* parent AST node */
 291         struct mdoc_node *child; /* first child AST node */
 292         struct mdoc_node *next; /* sibling AST node */
 293         struct mdoc_node *prev; /* prior sibling AST node */
 294         int               nchild; /* number children */
 295         int               line; /* parse line */
 296         int               pos; /* parse column */
 297         enum mdoct        tok; /* tok or MDOC__MAX if none */
 298         int               flags;
 299 #define MDOC_VALID       (1 << 0) /* has been validated */
 300 #define MDOC_ACTED       (1 << 1) /* has been acted upon */
 301 #define MDOC_EOS         (1 << 2) /* at sentence boundary */
 302 #define MDOC_LINE        (1 << 3) /* first macro/text on line */
 303         enum mdoc_type    type; /* AST node type */
 304         enum mdoc_sec     sec; /* current named section */
 305         struct mdoc_arg  *args;         /* BLOCK/ELEM */
 306 #ifdef  UGLY
 307         struct mdoc_node *pending;      /* BLOCK */
 308 #endif
 309         struct mdoc_node *head;         /* BLOCK */
 310         struct mdoc_node *body;         /* BLOCK */
 311         struct mdoc_node *tail;         /* BLOCK */
 312         char             *string;       /* TEXT */
 313
 314         union {
 315                 struct mdoc_bl Bl;
 316                 struct mdoc_bd Bd;
 317         } data;
 318 };
 319
 320 #define MDOC_IGN_SCOPE   (1 << 0) /* Ignore scope violations. */
 321 #define MDOC_IGN_ESCAPE  (1 << 1) /* Ignore bad escape sequences. */
 322 #define MDOC_IGN_MACRO   (1 << 2) /* Ignore unknown macros. */
 323
 324 /* See mdoc.3 for documentation. */
 325
 326 extern  const char *const *mdoc_macronames;
 327 extern  const char *const *mdoc_argnames;
 328
 329 __BEGIN_DECLS
 330
 331 struct  mdoc;
 332
 333 /* See mdoc.3 for documentation. */
 334
 335 void              mdoc_free(struct mdoc *);
 336 struct  mdoc     *mdoc_alloc(void *, int, mandocmsg);
 337 void              mdoc_reset(struct mdoc *);
 338 int               mdoc_parseln(struct mdoc *, int, char *, int);
 339 const struct mdoc_node *mdoc_node(const struct mdoc *);
 340 const struct mdoc_meta *mdoc_meta(const struct mdoc *);
 341 int               mdoc_endparse(struct mdoc *);
 342
 343 __END_DECLS
 344
 345 #endif /*!MDOC_H*/