mdoc.h

   1 /*      $Id: mdoc.h,v 1.96 2010/07/01 22:56:17 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 /* FIXME: make this into an enum. */
 159 #define MDOC_Split       0
 160 #define MDOC_Nosplit     1
 161 #define MDOC_Ragged      2
 162 #define MDOC_Unfilled    3
 163 #define MDOC_Literal     4
 164 #define MDOC_File        5
 165 #define MDOC_Offset      6
 166 #define MDOC_Bullet      7
 167 #define MDOC_Dash        8
 168 #define MDOC_Hyphen      9
 169 #define MDOC_Item        10
 170 #define MDOC_Enum        11
 171 #define MDOC_Tag         12
 172 #define MDOC_Diag        13
 173 #define MDOC_Hang        14
 174 #define MDOC_Ohang       15
 175 #define MDOC_Inset       16
 176 #define MDOC_Column      17
 177 #define MDOC_Width       18
 178 #define MDOC_Compact     19
 179 #define MDOC_Std         20
 180 #define MDOC_Filled      21
 181 #define MDOC_Words       22
 182 #define MDOC_Emphasis    23
 183 #define MDOC_Symbolic    24
 184 #define MDOC_Nested      25
 185 #define MDOC_Centred     26
 186 #define MDOC_ARG_MAX     27
 187
 188 /* Type of a syntax node. */
 189 enum    mdoc_type {
 190         MDOC_TEXT,
 191         MDOC_ELEM,
 192         MDOC_HEAD,
 193         MDOC_TAIL,
 194         MDOC_BODY,
 195         MDOC_BLOCK,
 196         MDOC_ROOT
 197 };
 198
 199 /* Section (named/unnamed) of `Sh'. */
 200 enum    mdoc_sec {
 201         SEC_NONE,               /* No section, yet. */
 202         SEC_NAME,
 203         SEC_LIBRARY,
 204         SEC_SYNOPSIS,
 205         SEC_DESCRIPTION,
 206         SEC_IMPLEMENTATION,
 207         SEC_RETURN_VALUES,
 208         SEC_ENVIRONMENT,
 209         SEC_FILES,
 210         SEC_EXIT_STATUS,
 211         SEC_EXAMPLES,
 212         SEC_DIAGNOSTICS,
 213         SEC_COMPATIBILITY,
 214         SEC_ERRORS,
 215         SEC_SEE_ALSO,
 216         SEC_STANDARDS,
 217         SEC_HISTORY,
 218         SEC_AUTHORS,
 219         SEC_CAVEATS,
 220         SEC_BUGS,
 221         SEC_SECURITY,
 222         SEC_CUSTOM,             /* User-defined. */
 223         SEC__MAX
 224 };
 225
 226 /* Information from prologue. */
 227 struct  mdoc_meta {
 228         char             *msec;
 229         char             *vol;
 230         char             *arch;
 231         time_t            date;
 232         char             *title;
 233         char             *os;
 234         char             *name;
 235 };
 236
 237 /* An argument to a macro (multiple values = `It -column'). */
 238 struct  mdoc_argv {
 239         int               arg;
 240         int               line;
 241         int               pos;
 242         size_t            sz;
 243         char            **value;
 244 };
 245
 246 struct  mdoc_arg {
 247         size_t            argc;
 248         struct mdoc_argv *argv;
 249         unsigned int      refcnt;
 250 };
 251
 252 enum    mdoc_endbody {
 253         ENDBODY_NOT = 0,
 254         ENDBODY_SPACE,
 255         ENDBODY_NOSPACE,
 256 };
 257
 258 enum    mdoc_list {
 259         LIST__NONE = 0,
 260         LIST_bullet,
 261         LIST_column,
 262         LIST_dash,
 263         LIST_diag,
 264         LIST_enum,
 265         LIST_hang,
 266         LIST_hyphen,
 267         LIST_inset,
 268         LIST_item,
 269         LIST_ohang,
 270         LIST_tag
 271 };
 272
 273 enum    mdoc_disp {
 274         DISP__NONE = 0,
 275         DISP_centred,
 276         DISP_ragged,
 277         DISP_unfilled,
 278         DISP_filled,
 279         DISP_literal
 280 };
 281
 282 struct  mdoc_bd {
 283         const char       *offs; /* -offset */
 284         enum mdoc_disp    type; /* -ragged, etc. */
 285         int               comp; /* -compact */
 286 };
 287
 288 struct  mdoc_bl {
 289         const char       *width; /* -width */
 290         const char       *offs; /* -offset */
 291         enum mdoc_list    type; /* -tag, -enum, etc. */
 292         int               comp; /* -compact */
 293 };
 294
 295 /* Node in AST. */
 296 struct  mdoc_node {
 297         struct mdoc_node *parent; /* parent AST node */
 298         struct mdoc_node *child; /* first child AST node */
 299         struct mdoc_node *next; /* sibling AST node */
 300         struct mdoc_node *prev; /* prior sibling AST node */
 301         int               nchild; /* number children */
 302         int               line; /* parse line */
 303         int               pos; /* parse column */
 304         enum mdoct        tok; /* tok or MDOC__MAX if none */
 305         int               flags;
 306 #define MDOC_VALID       (1 << 0) /* has been validated */
 307 #define MDOC_ACTED       (1 << 1) /* has been acted upon */
 308 #define MDOC_EOS         (1 << 2) /* at sentence boundary */
 309 #define MDOC_LINE        (1 << 3) /* first macro/text on line */
 310 #define MDOC_SYNPRETTY   (1 << 4) /* SYNOPSIS-style formatting */
 311 #define MDOC_ENDED       (1 << 5) /* rendering has been ended */
 312         enum mdoc_type    type; /* AST node type */
 313         enum mdoc_sec     sec; /* current named section */
 314         /* FIXME: these can be union'd to shave a few bytes. */
 315         struct mdoc_arg  *args;         /* BLOCK/ELEM */
 316         struct mdoc_node *pending;      /* BLOCK */
 317         struct mdoc_node *head;         /* BLOCK */
 318         struct mdoc_node *body;         /* BLOCK */
 319         struct mdoc_node *tail;         /* BLOCK */
 320         char             *string;       /* TEXT */
 321         enum mdoc_endbody end;          /* BODY */
 322
 323         union {
 324                 struct mdoc_bl *Bl;
 325                 struct mdoc_bd *Bd;
 326         } data;
 327 };
 328
 329 #define MDOC_IGN_SCOPE   (1 << 0) /* Ignore scope violations. */
 330 #define MDOC_IGN_ESCAPE  (1 << 1) /* Ignore bad escape sequences. */
 331 #define MDOC_IGN_MACRO   (1 << 2) /* Ignore unknown macros. */
 332
 333 /* See mdoc.3 for documentation. */
 334
 335 extern  const char *const *mdoc_macronames;
 336 extern  const char *const *mdoc_argnames;
 337
 338 __BEGIN_DECLS
 339
 340 struct  mdoc;
 341
 342 /* See mdoc.3 for documentation. */
 343
 344 void              mdoc_free(struct mdoc *);
 345 struct  mdoc     *mdoc_alloc(struct regset *, void *, int, mandocmsg);
 346 void              mdoc_reset(struct mdoc *);
 347 int               mdoc_parseln(struct mdoc *, int, char *, int);
 348 const struct mdoc_node *mdoc_node(const struct mdoc *);
 349 const struct mdoc_meta *mdoc_meta(const struct mdoc *);
 350 int               mdoc_endparse(struct mdoc *);
 351
 352 __END_DECLS
 353
 354 #endif /*!MDOC_H*/