==================
Config File Syntax
==================

This section describes the syntax used for the links_and_nodes manager
config file. The used notation is the same as in the [Python Language
Refernce](http://docs.python.org/2/reference/introduction.html#notation)
-- a modified [Backus–Naur
Form](http://en.wikipedia.org/wiki/Backus%E2%80%93Naur_Form) - please
refer to these pages for more information about this notation.

here is the lexical definition::

    config_file ::= config_section*
    config_section ::= section_header "\n" key_value_pairs*
    
    section_header ::= section_type [ WS section_name ]
    section_type ::= terminal_string
    section_name ::= config_string
    
    key_value_pairs ::= [WS] section_key [WS] ": " section_value "\n"
    section_key ::= terminal_string
    section_value ::= config_string | ( "[" config_string_multiline "]" )
    
    config_string_multiline ::= config_string "\n" [ config_string_multiline ]
    config_string ::= ( replacement | [ terminal_string ] )*
    
    replacement ::= "%(" config_string ")"
    terminal_string ::= any_text_wo_newline+
    
    any_text_wo_newline ::= <any character except "\n">
    
    WS ::= [ " " | "\t" | "\r" | "\n" ]+
    
(note: empty lines and lines starting with "#" are ignored, trailing
whitespace is ignored)

Single-line section names and single-line values also support trailing
``#``-comments. Everything after an unquoted ``#`` is ignored.

Example:

.. code-block:: lnc

   process some process # comment after section name
   command: ls -l # comment after value

If a literal ``#`` is part of the value, quote the value:

.. code-block:: lnc

   defines
   key_hash_value: "key#value"

Quoted strings can contain ``#`` normally. Unquoted values can not; there
``#`` starts a trailing comment.

This is relevant for compatibility with older config files. For example,
this used to assign the value ``key#value``:

.. code-block:: lnc

   defines
   key_hash_value: key#value

Now the same line assigns only ``key``. To keep the ``#value`` suffix,
use quotes as shown above.

For multi-line values enclosed in ``[`` and ``]``, trailing comments at the
end of a line are still not supported. Inside such blocks, only lines that
start with ``#`` are treated as comments.