docs/devel/parsing.xml

   1 <chapter id="parsing">
   2 <chapterinfo>
   3         <author>
   4                 <firstname>Chris</firstname><surname>Hertel</surname>
   5         </author>
   6         <pubdate>November 1997</pubdate>
   7 </chapterinfo>
   8
   9 <title>The smb.conf file</title>
  10
  11 <sect1>
  12 <title>Lexical Analysis</title>
  13
  14 <para>
  15 Basically, the file is processed on a line by line basis.  There are
  16 four types of lines that are recognized by the lexical analyzer
  17 (params.c):
  18 </para>
  19
  20 <orderedlist>
  21 <listitem><para>
  22 Blank lines - Lines containing only whitespace.
  23 </para></listitem>
  24 <listitem><para>
  25 Comment lines - Lines beginning with either a semi-colon or a
  26 pound sign (';' or '#').
  27 </para></listitem>
  28 <listitem><para>
  29 Section header lines - Lines beginning with an open square bracket ('[').
  30 </para></listitem>
  31 <listitem><para>
  32 Parameter lines - Lines beginning with any other character.
  33 (The default line type.)
  34 </para></listitem>
  35 </orderedlist>
  36
  37 <para>
  38 The first two are handled exclusively by the lexical analyzer, which
  39 ignores them.  The latter two line types are scanned for
  40 </para>
  41
  42 <orderedlist>
  43 <listitem><para>
  44   - Section names
  45 </para></listitem>
  46 <listitem><para>
  47   - Parameter names
  48 </para></listitem>
  49 <listitem><para>
  50   - Parameter values
  51 </para></listitem>
  52 </orderedlist>
  53
  54 <para>
  55 These are the only tokens passed to the parameter loader
  56 (loadparm.c).  Parameter names and values are divided from one
  57 another by an equal sign: '='.
  58 </para>
  59
  60 <sect2>
  61 <title>Handling of Whitespace</title>
  62
  63 <para>
  64 Whitespace is defined as all characters recognized by the isspace()
  65 function (see ctype(3C)) except for the newline character ('\n')
  66 The newline is excluded because it identifies the end of the line.
  67 </para>
  68
  69 <orderedlist>
  70 <listitem><para>
  71 The lexical analyzer scans past white space at the beginning of a line.
  72 </para></listitem>
  73
  74 <listitem><para>
  75 Section and parameter names may contain internal white space.  All
  76 whitespace within a name is compressed to a single space character.
  77 </para></listitem>
  78
  79 <listitem><para>
  80 Internal whitespace within a parameter value is kept verbatim with
  81 the exception of carriage return characters ('\r'), all of which
  82 are removed.
  83 </para></listitem>
  84
  85 <listitem><para>
  86 Leading and trailing whitespace is removed from names and values.
  87 </para></listitem>
  88
  89 </orderedlist>
  90
  91 </sect2>
  92
  93 <sect2>
  94 <title>Handling of Line Continuation</title>
  95
  96 <para>
  97 Long section header and parameter lines may be extended across
  98 multiple lines by use of the backslash character ('\\').  Line
  99 continuation is ignored for blank and comment lines.
 100 </para>
 101
 102 <para>
 103 If the last (non-whitespace) character within a section header or on
 104 a parameter line is a backslash, then the next line will be
 105 (logically) concatonated with the current line by the lexical
 106 analyzer.  For example:
 107 </para>
 108
 109 <para><programlisting>
 110         param name = parameter value string \
 111         with line continuation.
 112 </programlisting></para>
 113
 114 <para>Would be read as</para>
 115
 116 <para><programlisting>
 117     param name = parameter value string     with line continuation.
 118 </programlisting></para>
 119
 120 <para>
 121 Note that there are five spaces following the word 'string',
 122 representing the one space between 'string' and '\\' in the top
 123 line, plus the four preceeding the word 'with' in the second line.
 124 (Yes, I'm counting the indentation.)
 125 </para>
 126
 127 <para>
 128 Line continuation characters are ignored on blank lines and at the end
 129 of comments.  They are *only* recognized within section and parameter
 130 lines.
 131 </para>
 132
 133 </sect2>
 134
 135 <sect2>
 136 <title>Line Continuation Quirks</title>
 137
 138 <para>Note the following example:</para>
 139
 140 <para><programlisting>
 141         param name = parameter value string \
 142     \
 143     with line continuation.
 144 </programlisting></para>
 145
 146 <para>
 147 The middle line is *not* parsed as a blank line because it is first
 148 concatonated with the top line.  The result is
 149 </para>
 150
 151 <para><programlisting>
 152 param name = parameter value string         with line continuation.
 153 </programlisting></para>
 154
 155 <para>The same is true for comment lines.</para>
 156
 157 <para><programlisting>
 158         param name = parameter value string \
 159         ; comment \
 160     with a comment.
 161 </programlisting></para>
 162
 163 <para>This becomes:</para>
 164
 165 <para><programlisting>
 166 param name = parameter value string     ; comment     with a comment.
 167 </programlisting></para>
 168
 169 <para>
 170 On a section header line, the closing bracket (']') is considered a
 171 terminating character, and the rest of the line is ignored.  The lines
 172 </para>
 173
 174 <para><programlisting>
 175         [ section   name ] garbage \
 176     param  name  = value
 177 </programlisting></para>
 178
 179 <para>are read as</para>
 180
 181 <para><programlisting>
 182         [section name]
 183     param name = value
 184 </programlisting></para>
 185
 186 </sect2>
 187 </sect1>
 188
 189 <sect1>
 190 <title>Syntax</title>
 191
 192 <para>The syntax of the smb.conf file is as follows:</para>
 193
 194 <para><programlisting>
 195   &lt;file&gt;            :==  { &lt;section&gt; } EOF
 196   &lt;section&gt;         :==  &lt;section header&gt; { &lt;parameter line&gt; }
 197   &lt;section header&gt;  :==  '[' NAME ']'
 198   &lt;parameter line&gt;  :==  NAME '=' VALUE NL
 199 </programlisting></para>
 200
 201 <para>Basically, this means that</para>
 202
 203 <orderedlist>
 204 <listitem><para>
 205         a file is made up of zero or more sections, and is terminated by
 206         an EOF (we knew that).
 207 </para></listitem>
 208
 209 <listitem><para>
 210         A section is made up of a section header followed by zero or more
 211         parameter lines.
 212 </para></listitem>
 213
 214 <listitem><para>
 215         A section header is identified by an opening bracket and
 216         terminated by the closing bracket.  The enclosed NAME identifies
 217         the section.
 218 </para></listitem>
 219
 220 <listitem><para>
 221         A parameter line is divided into a NAME and a VALUE.  The *first*
 222         equal sign on the line separates the NAME from the VALUE.  The
 223         VALUE is terminated by a newline character (NL = '\n').
 224 </para></listitem>
 225
 226 </orderedlist>
 227
 228 <sect2>
 229 <title>About params.c</title>
 230
 231 <para>
 232 The parsing of the config file is a bit unusual if you are used to
 233 lex, yacc, bison, etc.  Both lexical analysis (scanning) and parsing
 234 are performed by params.c.  Values are loaded via callbacks to
 235 loadparm.c.
 236 </para>
 237 </sect2>
 238 </sect1>
 239 </chapter>