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