aboutsummaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
Diffstat (limited to 'doc')
-rw-r--r--doc/GRECS_SETUP.3131
-rw-r--r--doc/Makefile.am33
-rw-r--r--doc/grecs-syntax.texi10
-rw-r--r--doc/grecs_asprintf.390
-rw-r--r--doc/grecs_config.5343
-rw-r--r--doc/grecs_error.3132
-rw-r--r--doc/grecs_format_locus.368
-rw-r--r--doc/grecs_format_node.3102
-rw-r--r--doc/grecs_format_node_path.371
-rw-r--r--doc/grecs_format_value.366
-rw-r--r--doc/grecs_include_path_setup.368
-rw-r--r--doc/grecs_malloc.3129
-rw-r--r--doc/grecs_node_free.363
-rw-r--r--doc/grecs_parse.3185
-rw-r--r--doc/grecs_stmt_path.5123
-rw-r--r--doc/grecs_strdup.370
-rw-r--r--doc/grecs_tree_free.361
-rw-r--r--doc/tmpl.354
18 files changed, 1794 insertions, 5 deletions
diff --git a/doc/GRECS_SETUP.3 b/doc/GRECS_SETUP.3
new file mode 100644
index 0000000..23c0ad5
--- /dev/null
+++ b/doc/GRECS_SETUP.3
@@ -0,0 +1,131 @@
+.\" This file is part of grecs -*- nroff -*-
+.\" Copyright (C) 2007, 2009-2011 Sergey Poznyakoff
+.\"
+.\" Grecs is free software; you can redistribute it and/or modify
+.\" it under the terms of the GNU General Public License as published by
+.\" the Free Software Foundation; either version 3, or (at your option)
+.\" any later version.
+.\"
+.\" Grecs is distributed in the hope that it will be useful,
+.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
+.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+.\" GNU General Public License for more details.
+.\"
+.\" You should have received a copy of the GNU General Public License
+.\" along with Grecs. If not, see <http://www.gnu.org/licenses/>.
+.\" This file is part of SLB.
+.\" Copyright (C) 2011 Sergey Poznyakoff
+.\"
+.TH GRECS_SETUP 3 "May 4, 2011" "GRECS" "Grecs User Reference"
+.SH NAME
+GRECS_SETUP \- Initialize \fBgrecs\fR submodule.
+.SH SYNOPSIS
+.BI "GRECS_SETUP(" "dir" ", " "options" ", " "pp-setup-file" )
+.SH DESCRIPTION
+The \fBGRECS_SETUP\fR macro is invoked from the host project's
+\fBconfigure.ac\fR. It initializes the \fBgrecs\fR submodule
+variables for compilation within that project.
+.PP
+All arguments are optional.
+.PP
+The
+.I dir
+argument specifies the directory, relative to the source tree top,
+where \fBgrecs\fR has been cloned. If omitted, \fBgrecs\fR is assumed.
+.sp
+For example, if \fBgrecs\fR was cloned using the following command:
+.sp
+.nf
+ git clone ssh://git.gnu.org.ua/gitroot/grecs.git lib/grecs
+.fi
+.sp
+then the \fIdir\fR argument must be \fBlib/grecs\fR.
+.PP
+The
+.I options
+argument is a space-separated list of options. The following options
+are understood:
+.TP
+.B no-preproc
+Disable the use of preprocessor.
+.TP
+.B install
+Create and install shared library \fBlibgrecs.so\fR. Install the
+documentation as well.
+.TP
+.B std-pp-setup
+Install the standard \fBpp-setup\fR file.
+.TP
+.B pp-setup-option
+Add the
+.B --with-pp-setup-file
+option to the produced configuration file. This option allows user to
+control whether to install the \fBpp-setup\fR file.
+.TP
+.B tests
+Build tests.
+.TP
+.B getopt
+Add \fBgetopt.m4\fR to the distributed tarball. The file is located
+in \fIdir\fR/build-aux.
+.TP
+.B git2chg
+Add \fBgit2chg.awk\fR to the distributed tarball. The file is located
+in \fIdir\fR/build-aux.
+.PP
+The
+.I pp-setup-file
+argument supplies the pathname of the alternative preprocessor
+setup file. It is ignored if
+.B std-pp-setup option
+is given.
+.PP
+If neither
+.B std-pp-setup
+option, nor
+.I pp-setup-file
+parameter are supplied, no preprocessor setup file is installed.
+.SH EXAMPLE
+.SS "Default setup"
+.RS 4
+.nf
+GRECS_SETUP
+.fi
+.RE
+.SS "Complex setup"
+The library sources are in \fBlib/grecs\fR. Configure the testsuite
+and add the \fBgetopt.m4\fR file to the distribution. Install
+preprocessor setup file from \fBsrc/pp-setup\fR:
+.sp
+.RS 4
+.nf
+GRECS_SETUP(lib/grecs, [tests getopt], [$(top_srcdir)/src/pp-setup])
+.RE
+.SH "SEE ALSO"
+.BR getopt.m4 (5),
+.BR pp-setup (5).
+.SH AUTHORS
+Sergey Poznyakoff
+.SH "BUG REPORTS"
+Report bugs to <gray+grecs@gnu.org.ua>.
+.SH COLOPHON
+The \fBGrecs\fR library is constantly changing, so this manual page
+may be incorrect or out-of-date. For the latest copy of \fBGrecs\fR
+documentation, visit <http://www.gnu.org.ua/software/grecs>.
+.SH COPYRIGHT
+Copyright \(co 2011 Sergey Poznyakoff
+.br
+.na
+License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
+.br
+.ad
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+.\" Local variables:
+.\" eval: (add-hook 'write-file-hooks 'time-stamp)
+.\" time-stamp-start: ".TH [A-Z_][A-Z0-9_]* [0-9] \""
+.\" time-stamp-format: "%:B %:d, %:y"
+.\" time-stamp-end: "\""
+.\" time-stamp-line-limit: 20
+.\" end:
+
diff --git a/doc/Makefile.am b/doc/Makefile.am
new file mode 100644
index 0000000..9ee12bf
--- /dev/null
+++ b/doc/Makefile.am
@@ -0,0 +1,33 @@
+# This file is part of grecs - Gray's Extensible Configuration System
+# Copyright (C) 2007, 2009-2011 Sergey Poznyakoff
+#
+# Grecs is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 3, or (at your option)
+# any later version.
+#
+# Grecs is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with Grecs. If not, see <http://www.gnu.org/licenses/>.
+
+dist_man_MANS = \
+ GRECS_SETUP.3\
+ grecs_asprintf.3\
+ grecs_config.5\
+ grecs_error.3\
+ grecs_format_locus.3\
+ grecs_format_node_path.3\
+ grecs_format_node.3\
+ grecs_format_value.3\
+ grecs_include_path_setup.3\
+ grecs_malloc.3\
+ grecs_node_free.3\
+ grecs_parse.3\
+ grecs_stmt_path.5\
+ grecs_strdup.3\
+ grecs_tree_free.3
+
diff --git a/doc/grecs-syntax.texi b/doc/grecs-syntax.texi
index b95a0ba..5c7c5ca 100644
--- a/doc/grecs-syntax.texi
+++ b/doc/grecs-syntax.texi
@@ -94,8 +94,8 @@ path.
The default include search path is:
@enumerate 1
-@item @file{@var{prefix}/share/slb/@value{VERSION}/include}
-@item @file{@var{prefix}/share/slb/include}
+@item @file{@var{prefix}/share/@value{PROGNAME}/@value{VERSION}/include}
+@item @file{@var{prefix}/share/@value{PROGNAME}/include}
@end enumerate
@noindent
@@ -345,12 +345,12 @@ diagnostic.
An initial set of macro definitions is supplied by the
@file{pp-setup} file, located in
-@file{@var{$prefix}/share/@value{PROGNAME}/@var{version}/include}
-directory (where @var{version} means the version of @value{PACKAGE}).
+@file{@var{prefix}/share/@value{PROGNAME}/@value{VERSION}/include}
+directory.
The default @file{pp-setup} file renames all @command{m4} built-in
macro names so they all start with the prefix @samp{m4_}. This
-is similar to GNU m4 @option{--prefix-builtin} options, but has an
+is similar to GNU m4 @option{--prefix-builtin} option, but has an
advantage that it works with non-GNU @command{m4} implementations as
well.
diff --git a/doc/grecs_asprintf.3 b/doc/grecs_asprintf.3
new file mode 100644
index 0000000..73be7f0
--- /dev/null
+++ b/doc/grecs_asprintf.3
@@ -0,0 +1,90 @@
+.\" This file is part of grecs -*- nroff -*-
+.\" Copyright (C) 2007, 2009-2011 Sergey Poznyakoff
+.\"
+.\" Grecs is free software; you can redistribute it and/or modify
+.\" it under the terms of the GNU General Public License as published by
+.\" the Free Software Foundation; either version 3, or (at your option)
+.\" any later version.
+.\"
+.\" Grecs is distributed in the hope that it will be useful,
+.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
+.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+.\" GNU General Public License for more details.
+.\"
+.\" You should have received a copy of the GNU General Public License
+.\" along with Grecs. If not, see <http://www.gnu.org/licenses/>.
+.\" This file is part of SLB.
+.\" Copyright (C) 2011 Sergey Poznyakoff
+.\"
+.TH GRECS_ASPRINTF 3 "May 4, 2011" "GRECS" "Grecs User Reference"
+.SH NAME
+grecs_asprintf, grecs_vasprintf \- print to allocated string
+.SH SYNOPSIS
+.nf
+.B #include <grecs.h>
+.sp
+.BI "int grecs_vasprintf(char " "**pbuf" ", size_t " "*psize" \
+ ", const char " "*format" ", "
+.ti +17
+.BI "va_list " "ap" );
+.br
+.BI "int grecs_asprintf(char " "**pbuf" ", size_t " "*psize" \
+ ", const char *" "format" ", ...);"
+.SH DESCRIPTION
+The functions
+.BI grecs_asprintf ()
+and
+.BI grecs_vasprintf ()
+are analogs of
+.BR sprintf (3)
+and
+.BR vsprintf (3),
+except that they operate on dynamically allocated buffers.
+.PP
+If, on entry to the function, \fB*pbuf\fR is NULL and \fB*psize\fR is
+0, both functions will allocate a buffer large enough to hold the
+formatted message and will fill it with the formatted text.
+.PP
+If \fB*pbuf\fR is not NULL, \fBpsize\fR must point to its actual size.
+If that size is not large enough to accomodate the formatted message,
+the buffer will be reallocated accordingly, otherwise it will remain
+unchanged.
+.PP
+In both cases, if the buffer has been reallocated, on return
+\fBpbuf\fR will contain its new address and \fBpsize\fR its new size.
+.PP
+For initial allocation,
+.BR grecs_malloc (3)
+is used. To reallocate memory, both functions use
+.BR grecs_realloc (3).
+.SH RETURN VALUE
+None. If memory allocation fails, a diagnostics is output and the
+program is terminated.
+.SH "SEE ALSO"
+.BR grecs_malloc (3),
+.BR grecs_realloc (3).
+.SH AUTHORS
+Sergey Poznyakoff
+.SH "BUG REPORTS"
+Report bugs to <gray+grecs@gnu.org.ua>.
+.SH COLOPHON
+The \fBGrecs\fR library is constantly changing, so this manual page
+may be incorrect or out-of-date. For the latest copy of \fBGrecs\fR
+documentation, visit <http://www.gnu.org.ua/software/grecs>.
+.SH COPYRIGHT
+Copyright \(co 2011 Sergey Poznyakoff
+.br
+.na
+License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
+.br
+.ad
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+.\" Local variables:
+.\" eval: (add-hook 'write-file-hooks 'time-stamp)
+.\" time-stamp-start: ".TH [A-Z_][A-Z0-9_]* [0-9] \""
+.\" time-stamp-format: "%:B %:d, %:y"
+.\" time-stamp-end: "\""
+.\" time-stamp-line-limit: 20
+.\" end:
+
diff --git a/doc/grecs_config.5 b/doc/grecs_config.5
new file mode 100644
index 0000000..579875b
--- /dev/null
+++ b/doc/grecs_config.5
@@ -0,0 +1,343 @@
+.\" This file is part of grecs -*- nroff -*-
+.\" Copyright (C) 2007, 2009-2011 Sergey Poznyakoff
+.\"
+.\" Grecs is free software; you can redistribute it and/or modify
+.\" it under the terms of the GNU General Public License as published by
+.\" the Free Software Foundation; either version 3, or (at your option)
+.\" any later version.
+.\"
+.\" Grecs is distributed in the hope that it will be useful,
+.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
+.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+.\" GNU General Public License for more details.
+.\"
+.\" You should have received a copy of the GNU General Public License
+.\" along with Grecs. If not, see <http://www.gnu.org/licenses/>.
+.\" This file is part of SLB.
+.\" Copyright (C) 2011 Sergey Poznyakoff
+.\"
+.TH GRECS_CONFIG 3 "May 4, 2011" "GRECS" "Grecs User Reference"
+.SH NAME
+\fBGrecs\fR configuration file syntax
+.SH DESCRIPTION
+.PP
+A configuration file consists of statements and comments.
+.PP
+There are three classes of lexical tokens: keywords, values, and
+separators. Blanks, tabs, newlines and comments, collectively called
+\fIwhite space\fR are ignored except as they serve to separate
+tokens. Some white space is required to separate otherwise adjacent
+keywords and values.
+.SH COMMENTS
+Comments may appear anywhere where white space may appear in the
+configuration file. There are two kinds of comments:
+single-line and multi-line comments. Single-line comments start
+with
+.B #
+or
+.B //
+and continue to the end of the line:
+.sp
+.RS 4
+.nf
+# This is a comment
+// This too is a comment
+.fi
+.RE
+.PP
+\fIMulti-line\fB or \fIC-style\fB comments start with the two
+characters
+.B /*
+(slash, star) and continue until the first occurrence of
+.B */
+(star, slash).
+.PP
+Multi-line comments cannot be nested. However, single-line comments
+may well appear within multi-line ones.
+.SS "Pragmatic Comments"
+Pragmatic comments are similar to usual single-line comments,
+except that they cause some changes in the way the configuration is
+parsed. Pragmatic comments begin with a
+.B #
+sign and end with the next physical newline character.
+.TP
+.BR "#include <" "file" >
+.PD 0
+.TP
+.BR "#include " "file"
+.PD
+Include the contents of the file \fIfile\fR. If it is an
+absolute file name, both forms are equivalent. Otherwise, the form
+with angle brackets searches for the file in the \fIinclude
+search path\fR, while the second one looks for it in the current working
+directory first, and, if not found there, in the include search
+path.
+.sp
+The default include search path is:
+.sp
+\fIprefix\fR/share/\fIPROGNAME\fR/\fIVERSION\fR/include
+.br
+\fIprefix\fR/share/\fIPROGNAME\fR/include
+.sp
+where \fIprefix\fR stands for the installation prefix (normally
+\fB/usr\fR or \fB/usr/local\fR), \fIPROGNAME\fR stands for the name of
+the program which uses the configuration file, and \fIVERSION\fR for
+its version number.
+.sp
+The include search path can be modified using the
+.BI grecs_include_path_setup ()
+and
+.BI grecs_include_path_setup_v ()
+functions. Refer to
+.BR grecs_include_path_setup (3),
+for a detailed discussion.
+.TP
+.BR "#include_once <" "file" >
+.PD 0
+.TP
+.BR "#include_once " "file"
+.PD
+Same as \fB#include\fR, except that, if the \fIfile\fR has already
+been included, it will not be included again.
+.TP
+.BR "#line " "num"
+.PD 0
+.TP
+.BR "#line " "num" " \(dq" "file" "\(dq"
+.PD
+This line causes the parser to believe, for purposes of error
+diagnostics, that the line number of the next source line
+is given by \fInum\fR and the current input file is named by
+\fIfile\fR. If the latter is absent, the remembered file name
+does not change.
+.TP
+.BR "# " "num" " \(dq" "file" "\(dq"
+This is a special form of the \fB#line\fR statement, understood for
+compatibility with the C preprocessor.
+.PP
+These statements provide a rudimentary preprocessing
+features. For more sophisticated ways to modify configuration before
+parsing, see \fBPREPROCESSOR\fR.
+.SH STATEMENTS
+.SS "Simple statement"
+A \fIsimple statement\fR consists of a keyword and value
+separated by any amount of whitespace. Simple statement is terminated
+with a semicolon (\fB;\fR).
+.PP
+The following is a simple statement:
+.sp
+.RS 4
+.nf
+standalone yes;
+pidfile /var/run/slb.pid;
+.RE
+.fi
+.PP
+A \fIkeyword\fR begins with a letter and may contain letters,
+decimal digits, underscores (\fB_\fR) and dashes (\fB-\fR).
+Examples of keywords are:
+.sp
+.RS 4
+.nf
+expression
+output-file
+.RE
+.fi
+.PP
+A \fIvalue\fR can be one of the following:
+.TP
+.I number
+A number is a sequence of decimal digits.
+.TP
+.I boolean
+A boolean value is one of the following: \fByes\fR, \fBtrue\fR,
+\fBt\fR or \fB1\fR, meaning \fItrue\fR, and \fBno\fR,
+\fBfalse\fR, \fBnil\fR, \fB0\fR meaning \fIfalse\fR.
+.TP
+.I unquoted string
+An unquoted string may contain letters, digits, and any of the
+following characters: \fB_\fR, \fB\-\fR, \fB.\fR, \fB/\fR,
+\fB@\fR, \fB*\fR, \fB:\fR.
+.TP
+.I quoted string
+A quoted string is any sequence of characters enclosed in
+double-quotes (\fB\(dq\fR). A backslash appearing within a quoted
+string introduces an \fIescape sequence\fR, which is replaced
+with a single character according to the following rules:
+.nf
+.ul
+ Sequence Replaced with
+ \\a Audible bell character (ASCII 7)
+ \\b Backspace character (ASCII 8)
+ \\f Form-feed character (ASCII 12)
+ \\n Newline character (ASCII 10)
+ \\r Carriage return character (ASCII 13)
+ \\t Horizontal tabulation character (ASCII 9)
+ \\v Vertical tabulation character (ASCII 11)
+ \\\\ A single backslash
+ \\\(dq A double-quote.
+.fi
+In addition, the sequence \fB\\\fInewline\fR is removed from
+the string. This allows to split long strings over several
+physical lines, e.g.:
+.sp
+.nf
+ "a long string may be\\
+ split over several lines"
+.fi
+.sp
+If the character following a backslash is not one of those specified
+above, the backslash is ignored and a warning is issued.
+
+Two or more adjacent quoted strings are concatenated, which gives
+another way to split long strings over several lines to improve
+readability. The following fragment produces the same result as the
+example above:
+.sp
+.nf
+ "a long string may be"
+ " split over several lines"
+.fi
+.TP
+.I Here-document
+A \fIhere-document\fR is a special construct that allows to introduce
+strings of text containing embedded newlines.
+
+The
+.BI "<<" "word"
+construct instructs the parser to read all the following lines up to
+the line containing only \fIword\fR, with possible trailing blanks.
+Any lines thus read are concatenated together into a single string.
+For example:
+.sp
+.nf
+ <<EOT
+ A multiline
+ string
+ EOT
+.fi
+.sp
+The body of a here-document is interpreted the same way as a
+double-quoted string, unless \fIword\fR is preceded by a backslash
+(e.g. \fB<<\\EOT\fR) or enclosed in double-quotes, in which case
+the text is read as is, without interpretation of escape sequences.
+
+If \fIword\fR is prefixed with \fB\-\fR (a dash), then all leading
+tab characters are stripped from input lines and the line containing
+\fIword\fR. Furthermore, \fB\-\fR is followed by a single space,
+all leading whitespace is stripped from them. This allows to indent
+here-documents in a natural fashion. For example:
+.sp
+.nf
+ <<- TEXT
+ The leading whitespace will be
+ ignored when reading these lines.
+ TEXT
+.fi
+.sp
+It is important that the terminating delimiter be the only token on
+its line. The only exception to this rule is allowed if a
+here-document appears as the last element of a statement. In this
+case a semicolon can be placed on the same line with its terminating
+delimiter, as in:
+.sp
+.nf
+ help-text <<-EOT
+ A sample help text.
+ EOT;
+.fi
+.TP
+.I list
+A comma-separated list of values, enclosed in parentheses. The
+following example shows a statement whose value is a list of strings:
+.sp
+.nf
+ alias (test, null);
+.fi
+.sp
+In any context where a list is appropriate, a single value is allowed
+without being a member of a list: it is equivalent to a list with a
+single member. This means that, e.g.
+.sp
+.nf
+ alias test;
+.fi
+.sp
+is equivalent to
+.sp
+.nf
+ alias (test);
+.fi
+.sp
+provided that the \fBalias\fR statement is defined as taking a list as
+its argument.
+.TP
+.I block statement
+A block statement introduces a logical group of
+statements. It consists of a keyword, followed by an optional value,
+called a \fBtag\fR, and a sequence of statements enclosed in curly
+braces, as shown in the example below:
+.sp
+.nf
+ server srv1 {
+ host 10.0.0.1;
+ community "foo";
+ }
+.fi
+.sp
+The closing curly brace may be followed by a semicolon, although
+this is not required.
+.SS PREPROCESSOR
+Before being parsed, the configuration file is preprocessed.
+The built-in preprocessor handles only file inclusion
+and
+.B #line
+statements, while the rest of traditional preprocessing facilities,
+such as macro expansion, is supported via
+.BR m4 (1),
+which is used as external preprocessor.
+.PP
+The external preprocessor is invoked with the \fB-s\fR flag, which
+instructs it to include line synchronization information in its
+output. This information is then used by the parser to display meaningful
+diagnostic.
+.PP
+An initial set of macro definitions is supplied in the file named
+\fBpp-setup\fR file, which is located in
+\fIprefix\fB/share/\fIPROGNAME\fR/\fIVERSION\fR/include}
+directory.
+.PP
+The default \fBpp-setup\fR file renames all m4 built-in
+macro names so they all start with the prefix \fBm4_\fI. This
+is similar to GNU m4 \fB--prefix-builtin\fR option, but has an
+advantage that it works with non-GNU m4 implementations as
+well.
+.SH "SEE ALSO"
+.BR m4 (1),
+.BR grecs_parse (3),
+.BR grecs_include_path_setup (3),
+.BR grecs_tree_process (3).
+.SH AUTHORS
+Sergey Poznyakoff
+.SH "BUG REPORTS"
+Report bugs to <gray+grecs@gnu.org.ua>.
+.SH COLOPHON
+The \fBGrecs\fR library is constantly changing, so this manual page
+may be incorrect or out-of-date. For the latest copy of \fBGrecs\fR
+documentation, visit <http://www.gnu.org.ua/software/grecs>.
+.SH COPYRIGHT
+Copyright \(co 2011 Sergey Poznyakoff
+.br
+.na
+License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
+.br
+.ad
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+.\" Local variables:
+.\" eval: (add-hook 'write-file-hooks 'time-stamp)
+.\" time-stamp-start: ".TH [A-Z_][A-Z0-9_]* [0-9] \""
+.\" time-stamp-format: "%:B %:d, %:y"
+.\" time-stamp-end: "\""
+.\" time-stamp-line-limit: 20
+.\" end:
diff --git a/doc/grecs_error.3 b/doc/grecs_error.3
new file mode 100644
index 0000000..d747d9a
--- /dev/null
+++ b/doc/grecs_error.3
@@ -0,0 +1,132 @@
+.\" This file is part of grecs -*- nroff -*-
+.\" Copyright (C) 2007, 2009-2011 Sergey Poznyakoff
+.\"
+.\" Grecs is free software; you can redistribute it and/or modify
+.\" it under the terms of the GNU General Public License as published by
+.\" the Free Software Foundation; either version 3, or (at your option)
+.\" any later version.
+.\"
+.\" Grecs is distributed in the hope that it will be useful,
+.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
+.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+.\" GNU General Public License for more details.
+.\"
+.\" You should have received a copy of the GNU General Public License
+.\" along with Grecs. If not, see <http://www.gnu.org/licenses/>.
+.\" This file is part of SLB.
+.\" Copyright (C) 2011 Sergey Poznyakoff
+.\"
+.TH GRECS_ERROR 3 "May 4, 2011" "GRECS" "Grecs User Reference"
+.SH NAME
+grecs_error, grecs_warning \- grecs error reporting functions
+.SH SYNOPSIS
+.nf
+.B #include <grecs.h>
+.sp
+.BI "void grecs_error(grecs_locus_t " "*locus" ", int " "errnum" ", "
+.ti +17
+.BI "const char " "*format" ", ...);"
+.br
+.BI "void grecs_warning(grecs_locus_t " "*locus" ", int " "errnum" ", "
+.ti +17
+.BI "const char " "*format" ", ...);"
+.sp
+.BI "void (*grecs_print_diag_fun)(grecs_locus_t " "*locus" ", "
+.ti +17
+.BI "int " "err" ", int " "errnum" ", const char " "*msg" );
+.sp
+.B extern int grecs_error_count;
+.SH DESCRIPTION
+.BI grecs_error ()
+is a error reporting function for \fBgrecs\fR library. It flushes
+stdout, and outputs to stderr the file name and line number, as
+supplied by the
+.BI locus
+argument, a colon and a space, the message specified by the
+.BR printf (3)-style
+format string \fIformat\fR, and, if \fIerrnum\fR is non-zero, a second
+colon and a space followed by the string given by
+.BI perror (errnum).
+Any arguments required for format should follow \fIformat\fR in the
+argument list. The output is terminated by a newline character.
+.PP
+If \fIlocus\fR is \fBNULL\fR, it is ignored and no file location is
+printed.
+.PP
+Each call to
+.BI grecs_error ()
+increments the value of the
+.BI grecs_error_count
+global variable.
+The
+.BI grecs_warning ()
+function works the same as
+.BI grecs_error (),
+except that it outputs, before the formatted message and after the
+file location, the word \fBwarning\fR, followed by a semicolon
+and a space character. It does not modify the
+.BI grecs_error_count
+variable.
+.PP
+Calling program can modify the behavior of both functions by setting
+.BI grecs_print_diag_fun
+to the address of a custom error-reporting function. This function is
+called with the following arguments:
+.TP
+.I locus
+Location in the file where the error or warning condition is
+encountered. Can be \fBNULL\fR if the condition occurred outside of
+input file context.
+.TP
+.I err
+This argument is \fB1\fR, if the function is called to report an error
+condition and \fB0\fR otherwise (i.e. a warning).
+.TP
+.I errnum
+System error code, or \fB0\fR, if no system error occurred.
+.TP
+.I msg
+Formatted message.
+.PP
+The \fBgrecs_locus_t\fR structure is defined as:
+.sp
+.nf
+.in +5
+typedef struct {
+ char *file;
+ int line;
+} grecs_locus_t;
+.in
+.fi
+.PP
+The \fBfile\fR member points to the file name, and the \fBline\fR
+member contains the input line number.
+.SH RETURN VALUE
+None.
+.SH "SEE ALSO"
+.BR errno (3)
+.SH AUTHORS
+Sergey Poznyakoff
+.SH "BUG REPORTS"
+Report bugs to <gray+grecs@gnu.org.ua>.
+.SH COLOPHON
+The \fBGrecs\fR library is constantly changing, so this manual page
+may be incorrect or out-of-date. For the latest copy of \fBGrecs\fR
+documentation, visit <http://www.gnu.org.ua/software/grecs>.
+.SH COPYRIGHT
+Copyright \(co 2011 Sergey Poznyakoff
+.br
+.na
+License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
+.br
+.ad
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+.\" Local variables:
+.\" eval: (add-hook 'write-file-hooks 'time-stamp)
+.\" time-stamp-start: ".TH [A-Z_][A-Z0-9_]* [0-9] \""
+.\" time-stamp-format: "%:B %:d, %:y"
+.\" time-stamp-end: "\""
+.\" time-stamp-line-limit: 20
+.\" end:
+
diff --git a/doc/grecs_format_locus.3 b/doc/grecs_format_locus.3
new file mode 100644
index 0000000..3803c2b
--- /dev/null
+++ b/doc/grecs_format_locus.3
@@ -0,0 +1,68 @@
+.\" This file is part of grecs -*- nroff -*-
+.\" Copyright (C) 2007, 2009-2011 Sergey Poznyakoff
+.\"
+.\" Grecs is free software; you can redistribute it and/or modify
+.\" it under the terms of the GNU General Public License as published by
+.\" the Free Software Foundation; either version 3, or (at your option)
+.\" any later version.
+.\"
+.\" Grecs is distributed in the hope that it will be useful,
+.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
+.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+.\" GNU General Public License for more details.
+.\"
+.\" You should have received a copy of the GNU General Public License
+.\" along with Grecs. If not, see <http://www.gnu.org/licenses/>.
+.\" This file is part of SLB.
+.\" Copyright (C) 2011 Sergey Poznyakoff
+.\"
+.TH GRECS_FORMAT_LOCUS 3 "May 4, 2011" "GRECS" "Grecs User Reference"
+.SH NAME
+grecs_format_locus \- format and output source file location
+.SH SYNOPSIS
+.nf
+.B #include <grecs.h>
+.sp
+.BI "void grecs_format_locus(grecs_locus_t " "*locus" ", FILE " "*fp" );
+.SH DESCRIPTION
+\fBgrecs_format_locus\fR formats the location from \fIlocus\fR in the
+human-readable form and outputs it to file \fBfp\fR.
+.PP
+The location is output as follows: the file name, followed by a
+semicolon, followed by line number and another semicolon.
+.PP
+If \fIlocus\fR is \fBNULL\fR, \fBgrecs_format_locus\fR returns without
+doing anything.
+.SH "RETURN VALUE"
+None.
+.SH NOTES
+This is an auxiliary function used by
+.BR grecs_format_node (3).
+It is seldom needed in user programs.
+.SH "SEE ALSO"
+.BR grecs_format_node (3)
+.SH AUTHORS
+Sergey Poznyakoff
+.SH "BUG REPORTS"
+Report bugs to <gray+grecs@gnu.org.ua>.
+.SH COLOPHON
+The \fBGrecs\fR library is constantly changing, so this manual page
+may be incorrect or out-of-date. For the latest copy of \fBGrecs\fR
+documentation, visit <http://www.gnu.org.ua/software/grecs>.
+.SH COPYRIGHT
+Copyright \(co 2011 Sergey Poznyakoff
+.br
+.na
+License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
+.br
+.ad
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+.\" Local variables:
+.\" eval: (add-hook 'write-file-hooks 'time-stamp)
+.\" time-stamp-start: ".TH [A-Z_][A-Z0-9_]* [0-9] \""
+.\" time-stamp-format: "%:B %:d, %:y"
+.\" time-stamp-end: "\""
+.\" time-stamp-line-limit: 20
+.\" end:
+
diff --git a/doc/grecs_format_node.3 b/doc/grecs_format_node.3
new file mode 100644
index 0000000..d1d8b02
--- /dev/null
+++ b/doc/grecs_format_node.3
@@ -0,0 +1,102 @@
+.\" This file is part of grecs -*- nroff -*-
+.\" Copyright (C) 2007, 2009-2011 Sergey Poznyakoff
+.\"
+.\" Grecs is free software; you can redistribute it and/or modify
+.\" it under the terms of the GNU General Public License as published by
+.\" the Free Software Foundation; either version 3, or (at your option)
+.\" any later version.
+.\"
+.\" Grecs is distributed in the hope that it will be useful,
+.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
+.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+.\" GNU General Public License for more details.
+.\"
+.\" You should have received a copy of the GNU General Public License
+.\" along with Grecs. If not, see <http://www.gnu.org/licenses/>.
+.\" This file is part of SLB.
+.\" Copyright (C) 2011 Sergey Poznyakoff
+.\"
+.TH GRECS_FORMAT_NODE 3 "May 4, 2011" "GRECS" "Grecs User Reference"
+.SH NAME
+grecs_format_node \- format and print a single node from a syntax tree
+.SH SYNOPSIS
+.nf
+.B #include <grecs.h>
+.sp
+.BI "void grecs_format_node(struct grecs_node *" "node" ", int " \
+ "flags" ", FILE " "*fp" );
+.SH DESCRIPTION
+\fBgrecs_format_node\fR prints to the output file \fBfp\fR the
+contents of a parse tree node \fBnode\fR, according to formatting
+options, given by \fBflags\fR.
+.PP
+The \fBflags\fR argument is a bitwise \fBOR\fR of one or more of the
+following options:
+.TP
+.I (a punctuation character)
+This character will be used as pathname component separator, instead
+of the default dot.
+.TP
+.B GRECS_NODE_FLAG_LOCUS
+Print the source location. The location is printed as the file name,
+followed by a semicolon, followed by the line number and another
+semicolon. Locations are separated from the rest of output by a single
+space character.
+.TP
+.B GRECS_NODE_FLAG_PATH
+Print the \fInode path\fR. See
+.BR grecs_stmt_path (5),
+for a description. If printed, the path is separated from the
+remaining output on its right by a semicolon and a space.
+.TP
+.B GRECS_NODE_FLAG_VALUE
+Print the node value.
+.TP
+.B GRECS_NODE_FLAG_QUOTE
+Always quote the value. By default, the value will be quoted only
+when necessary, i.e. if it contains white space, quotes or special
+characters. This option is useful only together with
+\fBGRECS_NODE_FLAG_VALUE\fR.
+.TP
+.B GRECS_NODE_FLAG_QUOTE_HEX
+Print non-printable characters as C hex escapets. This option is
+useful only together with \fBGRECS_NODE_FLAG_QUOTE\fR and
+\fBGRECS_NODE_FLAG_VALUE\fR.
+.TP
+.B GRECS_NODE_FLAG_DEFAULT
+Same as
+.sp
+.nf
+GRECS_NODE_FLAG_PATH|GRECS_NODE_FLAG_VALUE|GRECS_NODE_FLAG_QUOTE
+.PP
+If \fBflag\fR is 0, \fBGRECS_NODE_FLAG_DEFAULT\fR is assumed.
+.SH "RETURN VALUE"
+None.
+.SH "SEE ALSO"
+.BR grecs_config (5),
+.BR grecs_stmt_path (5).
+.SH AUTHORS
+Sergey Poznyakoff
+.SH "BUG REPORTS"
+Report bugs to <gray+grecs@gnu.org.ua>.
+.SH COLOPHON
+The \fBGrecs\fR library is constantly changing, so this manual page
+may be incorrect or out-of-date. For the latest copy of \fBGrecs\f