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