mdoc.h

   1 /*      $Id: mdoc.h,v 1.81 2010/05/17 22:11:42 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 /*
  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_MAX
 153 };
 154
 155 /* What follows is a list of ALL possible macro arguments. */
 156
 157 #define MDOC_Split       0
 158 #define MDOC_Nosplit     1
 159 #define MDOC_Ragged      2
 160 #define MDOC_Unfilled    3
 161 #define MDOC_Literal     4
 162 #define MDOC_File        5
 163 #define MDOC_Offset      6
 164 #define MDOC_Bullet      7
 165 #define MDOC_Dash        8
 166 #define MDOC_Hyphen      9
 167 #define MDOC_Item        10
 168 #define MDOC_Enum        11
 169 #define MDOC_Tag         12
 170 #define MDOC_Diag        13
 171 #define MDOC_Hang        14
 172 #define MDOC_Ohang       15
 173 #define MDOC_Inset       16
 174 #define MDOC_Column      17
 175 #define MDOC_Width       18
 176 #define MDOC_Compact     19
 177 #define MDOC_Std         20
 178 #define MDOC_Filled      21
 179 #define MDOC_Words       22
 180 #define MDOC_Emphasis    23
 181 #define MDOC_Symbolic    24
 182 #define MDOC_Nested      25
 183 #define MDOC_Centred     26
 184 #define MDOC_ARG_MAX     27
 185
 186 /* Type of a syntax node. */
 187 enum    mdoc_type {
 188         MDOC_TEXT,
 189         MDOC_ELEM,
 190         MDOC_HEAD,
 191         MDOC_TAIL,
 192         MDOC_BODY,
 193         MDOC_BLOCK,
 194         MDOC_ROOT
 195 };
 196
 197 /* Section (named/unnamed) of `Sh'. */
 198 enum    mdoc_sec {
 199         SEC_NONE,               /* No section, yet. */
 200         SEC_NAME,
 201         SEC_LIBRARY,
 202         SEC_SYNOPSIS,
 203         SEC_DESCRIPTION,
 204         SEC_IMPLEMENTATION,
 205         SEC_RETURN_VALUES,
 206         SEC_ENVIRONMENT,
 207         SEC_FILES,
 208         SEC_EXIT_STATUS,
 209         SEC_EXAMPLES,
 210         SEC_DIAGNOSTICS,
 211         SEC_COMPATIBILITY,
 212         SEC_ERRORS,
 213         SEC_SEE_ALSO,
 214         SEC_STANDARDS,
 215         SEC_HISTORY,
 216         SEC_AUTHORS,
 217         SEC_CAVEATS,
 218         SEC_BUGS,
 219         SEC_SECURITY,
 220         SEC_CUSTOM,             /* User-defined. */
 221         SEC__MAX
 222 };
 223
 224 /* Information from prologue. */
 225 struct  mdoc_meta {
 226         char             *msec;
 227         char             *vol;
 228         char             *arch;
 229         time_t            date;
 230         char             *title;
 231         char             *os;
 232         char             *name;
 233 };
 234
 235 /* An argument to a macro (multiple values = `It -column'). */
 236 struct  mdoc_argv {
 237         int               arg;
 238         int               line;
 239         int               pos;
 240         size_t            sz;
 241         char            **value;
 242 };
 243
 244 struct  mdoc_arg {
 245         size_t            argc;
 246         struct mdoc_argv *argv;
 247         unsigned int      refcnt;
 248 };
 249
 250 /* Node in AST. */
 251 struct  mdoc_node {
 252         struct mdoc_node *parent; /* parent AST node */
 253         struct mdoc_node *child; /* first child AST node */
 254         struct mdoc_node *next; /* sibling AST node */
 255         struct mdoc_node *prev; /* prior sibling AST node */
 256         int               nchild; /* number children */
 257         int               line; /* parse line */
 258         int               pos; /* parse column */
 259         enum mdoct        tok; /* tok or MDOC__MAX if none */
 260         int               flags;
 261 #define MDOC_VALID       (1 << 0) /* has been validated */
 262 #define MDOC_ACTED       (1 << 1) /* has been acted upon */
 263 #define MDOC_EOS         (1 << 2) /* at sentence boundary */
 264 #define MDOC_LINE        (1 << 3) /* first macro/text on line */
 265         enum mdoc_type    type; /* AST node type */
 266         enum mdoc_sec     sec; /* current named section */
 267         struct mdoc_arg  *args;         /* BLOCK/ELEM */
 268 #ifdef  UGLY
 269         struct mdoc_node *pending;      /* BLOCK */
 270 #endif
 271         struct mdoc_node *head;         /* BLOCK */
 272         struct mdoc_node *body;         /* BLOCK */
 273         struct mdoc_node *tail;         /* BLOCK */
 274         char             *string;       /* TEXT */
 275 };
 276
 277 #define MDOC_IGN_SCOPE   (1 << 0) /* Ignore scope violations. */
 278 #define MDOC_IGN_ESCAPE  (1 << 1) /* Ignore bad escape sequences. */
 279 #define MDOC_IGN_MACRO   (1 << 2) /* Ignore unknown macros. */
 280
 281 /* See mdoc.3 for documentation. */
 282
 283 extern  const char *const *mdoc_macronames;
 284 extern  const char *const *mdoc_argnames;
 285
 286 __BEGIN_DECLS
 287
 288 struct  mdoc;
 289
 290 /* See mdoc.3 for documentation. */
 291
 292 void              mdoc_free(struct mdoc *);
 293 struct  mdoc     *mdoc_alloc(void *, int, mandocmsg);
 294 void              mdoc_reset(struct mdoc *);
 295 int               mdoc_parseln(struct mdoc *, int, char *, int);
 296 const struct mdoc_node *mdoc_node(const struct mdoc *);
 297 const struct mdoc_meta *mdoc_meta(const struct mdoc *);
 298 int               mdoc_endparse(struct mdoc *);
 299
 300 __END_DECLS
 301
 302 #endif /*!MDOC_H*/