man.3

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