Return to mandoc.3 CVS log | Up to [cvsweb.bsd.lv] / mandoc |
version 1.30, 2015/01/15 02:29:26 | version 1.33, 2015/10/13 22:59:54 | ||
---|---|---|---|
|
|
||
.\" $Id$ | .\" $Id$ | ||
.\" | .\" | ||
.\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv> | .\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv> | ||
.\" Copyright (c) 2010 Ingo Schwarze <schwarze@openbsd.org> | .\" Copyright (c) 2010, 2013, 2014, 2015 Ingo Schwarze <schwarze@openbsd.org> | ||
.\" | .\" | ||
.\" Permission to use, copy, modify, and distribute this software for any | .\" Permission to use, copy, modify, and distribute this software for any | ||
.\" purpose with or without fee is hereby granted, provided that the above | .\" purpose with or without fee is hereby granted, provided that the above | ||
|
|
||
.Nm mparse_result , | .Nm mparse_result , | ||
.Nm mparse_strerror , | .Nm mparse_strerror , | ||
.Nm mparse_strlevel | .Nm mparse_strlevel | ||
.Nm mparse_wait , | |||
.Nd mandoc macro compiler library | .Nd mandoc macro compiler library | ||
.Sh LIBRARY | |||
.Lb libmandoc | |||
.Sh SYNOPSIS | .Sh SYNOPSIS | ||
.In sys/types.h | .In sys/types.h | ||
.In mandoc.h | .In mandoc.h | ||
.Pp | |||
.Fd "#define ASCII_NBRSP" | .Fd "#define ASCII_NBRSP" | ||
.Fd "#define ASCII_HYPH" | .Fd "#define ASCII_HYPH" | ||
.Fd "#define ASCII_BREAK" | .Fd "#define ASCII_BREAK" | ||
|
|
||
.Fa "int options" | .Fa "int options" | ||
.Fa "enum mandoclevel wlevel" | .Fa "enum mandoclevel wlevel" | ||
.Fa "mandocmsg mmsg" | .Fa "mandocmsg mmsg" | ||
.Fa "const struct mchars *mchars" | |||
.Fa "char *defos" | .Fa "char *defos" | ||
.Fc | .Fc | ||
.Ft void | .Ft void | ||
|
|
||
.Fo mparse_strlevel | .Fo mparse_strlevel | ||
.Fa "enum mandoclevel" | .Fa "enum mandoclevel" | ||
.Fc | .Fc | ||
.Ft "enum mandoclevel" | |||
.Fo mparse_wait | |||
.Fa "struct mparse *parse" | |||
.Fc | |||
.In sys/types.h | .In sys/types.h | ||
.In mandoc.h | .In mandoc.h | ||
.In mdoc.h | .In mdoc.h | ||
|
|
||
and | and | ||
.Fn mparse_alloc ; | .Fn mparse_alloc ; | ||
.It | .It | ||
parse files with | open a file with | ||
.Fn mparse_open | .Xr open 2 | ||
and | or | ||
.Fn mparse_open ; | |||
.It | |||
parse it with | |||
.Fn mparse_readfd ; | .Fn mparse_readfd ; | ||
.It | .It | ||
retrieve a parsed syntax tree, if the parse was successful, with | retrieve the syntax tree with | ||
.Fn mparse_result ; | .Fn mparse_result ; | ||
.It | .It | ||
iterate over parse nodes with | iterate over parse nodes with | ||
|
|
||
.Ss Types | .Ss Types | ||
.Bl -ohang | .Bl -ohang | ||
.It Vt "enum mandocerr" | .It Vt "enum mandocerr" | ||
A fatal error, error, or warning message during parsing. | An error or warning message during parsing. | ||
.It Vt "enum mandoclevel" | .It Vt "enum mandoclevel" | ||
A classification of an | A classification of an | ||
.Vt "enum mandocerr" | .Vt "enum mandocerr" | ||
as regards system operation. | as regards system operation. | ||
.It Vt "struct mchars" | |||
An opaque pointer to a a character table. | |||
Created with | |||
.Xr mchars_alloc 3 | |||
and freed with | |||
.Xr mchars_free 3 . | |||
.It Vt "struct mparse" | .It Vt "struct mparse" | ||
An opaque pointer to a running parse sequence. | An opaque pointer to a running parse sequence. | ||
Created with | Created with | ||
|
|
||
.Fn mparse_reset | .Fn mparse_reset | ||
is called between parses. | is called between parses. | ||
.It Vt "mandocmsg" | .It Vt "mandocmsg" | ||
A prototype for a function to handle fatal error, error, and warning | A prototype for a function to handle error and warning | ||
messages emitted by the parser. | messages emitted by the parser. | ||
.El | .El | ||
.Ss Functions | .Ss Functions | ||
|
|
||
to quickly build minimal databases. | to quickly build minimal databases. | ||
.It Ar wlevel | .It Ar wlevel | ||
Can be set to | Can be set to | ||
.Dv MANDOCLEVEL_FATAL , | .Dv MANDOCLEVEL_BADARG , | ||
.Dv MANDOCLEVEL_ERROR , | .Dv MANDOCLEVEL_ERROR , | ||
or | or | ||
.Dv MANDOCLEVEL_WARNING . | .Dv MANDOCLEVEL_WARNING . | ||
|
|
||
See | See | ||
.Pa main.c | .Pa main.c | ||
for an example. | for an example. | ||
.It Ar mchars | |||
An opaque pointer to a a character table obtained from | |||
.Xr mchars_alloc 3 . | |||
.It Ar defos | .It Ar defos | ||
A default string for the | A default string for the | ||
.Xr mdoc 7 | .Xr mdoc 7 | ||
|
|
||
implemented in | implemented in | ||
.Pa read.c . | .Pa read.c . | ||
.It Fn mparse_open | .It Fn mparse_open | ||
If the | Open the file for reading. | ||
If that fails and | |||
.Fa fname | .Fa fname | ||
ends in | does not already end in | ||
.Pa .gz , | .Ql .gz , | ||
open with | try again after appending | ||
.Xr gunzip 1 ; | .Ql .gz . | ||
otherwise, with | Save the information whether the file is zipped or not. | ||
.Xr open 2 . | |||
If | |||
.Xr open 2 | |||
fails, append | |||
.Pa .gz | |||
and try with | |||
.Xr gunzip 1 . | |||
Return a file descriptor open for reading in | Return a file descriptor open for reading in | ||
.Fa fd , | .Fa fd , | ||
or -1 on failure. | or -1 on failure. | ||
|
|
||
.Fn mparse_open . | .Fn mparse_open . | ||
Pass the associated filename in | Pass the associated filename in | ||
.Va fname . | .Va fname . | ||
Calls | |||
.Fn mparse_wait | |||
before returning. | |||
This function may be called multiple times with different parameters; however, | This function may be called multiple times with different parameters; however, | ||
.Fn mparse_reset | .Fn mparse_reset | ||
should be invoked between parses. | should be invoked between parses. | ||
|
|
||
.Pa read.c . | .Pa read.c . | ||
.It Fn mparse_result | .It Fn mparse_result | ||
Obtain the result of a parse. | Obtain the result of a parse. | ||
Only successful parses | One of the three pointers will be filled in. | ||
.Po | |||
i.e., those where | |||
.Fn mparse_readfd | |||
returned less than MANDOCLEVEL_FATAL | |||
.Pc | |||
should invoke this function, in which case one of the three pointers will | |||
be filled in. | |||
Declared in | Declared in | ||
.In mandoc.h , | .In mandoc.h , | ||
implemented in | implemented in | ||
|
|
||
.Pa read.c . | .Pa read.c . | ||
.It Fn mparse_strlevel | .It Fn mparse_strlevel | ||
Return a statically-allocated string representation of a level code. | Return a statically-allocated string representation of a level code. | ||
Declared in | |||
.In mandoc.h , | |||
implemented in | |||
.Pa read.c . | |||
.It Fn mparse_wait | |||
Bury a | |||
.Xr gunzip 1 | |||
child process that was spawned with | |||
.Fn mparse_open . | |||
To be called after the parse sequence is complete. | |||
Not needed after | |||
.Fn mparse_readfd , | |||
but does no harm in that case, either. | |||
Returns | |||
.Dv MANDOCLEVEL_OK | |||
on success and | |||
.Dv MANDOCLEVEL_SYSERR | |||
on failure, that is, when | |||
.Xr wait 2 | |||
fails, or when | |||
.Xr gunzip 1 | |||
died from a signal or exited with non-zero status. | |||
Declared in | Declared in | ||
.In mandoc.h , | .In mandoc.h , | ||
implemented in | implemented in |