Variables
=========

Flexible variable declaration and propagation is the heart of the
FileWiki system.  While some variables affect the FileWiki system,
they are basically used as input to the template processor. Every page
merges its `vars` from various locations (see "Propagation" below).


Declaration
-----------

Variables are declared in a simple "key=value" or "key value"
format. Variable expansion is performed in occurrence of either
`$myvar`, `${myvar}`, or `${{myvar}}` (see "Variable Expansion"
below).

  * Lines starting with '#' (hash) are ignored
  * Trailing whitespaces are cut off
  * Double quotes are removed at beginning and end of value
  * Keys starting with '+' (plus) are appended to an array
  * Values starting with '\\\' are multi-line, with '\\\' on last line

Example:

    title=FileWiki Documentation
    menu=$title

This results in both "title" and "menu" variables to have the value
"Summary". This is equivalent to:

    title  "FileWiki Documentation"
    menu   $title


Propagation
-----------

#### tree vars

Parsed from file "tree.vars" in every directory.

`tree.vars` are propagated to `dir.vars` and `page.vars`, and are
persistent within sub-directories. `tree.vars` in sub-directories
supersede the `tree.vars` of the parent directory.


#### dir vars

Parsed from file "dir.vars" in every directory.

Used for the directory node. Consider the `dir.vars` as metadata for the
directory they are located in.  `dir.vars` are not propagated, but are
accessible on a page via the `DIR` variable.


#### page vars

Parsed from file "&lt;source_file&gt;.vars".

`page.vars` supersede the `tree.vars` for a page.  Consider the
`page.vars` as metadata for a page. Every source page can have
`page.vars`.


#### nested vars

Parsed from within the source files (if supported by the plugin
enabled).

Nested vars supersede the `page.vars`. FileWiki starts to parse nested
variables from the source file after it first encounters a line
starting with `<filewiki_vars>` or `[filewiki_vars]`, up to
`</filewiki_vars>` or `[/filewiki_vars]`.

Note that the `nested.vars` are stripped off the source file when
processing the input filters.

Example:

    Page text...

    <filewiki_vars>
    key=value
    ...
    </filewiki_vars>

    Page text...

As a special feature for pages which are also parsed outside FileWiki
(e.g. perl modules), a "un-comment" character is defined by the first
character preceding <code>&lt;filewiki_vars&gt;</code>.

Example (equivalent to example above):

    File text (e.g. Perl code)...
    #<filewiki_vars>
    #key=value
    #...
    #</filewiki_vars>
    File text...

In this example, the "un-comment" character is set to '#', and all
variables are parsed.


Variable Expansion
------------------

### Early Expansion

Variable early expansion happens directly at the time the key/value
line is read from disk. This is the common case for propagating
variables through directories.

Early expansion for expressions is accepted in form:

  * `$KEY`: expand to the value of variable `KEY`, or "" if `KEY` is
    not found.

  * `${KEY_EXPR}`: expression in form `${KEY0[|KEY1...]}`, returning the
    first valid value from KEYn.

  * `${KEY_EXPR[/MATCH/REPLACE]}`: performs a regular expression
    `s/MATCH/REPLACE/` on the value of `KEY_EXPR`.

  * `${KEY_EXPR[//MATCH/REPLACE]}`: performs a global regular
    expression `s/MATCH/REPLACE/g` on the value of `KEY_EXPR`.

Examples:

    OUTPUT_DIR   /tmp/filewiki/htdocs
    URI_PREFIX   $OUTPUT_DIR
    stylesheet   $URI_PREFIX/filewiki.css
    debug_name   XXX${NAME}XXX


### Late Expansion

Variable late expansion happens after all variables are read by a page
or directory node. This is particulary useful if you want to define a
variable derived from internal variables set by plugins. Note that
setting system variables on late-expansion time might lead to
undefined behaviour, as the plugins might rely on these variables
before late-expansion happens.

Late expansion has the same semantics as early expansion, except that
double brackets are used: `${{...}}`

Example:

    commit_msg   This page was committed by: ${{GIT_AUTHOR_NAME}}.
    date         ${{NAME/^(\d\d\d\d-\d\d-\d\d)-/$1}}
    title        ${{NAME/^\d\d\d\d-\d\d-\d\d-(.*)/$1}}

For files named like "yyyy-mm-dd-myfile", this sets a variables
`date` and `title` from the source file name.


Logical Expressions
-------------------

Expressions in form `$((...))` are executed at late expansion time.

Logical expressions are accepted in form:

  * `$(( [[!]CONDITION:] EXPR0 || EXPR1 || ... ))`: expands to
    expression `EXPR0`, or to `EXPR1`..., whichever expression
    resolves to true first. Expands to an empty string if `CONDITION`
    resolves to false.

Example:

    date    $(( ${{EXIF_TIME}} || ${{NAME/^(\d\d\d\d-\d\d-\d\d)-/$1}} || ${{MTIME}} ))
    title   $((IS_DIR: ${{NAME/^\d\d\d\d-\d\d-\d\d-/}} ))

This sets variable `date` from EXIF_TIME, falling back to the date
prefix of NAME, finally falling back to MTIME. Sets variable `title`
to the title portion of NAME, but only if `IS_DIR` variable is set
(i.e. only for a directory node).

