diff options
Diffstat (limited to 'doc/grecs-syntax.texi')
-rw-r--r-- | doc/grecs-syntax.texi | 386 |
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 | ||
40 | separators. Blanks, tabs, newlines and comments, collectively called | ||
41 | @dfn{white space} are ignored except as they serve to separate | ||
42 | tokens. Some white space is required to separate otherwise adjacent | ||
43 | keywords 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 | ||
57 | configuration file. There are two kinds of comments: | ||
58 | single-line and multi-line comments. @dfn{Single-line} comments start | ||
59 | with @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 | ||
68 | characters @samp{/*} (slash, star) and continue until the first | ||
69 | occurrence of @samp{*/} (star, slash). | ||
70 | |||
71 | Multi-line comments cannot be nested. However, single-line comments | ||
72 | may 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, | ||
79 | except that they cause some changes in the way the configuration is | ||
80 | parsed. Pragmatic comments begin with a @samp{#} sign and end with the | ||
81 | next physical newline character. | ||
82 | |||
83 | @table @code | ||
84 | @kwindex #include | ||
85 | @item #include <@var{file}> | ||
86 | @itemx #include @var{file} | ||
87 | Include the contents of the file @var{file}. If @var{file} is an | ||
88 | absolute file name, both forms are equivalent. Otherwise, the form | ||
89 | with angle brackets searches for the file in the @dfn{include | ||
90 | search path}, while the second one looks for it in the current working | ||
91 | directory first, and, if not found there, in the include search | ||
92 | path. | ||
93 | |||
94 | The 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 | ||
102 | where @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 | ||
113 | been 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 | ||
119 | diagnostics, 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}. | ||
121 | If 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 | ||
125 | compatibility with the @sc{c} preprocessor. | ||
126 | @end table | ||
127 | |||
128 | In fact, these statements provide a rudimentary preprocessing | ||
129 | features. For more sophisticated ways to modify configuration before | ||
130 | parsing, 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 | ||
139 | separated by any amount of whitespace. Simple statement is terminated | ||
140 | with a semicolon (@samp{;}). | ||
141 | |||
142 | The following is a simple statement: | ||
143 | |||
144 | @smallexample | ||
145 | standalone yes; | ||
146 | pidfile /var/run/slb.pid; | ||
147 | @end smallexample | ||
148 | |||
149 | A @dfn{keyword} begins with a letter and may contain letters, | ||
150 | decimal digits, underscores (@samp{_}) and dashes (@samp{-}). | ||
151 | Examples 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 | ||
168 | following 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 | ||
176 | double-quotes (@samp{"}). A backslash appearing within a quoted | ||
177 | string introduces an @dfn{escape sequence}, which is replaced | ||
178 | with 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 | ||
197 | the string. This allows to split long strings over several | ||
198 | physical 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 | ||
208 | above, the backslash is ignored and a warning is issued. | ||
209 | |||
210 | Two or more adjacent quoted strings are concatenated, which gives | ||
211 | another way to split long strings over several lines to improve | ||
212 | readability. The following fragment produces the same result as the | ||
213 | example 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 | ||
226 | strings of text containing embedded newlines. | ||
227 | |||
228 | The @code{<<@var{word}} construct instructs the parser to read all | ||
229 | the following lines up to the line containing only @var{word}, with | ||
230 | possible trailing blanks. Any lines thus read are concatenated | ||
231 | together into a single string. For example: | ||
232 | |||
233 | @smallexample | ||
234 | @group | ||
235 | <<EOT | ||
236 | A multiline | ||
237 | string | ||
238 |