diff options
Diffstat (limited to 'doc/grecs_config.5')
-rw-r--r-- | doc/grecs_config.5 | 343 |
1 files changed, 343 insertions, 0 deletions
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: |