mdoc.h

   1 /* $Id: mdoc.h,v 1.36 2009/03/02 12:09:32 kristaps Exp $ */
   2 /*
   3  * Copyright (c) 2008 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
   7  * above copyright notice and this permission notice appear in all
   8  * copies.
   9  *
  10  * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL
  11  * WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED
  12  * WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE
  13  * AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL
  14  * DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR
  15  * PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
  16  * TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
  17  * PERFORMANCE OF THIS SOFTWARE.
  18  */
  19 #ifndef MDOC_H
  20 #define MDOC_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_MAX         106
 139
 140 /* What follows is a list of ALL possible macro arguments. */
 141
 142 #define MDOC_Split       0
 143 #define MDOC_Nosplit     1
 144 #define MDOC_Ragged      2
 145 #define MDOC_Unfilled    3
 146 #define MDOC_Literal     4
 147 #define MDOC_File        5
 148 #define MDOC_Offset      6
 149 #define MDOC_Bullet      7
 150 #define MDOC_Dash        8
 151 #define MDOC_Hyphen      9
 152 #define MDOC_Item        10
 153 #define MDOC_Enum        11
 154 #define MDOC_Tag         12
 155 #define MDOC_Diag        13
 156 #define MDOC_Hang        14
 157 #define MDOC_Ohang       15
 158 #define MDOC_Inset       16
 159 #define MDOC_Column      17
 160 #define MDOC_Width       18
 161 #define MDOC_Compact     19
 162 #define MDOC_Std         20
 163 #define MDOC_p1003_1_88  21
 164 #define MDOC_p1003_1_90  22
 165 #define MDOC_p1003_1_96  23
 166 #define MDOC_p1003_1_2001 24
 167 #define MDOC_p1003_1_2004 25
 168 #define MDOC_p1003_1     26
 169 #define MDOC_p1003_1b    27
 170 #define MDOC_p1003_1b_93 28
 171 #define MDOC_p1003_1c_95 29
 172 #define MDOC_p1003_1g_2000 30
 173 #define MDOC_p1003_2_92  31
 174 #define MDOC_p1387_2_95  32
 175 #define MDOC_p1003_2     33
 176 #define MDOC_p1387_2     34
 177 #define MDOC_isoC_90     35
 178 #define MDOC_isoC_amd1   36
 179 #define MDOC_isoC_tcor1  37
 180 #define MDOC_isoC_tcor2  38
 181 #define MDOC_isoC_99     39
 182 #define MDOC_ansiC       40
 183 #define MDOC_ansiC_89    41
 184 #define MDOC_ansiC_99    42
 185 #define MDOC_ieee754     43
 186 #define MDOC_iso8802_3   44
 187 #define MDOC_xpg3        45
 188 #define MDOC_xpg4        46
 189 #define MDOC_xpg4_2      47
 190 #define MDOC_xpg4_3      48
 191 #define MDOC_xbd5        49
 192 #define MDOC_xcu5        50
 193 #define MDOC_xsh5        51
 194 #define MDOC_xns5        52
 195 #define MDOC_xns5_2d2_0  53
 196 #define MDOC_xcurses4_2  54
 197 #define MDOC_susv2       55
 198 #define MDOC_susv3       56
 199 #define MDOC_svid4       57
 200 #define MDOC_Filled      58
 201 #define MDOC_Words       59
 202 #define MDOC_Emphasis    60
 203 #define MDOC_Symbolic    61
 204 #define MDOC_ARG_MAX     62
 205
 206 /* Warnings are either syntax or groff-compatibility. */
 207 enum    mdoc_warn {
 208         WARN_SYNTAX,
 209         WARN_COMPAT
 210 };
 211
 212 /* Possible values for the `At' macro. */
 213 enum    mdoc_att {
 214         ATT_DEFAULT = 0,
 215         ATT_v1,
 216         ATT_v2,
 217         ATT_v3,
 218         ATT_v4,
 219         ATT_v5,
 220         ATT_v6,
 221         ATT_v7,
 222         ATT_32v,
 223         ATT_V,
 224         ATT_V1,
 225         ATT_V2,
 226         ATT_V3,
 227         ATT_V4
 228 };
 229
 230 /* An argument to a macro (multiple values = `It -column'). */
 231 struct  mdoc_arg {
 232         int               arg;
 233         int               line;
 234         int               pos;
 235         size_t            sz;
 236         char            **value;
 237 };
 238
 239 /* Type of a syntax node. */
 240 enum    mdoc_type {
 241         MDOC_TEXT,
 242         MDOC_ELEM,
 243         MDOC_HEAD,
 244         MDOC_TAIL,
 245         MDOC_BODY,
 246         MDOC_BLOCK,
 247         MDOC_ROOT
 248 };
 249
 250 /* Manual section. */
 251 enum    mdoc_msec {
 252         MSEC_DEFAULT = 0,
 253         MSEC_1,
 254         MSEC_2,
 255         MSEC_3,
 256         MSEC_3f,
 257         MSEC_3p,
 258         MSEC_4,
 259         MSEC_5,
 260         MSEC_6,
 261         MSEC_7,
 262         MSEC_8,
 263         MSEC_9,
 264         MSEC_X11,
 265         MSEC_X11R6,
 266         MSEC_local,
 267         MSEC_n,
 268         MSEC_unass,
 269         MSEC_draft,
 270         MSEC_paper
 271 };
 272
 273 /* Section (named/unnamed) of `Ss'. */
 274 enum    mdoc_sec {
 275         SEC_PROLOGUE = 0,
 276         SEC_BODY,
 277         SEC_NAME,
 278         SEC_SYNOPSIS,
 279         SEC_DESCRIPTION,
 280         SEC_RETURN_VALUES,
 281         SEC_ENVIRONMENT,
 282         SEC_FILES,
 283         SEC_EXAMPLES,
 284         SEC_DIAGNOSTICS,
 285         SEC_ERRORS,
 286         SEC_SEE_ALSO,
 287         SEC_STANDARDS,
 288         SEC_HISTORY,
 289         SEC_AUTHORS,
 290         SEC_CAVEATS,
 291         SEC_BUGS,
 292         SEC_CUSTOM
 293 };
 294
 295 /* Volume of `Dt'. */
 296 enum    mdoc_vol {
 297         VOL_DEFAULT = 0,
 298         VOL_AMD,
 299         VOL_IND,
 300         VOL_KM,
 301         VOL_LOCAL,
 302         VOL_PRM,
 303         VOL_PS1,
 304         VOL_SMM,
 305         VOL_URM,
 306         VOL_USD
 307 };
 308
 309 /* Architecture of `Dt'. */
 310 enum    mdoc_arch {
 311         ARCH_DEFAULT = 0,
 312         ARCH_alpha,
 313         ARCH_amd64,
 314         ARCH_amiga,
 315         ARCH_arc,
 316         ARCH_arm,
 317         ARCH_armish,
 318         ARCH_aviion,
 319         ARCH_hp300,
 320         ARCH_hppa,
 321         ARCH_hppa64,
 322         ARCH_i386,
 323         ARCH_landisk,
 324         ARCH_luna88k,
 325         ARCH_mac68k,
 326         ARCH_macppc,
 327         ARCH_mvme68k,
 328         ARCH_mvme88k,
 329         ARCH_mvmeppc,
 330         ARCH_pmax,
 331         ARCH_sgi,
 332         ARCH_socppc,
 333         ARCH_sparc,
 334         ARCH_sparc64,
 335         ARCH_sun3,
 336         ARCH_vax,
 337         ARCH_zaurus
 338 };
 339
 340 /* Information from prologue. */
 341 struct  mdoc_meta {
 342         enum mdoc_msec    msec;
 343         enum mdoc_vol     vol;
 344         enum mdoc_arch    arch;
 345         time_t            date;
 346         char             *title;
 347         char             *os;
 348         char             *name;
 349 };
 350
 351 /* Text-only node. */
 352 struct  mdoc_text {
 353         char             *string;
 354 };
 355
 356 /* Block (scoped) node. */
 357 struct  mdoc_block {
 358         size_t            argc;
 359         struct mdoc_arg  *argv;
 360         struct mdoc_node *head;
 361         struct mdoc_node *body;
 362         struct mdoc_node *tail;
 363 };
 364
 365 /* In-line element node. */
 366 struct  mdoc_elem {
 367         size_t            argc;
 368         struct mdoc_arg  *argv;
 369 };
 370
 371 /* Typed nodes of an AST node. */
 372 union   mdoc_data {
 373         struct mdoc_text  text;
 374         struct mdoc_elem  elem;
 375         struct mdoc_block block;
 376 };
 377
 378 /* Node in AST. */
 379 struct  mdoc_node {
 380         struct mdoc_node *parent;
 381         struct mdoc_node *child;
 382         struct mdoc_node *next;
 383         struct mdoc_node *prev;
 384         int               line;
 385         int               pos;
 386         int               tok;
 387         int               flags;
 388 #define MDOC_VALID       (1 << 0)
 389 #define MDOC_ACTED       (1 << 1)
 390         enum mdoc_type    type;
 391         union mdoc_data   data;
 392         enum mdoc_sec     sec;
 393 };
 394
 395 /* Call-backs for parse messages. */
 396 struct  mdoc_cb {
 397         void    (*mdoc_msg)(void *, int, int, const char *);
 398         int     (*mdoc_err)(void *, int, int, const char *);
 399         int     (*mdoc_warn)(void *, int, int,
 400                         enum mdoc_warn, const char *);
 401 };
 402
 403 /* Global table of macro names (`Bd', `Ed', etc.). */
 404 extern  const char *const *mdoc_macronames;
 405
 406 /* Global table of argument names (`column', `tag', etc.). */
 407 extern  const char *const *mdoc_argnames;
 408
 409 __BEGIN_DECLS
 410
 411 struct  mdoc;
 412
 413 /* Free memory allocated with mdoc_alloc. */
 414 void              mdoc_free(struct mdoc *);
 415
 416 /* Allocate a new parser instance. */
 417 struct  mdoc     *mdoc_alloc(void *data, const struct mdoc_cb *);
 418
 419 /* Parse a single line in a stream (boolean retval). */
 420 int               mdoc_parseln(struct mdoc *, int, char *buf);
 421
 422 /* Get result first node (after mdoc_endparse!). */
 423 const struct mdoc_node *mdoc_node(const struct mdoc *);
 424
 425 /* Get result meta-information (after mdoc_endparse!). */
 426 const struct mdoc_meta *mdoc_meta(const struct mdoc *);
 427
 428 /* Signal end of parse sequence (boolean retval). */
 429 int               mdoc_endparse(struct mdoc *);
 430
 431 /* The following are utility functions. */
 432 const char       *mdoc_arch2a(enum mdoc_arch);
 433 const char       *mdoc_vol2a(enum mdoc_vol);
 434 const char       *mdoc_msec2a(enum mdoc_msec);
 435 const char       *mdoc_att2a(enum mdoc_att);
 436 enum    mdoc_att  mdoc_atoatt(const char *);
 437 const char       *mdoc_st2a(int);
 438 int               mdoc_isdelim(const char *);
 439
 440 __END_DECLS
 441
 442 #endif /*!MDOC_H*/