contrib/mdocml/man.3

   1 .\"     $Id: man.3,v 1.29 2011/01/03 11:31:26 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 3 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 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.
 118 .Bl -ohang
 119 .It Fn man_addspan
 120 Add a table span to the parsing stream.
 121 Returns 0 on failure, 1 on success.
 122 .It Fn man_alloc
 123 Allocates a parsing structure.
 124 The
 125 .Fa data
 126 pointer is passed to
 127 .Fa msgs .
 128 Always returns a valid pointer.
 129 The pointer must be freed with
 130 .Fn man_free .
 131 .It Fn man_reset
 132 Reset the parser for another parse routine.
 133 After its use,
 134 .Fn man_parseln
 135 behaves as if invoked for the first time.
 136 .It Fn man_free
 137 Free all resources of a parser.
 138 The pointer is no longer valid after invocation.
 139 .It Fn man_parseln
 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
 144 .Fa buf
 145 is modified by this function.
 146 .It Fn man_endparse
 147 Signals that the parse is complete.
 148 Returns 0 on failure, 1 on success.
 149 .It Fn man_node
 150 Returns the first node of the parse.
 151 .It Fn man_meta
 152 Returns the document's parsed meta-data.
 153 .El
 154 .Ss Variables
 155 The following variables are also defined:
 156 .Bl -ohang
 157 .It Va man_macronames
 158 An array of string-ified token names.
 159 .El
 160 .Ss Abstract Syntax Tree
 161 The
 162 .Nm
 163 functions produce an abstract syntax tree (AST) describing input in a
 164 regular form.
 165 It may be reviewed at any time with
 166 .Fn man_nodes ;
 167 however, if called before
 168 .Fn man_endparse ,
 169 or after
 170 .Fn man_endparse
 171 or
 172 .Fn man_parseln
 173 fail, it may be incomplete.
 174 .Pp
 175 This AST is governed by the ontological rules dictated in
 176 .Xr man 7
 177 and derives its terminology accordingly.
 178 .Pp
 179 The AST is composed of
 180 .Vt struct man_node
 181 nodes with element, root and text types as declared by the
 182 .Va type
 183 field.
 184 Each node also provides its parse point (the
 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 ,
 192 .Va next
 193 and
 194 .Va prev
 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
 200 .Bl -tag -width "ELEMENTXX" -compact
 201 .It ROOT
 202 \(<- mnode+
 203 .It mnode
 204 \(<- ELEMENT | TEXT | BLOCK
 205 .It BLOCK
 206 \(<- HEAD BODY
 207 .It HEAD
 208 \(<- mnode*
 209 .It BODY
 210 \(<- mnode*
 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
 222 on the finished parse tree with
 223 .Fn parsed .
 224 This example does not error-check nor free memory upon failure.
 225 .Bd -literal -offset indent
 226 struct regset regs;
 227 struct man *man;
 228 struct man_node *node;
 229 char *buf;
 230 size_t len;
 231 int line;
 232
 233 bzero(&regs, sizeof(struct regset));
 234 line = 1;
 235 man = man_alloc(&regs, NULL, NULL);
 236 buf = NULL;
 237 alloc_len = 0;
 238
 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++;
 245 }
 246
 247 free(buf);
 248
 249 if ( ! man_endparse(man))
 250     errx(1, "man_endparse");
 251 if (NULL == (node = man_node(man)))
 252     errx(1, "man_node");
 253
 254 parsed(man, node);
 255 man_free(man);
 256 .Ed
 257 .Pp
 258 To compile this, execute
 259 .Pp
 260 .Dl % cc main.c libman.a libmandoc.a
 261 .Pp
 262 where
 263 .Pa main.c
 264 is the example file.
 265 .Sh SEE ALSO
 266 .Xr mandoc 1 ,
 267 .Xr man 7
 268 .Sh AUTHORS
 269 The
 270 .Nm
 271 library was written by
 272 .An Kristaps Dzonsons Aq kristaps@bsd.lv .