diff options
Diffstat (limited to 'doc/argot-syntax.texi')
-rw-r--r-- | doc/argot-syntax.texi | 404 |
1 files changed, 404 insertions, 0 deletions
diff --git a/doc/argot-syntax.texi b/doc/argot-syntax.texi new file mode 100644 index 0000000..db81133 --- /dev/null +++ b/doc/argot-syntax.texi | |||
@@ -0,0 +1,404 @@ | |||
1 | @c This file is part of argot - Gray's Extensible Configuration System | ||
2 | @c Copyright (C) 2007-2016 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 argot-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 | The configuration file consists of statements and comments. | ||
36 | |||
37 | There are three classes of lexical tokens: keywords, values, and | ||
38 | separators. Blanks, tabs, newlines and comments, collectively called | ||
39 | @dfn{white space} are ignored except as they serve to separate | ||
40 | tokens. Some white space is required to separate otherwise adjacent | ||
41 | keywords and values. | ||
42 | |||
43 | @menu | ||
44 | * Comments:: | ||
45 | * Pragmatic Comments:: | ||
46 | * Statements:: | ||
47 | * Preprocessor:: | ||
48 | @end menu | ||
49 | |||
50 | @node Comments | ||
51 | @subsection Comments | ||
52 | @cindex Comments in a configuration file | ||
53 | @cindex single-line comments | ||
54 | @dfn{Comments} may appear anywhere where white space may appear in the | ||
55 | configuration file. There are two kinds of comments: | ||
56 | single-line and multi-line comments. @dfn{Single-line} comments start | ||
57 | with @samp{#} or @samp{//} and continue to the end of the line: | ||
58 | |||
59 | @smallexample | ||
60 | # This is a comment | ||
61 | // This too is a comment | ||
62 | @end smallexample | ||
63 | |||
64 | @cindex multi-line comments | ||
65 | @dfn{Multi-line} or @dfn{C-style} comments start with the two | ||
66 | characters @samp{/*} (slash, star) and continue until the first | ||
67 | occurrence of @samp{*/} (star, slash). | ||
68 | |||
69 | Multi-line comments cannot be nested. However, single-line comments | ||
70 | may well appear within multi-line ones. | ||
71 | |||
72 | @node Pragmatic Comments | ||
73 | @subsection Pragmatic Comments | ||
74 | @cindex comments, pragmatic | ||
75 | @cindex pragmatic comments | ||
76 | Pragmatic comments are similar to usual single-line comments, | ||
77 | except that they cause some changes in the way the configuration is | ||
78 | parsed. Pragmatic comments begin with a @samp{#} sign and end with the | ||
79 | next physical newline character. | ||
80 | |||
81 | @table @code | ||
82 | @kwindex #include | ||
83 | @item #include <@var{file}> | ||
84 | @itemx #include @var{file} | ||
85 | Include the contents of the file @var{file}. There are three possible | ||
86 | use cases. | ||
87 | |||
88 | If @var{file} is an absolute file name, the named file is included. | ||
89 | An error message will be issued if it does not exist. | ||
90 | |||
91 | If @var{file} contains wildcard characters (@samp{*}, @samp{[}, | ||
92 | @samp{]} or @samp{?}), it is interpreted as shell globbing pattern and | ||
93 | all files matching that pattern are included, in lexicographical | ||
94 | order. If no files match the pattern, the statement is silently | ||
95 | ignored. | ||
96 | |||
97 | Otherwise, the form with angle brackets searches for file in the | ||
98 | @dfn{include search path}, while the second one looks for it in the | ||
99 | current working directory first, and, if not found there, in the | ||
100 | include search path. If the file is not found, an error message will | ||
101 | be issued. | ||
102 | |||
103 | The default include search path is: | ||
104 | |||
105 | @enumerate 1 | ||
106 | @item @file{@var{prefix}/share/@value{PROGNAME}/@value{VERSION}/include} | ||
107 | @item @file{@var{prefix}/share/@value{PROGNAME}/include} | ||
108 | @end enumerate | ||
109 | |||
110 | @noindent | ||
111 | where @var{prefix} is the installation prefix. | ||
112 | |||
113 | @c FIXME: Uncomment this, if necessary: | ||
114 | @ignore | ||
115 | New directories can be appended in front of it using @option{-I} | ||
116 | (@option{--include-directory}) command line option | ||
117 | (@pxref{Preprocessor, include-directory}). | ||
118 | } | ||
119 | @end ignore | ||
120 | |||
121 | @kwindex #include_once | ||
122 | @item #include_once <@var{file}> | ||
123 | @itemx #include_once @var{file} | ||
124 | Same as @code{#include}, except that, if the @var{file} has already | ||
125 | been included, it will not be included again. | ||
126 | |||
127 | @kwindex #line | ||
128 | @item #line @var{num} | ||
129 | @itemx #line @var{num} "@var{file}" | ||
130 | This line causes the parser to believe, for purposes of error | ||
131 | diagnostics, that the line number of the next source line is given by | ||
132 | @var{num} and the current input file is named by @var{file}. | ||
133 | If the latter is absent, the remembered file name does not change. | ||
134 | |||
135 | @item # @var{num} "@var{file}" | ||
136 | This is a special form of @code{#line} statement, understood for | ||
137 | compatibility with the @sc{c} preprocessor. | ||
138 | @end table | ||
139 | |||
140 | In fact, these statements provide a rudimentary preprocessing | ||
141 | features. For more sophisticated ways to modify configuration before | ||
142 | parsing, see @ref{Preprocessor}. | ||
143 | |||
144 | @node Statements | ||
145 | @subsection Statements | ||
146 | @cindex statements, configuration file | ||
147 | @cindex configuration file statements | ||
148 | @cindex statement, simple | ||
149 | @cindex simple statements | ||
150 | A @dfn{simple statement} consists of a keyword and value | ||
151 | separated by any amount of whitespace. Simple statement is terminated | ||
152 | with a semicolon (@samp{;}). | ||
153 | |||
154 | The following is a simple statement: | ||
155 | |||
156 | @smallexample | ||
157 | standalone yes; | ||
158 | pidfile /var/run/slb.pid; | ||
159 | @end smallexample | ||
160 | |||
161 | A @dfn{keyword} begins with a letter and may contain letters, | ||
162 | decimal digits, underscores (@samp{_}) and dashes (@samp{-}). | ||
163 | Examples of keywords are: @samp{expression}, @samp{output-file}. | ||
164 | |||
165 | A @dfn{value} can be one of the following: | ||
166 | |||
167 | @table @asis | ||
168 | @item number | ||
169 | A number is a sequence of decimal digits. | ||
170 | |||
171 | @item boolean | ||
172 | @cindex boolean value | ||
173 | A boolean value is one of the following: @samp{yes}, @samp{true}, | ||
174 | @samp{t} or @samp{1}, meaning @dfn{true}, and @samp{no}, | ||
175 | @samp{false}, @samp{nil}, @samp{0} meaning @dfn{false}. | ||
176 | |||
177 | @item unquoted string | ||
178 | @cindex string, unquoted | ||
179 | An unquoted string may contain letters, digits, and any of the | ||
180 | following characters: @samp{_}, @samp{-}, @samp{.}, @samp{/}, | ||
181 | @samp{@@}, @samp{*}, @samp{:}. | ||
182 | |||
183 | @item quoted string | ||
184 | @cindex quoted string | ||
185 | @cindex string, quoted | ||
186 | @cindex escape sequence | ||
187 | A quoted string is any sequence of characters enclosed in | ||
188 | double-quotes (@samp{"}). A backslash appearing within a quoted | ||
189 | string introduces an @dfn{escape sequence}, which is replaced | ||
190 | with a single character according to the following rules: | ||
191 | |||
192 | @float Table, backslash-interpretation | ||
193 | @caption{Backslash escapes} | ||
194 | @multitable @columnfractions 0.30 .5 | ||
195 | @item Sequence @tab Replaced with | ||
196 | @item \a @tab Audible bell character (@acronym{ASCII} 7) | ||
197 | @item \b @tab Backspace character (@acronym{ASCII} 8) | ||
198 | @item \f @tab Form-feed character (@acronym{ASCII} 12) | ||
199 | @item \n @tab Newline character (@acronym{ASCII} 10) | ||
200 | @item \r @tab Carriage return character (@acronym{ASCII} 13) | ||
201 | @item \t @tab Horizontal tabulation character (@acronym{ASCII} 9) | ||
202 | @item \v @tab Vertical tabulation character (@acronym{ASCII} 11) | ||
203 | @item \\ @tab A single backslash (@samp{\}) | ||
204 | @item \" @tab A double-quote. | ||
205 | @end multitable | ||
206 | @end float | ||
207 | |||
208 | In addition, the sequence @samp{\@var{newline}} is removed from | ||
209 | the string. This allows to split long strings over several | ||
210 | physical lines, e.g.: | ||
211 | |||
212 | @smallexample | ||
213 | @group | ||
214 | "a long string may be\ | ||
215 | split over several lines" | ||
216 | @end group | ||
217 | @end smallexample | ||
218 | |||
219 | If the character following a backslash is not one of those specified | ||
220 | above, the backslash is ignored and a warning is issued. | ||
221 | |||
222 | @c FIXME: If argot_parser_options variable has | ||
223 | @c FIXME: ARGOT_OPTION_QUOTED_STRING_CONCAT bit set, then the | ||
224 | @c FIXME: following holds: | ||
225 | |||
226 | @ignore | ||
227 | Two or more adjacent quoted strings are concatenated, which gives | ||
228 | another way to split long strings over several lines to improve | ||
229 | readability. The following fragment produces the same result as the | ||
230 | example above: | ||
231 | |||
232 | @smallexample | ||
233 | @group | ||
234 | "a long string may be" | ||
235 | " split over several lines" | ||
236 | @end group | ||
237 | @end smallexample | ||