From da56e338d346e358de864d18ca42f574305d8dfc Mon Sep 17 00:00:00 2001 From: Sergey Poznyakoff Date: Sun, 1 May 2011 18:01:03 +0300 Subject: Update copyright years. Add docs. --- am/grecs.m4 | 4 +- doc/grecs-syntax.texi | 386 ++++++++++++++++++++++++++++++++++++++++++++++++++ src/Makefile.am | 2 +- src/format.c | 2 +- src/grecs-gram.y | 2 +- src/grecs-lex.l | 2 +- src/grecs.h | 2 +- src/list.c | 2 +- src/pp-setup | 2 +- src/preproc.c | 2 +- src/text.c | 2 +- src/wordsplit.c | 2 +- 12 files changed, 398 insertions(+), 12 deletions(-) create mode 100644 doc/grecs-syntax.texi diff --git a/am/grecs.m4 b/am/grecs.m4 index 8d046f5..47c9867 100644 --- a/am/grecs.m4 +++ b/am/grecs.m4 @@ -1,5 +1,5 @@ # This file is part of grecs - Gray's Extensible Configuration System -*- autoconf -*- -# Copyright (C) 2007, 2009, 2010 Sergey Poznyakoff +# Copyright (C) 2007, 2009-2011 Sergey Poznyakoff # # Grex is free software; you can redistribute it and/or modify # it under the terms of the GNU General Public License as published by @@ -45,7 +45,7 @@ AC_DEFUN([_GRECS_OPTION_SWITCH], # _GRECS_SET_OPTIONS(OPTIONS) # ---------------------------------- -# OPTIONS is a space-separated list of Gint options. +# OPTIONS is a space-separated list of Grecs options. AC_DEFUN([_GRECS_SET_OPTIONS], [m4_foreach_w([_GRECS_Option], [$1], [_GRECS_SET_OPTION(_GRECS_Option)])]) diff --git a/doc/grecs-syntax.texi b/doc/grecs-syntax.texi new file mode 100644 index 0000000..b95a0ba --- /dev/null +++ b/doc/grecs-syntax.texi @@ -0,0 +1,386 @@ +@c This file is part of grecs - Gray's Extensible Configuration System +@c Copyright (C) 2007, 2009, 2010, 2011 Sergey Poznyakoff +@c +@c Grecs is free software; you can redistribute it and/or modify +@c it under the terms of the GNU General Public License as published by +@c the Free Software Foundation; either version 3, or (at your option) +@c any later version. +@c +@c Grecs is distributed in the hope that it will be useful, +@c but WITHOUT ANY WARRANTY; without even the implied warranty of +@c MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +@c GNU General Public License for more details. +@c +@c You should have received a copy of the GNU General Public License +@c along with Grecs. If not, see . + +@c TIPS: 1. You can @include this file directly into your Texinfo +@c document. It produces a section as its upper level sectioning +@c command. If it is not appropriate, use @raisesections or +@c @lowersections: +@c +@c @raisesections +@c @include grecs-syntax.texi +@c @lowersections +@c +@c 2. This texinfo source refers to the following values: +@c +@c PACKAGE - name of the package +@c PROGNAME - name of the program, which uses Grecs (without any +@c Texinfo markup) +@c +@c 3. Some additional/optional parts of the text are commented out, and +@c marked with `@c FIXME:' comments. + +@section Configuration file syntax + + The configuration file consists of statements and comments. + + There are three classes of lexical tokens: keywords, values, and +separators. Blanks, tabs, newlines and comments, collectively called +@dfn{white space} are ignored except as they serve to separate +tokens. Some white space is required to separate otherwise adjacent +keywords and values. + +@menu +* Comments:: +* Pragmatic Comments:: +* Statements:: +* Preprocessor:: +@end menu + +@node Comments +@subsection Comments +@cindex Comments in a configuration file +@cindex single-line comments + @dfn{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. @dfn{Single-line} comments start +with @samp{#} or @samp{//} and continue to the end of the line: + +@smallexample +# This is a comment +// This too is a comment +@end smallexample + +@cindex multi-line comments + @dfn{Multi-line} or @dfn{C-style} comments start with the two +characters @samp{/*} (slash, star) and continue until the first +occurrence of @samp{*/} (star, slash). + + Multi-line comments cannot be nested. However, single-line comments +may well appear within multi-line ones. + +@node Pragmatic Comments +@subsection Pragmatic Comments +@cindex comments, pragmatic +@cindex 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 @samp{#} sign and end with the +next physical newline character. + +@table @code +@kwindex #include +@item #include <@var{file}> +@itemx #include @var{file} +Include the contents of the file @var{file}. If @var{file} is an +absolute file name, both forms are equivalent. Otherwise, the form +with angle brackets searches for the file in the @dfn{include +search path}, while the second one looks for it in the current working +directory first, and, if not found there, in the include search +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} +@end enumerate + +@noindent +where @var{prefix} is the installation prefix. + +@c FIXME: Uncomment this, if necessary: +@c FIXME: New directories can be appended in front of it using @option{-I} +@c FIXME: (@option{--include-directory}) command line option +@c FIXME: (@pxref{Preprocessor, include-directory}). + +@kwindex #include_once +@item #include_once <@var{file}> +@itemx #include_once @var{file} + Same as @code{#include}, except that, if the @var{file} has already +been included, it will not be included again. + +@kwindex #line +@item #line @var{num} +@itemx #line @var{num} "@var{file}" + This line causes the parser to believe, for purposes of error +diagnostics, that the line number of the next source line is given by +@var{num} and the current input file is named by @var{file}. +If the latter is absent, the remembered file name does not change. + +@item # @var{num} "@var{file}" + This is a special form of @code{#line} statement, understood for +compatibility with the @sc{c} preprocessor. +@end table + + In fact, these statements provide a rudimentary preprocessing +features. For more sophisticated ways to modify configuration before +parsing, see @ref{Preprocessor}. + +@node Statements +@subsection Statements +@cindex statements, configuration file +@cindex configuration file statements +@cindex statement, simple +@cindex simple statements + A @dfn{simple statement} consists of a keyword and value +separated by any amount of whitespace. Simple statement is terminated +with a semicolon (@samp{;}). + + The following is a simple statement: + +@smallexample +standalone yes; +pidfile /var/run/slb.pid; +@end smallexample + + A @dfn{keyword} begins with a letter and may contain letters, +decimal digits, underscores (@samp{_}) and dashes (@samp{-}). +Examples of keywords are: @samp{expression}, @samp{output-file}. + + A @dfn{value} can be one of the following: + +@table @asis +@item number + A number is a sequence of decimal digits. + +@item boolean +@cindex boolean value + A boolean value is one of the following: @samp{yes}, @samp{true}, +@samp{t} or @samp{1}, meaning @dfn{true}, and @samp{no}, +@samp{false}, @samp{nil}, @samp{0} meaning @dfn{false}. + +@item unquoted string +@cindex string, unquoted + An unquoted string may contain letters, digits, and any of the +following characters: @samp{_}, @samp{-}, @samp{.}, @samp{/}, +@samp{@@}, @samp{*}, @samp{:}. + +@item quoted string +@cindex quoted string +@cindex string, quoted +@cindex escape sequence + A quoted string is any sequence of characters enclosed in +double-quotes (@samp{"}). A backslash appearing within a quoted +string introduces an @dfn{escape sequence}, which is replaced +with a single character according to the following rules: + +@float Table, backslash-interpretation +@caption{Backslash escapes} +@multitable @columnfractions 0.30 .5 +@item Sequence @tab Replaced with +@item \a @tab Audible bell character (@acronym{ASCII} 7) +@item \b @tab Backspace character (@acronym{ASCII} 8) +@item \f @tab Form-feed character (@acronym{ASCII} 12) +@item \n @tab Newline character (@acronym{ASCII} 10) +@item \r @tab Carriage return character (@acronym{ASCII} 13) +@item \t @tab Horizontal tabulation character (@acronym{ASCII} 9) +@item \v @tab Vertical tabulation character (@acronym{ASCII} 11) +@item \\ @tab A single backslash (@samp{\}) +@item \" @tab A double-quote. +@end multitable +@end float + + In addition, the sequence @samp{\@var{newline}} is removed from +the string. This allows to split long strings over several +physical lines, e.g.: + +@smallexample +@group +"a long string may be\ + split over several lines" +@end group +@end smallexample + + 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: + +@smallexample +@group +"a long string may be" +" split over several lines" +@end group +@end smallexample + +@anchor{here-document} +@item Here-document +@cindex here-document + A @dfn{here-document} is a special construct that allows to introduce +strings of text containing embedded newlines. + + The @code{<<@var{word}} construct instructs the parser to read all +the following lines up to the line containing only @var{word}, with +possible trailing blanks. Any lines thus read are concatenated +together into a single string. For example: + +@smallexample +@group +<