docs/devel/parsing.xml

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