roff.3

   1 .\"     $Id: roff.3,v 1.4 2010/07/03 16:02:12 schwarze Exp $
   2 .\"
   3 .\" Copyright (c) 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: July 3 2010 $
  18 .Dt ROFF 3
  19 .Os
  20 .Sh NAME
  21 .Nm roff ,
  22 .Nm roff_alloc ,
  23 .Nm roff_endparse ,
  24 .Nm roff_free ,
  25 .Nm roff_parseln ,
  26 .Nm roff_reset
  27 .Nd roff macro compiler library
  28 .Sh SYNOPSIS
  29 .In mandoc.h
  30 .In regs.h
  31 .In roff.h
  32 .Ft "struct roff *"
  33 .Fo roff_alloc
  34 .Fa "struct regset *regs"
  35 .Fa "mandocmsg msgs"
  36 .Fa "void *data"
  37 .Fc
  38 .Ft int
  39 .Fn roff_endparse "struct roff *roff"
  40 .Ft void
  41 .Fn roff_free "struct roff *roff"
  42 .Ft "enum rofferr"
  43 .Fo roff_parseln
  44 .Fa "struct roff *roff"
  45 .Fa "int line"
  46 .Fa "char **bufp"
  47 .Fa "size_t *bufsz"
  48 .Fa "int pos"
  49 .Fa "int *offs"
  50 .Fc
  51 .Ft void
  52 .Fn roff_reset "struct roff *roff"
  53 .In regs.h
  54 .Ft "char *"
  55 .Fn roff_setstr "const char *name" "const char *string"
  56 .Ft "char *"
  57 .Fn roff_getstr "const char *name"
  58 .Ft "char *"
  59 .Fn roff_getstrn "const char *name" "size_t len"
  60 .Ft void
  61 .Fn roff_freestr void
  62 .Sh DESCRIPTION
  63 The
  64 .Nm
  65 library processes lines of
  66 .Xr roff 7
  67 input.
  68 .Pp
  69 In general, applications initiate a parsing sequence with
  70 .Fn roff_alloc ,
  71 parse each line in a document with
  72 .Fn roff_parseln ,
  73 close the parsing session with
  74 .Fn roff_endparse ,
  75 and finally free all allocated memory with
  76 .Fn roff_free .
  77 The
  78 .Fn roff_reset
  79 function may be used in order to reset the parser for another input
  80 sequence.
  81 .Pp
  82 The
  83 .Fn roff_parseln
  84 function should be invoked before passing a line into the
  85 .Xr mdoc 3
  86 or
  87 .Xr man 3
  88 libraries.
  89 .Pp
  90 See the
  91 .Sx EXAMPLES
  92 section for a full example.
  93 .Sh REFERENCE
  94 This section further defines the
  95 .Sx Types
  96 and
  97 .Sx Functions
  98 available to programmers.
  99 .Ss Types
 100 Functions (see
 101 .Sx Functions )
 102 may use the following types:
 103 .Bl -ohang
 104 .It Vt "enum rofferr"
 105 Instructions for further processing to the caller of
 106 .Fn roff_parseln .
 107 .It Vt struct roff
 108 An opaque type defined in
 109 .Pa roff.c .
 110 Its values are only used privately within the library.
 111 .It Vt mandocmsg
 112 A function callback type defined in
 113 .Pa mandoc.h .
 114 .El
 115 .Ss Functions
 116 Function descriptions follow:
 117 .Bl -ohang
 118 .It Fn roff_alloc
 119 Allocates a parsing structure.
 120 The
 121 .Fa data
 122 pointer is passed to
 123 .Fa msgs .
 124 The
 125 .Fa pflags
 126 arguments are defined in
 127 .Pa roff.h .
 128 Returns NULL on failure.
 129 If non-NULL, the pointer must be freed with
 130 .Fn roff_free .
 131 .It Fn roff_reset
 132 Reset the parser for another parse routine.
 133 After its use,
 134 .Fn roff_parseln
 135 behaves as if invoked for the first time.
 136 .It Fn roff_free
 137 Free all resources of a parser.
 138 The pointer is no longer valid after invocation.
 139 .It Fn roff_parseln
 140 Parse a nil-terminated line of input.
 141 The character array
 142 .Fa bufp
 143 may be modified or reallocated within this function.
 144 In the latter case,
 145 .Fa bufsz
 146 will be modified accordingly.
 147 The
 148 .Fa offs
 149 pointer will be modified if the line start during subsequent processing
 150 of the line is not at the zeroth index.
 151 This line should not contain the trailing newline.
 152 Returns 0 on failure, 1 on success.
 153 .It Fn roff_endparse
 154 Signals that the parse is complete.
 155 Returns 0 on failure, 1 on success.
 156 .El
 157 .Sh USER-DEFINED STRINGS
 158 Strings defined by the
 159 .Xr roff 7
 160 .Sx \&ds
 161 instruction are saved using the
 162 .Fn roff_setstr
 163 function and retrieved using the
 164 .Fn roff_getstr
 165 and
 166 .Fn roff_getstrn
 167 functions.
 168 .Pp
 169 These functions take the name of the string to be accessed
 170 as their first argument.
 171 While
 172 .Fn roff_getstr
 173 requires the name to be null-terminated,
 174 .Fn roff_getstrn
 175 accepts non-terminated strings, but requires the length of the name
 176 to be specified.
 177 .Pp
 178 The second argument to
 179 .Fn roff_setstr
 180 is the new value of the string.
 181 It will be copied to internal storage, so both pointers to constant
 182 strings and pointers to volatile storage are acceptable.
 183 .Pp
 184 All of these functions return a pointer to the new value of the string
 185 in internal storage, which should be considered read-only, so use
 186 .Xr strdup 3
 187 on it as appropriate.
 188 The read functions return NULL when a string of the specified name
 189 is not available or empty, and
 190 .Fn roff_setstr
 191 returns NULL when memory allocation fails.
 192 In the latter case, the string will remain unset.
 193 .Pp
 194 The function
 195 .Fn roff_freestr
 196 clears all user-defined strings.
 197 It always succeeds.
 198 Both
 199 .Fn roff_reset
 200 and
 201 .Fn roff_free
 202 call it.
 203 .Sh EXAMPLES
 204 See
 205 .Pa main.c
 206 in the source distribution for an example of usage.
 207 .Sh SEE ALSO
 208 .Xr mandoc 1 ,
 209 .Xr man 3 ,
 210 .Xr mdoc 3 ,
 211 .Xr roff 7
 212 .Sh AUTHORS
 213 The
 214 .Nm
 215 library was written by
 216 .An Kristaps Dzonsons Aq kristaps@bsd.lv .
 217 .Sh BUGS
 218 The implementation of user-defined strings needs improvement:
 219 .Bl -dash
 220 .It
 221 String values are taken literally and are not interpreted.
 222 .It
 223 Parsing of quoted strings is incomplete.
 224 .It
 225 The stings are stored internally using a singly linked list,
 226 which is fine for small numbers of strings,
 227 but ineffient when handling many strings.
 228 .El