Annotation of mandoc/mdoc.3, Revision 1.38
1.38 ! kristaps 1: .\" $Id: mdoc.3,v 1.37 2010/02/17 19:22:01 kristaps Exp $
1.6 kristaps 2: .\"
1.37 kristaps 3: .\" Copyright (c) 2009-2010 Kristaps Dzonsons <kristaps@bsd.lv>
1.6 kristaps 4: .\"
5: .\" Permission to use, copy, modify, and distribute this software for any
1.28 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.6 kristaps 8: .\"
1.28 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.33 kristaps 16: .\"
1.38 ! kristaps 17: .Dd $Mdocdate: February 17 2010 $
1.27 kristaps 18: .Dt MDOC 3
1.1 kristaps 19: .Os
20: .Sh NAME
21: .Nm mdoc_alloc ,
22: .Nm mdoc_endparse ,
1.38 ! kristaps 23: .Nm mdoc_free ,
! 24: .Nm mdoc_meta ,
1.4 kristaps 25: .Nm mdoc_node ,
1.38 ! kristaps 26: .Nm mdoc_parseln ,
1.20 kristaps 27: .Nm mdoc_reset
1.2 kristaps 28: .Nd mdoc macro compiler library
1.1 kristaps 29: .Sh SYNOPSIS
1.38 ! kristaps 30: .In mandoc.h
1.35 kristaps 31: .In mdoc.h
1.4 kristaps 32: .Vt extern const char * const * mdoc_macronames;
33: .Vt extern const char * const * mdoc_argnames;
1.1 kristaps 34: .Ft "struct mdoc *"
1.38 ! kristaps 35: .Fn mdoc_alloc "void *data" "int pflags" "mandocmsg msgs"
1.26 kristaps 36: .Ft int
1.38 ! kristaps 37: .Fn mdoc_endparse "struct mdoc *mdoc"
1.1 kristaps 38: .Ft void
1.2 kristaps 39: .Fn mdoc_free "struct mdoc *mdoc"
1.38 ! kristaps 40: .Ft "const struct mdoc_meta *"
! 41: .Fn mdoc_meta "const struct mdoc *mdoc"
! 42: .Ft "const struct mdoc_node *"
! 43: .Fn mdoc_node "const struct mdoc *mdoc"
1.1 kristaps 44: .Ft int
1.2 kristaps 45: .Fn mdoc_parseln "struct mdoc *mdoc" "int line" "char *buf"
1.1 kristaps 46: .Ft int
1.38 ! kristaps 47: .Fn mdoc_reset "struct mdoc *mdoc"
1.1 kristaps 48: .Sh DESCRIPTION
49: The
50: .Nm mdoc
1.33 kristaps 51: library parses lines of
1.17 kristaps 52: .Xr mdoc 7
1.38 ! kristaps 53: input
! 54: into an abstract syntax tree (AST).
1.6 kristaps 55: .Pp
1.1 kristaps 56: In general, applications initiate a parsing sequence with
57: .Fn mdoc_alloc ,
1.33 kristaps 58: parse each line in a document with
1.1 kristaps 59: .Fn mdoc_parseln ,
60: close the parsing session with
61: .Fn mdoc_endparse ,
62: operate over the syntax tree returned by
1.33 kristaps 63: .Fn mdoc_node
1.4 kristaps 64: and
65: .Fn mdoc_meta ,
1.1 kristaps 66: then free all allocated memory with
67: .Fn mdoc_free .
1.20 kristaps 68: The
69: .Fn mdoc_reset
70: function may be used in order to reset the parser for another input
1.38 ! kristaps 71: sequence.
! 72: See the
1.1 kristaps 73: .Sx EXAMPLES
1.38 ! kristaps 74: section for a simple example.
1.2 kristaps 75: .Pp
1.33 kristaps 76: This section further defines the
1.6 kristaps 77: .Sx Types ,
1.33 kristaps 78: .Sx Functions
1.6 kristaps 79: and
80: .Sx Variables
1.38 ! kristaps 81: available to programmers.
! 82: Following that, the
1.33 kristaps 83: .Sx Abstract Syntax Tree
1.17 kristaps 84: section documents the output tree.
1.6 kristaps 85: .Ss Types
86: Both functions (see
87: .Sx Functions )
88: and variables (see
89: .Sx Variables )
90: may use the following types:
1.37 kristaps 91: .Bl -ohang
1.6 kristaps 92: .It Vt struct mdoc
93: An opaque type defined in
94: .Pa mdoc.c .
95: Its values are only used privately within the library.
96: .It Vt struct mdoc_node
1.38 ! kristaps 97: A parsed node.
! 98: Defined in
1.6 kristaps 99: .Pa mdoc.h .
1.33 kristaps 100: See
1.6 kristaps 101: .Sx Abstract Syntax Tree
102: for details.
1.38 ! kristaps 103: .It Vt mandocmsg
! 104: A function callback type defined in
! 105: .Pa mandoc.h .
1.6 kristaps 106: .El
107: .Ss Functions
1.2 kristaps 108: Function descriptions follow:
1.37 kristaps 109: .Bl -ohang
1.2 kristaps 110: .It Fn mdoc_alloc
1.38 ! kristaps 111: Allocates a parsing structure.
! 112: The
1.2 kristaps 113: .Fa data
114: pointer is passed to callbacks in
1.33 kristaps 115: .Fa cb ,
116: which are documented further in the header file.
1.20 kristaps 117: The
118: .Fa pflags
119: arguments are defined in
120: .Pa mdoc.h .
1.38 ! kristaps 121: Returns NULL on failure.
! 122: If non-NULL, the pointer must be freed with
1.2 kristaps 123: .Fn mdoc_free .
1.20 kristaps 124: .It Fn mdoc_reset
1.38 ! kristaps 125: Reset the parser for another parse routine.
! 126: After its use,
1.20 kristaps 127: .Fn mdoc_parseln
1.38 ! kristaps 128: behaves as if invoked for the first time.
! 129: If it returns 0, memory could not be allocated.
1.2 kristaps 130: .It Fn mdoc_free
1.38 ! kristaps 131: Free all resources of a parser.
! 132: The pointer is no longer valid after invocation.
1.2 kristaps 133: .It Fn mdoc_parseln
1.38 ! kristaps 134: Parse a nil-terminated line of input.
! 135: This line should not contain the trailing newline.
! 136: Returns 0 on failure, 1 on success.
! 137: The input buffer
1.2 kristaps 138: .Fa buf
139: is modified by this function.
140: .It Fn mdoc_endparse
1.38 ! kristaps 141: Signals that the parse is complete.
! 142: Note that if
1.2 kristaps 143: .Fn mdoc_endparse
144: is called subsequent to
1.4 kristaps 145: .Fn mdoc_node ,
1.38 ! kristaps 146: the resulting tree is incomplete.
! 147: Returns 0 on failure, 1 on success.
1.4 kristaps 148: .It Fn mdoc_node
1.38 ! kristaps 149: Returns the first node of the parse.
! 150: Note that if
1.2 kristaps 151: .Fn mdoc_parseln
152: or
153: .Fn mdoc_endparse
154: return 0, the tree will be incomplete.
1.4 kristaps 155: .It Fn mdoc_meta
1.38 ! kristaps 156: Returns the document's parsed meta-data.
! 157: If this information has not yet been supplied or
1.4 kristaps 158: .Fn mdoc_parseln
159: or
160: .Fn mdoc_endparse
161: return 0, the data will be incomplete.
162: .El
1.6 kristaps 163: .Ss Variables
1.4 kristaps 164: The following variables are also defined:
1.37 kristaps 165: .Bl -ohang
1.4 kristaps 166: .It Va mdoc_macronames
167: An array of string-ified token names.
168: .It Va mdoc_argnames
169: An array of string-ified token argument names.
1.2 kristaps 170: .El
1.6 kristaps 171: .Ss Abstract Syntax Tree
1.33 kristaps 172: The
1.6 kristaps 173: .Nm
1.17 kristaps 174: functions produce an abstract syntax tree (AST) describing input in a
1.38 ! kristaps 175: regular form.
! 176: It may be reviewed at any time with
1.6 kristaps 177: .Fn mdoc_nodes ;
178: however, if called before
179: .Fn mdoc_endparse ,
180: or after
1.33 kristaps 181: .Fn mdoc_endparse
1.6 kristaps 182: or
183: .Fn mdoc_parseln
1.33 kristaps 184: fail, it may be incomplete.
1.18 kristaps 185: .Pp
186: This AST is governed by the ontological
1.17 kristaps 187: rules dictated in
188: .Xr mdoc 7
1.33 kristaps 189: and derives its terminology accordingly.
1.17 kristaps 190: .Qq In-line
191: elements described in
192: .Xr mdoc 7
1.33 kristaps 193: are described simply as
1.17 kristaps 194: .Qq elements .
1.6 kristaps 195: .Pp
1.33 kristaps 196: The AST is composed of
1.6 kristaps 197: .Vt struct mdoc_node
198: nodes with block, head, body, element, root and text types as declared
199: by the
200: .Va type
1.38 ! kristaps 201: field.
! 202: Each node also provides its parse point (the
1.6 kristaps 203: .Va line ,
204: .Va sec ,
205: and
206: .Va pos
207: fields), its position in the tree (the
208: .Va parent ,
209: .Va child ,
1.33 kristaps 210: .Va next
1.6 kristaps 211: and
1.33 kristaps 212: .Va prev
1.25 kristaps 213: fields) and some type-specific data.
1.6 kristaps 214: .Pp
215: The tree itself is arranged according to the following normal form,
216: where capitalised non-terminals represent nodes.
217: .Pp
1.37 kristaps 218: .Bl -tag -width "ELEMENTXX" -compact
1.6 kristaps 219: .It ROOT
220: \(<- mnode+
221: .It mnode
222: \(<- BLOCK | ELEMENT | TEXT
223: .It BLOCK
224: \(<- (HEAD [TEXT])+ [BODY [TEXT]] [TAIL [TEXT]]
225: .It BLOCK
226: \(<- BODY [TEXT] [TAIL [TEXT]]
227: .It ELEMENT
228: \(<- TEXT*
229: .It HEAD
230: \(<- mnode+
231: .It BODY
232: \(<- mnode+
233: .It TAIL
234: \(<- mnode+
235: .It TEXT
1.38 ! kristaps 236: \(<- [[:printable:],0x1e]*
1.6 kristaps 237: .El
1.2 kristaps 238: .Pp
1.6 kristaps 239: Of note are the TEXT nodes following the HEAD, BODY and TAIL nodes of
1.38 ! kristaps 240: the BLOCK production.
! 241: These refer to punctuation marks.
! 242: Furthermore, although a TEXT node will generally have a non-zero-length
! 243: string, in the specific case of
1.8 kristaps 244: .Sq \&.Bd \-literal ,
1.6 kristaps 245: an empty line will produce a zero-length string.
1.2 kristaps 246: .Sh EXAMPLES
247: The following example reads lines from stdin and parses them, operating
1.33 kristaps 248: on the finished parse tree with
1.2 kristaps 249: .Fn parsed .
1.37 kristaps 250: This example does not error-check nor free memory upon failure.
251: .Bd -literal -offset indent
1.2 kristaps 252: struct mdoc *mdoc;
1.31 kristaps 253: const struct mdoc_node *node;
1.2 kristaps 254: char *buf;
255: size_t len;
256: int line;
257:
258: line = 1;
1.25 kristaps 259: mdoc = mdoc_alloc(NULL, 0, NULL);
1.37 kristaps 260: buf = NULL;
261: alloc_len = 0;
1.2 kristaps 262:
1.37 kristaps 263: while ((len = getline(&buf, &alloc_len, stdin)) >= 0) {
264: if (len && buflen[len - 1] = '\en')
265: buf[len - 1] = '\e0';
266: if ( ! mdoc_parseln(mdoc, line, buf))
267: errx(1, "mdoc_parseln");
268: line++;
1.2 kristaps 269: }
270:
271: if ( ! mdoc_endparse(mdoc))
1.37 kristaps 272: errx(1, "mdoc_endparse");
1.4 kristaps 273: if (NULL == (node = mdoc_node(mdoc)))
1.37 kristaps 274: errx(1, "mdoc_node");
1.2 kristaps 275:
276: parsed(mdoc, node);
277: mdoc_free(mdoc);
278: .Ed
1.38 ! kristaps 279: .Pp
! 280: Please see
! 281: .Pa main.c
! 282: in the source archive for a rigorous reference.
1.17 kristaps 283: .Sh SEE ALSO
1.20 kristaps 284: .Xr mandoc 1 ,
1.14 kristaps 285: .Xr mdoc 7
1.2 kristaps 286: .Sh AUTHORS
287: The
288: .Nm
1.38 ! kristaps 289: library was written by
1.37 kristaps 290: .An Kristaps Dzonsons Aq kristaps@bsd.lv .
CVSweb
![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to mdoc.3 CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [cvsweb.bsd.lv] / mandoc