aboutsummaryrefslogtreecommitdiff
path: root/doc/grecs-syntax.texi
diff options
context:
space:
mode:
Diffstat (limited to 'doc/grecs-syntax.texi')
-rw-r--r--doc/grecs-syntax.texi386
1 files changed, 386 insertions, 0 deletions
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 @@
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
238