Annotation of src/usr.bin/mandoc/mdoc.h, Revision 1.1
1.1 ! kristaps 1: /* $Id: mdoc.h,v 1.54 2009/03/31 13:50:19 kristaps Exp $ */
! 2: /*
! 3: * Copyright (c) 2008, 2009 Kristaps Dzonsons <kristaps@openbsd.org>
! 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: #include <time.h>
! 23:
! 24: /*
! 25: * This library implements a validating scanner/parser for ``mdoc'' roff
! 26: * macro documents, a.k.a. BSD manual page documents. The mdoc.c file
! 27: * drives the parser, while macro.c describes the macro ontologies.
! 28: * validate.c pre- and post-validates parsed macros, and action.c
! 29: * performs actions on parsed and validated macros.
! 30: */
! 31:
! 32: /* What follows is a list of ALL possible macros. */
! 33:
! 34: #define MDOC___ 0
! 35: #define MDOC_Dd 1
! 36: #define MDOC_Dt 2
! 37: #define MDOC_Os 3
! 38: #define MDOC_Sh 4
! 39: #define MDOC_Ss 5
! 40: #define MDOC_Pp 6
! 41: #define MDOC_D1 7
! 42: #define MDOC_Dl 8
! 43: #define MDOC_Bd 9
! 44: #define MDOC_Ed 10
! 45: #define MDOC_Bl 11
! 46: #define MDOC_El 12
! 47: #define MDOC_It 13
! 48: #define MDOC_Ad 14
! 49: #define MDOC_An 15
! 50: #define MDOC_Ar 16
! 51: #define MDOC_Cd 17
! 52: #define MDOC_Cm 18
! 53: #define MDOC_Dv 19
! 54: #define MDOC_Er 20
! 55: #define MDOC_Ev 21
! 56: #define MDOC_Ex 22
! 57: #define MDOC_Fa 23
! 58: #define MDOC_Fd 24
! 59: #define MDOC_Fl 25
! 60: #define MDOC_Fn 26
! 61: #define MDOC_Ft 27
! 62: #define MDOC_Ic 28
! 63: #define MDOC_In 29
! 64: #define MDOC_Li 30
! 65: #define MDOC_Nd 31
! 66: #define MDOC_Nm 32
! 67: #define MDOC_Op 33
! 68: #define MDOC_Ot 34
! 69: #define MDOC_Pa 35
! 70: #define MDOC_Rv 36
! 71: #define MDOC_St 37
! 72: #define MDOC_Va 38
! 73: #define MDOC_Vt 39
! 74: #define MDOC_Xr 40
! 75: #define MDOC__A 41
! 76: #define MDOC__B 42
! 77: #define MDOC__D 43
! 78: #define MDOC__I 44
! 79: #define MDOC__J 45
! 80: #define MDOC__N 46
! 81: #define MDOC__O 47
! 82: #define MDOC__P 48
! 83: #define MDOC__R 49
! 84: #define MDOC__T 50
! 85: #define MDOC__V 51
! 86: #define MDOC_Ac 52
! 87: #define MDOC_Ao 53
! 88: #define MDOC_Aq 54
! 89: #define MDOC_At 55
! 90: #define MDOC_Bc 56
! 91: #define MDOC_Bf 57
! 92: #define MDOC_Bo 58
! 93: #define MDOC_Bq 59
! 94: #define MDOC_Bsx 60
! 95: #define MDOC_Bx 61
! 96: #define MDOC_Db 62
! 97: #define MDOC_Dc 63
! 98: #define MDOC_Do 64
! 99: #define MDOC_Dq 65
! 100: #define MDOC_Ec 66
! 101: #define MDOC_Ef 67
! 102: #define MDOC_Em 68
! 103: #define MDOC_Eo 69
! 104: #define MDOC_Fx 70
! 105: #define MDOC_Ms 71
! 106: #define MDOC_No 72
! 107: #define MDOC_Ns 73
! 108: #define MDOC_Nx 74
! 109: #define MDOC_Ox 75
! 110: #define MDOC_Pc 76
! 111: #define MDOC_Pf 77
! 112: #define MDOC_Po 78
! 113: #define MDOC_Pq 79
! 114: #define MDOC_Qc 80
! 115: #define MDOC_Ql 81
! 116: #define MDOC_Qo 82
! 117: #define MDOC_Qq 83
! 118: #define MDOC_Re 84
! 119: #define MDOC_Rs 85
! 120: #define MDOC_Sc 86
! 121: #define MDOC_So 87
! 122: #define MDOC_Sq 88
! 123: #define MDOC_Sm 89
! 124: #define MDOC_Sx 90
! 125: #define MDOC_Sy 91
! 126: #define MDOC_Tn 92
! 127: #define MDOC_Ux 93
! 128: #define MDOC_Xc 94
! 129: #define MDOC_Xo 95
! 130: #define MDOC_Fo 96
! 131: #define MDOC_Fc 97
! 132: #define MDOC_Oo 98
! 133: #define MDOC_Oc 99
! 134: #define MDOC_Bk 100
! 135: #define MDOC_Ek 101
! 136: #define MDOC_Bt 102
! 137: #define MDOC_Hf 103
! 138: #define MDOC_Fr 104
! 139: #define MDOC_Ud 105
! 140: #define MDOC_Lb 106
! 141: #define MDOC_Ap 107
! 142: #define MDOC_Lp 108
! 143: #define MDOC_Lk 109
! 144: #define MDOC_Mt 110
! 145: #define MDOC_Brq 111
! 146: #define MDOC_Bro 112
! 147: #define MDOC_Brc 113
! 148: #define MDOC__C 114
! 149: #define MDOC_Es 115
! 150: #define MDOC_En 116
! 151: #define MDOC_Dx 117
! 152: #define MDOC__Q 118
! 153: #define MDOC_MAX 119
! 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_ARG_MAX 26
! 184:
! 185: /* Warnings are either syntax or groff-compatibility. */
! 186: enum mdoc_warn {
! 187: WARN_SYNTAX,
! 188: WARN_COMPAT
! 189: };
! 190:
! 191: /* Type of a syntax node. */
! 192: enum mdoc_type {
! 193: MDOC_TEXT,
! 194: MDOC_ELEM,
! 195: MDOC_HEAD,
! 196: MDOC_TAIL,
! 197: MDOC_BODY,
! 198: MDOC_BLOCK,
! 199: MDOC_ROOT
! 200: };
! 201:
! 202: /* Section (named/unnamed) of `Sh'. */
! 203: enum mdoc_sec {
! 204: SEC_PROLOGUE = 0,
! 205: SEC_BODY = 1,
! 206: SEC_NAME = 2,
! 207: SEC_LIBRARY = 3,
! 208: SEC_SYNOPSIS = 4,
! 209: SEC_DESCRIPTION = 5,
! 210: SEC_IMPLEMENTATION = 6,
! 211: SEC_RETURN_VALUES = 7,
! 212: SEC_ENVIRONMENT = 8,
! 213: SEC_FILES = 9,
! 214: SEC_EXAMPLES = 10,
! 215: SEC_DIAGNOSTICS = 11,
! 216: SEC_COMPATIBILITY = 12,
! 217: SEC_ERRORS = 13,
! 218: SEC_SEE_ALSO = 14,
! 219: SEC_STANDARDS = 15,
! 220: SEC_HISTORY = 16,
! 221: SEC_AUTHORS = 17,
! 222: SEC_CAVEATS = 18,
! 223: SEC_BUGS = 19,
! 224: SEC_CUSTOM
! 225: };
! 226:
! 227: /* Information from prologue. */
! 228: struct mdoc_meta {
! 229: int 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: int 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: /* Node in AST. */
! 254: struct mdoc_node {
! 255: struct mdoc_node *parent;
! 256: struct mdoc_node *child;
! 257: struct mdoc_node *next;
! 258: struct mdoc_node *prev;
! 259: int line;
! 260: int pos;
! 261: int tok;
! 262: int flags;
! 263: #define MDOC_VALID (1 << 0)
! 264: #define MDOC_ACTED (1 << 1)
! 265: enum mdoc_type type;
! 266: enum mdoc_sec sec;
! 267:
! 268: /* FIXME: union/struct this with #defines. */
! 269: struct mdoc_arg *args; /* BLOCK/ELEM */
! 270: struct mdoc_node *head; /* BLOCK */
! 271: struct mdoc_node *body; /* BLOCK */
! 272: struct mdoc_node *tail; /* BLOCK */
! 273: char *string; /* TEXT */
! 274: };
! 275:
! 276: #define MDOC_IGN_SCOPE (1 << 0) /* Ignore scope violations. */
! 277: #define MDOC_IGN_ESCAPE (1 << 1) /* Ignore bad escape sequences. */
! 278: #define MDOC_IGN_MACRO (1 << 2) /* Ignore unknown macros. */
! 279: #define MDOC_IGN_CHARS (1 << 3) /* Ignore disallowed chars. */
! 280:
! 281: /* Call-backs for parse messages. */
! 282: struct mdoc_cb {
! 283: void (*mdoc_msg)(void *, int, int, const char *);
! 284: int (*mdoc_err)(void *, int, int, const char *);
! 285: int (*mdoc_warn)(void *, int, int,
! 286: enum mdoc_warn, const char *);
! 287: };
! 288:
! 289: /* Global table of macro names (`Bd', `Ed', etc.). */
! 290: extern const char *const *mdoc_macronames;
! 291:
! 292: /* Global table of argument names (`column', `tag', etc.). */
! 293: extern const char *const *mdoc_argnames;
! 294:
! 295: __BEGIN_DECLS
! 296:
! 297: struct mdoc;
! 298:
! 299: /* Free memory allocated with mdoc_alloc. */
! 300: void mdoc_free(struct mdoc *);
! 301:
! 302: /* Allocate a new parser instance. */
! 303: struct mdoc *mdoc_alloc(void *, int, const struct mdoc_cb *);
! 304:
! 305: /* Gets system ready for another parse. */
! 306: int mdoc_reset(struct mdoc *);
! 307:
! 308: /* Parse a single line in a stream (boolean retval). */
! 309: int mdoc_parseln(struct mdoc *, int, char *buf);
! 310:
! 311: /* Get result first node (after mdoc_endparse!). */
! 312: const struct mdoc_node *mdoc_node(const struct mdoc *);
! 313:
! 314: /* Get result meta-information (after mdoc_endparse!). */
! 315: const struct mdoc_meta *mdoc_meta(const struct mdoc *);
! 316:
! 317: /* Signal end of parse sequence (boolean retval). */
! 318: int mdoc_endparse(struct mdoc *);
! 319:
! 320: /* The following are utility functions. */
! 321:
! 322: const char *mdoc_a2att(const char *);
! 323: const char *mdoc_a2lib(const char *);
! 324: const char *mdoc_a2st(const char *);
! 325:
! 326: __END_DECLS
! 327:
! 328: #endif /*!MDOC_H*/