version 1.26, 2014/09/03 23:21:47 |
version 1.35, 2016/01/08 02:53:13 |
|
|
.\" $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" |
|
|
.Fo mparse_keep |
.Fo mparse_keep |
.Fa "struct mparse *parse" |
.Fa "struct mparse *parse" |
.Fc |
.Fc |
.Ft "enum mandoclevel" |
.Ft int |
.Fo mparse_open |
.Fo mparse_open |
.Fa "struct mparse *parse" |
.Fa "struct mparse *parse" |
.Fa "int *fd" |
|
.Fa "const char *fname" |
.Fa "const char *fname" |
.Fa "pid_t *child_pid" |
|
.Fc |
.Fc |
.Ft "enum mandoclevel" |
.Ft "enum mandoclevel" |
.Fo mparse_readfd |
.Fo mparse_readfd |
|
|
.Fo mparse_strlevel |
.Fo mparse_strlevel |
.Fa "enum mandoclevel" |
.Fa "enum mandoclevel" |
.Fc |
.Fc |
.Ft "enum mandoclevel" |
|
.Fo mparse_wait |
|
.Fa "struct mparse *parse" |
|
.Fa "pid_t child_pid" |
|
.Fc |
|
.In sys/types.h |
.In sys/types.h |
.In mandoc.h |
.In mandoc.h |
.In mdoc.h |
.In mdoc.h |
Line 173 The following describes a general parse sequence: |
|
Line 164 The following describes a general parse sequence: |
|
.Bl -enum |
.Bl -enum |
.It |
.It |
initiate a parsing sequence with |
initiate a parsing sequence with |
|
.Xr mchars_alloc 3 |
|
and |
.Fn mparse_alloc ; |
.Fn mparse_alloc ; |
.It |
.It |
parse files or file descriptors with |
open a file with |
|
.Xr open 2 |
|
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 |
close it with |
|
.Xr close 2 ; |
|
.It |
|
retrieve the syntax tree with |
.Fn mparse_result ; |
.Fn mparse_result ; |
.It |
.It |
iterate over parse nodes with |
iterate over parse nodes with |
|
|
.Fn man_node ; |
.Fn man_node ; |
.It |
.It |
free all allocated memory with |
free all allocated memory with |
.Fn mparse_free , |
.Fn mparse_free |
|
and |
|
.Xr mchars_free 3 , |
or invoke |
or invoke |
.Fn mparse_reset |
.Fn mparse_reset |
and parse new files. |
and parse new files. |
|
|
.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" |
Line 218 This may be used across parsed input if |
|
Line 221 This may be used across parsed input if |
|
.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 |
Line 322 This is for example useful in |
|
Line 325 This is for example useful in |
|
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 . |
|
|
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 . |
Return a file descriptor open for reading or -1 on failure. |
Return a file descriptor open for reading in |
|
.Fa fd , |
|
or -1 on failure. |
|
It can be passed to |
It can be passed to |
.Fn mparse_readfd |
.Fn mparse_readfd |
or used directly. |
or used directly. |
If applicable, return the |
|
.Xr gunzip 1 |
|
child process ID in |
|
.Fa child_pid , |
|
or otherwise 0. |
|
If non-zero, it should be passed to |
|
.Fn mparse_wait |
|
after completing the parse sequence. |
|
Declared in |
Declared in |
.In mandoc.h , |
.In mandoc.h , |
implemented in |
implemented in |
.Pa read.c . |
.Pa read.c . |
.It Fn mparse_readfd |
.It Fn mparse_readfd |
Parse a file or file descriptor. |
Parse a file descriptor opened with |
If |
.Xr open 2 |
.Va fd |
or |
is -1, |
.Fn mparse_open . |
.Va fname |
Pass the associated filename in |
is opened for reading. |
.Va fname . |
Otherwise, |
This function may be called multiple times with different parameters; however, |
.Va fname |
.Xr close 2 |
is assumed to be the name associated with |
and |
.Va fd . |
|
This 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. |
Declared in |
Declared in |
|
|
.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 |
|
.Fa child_pid |
|
that was spawned with |
|
.Fn mparse_open . |
|
To be called after the parse sequence is complete. |
|
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 |