[BACK]Return to mdoc.h CVS log [TXT][DIR] Up to [cvsweb.bsd.lv] / mandoc

Annotation of mandoc/mdoc.h, Revision 1.94

1.94    ! kristaps    1: /*     $Id: mdoc.h,v 1.93 2010/06/27 15:52:41 kristaps Exp $ */
1.1       kristaps    2: /*
1.90      kristaps    3:  * Copyright (c) 2008, 2009 Kristaps Dzonsons <kristaps@bsd.lv>
1.1       kristaps    4:  *
                      5:  * Permission to use, copy, modify, and distribute this software for any
1.56      kristaps    6:  * purpose with or without fee is hereby granted, provided that the above
                      7:  * copyright notice and this permission notice appear in all copies.
1.1       kristaps    8:  *
1.56      kristaps    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.
1.1       kristaps   16:  */
                     17: #ifndef MDOC_H
                     18: #define MDOC_H
                     19:
1.33      kristaps   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:
1.22      kristaps   28: /* What follows is a list of ALL possible macros. */
                     29:
1.74      kristaps   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,
1.83      kristaps  152:        MDOC_Ta,
1.74      kristaps  153:        MDOC_MAX
                    154: };
1.1       kristaps  155:
1.22      kristaps  156: /* What follows is a list of ALL possible macro arguments. */
                    157:
1.91      kristaps  158: /* FIXME: make this into an enum. */
1.1       kristaps  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
1.37      kristaps  180: #define        MDOC_Filled      21
                    181: #define        MDOC_Words       22
                    182: #define        MDOC_Emphasis    23
                    183: #define        MDOC_Symbolic    24
1.47      kristaps  184: #define        MDOC_Nested      25
1.70      kristaps  185: #define        MDOC_Centred     26
                    186: #define        MDOC_ARG_MAX     27
1.1       kristaps  187:
1.23      kristaps  188: /* Type of a syntax node. */
1.1       kristaps  189: enum   mdoc_type {
                    190:        MDOC_TEXT,
                    191:        MDOC_ELEM,
                    192:        MDOC_HEAD,
1.14      kristaps  193:        MDOC_TAIL,
1.1       kristaps  194:        MDOC_BODY,
1.18      kristaps  195:        MDOC_BLOCK,
                    196:        MDOC_ROOT
1.1       kristaps  197: };
                    198:
1.37      kristaps  199: /* Section (named/unnamed) of `Sh'. */
1.2       kristaps  200: enum   mdoc_sec {
1.60      kristaps  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,
1.68      kristaps  208:        SEC_ENVIRONMENT,
1.60      kristaps  209:        SEC_FILES,
1.76      kristaps  210:        SEC_EXIT_STATUS,
1.60      kristaps  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,
1.69      kristaps  221:        SEC_SECURITY,
1.76      kristaps  222:        SEC_CUSTOM,             /* User-defined. */
                    223:        SEC__MAX
1.2       kristaps  224: };
                    225:
1.29      kristaps  226: /* Information from prologue. */
1.2       kristaps  227: struct mdoc_meta {
1.79      kristaps  228:        char             *msec;
1.37      kristaps  229:        char             *vol;
                    230:        char             *arch;
1.3       kristaps  231:        time_t            date;
1.25      kristaps  232:        char             *title;
                    233:        char             *os;
                    234:        char             *name;
1.2       kristaps  235: };
                    236:
1.38      kristaps  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;
1.1       kristaps  244: };
                    245:
1.38      kristaps  246: struct         mdoc_arg {
1.1       kristaps  247:        size_t            argc;
1.38      kristaps  248:        struct mdoc_argv *argv;
                    249:        unsigned int      refcnt;
1.1       kristaps  250: };
                    251:
1.82      kristaps  252: enum   mdoc_list {
                    253:        LIST__NONE = 0,
                    254:        LIST_bullet,
                    255:        LIST_column,
                    256:        LIST_dash,
                    257:        LIST_diag,
                    258:        LIST_enum,
                    259:        LIST_hang,
                    260:        LIST_hyphen,
                    261:        LIST_inset,
                    262:        LIST_item,
                    263:        LIST_ohang,
                    264:        LIST_tag
                    265: };
                    266:
1.84      kristaps  267: enum   mdoc_disp {
                    268:        DISP__NONE = 0,
                    269:        DISP_centred,
                    270:        DISP_ragged,
                    271:        DISP_unfilled,
                    272:        DISP_filled,
                    273:        DISP_literal
                    274: };
                    275:
