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