mdoc.h

   1 /*      $Id: mdoc.h,v 1.102 2010/07/21 09:08:26 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  * 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 enum    mdocargt {
 159         MDOC_Split,
 160         MDOC_Nosplit,
 161         MDOC_Ragged,
 162         MDOC_Unfilled,
 163         MDOC_Literal,
 164         MDOC_File,
 165         MDOC_Offset,
 166         MDOC_Bullet,
 167         MDOC_Dash,
 168         MDOC_Hyphen,
 169         MDOC_Item,
 170         MDOC_Enum,
 171         MDOC_Tag,
 172         MDOC_Diag,
 173         MDOC_Hang,
 174         MDOC_Ohang,
 175         MDOC_Inset,
 176         MDOC_Column,
 177         MDOC_Width,
 178         MDOC_Compact,
 179         MDOC_Std,
 180         MDOC_Filled,
 181         MDOC_Words,
 182         MDOC_Emphasis,
 183         MDOC_Symbolic,
 184         MDOC_Nested,
 185         MDOC_Centred,
 186         MDOC_ARG_MAX
 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_NONE,               /* 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 /* Information from prologue. */
 228 struct  mdoc_meta {
 229         char             *msec;
 230         char             *vol;
 231         char             *arch;
 232         time_t            date;
 233         char             *title;
 234         char             *os;
 235         char             *name;
 236 };
 237
 238 /* An argument to a macro (multiple values = `It -column'). */
 239 struct  mdoc_argv {
 240         enum mdocargt     arg;
 241         int               line;
 242         int               pos;
 243         size_t            sz;
 244         char            **value;
 245 };
 246
 247 struct  mdoc_arg {
 248         size_t            argc;
 249         struct mdoc_argv *argv;
 250         unsigned int      refcnt;
 251 };
 252
 253 enum    mdoc_endbody {
 254         ENDBODY_NOT = 0,
 255         ENDBODY_SPACE,
 256         ENDBODY_NOSPACE
 257 };
 258
 259 enum    mdoc_list {
 260         LIST__NONE = 0,
 261         LIST_bullet,
 262         LIST_column,
 263         LIST_dash,
 264         LIST_diag,
 265         LIST_enum,
 266         LIST_hang,
 267         LIST_hyphen,
 268         LIST_inset,
 269         LIST_item,
 270         LIST_ohang,
 271         LIST_tag
 272 };
 273
 274 enum    mdoc_disp {
 275         DISP__NONE = 0,
 276         DISP_centred,
 277         DISP_ragged,
 278         DISP_unfilled,
 279         DISP_filled,
 280         DISP_literal
 281 };
 282
 283 enum    mdoc_auth {
 284         AUTH__NONE = 0,
 285         AUTH_split,
 286         AUTH_nosplit
 287 };
 288
 289 enum    mdoc_font {
 290         FONT__NONE = 0,
 291         FONT_Em,
 292         FONT_Li,
 293         FONT_Sy
 294 };
 295
 296 struct  mdoc_bd {
 297         const char       *offs; /* -offset */
 298         enum mdoc_disp    type; /* -ragged, etc. */
 299         int               comp; /* -compact */
 300 };
 301
 302 struct  mdoc_bl {
 303         const char       *width; /* -width */
 304         const char       *offs; /* -offset */
 305         enum mdoc_list    type; /* -tag, -enum, etc. */
 306         int               comp; /* -compact */
 307         size_t            ncols; /* -column arg count */
 308         const char      **cols; /* -column val ptr */
 309 };
 310
 311 struct  mdoc_bf {
 312         enum mdoc_font    font; /* font */
 313 };
 314
 315 struct  mdoc_an {
 316         enum mdoc_auth    auth; /* -split, etc. */
 317 };
 318
 319 /* Node in AST. */
 320 struct  mdoc_node {
 321         struct mdoc_node *parent; /* parent AST node */
 322         struct mdoc_node *child; /* first child AST node */
 323         struct mdoc_node *next; /* sibling AST node */
 324         struct mdoc_node *prev; /* prior sibling AST node */
 325         int               nchild; /* number children */
 326         int               line; /* parse line */
 327         int               pos; /* parse column */
 328         enum mdoct        tok; /* tok or MDOC__MAX if none */
 329         int               flags;
 330 #define MDOC_VALID       (1 << 0) /* has been validated */
 331 #define MDOC_ACTED       (1 << 1) /* has been acted upon */
 332 #define MDOC_EOS         (1 << 2) /* at sentence boundary */
 333 #define MDOC_LINE        (1 << 3) /* first macro/text on line */
 334 #define MDOC_SYNPRETTY   (1 << 4) /* SYNOPSIS-style formatting */
 335 #define MDOC_ENDED       (1 << 5) /* rendering has been ended */
 336         enum mdoc_type    type; /* AST node type */
 337         enum mdoc_sec     sec; /* current named section */
 338         /* FIXME: these can be union'd to shave a few bytes. */
 339         struct mdoc_arg  *args;         /* BLOCK/ELEM */
 340         struct mdoc_node *pending;      /* BLOCK */
 341         struct mdoc_node *head;         /* BLOCK */
 342         struct mdoc_node *body;         /* BLOCK */
 343         struct mdoc_node *tail;         /* BLOCK */
 344         char             *string;       /* TEXT */
 345         enum mdoc_endbody end;          /* BODY */
 346
 347         union {
 348                 struct mdoc_an  An;
 349                 struct mdoc_bd *Bd;
 350                 struct mdoc_bf *Bf;
 351                 struct mdoc_bl *Bl;
 352         } data;
 353 };
 354
 355 #define MDOC_IGN_SCOPE   (1 << 0) /* Ignore scope violations. */
 356 #define MDOC_IGN_ESCAPE  (1 << 1) /* Ignore bad escape sequences. */
 357 #define MDOC_IGN_MACRO   (1 << 2) /* Ignore unknown macros. */
 358
 359 /* See mdoc.3 for documentation. */
 360
 361 extern  const char *const *mdoc_macronames;
 362 extern  const char *const *mdoc_argnames;
 363
 364 __BEGIN_DECLS
 365
 366 struct  mdoc;
 367
 368 /* See mdoc.3 for documentation. */
 369
 370 void              mdoc_free(struct mdoc *);
 371 struct  mdoc     *mdoc_alloc(struct regset *, void *, int, mandocmsg);
 372 void              mdoc_reset(struct mdoc *);
 373 int               mdoc_parseln(struct mdoc *, int, char *, int);
 374 const struct mdoc_node *mdoc_node(const struct mdoc *);
 375 const struct mdoc_meta *mdoc_meta(const struct mdoc *);
 376 int               mdoc_endparse(struct mdoc *);
 377
 378 __END_DECLS
 379
 380 #endif /*!MDOC_H*/