1.85      kristaps  276: struct mdoc_bd {
1.87      kristaps  277:        const char       *offs; /* -offset */
                    278:        enum mdoc_disp    type; /* -ragged, etc. */
                    279:        int               comp; /* -compact */
1.85      kristaps  280: };
                    281:
1.86      kristaps  282: struct mdoc_bl {
1.89      kristaps  283:        const char       *width; /* -width */
1.88      kristaps  284:        const char       *offs; /* -offset */
1.87      kristaps  285:        enum mdoc_list    type; /* -tag, -enum, etc. */
                    286:        int               comp; /* -compact */
1.86      kristaps  287: };
                    288:
1.29      kristaps  289: /* Node in AST. */
1.1       kristaps  290: struct mdoc_node {
1.78      kristaps  291:        struct mdoc_node *parent; /* parent AST node */
                    292:        struct mdoc_node *child; /* first child AST node */
                    293:        struct mdoc_node *next; /* sibling AST node */
                    294:        struct mdoc_node *prev; /* prior sibling AST node */
                    295:        int               nchild; /* number children */
                    296:        int               line; /* parse line */
                    297:        int               pos; /* parse column */
                    298:        enum mdoct        tok; /* tok or MDOC__MAX if none */
1.26      kristaps  299:        int               flags;
1.78      kristaps  300: #define        MDOC_VALID       (1 << 0) /* has been validated */
                    301: #define        MDOC_ACTED       (1 << 1) /* has been acted upon */
                    302: #define        MDOC_EOS         (1 << 2) /* at sentence boundary */
                    303: #define        MDOC_LINE        (1 << 3) /* first macro/text on line */
1.94    ! kristaps  304: #define        MDOC_SYNPRETTY   (1 << 4) /* SYNOPSIS-style formatting */
1.78      kristaps  305:        enum mdoc_type    type; /* AST node type */
                    306:        enum mdoc_sec     sec; /* current named section */
1.93      kristaps  307:        /* FIXME: these can be union'd to shave a few bytes. */
1.38      kristaps  308:        struct mdoc_arg  *args;         /* BLOCK/ELEM */
1.74      kristaps  309:        struct mdoc_node *pending;      /* BLOCK */
1.38      kristaps  310:        struct mdoc_node *head;         /* BLOCK */
                    311:        struct mdoc_node *body;         /* BLOCK */
                    312:        struct mdoc_node *tail;         /* BLOCK */
                    313:        char             *string;       /* TEXT */
1.82      kristaps  314:
                    315:        union {
1.86      kristaps  316:                struct mdoc_bl Bl;
1.85      kristaps  317:                struct mdoc_bd Bd;
1.82      kristaps  318:        } data;
1.1       kristaps  319: };
                    320:
1.40      kristaps  321: #define        MDOC_IGN_SCOPE   (1 << 0) /* Ignore scope violations. */
                    322: #define        MDOC_IGN_ESCAPE  (1 << 1) /* Ignore bad escape sequences. */
1.43      kristaps  323: #define        MDOC_IGN_MACRO   (1 << 2) /* Ignore unknown macros. */
1.38      kristaps  324:
1.60      kristaps  325: /* See mdoc.3 for documentation. */
                    326:
1.1       kristaps  327: extern const char *const *mdoc_macronames;
                    328: extern const char *const *mdoc_argnames;
                    329:
                    330: __BEGIN_DECLS
                    331:
                    332: struct mdoc;
                    333:
1.60      kristaps  334: /* See mdoc.3 for documentation. */
                    335:
1.1       kristaps  336: void             mdoc_free(struct mdoc *);
1.94    ! kristaps  337: struct mdoc     *mdoc_alloc(struct regset *, void *, int, mandocmsg);
1.73      kristaps  338: void             mdoc_reset(struct mdoc *);
1.93      kristaps  339: int              mdoc_parseln(struct mdoc *, int, char *, int);
1.32      kristaps  340: const struct mdoc_node *mdoc_node(const struct mdoc *);
                    341: const struct mdoc_meta *mdoc_meta(const struct mdoc *);
1.16      kristaps  342: int              mdoc_endparse(struct mdoc *);
1.1       kristaps  343:
                    344: __END_DECLS
                    345:
                    346: #endif /*!MDOC_H*/

CVSweb