aboutsummaryrefslogtreecommitdiff
path: root/doc/argot-syntax.texi
diff options
context:
space:
mode:
Diffstat (limited to 'doc/argot-syntax.texi')
-rw-r--r--doc/argot-syntax.texi404
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
38separators. Blanks, tabs, newlines and comments, collectively called
39@dfn{white space} are ignored except as they serve to separate
40tokens. Some white space is required to separate otherwise adjacent
41keywords 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
55configuration file. There are two kinds of comments:
56single-line and multi-line comments. @dfn{Single-line} comments start
57with @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
66characters @samp{/*} (slash, star) and continue until the first
67occurrence of @samp{*/} (star, slash).
68
69 Multi-line comments cannot be nested. However, single-line comments
70may 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,
77except that they cause some changes in the way the configuration is
78parsed. Pragmatic comments begin with a @samp{#} sign and end with the
79next physical newline character.
80
81@table @code
82@kwindex #include
83@item #include <@var{file}>
84@itemx #include @var{file}
85Include the contents of the file @var{file}. There are three possible
86use cases.
87
88If @var{file} is an absolute file name, the named file is included.
89An error message will be issued if it does not exist.
90
91If @var{file} contains wildcard characters (@samp{*}, @samp{[},
92@samp{]} or @samp{?}), it is interpreted as shell globbing pattern and
93all files matching that pattern are included, in lexicographical
94order. If no files match the pattern, the statement is silently
95ignored.
96
97Otherwise, the form with angle brackets searches for file in the
98@dfn{include search path}, while the second one looks for it in the
99current working directory first, and, if not found there, in the
100include search path. If the file is not found, an error message will
101be issued.
102
103The 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
111where @var{prefix} is the installation prefix.
112
113@c FIXME: Uncomment this, if necessary:
114@ignore
115New 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
125been 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
131diagnostics, 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}.
133If 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
137compatibility with the @sc{c} preprocessor.
138@end table
139
140 In fact, these statements provide a rudimentary preprocessing
141features. For more sophisticated ways to modify configuration before
142parsing, 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
151separated by any amount of whitespace. Simple statement is terminated
152with a semicolon (@samp{;}).
153
154 The following is a simple statement:
155
156@smallexample
157standalone yes;
158pidfile /var/run/slb.pid;
159@end smallexample
160
161 A @dfn{keyword} begins with a letter and may contain letters,
162decimal digits, underscores (@samp{_}) and dashes (@samp{-}).
163Examples 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
180following 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
188double-quotes (@samp{"}). A backslash appearing within a quoted
189string introduces an @dfn{escape sequence}, which is replaced
190with 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
209the string. This allows to split long strings over several
210physical 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
220above, 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
228another way to split long strings over several lines to improve
229readability. The following fragment produces the same result as the
230example above:
231
232@smallexample
233@group
234"a long string may be"
235" split over several lines"
236@end group
237@end smallexample