diff options
Diffstat (limited to 'docs/docbook/devdoc/parsing.xml')
| -rw-r--r-- | docs/docbook/devdoc/parsing.xml | 239 |
1 files changed, 0 insertions, 239 deletions
diff --git a/docs/docbook/devdoc/parsing.xml b/docs/docbook/devdoc/parsing.xml deleted file mode 100644 index 8d929617f5..0000000000 --- a/docs/docbook/devdoc/parsing.xml +++ /dev/null @@ -1,239 +0,0 @@ -<chapter id="parsing"> -<chapterinfo> - <author> - <firstname>Chris</firstname><surname>Hertel</surname> - </author> - <pubdate>November 1997</pubdate> -</chapterinfo> - -<title>The smb.conf file</title> - -<sect1> -<title>Lexical Analysis</title> - -<para> -Basically, the file is processed on a line by line basis. There are -four types of lines that are recognized by the lexical analyzer -(params.c): -</para> - -<orderedlist> -<listitem><para> -Blank lines - Lines containing only whitespace. -</para></listitem> -<listitem><para> -Comment lines - Lines beginning with either a semi-colon or a -pound sign (';' or '#'). -</para></listitem> -<listitem><para> -Section header lines - Lines beginning with an open square bracket ('['). -</para></listitem> -<listitem><para> -Parameter lines - Lines beginning with any other character. -(The default line type.) -</para></listitem> -</orderedlist> - -<para> -The first two are handled exclusively by the lexical analyzer, which -ignores them. The latter two line types are scanned for -</para> - -<orderedlist> -<listitem><para> - - Section names -</para></listitem> -<listitem><para> - - Parameter names -</para></listitem> -<listitem><para> - - Parameter values -</para></listitem> -</orderedlist> - -<para> -These are the only tokens passed to the parameter loader -(loadparm.c). Parameter names and values are divided from one -another by an equal sign: '='. -</para> - -<sect2> -<title>Handling of Whitespace</title> - -<para> -Whitespace is defined as all characters recognized by the isspace() -function (see ctype(3C)) except for the newline character ('\n') -The newline is excluded because it identifies the end of the line. -</para> - -<orderedlist> -<listitem><para> -The lexical analyzer scans past white space at the beginning of a line. -</para></listitem> - -<listitem><para> -Section and parameter names may contain internal white space. All -whitespace within a name is compressed to a single space character. -</para></listitem> - -<listitem><para> -Internal whitespace within a parameter value is kept verbatim with -the exception of carriage return characters ('\r'), all of which -are removed. -</para></listitem> - -<listitem><para> -Leading and trailing whitespace is removed from names and values. -</para></listitem> - -</orderedlist> - -</sect2> - -<sect2> -<title>Handling of Line Continuation</title> - -<para> -Long section header and parameter lines may be extended across -multiple lines by use of the backslash character ('\\'). Line -continuation is ignored for blank and comment lines. -</para> - -<para> -If the last (non-whitespace) character within a section header or on -a parameter line is a backslash, then the next line will be -(logically) concatonated with the current line by the lexical -analyzer. For example: -</para> - -<para><programlisting> - param name = parameter value string \ - with line continuation. -</programlisting></para> - -<para>Would be read as</para> - -<para><programlisting> - param name = parameter value string with line continuation. -</programlisting></para> - -<para> -Note that there are five spaces following the word 'string', -representing the one space between 'string' and '\\' in the top -line, plus the four preceeding the word 'with' in the second line. -(Yes, I'm counting the indentation.) -</para> - -<para> -Line continuation characters are ignored on blank lines and at the end -of comments. They are *only* recognized within section and parameter -lines. -</para> - -</sect2> - -<sect2> -<title>Line Continuation Quirks</title> - -<para>Note the following example:</para> - -<para><programlisting> - param name = parameter value string \ - \ - with line continuation. -</programlisting></para> - -<para> -The middle line is *not* parsed as a blank line because it is first -concatonated with the top line. The result is -</para> - -<para><programlisting> -param name = parameter value string with line continuation. -</programlisting></para> - -<para>The same is true for comment lines.</para> - -<para><programlisting> - param name = parameter value string \ - ; comment \ - with a comment. -</programlisting></para> - -<para>This becomes:</para> - -<para><programlisting> -param name = parameter value string ; comment with a comment. -</programlisting></para> - -<para> -On a section header line, the closing bracket (']') is considered a -terminating character, and the rest of the line is ignored. The lines -</para> - -<para><programlisting> - [ section name ] garbage \ - param name = value -</programlisting></para> - -<para>are read as</para> - -<para><programlisting> - [section name] - param name = value -</programlisting></para> - -</sect2> -</sect1> - -<sect1> -<title>Syntax</title> - -<para>The syntax of the smb.conf file is as follows:</para> - -<para><programlisting> - <file> :== { <section> } EOF - <section> :== <section header> { <parameter line> } - <section header> :== '[' NAME ']' - <parameter line> :== NAME '=' VALUE NL -</programlisting></para> - -<para>Basically, this means that</para> - -<orderedlist> -<listitem><para> - a file is made up of zero or more sections, and is terminated by - an EOF (we knew that). -</para></listitem> - -<listitem><para> - A section is made up of a section header followed by zero or more - parameter lines. -</para></listitem> - -<listitem><para> - A section header is identified by an opening bracket and - terminated by the closing bracket. The enclosed NAME identifies - the section. -</para></listitem> - -<listitem><para> - A parameter line is divided into a NAME and a VALUE. The *first* - equal sign on the line separates the NAME from the VALUE. The - VALUE is terminated by a newline character (NL = '\n'). -</para></listitem> - -</orderedlist> - -<sect2> -<title>About params.c</title> - -<para> -The parsing of the config file is a bit unusual if you are used to -lex, yacc, bison, etc. Both lexical analysis (scanning) and parsing -are performed by params.c. Values are loaded via callbacks to -loadparm.c. -</para> -</sect2> -</sect1> -</chapter> |