Annotation of mandoc/man.3, Revision 1.29
1.29 ! kristaps 1: .\" $Id: man.3,v 1.28 2011/01/01 12:59:17 kristaps Exp $
1.1 kristaps 2: .\"
1.12 kristaps 3: .\" Copyright (c) 2009-2010 Kristaps Dzonsons <kristaps@bsd.lv>
1.1 kristaps 4: .\"
5: .\" Permission to use, copy, modify, and distribute this software for any
1.3 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.
8: .\"
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: .\"
1.29 ! kristaps 17: .Dd $Mdocdate: January 1 2011 $
1.2 kristaps 18: .Dt MAN 3
1.1 kristaps 19: .Os
20: .Sh NAME
1.13 kristaps 21: .Nm man ,
1.1 kristaps 22: .Nm man_alloc ,
23: .Nm man_endparse ,
1.17 kristaps 24: .Nm man_free ,
25: .Nm man_meta ,
1.1 kristaps 26: .Nm man_node ,
1.17 kristaps 27: .Nm man_parseln ,
1.1 kristaps 28: .Nm man_reset
29: .Nd man macro compiler library
30: .Sh SYNOPSIS
1.17 kristaps 31: .In mandoc.h
1.10 kristaps 32: .In man.h
1.1 kristaps 33: .Vt extern const char * const * man_macronames;
1.28 kristaps 34: .Ft int
35: .Fo man_addspan
36: .Fa "struct man *man"
37: .Fa "const struct tbl_span *span"
38: .Fc
1.1 kristaps 39: .Ft "struct man *"
1.20 kristaps 40: .Fo man_alloc
1.21 kristaps 41: .Fa "struct regset *regs"
1.20 kristaps 42: .Fa "void *data"
43: .Fa "mandocmsg msgs"
44: .Fc
1.17 kristaps 45: .Ft int
46: .Fn man_endparse "struct man *man"
1.1 kristaps 47: .Ft void
48: .Fn man_free "struct man *man"
1.17 kristaps 49: .Ft "const struct man_meta *"
50: .Fn man_meta "const struct man *man"
1.1 kristaps 51: .Ft "const struct man_node *"
1.6 kristaps 52: .Fn man_node "const struct man *man"
1.1 kristaps 53: .Ft int
1.19 kristaps 54: .Fo man_parseln
55: .Fa "struct man *man"
56: .Fa "int line"
57: .Fa "char *buf"
58: .Fc
1.17 kristaps 59: .Ft void
60: .Fn man_reset "struct man *man"
1.1 kristaps 61: .Sh DESCRIPTION
62: The
1.13 kristaps 63: .Nm
1.7 kristaps 64: library parses lines of
1.1 kristaps 65: .Xr man 7
1.17 kristaps 66: input into an abstract syntax tree (AST).
1.1 kristaps 67: .Pp
68: In general, applications initiate a parsing sequence with
69: .Fn man_alloc ,
1.7 kristaps 70: parse each line in a document with
1.1 kristaps 71: .Fn man_parseln ,
72: close the parsing session with
73: .Fn man_endparse ,
74: operate over the syntax tree returned by
1.7 kristaps 75: .Fn man_node
1.1 kristaps 76: and
77: .Fn man_meta ,
78: then free all allocated memory with
79: .Fn man_free .
80: The
81: .Fn man_reset
82: function may be used in order to reset the parser for another input
1.17 kristaps 83: sequence.
1.13 kristaps 84: .Pp
85: Beyond the full set of macros defined in
86: .Xr man 7 ,
87: the
88: .Nm
1.26 kristaps 89: library also accepts the following macro:
1.1 kristaps 90: .Pp
1.13 kristaps 91: .Bl -tag -width Ds -compact
92: .It PD
1.26 kristaps 93: Has no effect.
1.13 kristaps 94: Handled as a current-scope line macro.
95: .El
1.1 kristaps 96: .Ss Types
1.12 kristaps 97: .Bl -ohang
1.1 kristaps 98: .It Vt struct man
1.25 kristaps 99: An opaque type.
1.1 kristaps 100: Its values are only used privately within the library.
101: .It Vt struct man_node
1.17 kristaps 102: A parsed node.
1.7 kristaps 103: See
1.1 kristaps 104: .Sx Abstract Syntax Tree
105: for details.
106: .El
107: .Ss Functions
1.29 ! kristaps 108: If
! 109: .Fn man_addspan ,
! 110: .Fn man_parseln ,
! 111: or
! 112: .Fn man_endparse
! 113: return 0, calls to any function but
! 114: .Fn man_reset
! 115: or
! 116: .Fn man_free
! 117: will raise an assertion.
1.12 kristaps 118: .Bl -ohang
1.28 kristaps 119: .It Fn man_addspan
120: Add a table span to the parsing stream.
121: Returns 0 on failure, 1 on success.
1.1 kristaps 122: .It Fn man_alloc
1.17 kristaps 123: Allocates a parsing structure.
124: The
1.1 kristaps 125: .Fa data
1.18 kristaps 126: pointer is passed to
127: .Fa msgs .
1.29 ! kristaps 128: Always returns a valid pointer.
! 129: The pointer must be freed with
1.1 kristaps 130: .Fn man_free .
131: .It Fn man_reset
1.17 kristaps 132: Reset the parser for another parse routine.
133: After its use,
1.1 kristaps 134: .Fn man_parseln
135: behaves as if invoked for the first time.
136: .It Fn man_free
1.17 kristaps 137: Free all resources of a parser.
138: The pointer is no longer valid after invocation.
1.1 kristaps 139: .It Fn man_parseln
1.17 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.1 kristaps 144: .Fa buf
145: is modified by this function.
146: .It Fn man_endparse
1.17 kristaps 147: Signals that the parse is complete.
148: Returns 0 on failure, 1 on success.
1.1 kristaps 149: .It Fn man_node
1.17 kristaps 150: Returns the first node of the parse.
1.1 kristaps 151: .It Fn man_meta
1.17 kristaps 152: Returns the document's parsed meta-data.
1.1 kristaps 153: .El
154: .Ss Variables
155: The following variables are also defined:
1.12 kristaps 156: .Bl -ohang
1.1 kristaps 157: .It Va man_macronames
158: An array of string-ified token names.
159: .El
160: .Ss Abstract Syntax Tree
1.7 kristaps 161: The
1.1 kristaps 162: .Nm
163: functions produce an abstract syntax tree (AST) describing input in a
1.17 kristaps 164: regular form.
165: It may be reviewed at any time with
1.1 kristaps 166: .Fn man_nodes ;
167: however, if called before
168: .Fn man_endparse ,
169: or after
1.7 kristaps 170: .Fn man_endparse
1.1 kristaps 171: or
172: .Fn man_parseln
1.7 kristaps 173: fail, it may be incomplete.
1.1 kristaps 174: .Pp
1.17 kristaps 175: This AST is governed by the ontological rules dictated in
1.1 kristaps 176: .Xr man 7
1.7 kristaps 177: and derives its terminology accordingly.
1.1 kristaps 178: .Pp
1.7 kristaps 179: The AST is composed of
1.1 kristaps 180: .Vt struct man_node
1.17 kristaps 181: nodes with element, root and text types as declared by the
1.1 kristaps 182: .Va type
1.17 kristaps 183: field.
184: Each node also provides its parse point (the
1.1 kristaps 185: .Va line ,
186: .Va sec ,
187: and
188: .Va pos
189: fields), its position in the tree (the
190: .Va parent ,
191: .Va child ,
1.7 kristaps 192: .Va next
1.1 kristaps 193: and
1.7 kristaps 194: .Va prev
1.1 kristaps 195: fields) and some type-specific data.
196: .Pp
197: The tree itself is arranged according to the following normal form,
198: where capitalised non-terminals represent nodes.
199: .Pp
1.12 kristaps 200: .Bl -tag -width "ELEMENTXX" -compact
1.1 kristaps 201: .It ROOT
202: \(<- mnode+
203: .It mnode
1.8 kristaps 204: \(<- ELEMENT | TEXT | BLOCK
205: .It BLOCK
206: \(<- HEAD BODY
207: .It HEAD
208: \(<- mnode*
209: .It BODY
210: \(<- mnode*
1.1 kristaps 211: .It ELEMENT
212: \(<- ELEMENT | TEXT*
213: .It TEXT
214: \(<- [[:alpha:]]*
215: .El
216: .Pp
217: The only elements capable of nesting other elements are those with
218: next-lint scope as documented in
219: .Xr man 7 .
220: .Sh EXAMPLES
221: The following example reads lines from stdin and parses them, operating
1.7 kristaps 222: on the finished parse tree with
1.1 kristaps 223: .Fn parsed .
1.12 kristaps 224: This example does not error-check nor free memory upon failure.
225: .Bd -literal -offset indent
1.21 kristaps 226: struct regset regs;
1.1 kristaps 227: struct man *man;
228: struct man_node *node;
229: char *buf;
230: size_t len;
231: int line;
232:
1.21 kristaps 233: bzero(®s, sizeof(struct regset));
1.1 kristaps 234: line = 1;
1.24 schwarze 235: man = man_alloc(®s, NULL, NULL);
1.12 kristaps 236: buf = NULL;
237: alloc_len = 0;
1.1 kristaps 238:
1.12 kristaps 239: while ((len = getline(&buf, &alloc_len, stdin)) >= 0) {
240: if (len && buflen[len - 1] = '\en')
241: buf[len - 1] = '\e0';
242: if ( ! man_parseln(man, line, buf))
243: errx(1, "man_parseln");
244: line++;
1.1 kristaps 245: }
246:
1.12 kristaps 247: free(buf);
248:
1.1 kristaps 249: if ( ! man_endparse(man))
1.12 kristaps 250: errx(1, "man_endparse");
1.1 kristaps 251: if (NULL == (node = man_node(man)))
1.12 kristaps 252: errx(1, "man_node");
1.1 kristaps 253:
254: parsed(man, node);
255: man_free(man);
256: .Ed
1.17 kristaps 257: .Pp
1.25 kristaps 258: To compile this, execute
259: .Pp
1.27 kristaps 260: .Dl % cc main.c libman.a libmandoc.a
1.25 kristaps 261: .Pp
262: where
1.17 kristaps 263: .Pa main.c
1.25 kristaps 264: is the example file.
1.1 kristaps 265: .Sh SEE ALSO
266: .Xr mandoc 1 ,
267: .Xr man 7
268: .Sh AUTHORS
269: The
270: .Nm
1.17 kristaps 271: library was written by
1.12 kristaps 272: .An Kristaps Dzonsons Aq kristaps@bsd.lv .
CVSweb
![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to man.3 CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [cvsweb.bsd.lv] / mandoc