.\"	$Id: roff.3,v 1.6 2011/01/04 22:28:17 schwarze Exp $
.\"
.\" Copyright (c) 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv>
.\"
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.Dd $Mdocdate: January 4 2011 $
.Dt ROFF 3
.Os
.Sh NAME
.Nm roff ,
.Nm roff_alloc ,
.Nm roff_endparse ,
.Nm roff_free ,
.Nm roff_parseln ,
.Nm roff_reset ,
.Nm roff_span
.Nd roff macro compiler library
.Sh SYNOPSIS
.In mandoc.h
.In roff.h
.Ft "struct roff *"
.Fo roff_alloc
.Fa "struct regset *regs"
.Fa "void *data"
.Fa "mandocmsg msgs"
.Fc
.Ft void
.Fn roff_endparse "struct roff *roff"
.Ft void
.Fn roff_free "struct roff *roff"
.Ft "enum rofferr"
.Fo roff_parseln
.Fa "struct roff *roff"
.Fa "int line"
.Fa "char **bufp"
.Fa "size_t *bufsz"
.Fa "int pos"
.Fa "int *offs"
.Fc
.Ft void
.Fn roff_reset "struct roff *roff"
.Ft "const struct tbl_span *"
.Fn roff_span "const struct roff *roff"
.Sh DESCRIPTION
The
.Nm
library processes lines of
.Xr roff 7
input.
.Pp
In general, applications initiate a parsing sequence with
.Fn roff_alloc ,
parse each line in a document with
.Fn roff_parseln ,
close the parsing session with
.Fn roff_endparse ,
and finally free all allocated memory with
.Fn roff_free .
The
.Fn roff_reset
function may be used in order to reset the parser for another input
sequence.
.Pp
The
.Fn roff_parseln
function should be invoked before passing a line into the
.Xr mdoc 3
or
.Xr man 3
libraries.
.Pp
See the
.Sx EXAMPLES
section for a full example.
.Sh REFERENCE
This section further defines the
.Sx Types
and
.Sx Functions
available to programmers.
.Ss Types
Functions (see
.Sx Functions )
may use the following types:
.Bl -ohang
.It Vt "enum rofferr"
Instructions for further processing to the caller of
.Fn roff_parseln .
.It Vt struct roff
An opaque type defined in
.Pa roff.c .
Its values are only used privately within the library.
.It Vt mandocmsg
A function callback type defined in
.Pa mandoc.h .
.El
.Ss Functions
Function descriptions follow:
.Bl -ohang
.It Fn roff_alloc
Allocates a parsing structure.
The
.Fa data
pointer is passed to
.Fa msgs .
Returns NULL on failure.
If non-NULL, the pointer must be freed with
.Fn roff_free .
.It Fn roff_reset
Reset the parser for another parse routine.
After its use,
.Fn roff_parseln
behaves as if invoked for the first time.
.It Fn roff_free
Free all resources of a parser.
The pointer is no longer valid after invocation.
.It Fn roff_parseln
Parse a nil-terminated line of input.
The character array
.Fa bufp
may be modified or reallocated within this function.
In the latter case,
.Fa bufsz
will be modified accordingly.
The
.Fa offs
pointer will be modified if the line start during subsequent processing
of the line is not at the zeroth index.
This line should not contain the trailing newline.
Returns 0 on failure, 1 on success.
.It Fn roff_endparse
Signals that the parse is complete.
.It Fn roff_span
If
.Fn roff_parseln
returned
.Va ROFF_TBL ,
return the last parsed table row.
Returns NULL otherwise.
.El
.Sh EXAMPLES
See
.Pa main.c
in the source distribution for an example of usage.
.Sh SEE ALSO
.Xr mandoc 1 ,
.Xr man 3 ,
.Xr mdoc 3 ,
.Xr roff 7
.Sh AUTHORS
The
.Nm
library was written by
.An Kristaps Dzonsons Aq kristaps@bsd.lv .
.Sh BUGS
The implementation of user-defined strings needs improvement:
.Bl -dash
.It
String values are taken literally and are not interpreted.
.It
Parsing of quoted strings is incomplete.
.It
The stings are stored internally using a singly linked list,
which is fine for small numbers of strings,
but ineffient when handling many strings.
.El