ROFF(3)

NAME

roff, roff_alloc, roff_endparse, roff_free, roff_parseln, roff_reset — roff macro compiler library

SYNOPSIS

#include <mandoc.h>

#include <roff.h>

struct roff *

roff_alloc(struct regset *regs, mandocmsg msgs, void *data);

int

roff_endparse(struct roff *roff);

void

roff_free(struct roff *roff);

enum rofferr

roff_parseln(struct roff *roff, int line, char **bufp, size_t *bufsz, int pos, int *offs);

void

roff_reset(struct roff *roff);

DESCRIPTION

The roff library processes lines of roff(7) input.

In general, applications initiate a parsing sequence with roff_alloc(), parse each line in a document with roff_parseln(), close the parsing session with roff_endparse(), and finally free all allocated memory with roff_free(). The roff_reset() function may be used in order to reset the parser for another input sequence.

The roff_parseln() function should be invoked before passing a line into the mdoc(3) or man(3) libraries.

See the EXAMPLES section for a full example.

REFERENCE

This section further defines the Types and Functions available to programmers.

Types

Functions (see Functions) may use the following types:

enum rofferr

Instructions for further processing to the caller of roff_parseln().

struct roff

An opaque type defined in roff.c. Its values are only used privately within the library.

mandocmsg

A function callback type defined in mandoc.h.

Functions

Function descriptions follow:

roff_alloc()

Allocates a parsing structure. The data pointer is passed to msgs. The pflags arguments are defined in roff.h. Returns NULL on failure. If non-NULL, the pointer must be freed with roff_free().

roff_reset()

Reset the parser for another parse routine. After its use, roff_parseln() behaves as if invoked for the first time.

roff_free()

Free all resources of a parser. The pointer is no longer valid after invocation.

roff_parseln()

Parse a nil-terminated line of input. The character array bufp may be modified or reallocated within this function. In the latter case, bufsz will be modified accordingly. The 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.

roff_endparse()

Signals that the parse is complete. Returns 0 on failure, 1 on success.

EXAMPLES

See main.c in the source distribution for an example of usage.