man.3

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