diff options
author | Sergey Poznyakoff <gray@gnu.org.ua> | 2011-05-04 20:10:36 +0300 |
---|---|---|
committer | Sergey Poznyakoff <gray@gnu.org.ua> | 2011-05-04 21:41:39 +0300 |
commit | a60eb4b18345626a84e23784d77ca231812e1dff (patch) | |
tree | 80192afeadd44b073958c2762491cc7dfea778a1 | |
parent | b65bfa7564f564f85d3c595c6c1030af2acf5056 (diff) | |
download | grecs-a60eb4b18345626a84e23784d77ca231812e1dff.tar.gz grecs-a60eb4b18345626a84e23784d77ca231812e1dff.tar.bz2 |
Improve docs. Add an option to create installable distribution.
-rw-r--r-- | .gitignore | 3 | ||||
-rw-r--r-- | Makefile.am | 2 | ||||
-rw-r--r-- | am/grecs.m4 | 21 | ||||
-rw-r--r-- | doc/GRECS_SETUP.3 | 131 | ||||
-rw-r--r-- | doc/Makefile.am | 33 | ||||
-rw-r--r-- | doc/grecs-syntax.texi | 10 | ||||
-rw-r--r-- | doc/grecs_asprintf.3 | 90 | ||||
-rw-r--r-- | doc/grecs_config.5 | 343 | ||||
-rw-r--r-- | doc/grecs_error.3 | 132 | ||||
-rw-r--r-- | doc/grecs_format_locus.3 | 68 | ||||
-rw-r--r-- | doc/grecs_format_node.3 | 102 | ||||
-rw-r--r-- | doc/grecs_format_node_path.3 | 71 | ||||
-rw-r--r-- | doc/grecs_format_value.3 | 66 | ||||
-rw-r--r-- | doc/grecs_include_path_setup.3 | 68 | ||||
-rw-r--r-- | doc/grecs_malloc.3 | 129 | ||||
-rw-r--r-- | doc/grecs_node_free.3 | 63 | ||||
-rw-r--r-- | doc/grecs_parse.3 | 185 | ||||
-rw-r--r-- | doc/grecs_stmt_path.5 | 123 | ||||
-rw-r--r-- | doc/grecs_strdup.3 | 70 | ||||
-rw-r--r-- | doc/grecs_tree_free.3 | 61 | ||||
-rw-r--r-- | doc/tmpl.3 | 54 | ||||
-rw-r--r-- | src/.gitignore | 2 | ||||
-rw-r--r-- | src/Make-inst.am | 19 | ||||
-rw-r--r-- | src/Make-noinst.am | 18 | ||||
-rw-r--r-- | src/Make.am | 42 | ||||
-rw-r--r-- | tests/Makefile.am | 2 |
26 files changed, 1900 insertions, 8 deletions
@@ -1,4 +1,6 @@ *.a +*.la +*.lo *.o *.tar.* *~ @@ -6,6 +8,7 @@ .emacs.desktop .emacs.desktop.lock .emacsrc +.libs ABOUT-NLS ChangeLog INSTALL diff --git a/Makefile.am b/Makefile.am index 96bfab7..643d06a 100644 --- a/Makefile.am +++ b/Makefile.am @@ -1,2 +1,2 @@ -SUBDIRS=src @GRECS_TESTDIR@ +SUBDIRS=src @GRECS_TESTDIR@ @GRECS_DOCDIR@ EXTRA_DIST=@GRECS_BUILD_AUX@ diff --git a/am/grecs.m4 b/am/grecs.m4 index 8de0d08..764ce46 100644 --- a/am/grecs.m4 +++ b/am/grecs.m4 @@ -72,6 +72,8 @@ AC_DEFUN([GRECS_SETUP],[ AC_PROG_YACC AM_PROG_LEX + AC_HEADER_SYS_WAIT + AC_SUBST([GRECS_SUBDIR],m4_if([$1],,grecs,$1)) _GRECS_SET_OPTIONS([$2]) # ********************** @@ -139,9 +141,26 @@ AC_DEFUN([GRECS_SETUP],[ AM_MISSING_PROG([AUTOM4TE], [autom4te]) GRECS_TESTDIR=tests ]) - _GRECS_IF_OPTION_SET([getopt],[GRECS_BUILD_AUX="build-aux/getopt.m4"]) + _GRECS_IF_OPTION_SET([getopt],[ + AC_CHECK_HEADERS([getopt.h]) + AC_CHECK_FUNCS([sysconf getdtablesize getopt_long]) + GRECS_BUILD_AUX="build-aux/getopt.m4" + ]) _GRECS_IF_OPTION_SET([git2chg],[GRECS_BUILD_AUX="$GRECS_BUILD_AUX build-aux/git2chg.awk"]) AC_SUBST([GRECS_BUILD_AUX]) AC_SUBST([GRECS_INCLUDES]) AC_SUBST([GRECS_TESTDIR]) + AC_SUBST([GRECS_LDADD]) + AC_SUBST([GRECS_DOCDIR]) + _GRECS_IF_OPTION_SET([install],[ + LT_INIT + GRECS_LDADD='$(top_builddir)/m4_if([$1],,grecs,$1)/src/libgrecs.la' + GRECS_DOCDIR='doc' + AC_CONFIG_FILES(m4_if([$1],,grecs,$1)/src/Makefile:m4_if([$1],,grecs,$1)/src/Make-inst.in + m4_if([$1],,grecs,$1)/doc/Makefile) + ],[ + GRECS_LDADD='$(top_builddir)/m4_if([$1],,grecs,$1)/src/libgrecs.a' + AC_CONFIG_FILES(m4_if([$1],,grecs,$1)/src/Makefile:m4_if([$1],,grecs,$1)/src/Make-noinst.in) + ]) + AC_CONFIG_FILES(m4_if([$1],,grecs,$1)/Makefile) ]) 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/>. +.\" |