roff.3

   1 .\"     $Id: roff.3,v 1.3 2010/06/27 15:52:41 kristaps 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: June 27 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 .Sh DESCRIPTION
  54 The
  55 .Nm
  56 library processes lines of
  57 .Xr roff 7
  58 input.
  59 .Pp
  60 In general, applications initiate a parsing sequence with
  61 .Fn roff_alloc ,
  62 parse each line in a document with
  63 .Fn roff_parseln ,
  64 close the parsing session with
  65 .Fn roff_endparse ,
  66 and finally free all allocated memory with
  67 .Fn roff_free .
  68 The
  69 .Fn roff_reset
  70 function may be used in order to reset the parser for another input
  71 sequence.
  72 .Pp
  73 The
  74 .Fn roff_parseln
  75 function should be invoked before passing a line into the
  76 .Xr mdoc 3
  77 or
  78 .Xr man 3
  79 libraries.
  80 .Pp
  81 See the
  82 .Sx EXAMPLES
  83 section for a full example.
  84 .Sh REFERENCE
  85 This section further defines the
  86 .Sx Types
  87 and
  88 .Sx Functions
  89 available to programmers.
  90 .Ss Types
  91 Functions (see
  92 .Sx Functions )
  93 may use the following types:
  94 .Bl -ohang
  95 .It Vt "enum rofferr"
  96 Instructions for further processing to the caller of
  97 .Fn roff_parseln .
  98 .It Vt struct roff
  99 An opaque type defined in
 100 .Pa roff.c .
 101 Its values are only used privately within the library.
 102 .It Vt mandocmsg
 103 A function callback type defined in
 104 .Pa mandoc.h .
 105 .El
 106 .Ss Functions
 107 Function descriptions follow:
 108 .Bl -ohang
 109 .It Fn roff_alloc
 110 Allocates a parsing structure.
 111 The
 112 .Fa data
 113 pointer is passed to
 114 .Fa msgs .
 115 The
 116 .Fa pflags
 117 arguments are defined in
 118 .Pa roff.h .
 119 Returns NULL on failure.
 120 If non-NULL, the pointer must be freed with
 121 .Fn roff_free .
 122 .It Fn roff_reset
 123 Reset the parser for another parse routine.
 124 After its use,
 125 .Fn roff_parseln
 126 behaves as if invoked for the first time.
 127 .It Fn roff_free
 128 Free all resources of a parser.
 129 The pointer is no longer valid after invocation.
 130 .It Fn roff_parseln
 131 Parse a nil-terminated line of input.
 132 The character array
 133 .Fa bufp
 134 may be modified or reallocated within this function.
 135 In the latter case,
 136 .Fa bufsz
 137 will be modified accordingly.
 138 The
 139 .Fa offs
 140 pointer will be modified if the line start during subsequent processing
 141 of the line is not at the zeroth index.
 142 This line should not contain the trailing newline.
 143 Returns 0 on failure, 1 on success.
 144 .It Fn roff_endparse
 145 Signals that the parse is complete.
 146 Returns 0 on failure, 1 on success.
 147 .El
 148 .Sh EXAMPLES
 149 See
 150 .Pa main.c
 151 in the source distribution for an example of usage.
 152 .Sh SEE ALSO
 153 .Xr mandoc 1 ,
 154 .Xr man 3 ,
 155 .Xr mdoc 3 ,
 156 .Xr roff 7
 157 .Sh AUTHORS
 158 The
 159 .Nm
 160 library was written by
 161 .An Kristaps Dzonsons Aq kristaps@bsd.lv .