summaryrefslogtreecommitdiffabout
authorSergey Poznyakoff <gray@gnu.org.ua>2011-05-01 15:01:03 (GMT)
committer Sergey Poznyakoff <gray@gnu.org.ua>2011-05-01 15:01:03 (GMT)
commitda56e338d346e358de864d18ca42f574305d8dfc (patch) (unidiff)
tree30e40f293aa1978460f78dfe43a2084227ae6c77
parent5906ff8971e683deb35ee0beea1425aa93aeb499 (diff)
downloadgrecs-da56e338d346e358de864d18ca42f574305d8dfc.tar.gz
grecs-da56e338d346e358de864d18ca42f574305d8dfc.tar.bz2
Update copyright years. Add docs.
Diffstat (more/less context) (ignore whitespace changes)
-rw-r--r--am/grecs.m44
-rw-r--r--doc/grecs-syntax.texi386
-rw-r--r--src/Makefile.am2
-rw-r--r--src/format.c2
-rw-r--r--src/grecs-gram.y2
-rw-r--r--src/grecs-lex.l2
-rw-r--r--src/grecs.h2
-rw-r--r--src/list.c2
-rw-r--r--src/pp-setup2
-rw-r--r--src/preproc.c2
-rw-r--r--src/text.c2
-rw-r--r--src/wordsplit.c2
12 files changed, 398 insertions, 12 deletions
diff --git a/am/grecs.m4 b/am/grecs.m4
index 8d046f5..47c9867 100644
--- a/am/grecs.m4
+++ b/am/grecs.m4
@@ -1,3 +1,3 @@
1# This file is part of grecs - Gray's Extensible Configuration System -*- autoconf -*- 1# This file is part of grecs - Gray's Extensible Configuration System -*- autoconf -*-
2# Copyright (C) 2007, 2009, 2010 Sergey Poznyakoff 2# Copyright (C) 2007, 2009-2011 Sergey Poznyakoff
3# 3#
@@ -47,3 +47,3 @@ AC_DEFUN([_GRECS_OPTION_SWITCH],
47# ---------------------------------- 47# ----------------------------------
48# OPTIONS is a space-separated list of Gint options. 48# OPTIONS is a space-separated list of Grecs options.
49AC_DEFUN([_GRECS_SET_OPTIONS], 49AC_DEFUN([_GRECS_SET_OPTIONS],
diff --git a/doc/grecs-syntax.texi b/doc/grecs-syntax.texi
new file mode 100644
index 0000000..b95a0ba
--- a/dev/null
+++ b/doc/grecs-syntax.texi
@@ -0,0 +1,386 @@
1@c This file is part of grecs - Gray's Extensible Configuration System
2@c Copyright (C) 2007, 2009, 2010, 2011 Sergey Poznyakoff
3@c
4@c Grecs is free software; you can redistribute it and/or modify
5@c it under the terms of the GNU General Public License as published by
6@c the Free Software Foundation; either version 3, or (at your option)
7@c any later version.
8@c
9@c Grecs is distributed in the hope that it will be useful,
10@c but WITHOUT ANY WARRANTY; without even the implied warranty of
11@c MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12@c GNU General Public License for more details.
13@c
14@c You should have received a copy of the GNU General Public License
15@c along with Grecs. If not, see <http://www.gnu.org/licenses/>.
16
17@c TIPS: 1. You can @include this file directly into your Texinfo
18@c document. It produces a section as its upper level sectioning
19@c command. If it is not appropriate, use @raisesections or
20@c @lowersections:
21@c
22@c @raisesections
23@c @include grecs-syntax.texi
24@c @lowersections
25@c
26@c 2. This texinfo source refers to the following values:
27@c
28@c PACKAGE - name of the package
29@c PROGNAME - name of the program, which uses Grecs (without any
30@c Texinfo markup)
31@c
32@c 3. Some additional/optional parts of the text are commented out, and
33@c marked with `@c FIXME:' comments.
34
35@section Configuration file syntax
36
37 The configuration file consists of statements and comments.
38
39 There are three classes of lexical tokens: keywords, values, and
40separators. Blanks, tabs, newlines and comments, collectively called
41@dfn{white space} are ignored except as they serve to separate
42tokens. Some white space is required to separate otherwise adjacent
43keywords and values.
44
45@menu
46* Comments::
47* Pragmatic Comments::
48* Statements::
49* Preprocessor::
50@end menu
51
52@node Comments
53@subsection Comments
54@cindex Comments in a configuration file
55@cindex single-line comments
56 @dfn{Comments} may appear anywhere where white space may appear in the
57configuration file. There are two kinds of comments:
58single-line and multi-line comments. @dfn{Single-line} comments start
59with @samp{#} or @samp{//} and continue to the end of the line:
60
61@smallexample
62# This is a comment
63// This too is a comment
64@end smallexample
65
66@cindex multi-line comments
67 @dfn{Multi-line} or @dfn{C-style} comments start with the two
68characters @samp{/*} (slash, star) and continue until the first
69occurrence of @samp{*/} (star, slash).
70
71 Multi-line comments cannot be nested. However, single-line comments
72may well appear within multi-line ones.
73
74@node Pragmatic Comments
75@subsection Pragmatic Comments
76@cindex comments, pragmatic
77@cindex pragmatic comments
78 Pragmatic comments are similar to usual single-line comments,
79except that they cause some changes in the way the configuration is
80parsed. Pragmatic comments begin with a @samp{#} sign and end with the
81next physical newline character.
82
83@table @code
84@kwindex #include
85@item #include <@var{file}>
86@itemx #include @var{file}
87Include the contents of the file @var{file}. If @var{file} is an
88absolute file name, both forms are equivalent. Otherwise, the form
89with angle brackets searches for the file in the @dfn{include
90search path}, while the second one looks for it in the current working
91directory first, and, if not found there, in the include search
92path.
93
94The default include search path is:
95
96@enumerate 1
97@item @file{@var{prefix}/share/slb/@value{VERSION}/include}
98@item @file{@var{prefix}/share/slb/include}
99@end enumerate
100
101@noindent
102where @var{prefix} is the installation prefix.
103
104@c FIXME: Uncomment this, if necessary:
105@c FIXME: New directories can be appended in front of it using @option{-I}
106@c FIXME: (@option{--include-directory}) command line option
107@c FIXME: (@pxref{Preprocessor, include-directory}).
108
109@kwindex #include_once
110@item #include_once <@var{file}>
111@itemx #include_once @var{file}
112 Same as @code{#include}, except that, if the @var{file} has already
113been included, it will not be included again.
114
115@kwindex #line
116@item #line @var{num}
117@itemx #line @var{num} "@var{file}"
118 This line causes the parser to believe, for purposes of error
119diagnostics, that the line number of the next source line is given by
120@var{num} and the current input file is named by @var{file}.
121If the latter is absent, the remembered file name does not change.
122
123@item # @var{num} "@var{file}"
124 This is a special form of @code{#line} statement, understood for
125compatibility with the @sc{c} preprocessor.
126@end table
127
128 In fact, these statements provide a rudimentary preprocessing
129features. For more sophisticated ways to modify configuration before
130parsing, see @ref{Preprocessor}.
131
132@node Statements
133@subsection Statements
134@cindex statements, configuration file
135@cindex configuration file statements
136@cindex statement, simple
137@cindex simple statements
138 A @dfn{simple statement} consists of a keyword and value
139separated by any amount of whitespace. Simple statement is terminated
140with a semicolon (@samp{;}).
141
142 The following is a simple statement:
143
144@smallexample
145standalone yes;
146pidfile /var/run/slb.pid;
147@end smallexample
148
149 A @dfn{keyword} begins with a letter and may contain letters,
150decimal digits, underscores (@samp{_}) and dashes (@samp{-}).
151Examples of keywords are: @samp{expression}, @samp{output-file}.
152
153 A @dfn{value} can be one of the following:
154
155@table @asis
156@item number
157 A number is a sequence of decimal digits.
158
159@item boolean
160@cindex boolean value
161 A boolean value is one of the following: @samp{yes}, @samp{true},
162@samp{t} or @samp{1}, meaning @dfn{true}, and @samp{no},
163@samp{false}, @samp{nil}, @samp{0} meaning @dfn{false}.
164
165@item unquoted string
166@cindex string, unquoted
167 An unquoted string may contain letters, digits, and any of the
168following characters: @samp{_}, @samp{-}, @samp{.}, @samp{/},
169@samp{@@}, @samp{*}, @samp{:}.
170
171@item quoted string
172@cindex quoted string
173@cindex string, quoted
174@cindex escape sequence
175 A quoted string is any sequence of characters enclosed in
176double-quotes (@samp{"}). A backslash appearing within a quoted
177string introduces an @dfn{escape sequence}, which is replaced
178with a single character according to the following rules:
179
180@float Table, backslash-interpretation
181@caption{Backslash escapes}
182@multitable @columnfractions 0.30 .5
183@item Sequence @tab Replaced with
184@item \a @tab Audible bell character (@acronym{ASCII} 7)
185@item \b @tab Backspace character (@acronym{ASCII} 8)
186@item \f @tab Form-feed character (@acronym{ASCII} 12)
187@item \n @tab Newline character (@acronym{ASCII} 10)
188@item \r @tab Carriage return character (@acronym{ASCII} 13)
189@item \t @tab Horizontal tabulation character (@acronym{ASCII} 9)
190@item \v @tab Vertical tabulation character (@acronym{ASCII} 11)
191@item \\ @tab A single backslash (@samp{\})
192@item \" @tab A double-quote.
193@end multitable
194@end float
195
196 In addition, the sequence @samp{\@var{newline}} is removed from
197the string. This allows to split long strings over several
198physical lines, e.g.:
199
200@smallexample
201@group
202"a long string may be\
203 split over several lines"
204@end group
205@end smallexample
206
207 If the character following a backslash is not one of those specified
208above, the backslash is ignored and a warning is issued.
209
210 Two or more adjacent quoted strings are concatenated, which gives
211another way to split long strings over several lines to improve
212readability. The following fragment produces the same result as the
213example above:
214
215@smallexample
216@group
217"a long string may be"
218" split over several lines"
219@end group
220@end smallexample
221
222@anchor{here-document}
223@item Here-document
224@cindex here-document
225 A @dfn{here-document} is a special construct that allows to introduce
226strings of text containing embedded newlines.
227
228 The @code{<<@var{word}} construct instructs the parser to read all
229the following lines up to the line containing only @var{word}, with
230possible trailing blanks. Any lines thus read are concatenated
231together into a single string. For example:
232
233@smallexample
234@group
235<<EOT
236A multiline
237string
238EOT
239@end group
240@end smallexample
241
242 The body of a here-document is interpreted the same way as a
243double-quoted string, unless @var{word} is preceded by a backslash
244(e.g. @samp{<<\EOT}) or enclosed in double-quotes, in which case
245the text is read as is, without interpretation of escape sequences.
246
247 If @var{word} is prefixed with @code{-} (a dash), then all leading
248tab characters are stripped from input lines and the line containing
249@var{word}. Furthermore, if @code{-} is followed by a single space,
250all leading whitespace is stripped from them. This allows to indent
251here-documents in a natural fashion. For example:
252
253@smallexample
254@group
255<<- TEXT
256 The leading whitespace will be
257 ignored when reading these lines.
258TEXT
259@end group
260@end smallexample
261
262 It is important that the terminating delimiter be the only token on
263its line. The only exception to this rule is allowed if a
264here-document appears as the last element of a statement. In this
265case a semicolon can be placed on the same line with its terminating
266delimiter, as in:
267
268@smallexample
269help-text <<-EOT
270 A sample help text.
271EOT;
272@end smallexample
273
274@item list
275@cindex list
276 A @dfn{list} is a comma-separated list of values. Lists are
277enclosed in parentheses. The following example shows a statement
278whose value is a list of strings:
279
280@smallexample
281alias (test,null);
282@end smallexample
283
284 In any case where a list is appropriate, a single value is allowed
285without being a member of a list: it is equivalent to a list with a
286single member. This means that, e.g.
287
288@smallexample
289alias test;
290@end smallexample
291
292@noindent
293is equivalent to
294
295@smallexample
296alias (test);
297@end smallexample
298@end table
299
300@cindex statement, block
301@cindex block statement
302 A @dfn{block statement} introduces a logical group of
303statements. It consists of a keyword, followed by an optional value,
304and a sequence of statements enclosed in curly braces, as shown in
305the example below:
306
307@smallexample
308@group
309server srv1 @{
310 host 10.0.0.1;
311 community "foo";
312@}
313@end group
314@end smallexample
315
316 The closing curly brace may be followed by a semicolon, although
317this is not required.
318
319@node Preprocessor
320@subsection Preprocessor
321@cindex preprocessor
322@cindex m4
323 Before actual parsing, the configuration file is preprocessed.
324The built-in preprocessor handles only file inclusion
325and @code{#line} statements (@pxref{Pragmatic Comments}), while the
326rest of traditional preprocessing facilities, such as macro expansion,
327is supported via @command{m4}, which serves as external preprocessor.
328
329 The detailed description of @command{m4} facilities lies far beyond
330the scope of this document. You will find a complete user manual in
331@ifnothtml
332@ref{Top, GNU M4 manual, GNU M4, m4, GNU M4 macro processor}.
333@end ifnothtml
334@ifhtml
335@uref{http://www.gnu.org/software/m4/manual}.
336@end ifhtml
337For the rest of this subsection we assume the reader is sufficiently
338acquainted with @command{m4} macro processor.
339
340@cindex @file{pp-setup}
341 The external preprocessor is invoked with @option{-s} flag, which
342instructs it to include line synchronization information in its
343output. This information is then used by the parser to display meaningful
344diagnostic.
345
346An initial set of macro definitions is supplied by the
347@file{pp-setup} file, located in
348@file{@var{$prefix}/share/@value{PROGNAME}/@var{version}/include}
349directory (where @var{version} means the version of @value{PACKAGE}).
350
351 The default @file{pp-setup} file renames all @command{m4} built-in
352macro names so they all start with the prefix @samp{m4_}. This
353is similar to GNU m4 @option{--prefix-builtin} options, but has an
354advantage that it works with non-GNU @command{m4} implementations as
355well.
356
357@c FIXME:
358@ignore
359 Additional control over the preprocessor is provided via the
360following command line options:
361
362@table @option
363@xopindex{define, introduced}
364@sopindex{D, introduced}
365@item --define=@var{name}[=@var{value}]
366@itemx -D@var{name}[=@var{value}]
367 Define the preprocessor symbol @var{name} as having @var{value}, or
368empty.
369
370@xopindex{include-directory, introduced}
371@sopindex{I, introduced}
372@item --include-directory=@var{dir}
373@itemx -I@var{dir}
374 Add @var{dir} to the list of directories searched for preprocessor
375include files.
376
377@xopindex{no-preprocessor, defined}
378@item --no-preprocessor
379 Disable preprocessor.
380
381@xopindex{preprocessor, defined}
382@item --preprocessor=@var{command}
383Use @var{command} instead of the default preprocessor.
384@end table
385@end ignore
386
diff --git a/src/Makefile.am b/src/Makefile.am
index 772a647..2f35f52 100644
--- a/src/Makefile.am
+++ b/src/Makefile.am
@@ -1,3 +1,3 @@
1# This file is part of grecs - Gray's Extensible Configuration System 1# This file is part of grecs - Gray's Extensible Configuration System
2# Copyright (C) 2007, 2009, 2010 Sergey Poznyakoff 2# Copyright (C) 2007, 2009-2011 Sergey Poznyakoff
3# 3#
diff --git a/src/format.c b/src/format.c
index 76121f8..a1aa67d 100644
--- a/src/format.c
+++ b/src/format.c
@@ -1,3 +1,3 @@
1/* grecs - Gray's Extensible Configuration System 1/* grecs - Gray's Extensible Configuration System
2 Copyright (C) 2007, 2008, 2009, 2010 Sergey Poznyakoff 2 Copyright (C) 2007-2011 Sergey Poznyakoff
3 3
diff --git a/src/grecs-gram.y b/src/grecs-gram.y
index 114e151..0edea13 100644
--- a/src/grecs-gram.y
+++ b/src/grecs-gram.y
@@ -2,3 +2,3 @@
2/* grecs - Gray's Extensible Configuration System 2/* grecs - Gray's Extensible Configuration System
3 Copyright (C) 2007, 2008, 2009, 2010 Sergey Poznyakoff 3 Copyright (C) 2007-2011 Sergey Poznyakoff
4 4
diff --git a/src/grecs-lex.l b/src/grecs-lex.l
index a16045a..baf85de 100644
--- a/src/grecs-lex.l
+++ b/src/grecs-lex.l
@@ -8,3 +8,3 @@
8/* grecs - Gray's Extensible Configuration System 8/* grecs - Gray's Extensible Configuration System
9 Copyright (C) 2007, 2008, 2009, 2010 Sergey Poznyakoff 9 Copyright (C) 2007-2011 Sergey Poznyakoff
10 10
diff --git a/src/grecs.h b/src/grecs.h
index 99c0453..ec98979 100644
--- a/src/grecs.h
+++ b/src/grecs.h
@@ -1,3 +1,3 @@
1/* grecs - Gray's Extensible Configuration System 1/* grecs - Gray's Extensible Configuration System
2 Copyright (C) 2007, 2008, 2009, 2010 Sergey Poznyakoff 2 Copyright (C) 2007-2011 Sergey Poznyakoff
3 3
diff --git a/src/list.c b/src/list.c
index 3bb0757..4a5d3f6 100644
--- a/src/list.c
+++ b/src/list.c
@@ -1,3 +1,3 @@
1/* grecs - Gray's Extensible Configuration System 1/* grecs - Gray's Extensible Configuration System
2 Copyright (C) 2007, 2008, 2009, 2010 Sergey Poznyakoff 2 Copyright (C) 2007-2011 Sergey Poznyakoff
3 3
diff --git a/src/pp-setup b/src/pp-setup
index ad97441..9076ada 100644
--- a/src/pp-setup
+++ b/src/pp-setup
@@ -2,3 +2,3 @@ divert(-1) dnl -*- m4 -*-
2# This file is part of grecs - Gray's Extensible Configuration System 2# This file is part of grecs - Gray's Extensible Configuration System
3# Copyright (C) 2007, 2009, 2010 Sergey Poznyakoff 3# Copyright (C) 2007, 2009-2011 Sergey Poznyakoff
4# 4#
diff --git a/src/preproc.c b/src/preproc.c
index a71c93f..7ea9442 100644
--- a/src/preproc.c
+++ b/src/preproc.c
@@ -1,3 +1,3 @@
1/* grecs - Gray's Extensible Configuration System 1/* grecs - Gray's Extensible Configuration System
2 Copyright (C) 2007, 2008, 2009, 2010 Sergey Poznyakoff 2 Copyright (C) 2007-2011 Sergey Poznyakoff
3 3
diff --git a/src/text.c b/src/text.c
index 18f6549..6b8b905 100644
--- a/src/text.c
+++ b/src/text.c
@@ -1,3 +1,3 @@
1/* grecs - Gray's Extensible Configuration System 1/* grecs - Gray's Extensible Configuration System
2 Copyright (C) 2007, 2008, 2009, 2010 Sergey Poznyakoff 2 Copyright (C) 2007-2011 Sergey Poznyakoff
3 3
diff --git a/src/wordsplit.c b/src/wordsplit.c
index ccc1080..662a1e1 100644
--- a/src/wordsplit.c
+++ b/src/wordsplit.c
@@ -1,3 +1,3 @@
1/* wordsplit - a word splitter 1/* wordsplit - a word splitter
2 Copyright (C) 2009, 2010 Sergey Poznyakoff 2 Copyright (C) 2009-2011 Sergey Poznyakoff
3 3

Return to:

Send suggestions and report system problems to the System administrator.