From a60eb4b18345626a84e23784d77ca231812e1dff Mon Sep 17 00:00:00 2001 From: Sergey Poznyakoff Date: Wed, 4 May 2011 20:10:36 +0300 Subject: Improve docs. Add an option to create installable distribution. --- .gitignore | 3 + Makefile.am | 2 +- am/grecs.m4 | 21 ++- doc/GRECS_SETUP.3 | 131 ++++++++++++++++ doc/Makefile.am | 33 ++++ doc/grecs-syntax.texi | 10 +- doc/grecs_asprintf.3 | 90 +++++++++++ doc/grecs_config.5 | 343 +++++++++++++++++++++++++++++++++++++++++ doc/grecs_error.3 | 132 ++++++++++++++++ doc/grecs_format_locus.3 | 68 ++++++++ doc/grecs_format_node.3 | 102 ++++++++++++ doc/grecs_format_node_path.3 | 71 +++++++++ doc/grecs_format_value.3 | 66 ++++++++ doc/grecs_include_path_setup.3 | 68 ++++++++ doc/grecs_malloc.3 | 129 ++++++++++++++++ doc/grecs_node_free.3 | 63 ++++++++ doc/grecs_parse.3 | 185 ++++++++++++++++++++++ doc/grecs_stmt_path.5 | 123 +++++++++++++++ doc/grecs_strdup.3 | 70 +++++++++ doc/grecs_tree_free.3 | 61 ++++++++ doc/tmpl.3 | 54 +++++++ src/.gitignore | 2 + src/Make-inst.am | 19 +++ src/Make-noinst.am | 18 +++ src/Make.am | 42 +++++ tests/Makefile.am | 2 +- 26 files changed, 1900 insertions(+), 8 deletions(-) create mode 100644 doc/GRECS_SETUP.3 create mode 100644 doc/Makefile.am create mode 100644 doc/grecs_asprintf.3 create mode 100644 doc/grecs_config.5 create mode 100644 doc/grecs_error.3 create mode 100644 doc/grecs_format_locus.3 create mode 100644 doc/grecs_format_node.3 create mode 100644 doc/grecs_format_node_path.3 create mode 100644 doc/grecs_format_value.3 create mode 100644 doc/grecs_include_path_setup.3 create mode 100644 doc/grecs_malloc.3 create mode 100644 doc/grecs_node_free.3 create mode 100644 doc/grecs_parse.3 create mode 100644 doc/grecs_stmt_path.5 create mode 100644 doc/grecs_strdup.3 create mode 100644 doc/grecs_tree_free.3 create mode 100644 doc/tmpl.3 create mode 100644 src/Make-inst.am create mode 100644 src/Make-noinst.am create mode 100644 src/Make.am diff --git a/.gitignore b/.gitignore index 4e0f5dd..b4b4597 100644 --- a/.gitignore +++ b/.gitignore @@ -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 . +.\" 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 . +.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 . +.SH COPYRIGHT +Copyright \(co 2011 Sergey Poznyakoff +.br +.na +License GPLv3+: GNU GPL version 3 or later +.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 . + +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 . +.\" 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 +.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 . +.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 . +.SH COPYRIGHT +Copyright \(co 2011 Sergey Poznyakoff +.br +.na +License GPLv3+: GNU GPL version 3 or later +.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 . +.\" 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 + <. +.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 . +.SH COPYRIGHT +Copyright \(co 2011 Sergey Poznyakoff +.br +.na +License GPLv3+: GNU GPL version 3 or later +.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 . +.\" 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 +.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 . +.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 . +.SH COPYRIGHT +Copyright \(co 2011 Sergey Poznyakoff +.br +.na +License GPLv3+: GNU GPL version 3 or later +.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 . +.\" 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 +.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 . +.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 . +.SH COPYRIGHT +Copyright \(co 2011 Sergey Poznyakoff +.br +.na +License GPLv3+: GNU GPL version 3 or later +.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 . +.\" 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 +.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 . +.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 . +.SH COPYRIGHT +Copyright \(co 2011 Sergey Poznyakoff +.br +.na +License GPLv3+: GNU GPL version 3 or later +.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_path.3 b/doc/grecs_format_node_path.3 new file mode 100644 index 0000000..2f8cff6 --- /dev/null +++ b/doc/grecs_format_node_path.3 @@ -0,0 +1,71 @@ +.\" 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 . +.\" This file is part of SLB. +.\" Copyright (C) 2011 Sergey Poznyakoff +.\" +.TH GRECS_FORMAT_NODE_PATH 3 "May 4, 2011" "GRECS" "Grecs User Reference" +.SH NAME +grecs_format_node_path \- format and output statement pathname for the +node +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "void grecs_format_node_path(struct grecs_node " "*node" ", int " \ + "flag" ", FILE " "*fp" ); +.SH DESCRIPTION +\fBgrecs_format_node_path\fR computes the \fIstatement pathname\fR for +the \fInode\fR, and outputs it to the file \fBfp\fR. +.PP +The \fIflags\fR argument describes what character to use as a pathname +component separator and how to format the statement tag, if \fInode\fR +refers to a block statement. See +.BR grecs_format_node (3), +for a discussion of available flags. +.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), +.BR grecs_stmt_path (5). +.SH AUTHORS +Sergey Poznyakoff +.SH "BUG REPORTS" +Report bugs to . +.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 . +.SH COPYRIGHT +Copyright \(co 2011 Sergey Poznyakoff +.br +.na +License GPLv3+: GNU GPL version 3 or later +.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_value.3 b/doc/grecs_format_value.3 new file mode 100644 index 0000000..8a8af9f --- /dev/null +++ b/doc/grecs_format_value.3 @@ -0,0 +1,66 @@ +.\" 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 . +.\" This file is part of SLB. +.\" Copyright (C) 2011 Sergey Poznyakoff +.\" +.TH GRECS_FORMAT_VALUE 3 "May 4, 2011" "GRECS" "Grecs User Reference" +.SH NAME +grecs_format_value \- format and output a configuration value +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "void grecs_format_value(struct grecs_value *" "val" ", int " \ + "flags" ", FILE " "*fp" ); +.SH DESCRIPTION +\fBgrecs_format_value\fR formats and outputs to the file \fBfp\fR the +value \fIval\fR. The \fIflags\fR argument describes how to format the +value. See +.BR grecs_format_node (3), +for a discussion of available flags. +.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 . +.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 . +.SH COPYRIGHT +Copyright \(co 2011 Sergey Poznyakoff +.br +.na +License GPLv3+: GNU GPL version 3 or later +.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_include_path_setup.3 b/doc/grecs_include_path_setup.3 new file mode 100644 index 0000000..d179773 --- /dev/null +++ b/doc/grecs_include_path_setup.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 . +.\" This file is part of SLB. +.\" Copyright (C) 2011 Sergey Poznyakoff +.\" +.TH GRECS_INCLUDE_PATH_SETUP 3 "May 4, 2011" "GRECS" "Grecs User Reference" +.SH NAME +grecs_include_path_setup, grecs_include_path_setup_v \- add +directories to the \fBgrecs\fR preprocessor include path +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "void grecs_include_path_setup(const char *" "dir" ", ...);" +.br +.BI "void grecs_include_path_setup_v(char **" "dirs" ); +.SH DESCRIPTION +These functions add directories to the end of the include search path +used by the \fBgrecs\fR preprocessor. +.PP +\fBgrecs_include_path_setup\fR takes arbitrary number of +arguments. Each argument must be pointer to a directory name. The +argument list must terminate with a \fBNULL\fR argument. +.PP +\fBgrecs_include_path_setup_v\fR takes directory names from a +\fBNULL\fR-terminated array of character pointers. +.SH "RETURN VALUE" +None. +.SH "SEE ALSO" +.BR grecs_config (5). +.SH AUTHORS +Sergey Poznyakoff +.SH "BUG REPORTS" +Report bugs to . +.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 . +.SH COPYRIGHT +Copyright \(co 2011 Sergey Poznyakoff +.br +.na +License GPLv3+: GNU GPL version 3 or later +.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_malloc.3 b/doc/grecs_malloc.3 new file mode 100644 index 0000000..58cc9a0 --- /dev/null +++ b/doc/grecs_malloc.3 @@ -0,0 +1,129 @@ +.\" 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 . +.\" This file is part of SLB. +.\" Copyright (C) 2011 Sergey Poznyakoff +.\" +.TH GRECS_MALLOC 3 "May 3, 2011" "GRECS" "Grecs User Reference" +.SH NAME +grecs_malloc, grecs_zalloc, grecs_calloc, grecs_realloc \- Allocate +dynamic memory for \fBGrecs\fR. +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "void *grecs_malloc(size_t " "size" ); +.br +.BI "void *grecs_zalloc(size_t " "size" ); +.br +.BI "void *grecs_calloc(size_t " "nmemb" ", size_t " "size" ); +.br +.BI "void *grecs_realloc(void " "*ptr" ", size_t " "size" ); +.br +.BI "void grecs_alloc_die(void);" +.sp +.BI "void *(*grecs_malloc_fun)(size_t " "size" ); +.br +.BI "void *(*grecs_realloc_fun)(void " "*ptr" ", size_t " "size" ); +.br +.BI "void (*grecs_alloc_die_fun)(void);" +.SH DESCRIPTION +.PP +The \fBgrecs_malloc\fR, \fBgrecs_calloc\fR and \fBgrecs_realloc\fR +functions work exactly as they \fIlibc\fR counterparts do, except that +if unable to allocate memory they terminate the program, by calling +\fBgrecs_alloc_die\fR function. +.PP +.BR grecs_calloc () +allocates memory for an array of +.I nmemb +elements of +.I size +bytes each and returns a pointer to the allocated memory. +The memory is set to zero. +.PP +.BR grecs_malloc () +allocates +.I size +bytes and returns a pointer to the allocated memory. +The memory is not cleared. +.PP +.BR grecs_realloc () +changes the size of the memory block pointed to by +.I ptr +to +.I size +bytes. +The contents will be unchanged to the minimum of the old and new +sizes; +newly allocated memory will be uninitialized. +.PP +.BR grecs_zalloc () +allocates +.I size +bytes and returns a pointer to the allocated memory. The memory is +set to zero. +.PP +If \fBgrecs_malloc_fun\fR is not \fINULL\fR, it will be used by +\fBgrecs_malloc\fR, \fBgrecs_calloc\fR and \fBgrecs_zalloc\fR to +allocate new memory chunk. If it is not set, these function use +\fBmalloc(3)\fR. +.PP +Similarly, the \fBgrecs_realloc_fun\fR, if set, is used by +\fBgrecs_realloc\fR function. Otherwise, this function uses +\fBrealloc(3)\fR. +.PP +These hooks provide a way for the calling program to use its custom +memory allocation routines. +.PP +.BR grecs_alloc_die () +This function is called when memory allocation fails. It prints +appropriate diagnostics using \fBgrecs_error(3)\fR and aborts the +program. If \fBgrecs_alloc_die_fun\fR, it is called prior to +outputting the diagnostics. + +.SH "RETURN VALUE" +For \fBgrecs_malloc\fR, \fBgrecs_calloc\fR, \fBgrecs_zalloc\fR and +\fBgrecs_realloc\fR return a pointer to the allocated memory, which is +suitably aligned for any kind of variable. +.PP +On error, \fBgrecs_alloc_die\fR is called and the program is terminated. +.SH "SEE ALSO" +.BR grecs_strdup (3) +.SH AUTHORS +Sergey Poznyakoff. +.SH "BUG REPORTS" +Report bugs to . +.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 . +.SH COPYRIGHT +Copyright \(co 2011 Sergey Poznyakoff +.br +.na +License GPLv3+: GNU GPL version 3 or later +.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_node_free.3 b/doc/grecs_node_free.3 new file mode 100644 index 0000000..af453c0 --- /dev/null +++ b/doc/grecs_node_free.3 @@ -0,0 +1,63 @@ +.\" 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 . +.\" This file is part of SLB. +.\" Copyright (C) 2011 Sergey Poznyakoff +.\" +.TH GRECS_NODE_FREE 3 "May 4, 2011" "GRECS" "Grecs User Reference" +.SH NAME +grecs_node_free \- reclaim the memory used by a node +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "void grecs_node_free(struct grecs_node " "*node" ); +.SH DESCRIPTION +\fBgrecs_node_free\fR reclaims the memory used by the parse tree node +\fInode\fR. +.PP +The function does not unlink the node from the lists it is part of, +see +.BR grecs_tree_free (3), +if this is what you need. +.SH "RETURN VALUE" +None. +.SH "SEE ALSO" +.BR grecs_tree_free (3). +.SH AUTHORS +Sergey Poznyakoff +.SH "BUG REPORTS" +Report bugs to . +.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 . +.SH COPYRIGHT +Copyright \(co 2011 Sergey Poznyakoff +.br +.na +License GPLv3+: GNU GPL version 3 or later +.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_parse.3 b/doc/grecs_parse.3 new file mode 100644 index 0000000..357889f --- /dev/null +++ b/doc/grecs_parse.3 @@ -0,0 +1,185 @@ +.\" 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 . +.\" This file is part of SLB. +.\" Copyright (C) 2011 Sergey Poznyakoff +.\" +.TH GRECS_PARSE 3 "May 4, 2011" "GRECS" "Grecs User Reference" +.SH NAME +grecs_parse \- parse a configuration file. +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "struct grecs_node *grecs_parse(const char *" "name" ); +.SH DESCRIPTION +The +.BR grecs_parse () +function reads the file \fBname\fR, which must be formatted +according to +.BR grecs_config (5) +and returns the parsed-out syntax tree. On errors, \fBNULL\fR is +returned and appropriate diagnostic messages are printed using +.BR grecs_error (3). +.PP +The syntax tree consists of \fInodes\fR, linked together so as to +represent the file structure. A node is described by the following +object: +.sp +.nf +.in +5 +typedef struct grecs_node { + enum grecs_node_type type; + grecs_locus_t locus; + struct grecs_node *up; + struct grecs_node *down; + struct grecs_node *next; + struct grecs_node *prev; + char *ident; + struct grecs_value value; +} grecs_node_t; +.in +.fi +.PP +The \fItype\fR member describes the type of this node. Its value is +\fBgrecs_node_stmt\fR for simple statements, and +\fBgrecs_node_block\fR, for block statements. +.PP +The \fIlocus\fR describes the location in the input file, which this +node described. See +.BR grecs_error (3), +for a description of \fBgrecs_locus_t\fR. +.PP +Adjacent nodes form a doubly-linked list using the \fBnext\fR and +\fBprev\fR pointers. Thus, the node pointed to by \fBnext\fR +describes the statement that appears immediately after the one +described by the current node, whereas \fBprev\fR points to the node +describing a preceding statement. +.PP +If \fItype\fR is \fBgrecs_node_block\fR, the \fBdown\fR member points +to the first \fBsub-statement\fR in this block. \fBdown->next\fR +will point to the second statement (if any), and so on. +.PP +Whatever the node type is, its \fBup\fR member will point to the node +corresponding to the upper-level block statement, if any. In other +words, \fBdown\fR and \fBup\fR pointers reflect the hierarchical +structure of the file, so that the following holds true: +.sp +.nf +.in +5 +node->up->down == node +node->down->up == node +.in +.fi +.sp +provided that \fBnode->up\fR and \fBnode->down\fR are not NULL. +.PP +The \fBident\fR member points to the keyword of that node. For +example, a node corresponding to the input line: +.sp +.nf +.in +5 +pidfile "/var/run/mypid"; +.in +.fi +.sp +will have \fBident\fR pointing to the string \fB/var/run/mypid\fR. +.PP +Finally, the \fBvalue\fR member keeps the value associated with this +statement. It is defined as: +.sp +.nf +.in +5 +typedef struct grecs_value { + int type; + union { + struct grecs_list *list; + const char *string; + struct { + size_t c; + struct grecs_value *v; + } arg; + } v; +} grecs_value_t; +.in +.fi +.PP +The \fBtype\fR will be \fBGRECS_TYPE_STRING\fR, for string values, +\fBGRECS_TYPE_LIST\fR, for list values, and \fBGRECS_TYPE_ARRAY\fR, +for arrays of values. Depending on its value, the following members +of the union are used: +.TP +.B GRECS_TYPE_STRING +Actual string value is pointed to by \fBv.string\fR. +.TP +.B GRECS_TYPE_LIST +The list value is pointed to by \fBv.list\fR. +.TP +.B GRECS_TYPE_ARRAY +The array itself is stored in \fBv.arg.v\fR. The \fBv.arg.c\fR member +contains the number of elements in the array. +.SH RETURN VALUE +On success, a pointer to the root node. On error, \fBNULL\fR. +.SH EXAMPLE +The following program parses the file and prints its contents on +screen: +.sp +.nf +.in +5 +int +main(int argc, char **argv) +{ + struct grecs_node *tree, *node; + + tree = grecs_parse(argv[1]); + for (node = tree; node; node = node->next) { + grecs_format_node(node, GRECS_NODE_FLAG_DEFAULT, stdout); + fputc('\n', stdout); + } + grecs_tree_free(tree); + exit(0); +} +.in +.fi +.SH "SEE ALSO" +.BR grecs_config (5), +.BR grecs_error (3), +.BR grecs_format_node (3), +.BR grecs_tree_free (3). +.SH AUTHORS +Sergey Poznyakoff +.SH "BUG REPORTS" +Report bugs to . +.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 . +.SH COPYRIGHT +Copyright \(co 2011 Sergey Poznyakoff +.br +.na +License GPLv3+: GNU GPL version 3 or later +.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_stmt_path.5 b/doc/grecs_stmt_path.5 new file mode 100644 index 0000000..52941d5 --- /dev/null +++ b/doc/grecs_stmt_path.5 @@ -0,0 +1,123 @@ +.\" 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 . +.\" This file is part of SLB. +.\" Copyright (C) 2011 Sergey Poznyakoff +.\" +.TH GRECS_STMT_PATH 5 "May 4, 2011" "GRECS" "Grecs User Reference" +.SH NAME +Statement pathname \- a unique identifier of a statement in +\fBgrecs\fR configuration file. +.SH DESCRIPTION +\fBGrecs\fR configuration files have a distinct hierarchical +structure. Each statement in such a file can therefore be identified +by its name and the names of block statements containing it. Such +names form this statement \fIpathname\fR, similar to that used, +e.g. by UNIX file system. +.PP +For example, consider the following file: +.sp +.nf +.in +2 +foo { + bar { + baz 45; # \fBA\fR. + } + baz 98; # \fBB\fR. +} +.fi +.PP +The full pathname of the statement marked with \fBA\fR can be written +as: +.sp +.nf +.in +2 + .foo.bar.baz +.fi +.PP +Similarly, the statement marked with \fBB\fR has the following +pathname: +.sp +.nf +.in +2 + .foo.baz +.fi +.PP +The default path component separator is dot. A pathname beginning with +a component separator is called an \fIabsolute pathname\fR. Absolute +pathnames uniquely identify corresponding statements. If the leading +dot is omitted, the resulting pathname is called +\fIrelative\fR. Relative pathnames identify statements in relation to +the current point of reference in the configuration file. +.PP +Any other punctuation character can be used as a component separator, +provided that it appears at the beginning of the pathname. In other +words, only absolute pathnames can be written this way. +.PP +A block statement that has a tag is referred to by its name, followed +by an equals sign, followed by the tag value. For example, the +statement \fBA\fR in the file below: +.sp +.nf +.in +2 +program x { + bar { + baz 45; # \fBA\fR. + } +} +.fi +.PP +is identified by the following pathname: +.sp +.nf +.in +2 + .program=x.bar.baz +.fi +.PP +The tag can optionally be enclosed in a pair of double quotes. Such a +quoting becomes mandatory for tags that contain white space or path +component separator, e.g.: +.sp +.nf +.in +2 + .program=\(dqa.out\(dq.bar.baz +.fi +.SH "SEE ALSO" +.BR grecs_config (5). +.SH AUTHORS +Sergey Poznyakoff +.SH "BUG REPORTS" +Report bugs to . +.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 . +.SH COPYRIGHT +Copyright \(co 2011 Sergey Poznyakoff +.br +.na +License GPLv3+: GNU GPL version 3 or later +.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_strdup.3 b/doc/grecs_strdup.3 new file mode 100644 index 0000000..441eb23 --- /dev/null +++ b/doc/grecs_strdup.3 @@ -0,0 +1,70 @@ +.\" 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 . +.\" This file is part of SLB. +.\" Copyright (C) 2011 Sergey Poznyakoff +.\" +.TH GRECS_STRDUP 3 "May 3, 2011" "GRECS" "Grecs User Reference" +.SH NAME +grecs_strdup \- duplicate a string +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "char *grecs_strdup(const char *" "str" ); + +.SH DESCRIPTION +The +.BR strdup () +function returns a pointer to a new string which is a duplicate of the +string \fIstr\fR. Memory for the new string is obtained with +.BR grecs_malloc (3), +and can be freed with +.BR free(3). +.SH "RETURN VALUE" +The +.BR grecs_strdup () +function returns a pointer to the duplicated string. +.PP +On error, +.BR grecs_alloc_die (3) +is called, which terminates the program. +.SH "SEE ALSO" +.BR grecs_alloc_die (3) +.SH AUTHORS +Sergey Poznyakoff +.SH "BUG REPORTS" +Report bugs to . +.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 . +.SH COPYRIGHT +Copyright \(co 2011 Sergey Poznyakoff +.br +.na +License GPLv3+: GNU GPL version 3 or later +.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_tree_free.3 b/doc/grecs_tree_free.3 new file mode 100644 index 0000000..527995a --- /dev/null +++ b/doc/grecs_tree_free.3 @@ -0,0 +1,61 @@ +.\" 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 . +.\" This file is part of SLB. +.\" Copyright (C) 2011 Sergey Poznyakoff +.\" +.TH GRECS_XXX 3 "May 4, 2011" "GRECS" "Grecs User Reference" +.SH NAME +grecs_tree_free \- reclaim the memory used by entire parse tree +.SH SYNOPSIS +.nf +.B #include +.sp +.BI "void grecs_tree_free(struct grecs_node " "*node" ); +.SH DESCRIPTION +\fBgrecs_tree_free\fR reclaims the memory used by \fInode\fR and all +nodes it points to, recursively. +.PP +The argument \fInode\fR must be the root of a parse tree. +.SH "RETURN VALUE" +None. +.SH "SEE ALSO" +.BR grecs_parse (3), +.BR grecs_node_free (3). +.SH AUTHORS +Sergey Poznyakoff +.SH "BUG REPORTS" +Report bugs to . +.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 . +.SH COPYRIGHT +Copyright \(co 2011 Sergey Poznyakoff +.br +.na +License GPLv3+: GNU GPL version 3 or later +.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/tmpl.3 b/doc/tmpl.3 new file mode 100644 index 0000000..30c60e7 --- /dev/null +++ b/doc/tmpl.3 @@ -0,0 +1,54 @@ +.\" This file is part of grecs -*- nroff -