System Variables

This chapter lists all variables interpreted or produced by FileWiki. Note that these variables are in capital letters, in order to distinguish them from the user-defined variables.

Configuration Variables

The variables described here directly affect the FileWiki behaviour.

BASEDIR

Mandatory. Points to the top-level directory of the website. This must be set as function parameter to the FileWiki calls.

OUTPUT_DIR

Target (output) directory of the website. Mandatory for the FileWiki::create() function. Absolute as well as relative paths are allowed.

NOTE: The given directory as well as all subdirectories will be created on the fly, without checking or user inerraction. Make sure to provide a reasonable value here.

Example:

OUTPUT_DIR=/tmp/filewiki/${BUILD_TIME}

PLUGINS

Mandatory. Defines a list of plugins to be enabled. There are three types of plugins:

Page handler: Create a web page (e.g. Markdown, Copy, GenericPageHandler), or more generically spoken: Generates a target by transforming a source file. Only one page handler is allowed per source file. If no page handler plugin is enabled, the source file will not be processed.
Vars provider: Provide extra variables (e.g. Git, EXIF). Multiple vars provider are allowed.
Resource creator: Creates additional resources for a page (e.g. ImageMagick, ExtCmd). Multiple resiource creators are allowed.

Refer to FileWiki::Plugin::* modules documentation for further information about each plugin.

Example:

PLUGINS=Markdown,Copy

This enables the Markdown and Copy plugin.

PLUGIN_<plugin>_MATCH

Defines a match on file names for a plugin. The given plugin will be enabled if the file matches the expression.

Example:

PLUGINS=Markdown,Copy
PLUGIN_MARKDOWN_MATCH=\.txt$
PLUGIN_COPY_MATCH=\.(ico|png)$

This enables the "Markdown" plugin for all files ending with ".txt", and the "Copy" plugin for all files ending in ".ico" or ".png".

PLUGIN_GROUP_<group>_MATCH

Defines a match on file names for a plugin group. The plugins in the given group will be enabled if the file matches the expression.

Example:

PLUGINS=EXIF<IMAGE>, ImageMagick<IMAGE>(THUMB), GenericPageHandler<IMAGE>
PLUGIN_GROUP_IMAGE_MATCH=\.(jpg|png)$

This assigns the EXIF (vars provider), ImageMagick (resource creator) and GenericPageHandler (page handler) plugins to the IMAGE group. All files ending in ".jpg" or ".png" will be processed by the plugins in the IMAGE group.

TEMPLATE

Mandatory. Template to be parsed for the page. Relative to TT_INCLUDE_PATH.

TT_*

Set configuration options for Template Toolkit. See Template::Manual::Config for a complete list of options.

Make sure the INCLUDE_PATH points to your template directory.

For the FileWiki apache handler to work correctly, you also need to set ABSOLUTE=1.

Example:

TT_INCLUDE_PATH=${BASEDIR}/template
TT_ABSOLUTE=1

CMD_*

Command being executed by FileWiki::command($command) function.

Example:

CMD_INSTALL=rsync -rvz --delete -e "ssh -l webmaster" ${OUTPUT_DIR}/ www.example.org:/var/www/htdocs

This installs the page to the host www.example.org when typing:

filewiki -c install example.org

URI_PREFIX

Prefix for the URI's generated by FileWiki. Useful if the website generated is in a subdirectory within some other site.

URI_DIR

Set the root URI to a new value. This will make the source directory (as well as all including files and folders recursively) appear under a new root URI.

NOTE: Set this in dir.vars. You will get unexpected result when set in tree.vars!

URI_TRANSFORM_LC

If set, convert all URI's to lowercase.

TARGET_MTIME

Format: "YYYY-MM-DD hh:mm:ss" or unix timestamp

If set, affects modification date for the target (output) file of a page.

This is particulary useful if you use rsync -t for installing the site, and you don't want a page's mtime to change on every install.

TIME_FORMAT

Defines how time is formatted in the system. They correspond to the C library routines "strftime" and "ctime". Defaults to "%C".

Example:

TIME_FORMAT=%B %e, %Y

Result: "January 1, 2011"

SKIP

If set in dir.vars or tree.vars, files as well as subdirectories will not be processed. If set in page.vars, the page will not be processed.

SKIP_PREVNEXT

If set, the page will be excluded from the PAGE_PREV / PAGE_NEXT list (see below).

INDEX

Specifies the order of the page within the current directory. Defaults to the source file name.

Important when creating menues using the PageTree() or PageList() functions in the templates.

Note that the index is being sorted lexically (NOT numerically): This means for example that "10" is considered smaller than "2". You should use "02" here.

MAKE_INDEX_PAGE

Marks the page as INDEX_PAGE for the directory. This is mainly used by the menu.

REF

Comma separated list of references to the page URI. Used by the HTML converter (Markdown or Textile) to create links from a reference.

Only useful in page.vars.

SORT_KEY

Key to use for sorting pages within a directory. Defaults to "INDEX".

SORT_STRATEGY

Strategy to use for sorting pages within a directory. Supported values are:

sortkey-only: sort by SORT_KEY (default).
dir-first: sort by SORT_KEY, but put directories in front.
dir-last: sort by SORT_KEY, but push directories to back.
none: do not sort (useful when using INCLUDE).

SORT_ORDER

Order to use for sorting pages within a directory. Supported values are:

asc: sort ascending (default).
desc: sort descending.

INCLUDE_VARS

Include variables from a given vars file. Note that no checking on circular including is performed. Make sure that you don't include vars files which include the currently parsed file again!

INCLUDE

Include files/directories. Multiple includes are separated by a colon, or by using array variables. Optionally, you can specify a prefix from where to read additional tree-, page- and file-vars in square brackets.

Example (include files):

INCLUDE=/my/include/file[myprefix]:/my/other/file

This includes the file specified. The vars for the included file will be read from myprefix.vars in the current directory.

Example (include file and assign plugin):

INCLUDE=/my/special/script.js > JavaScript

This includes the file specified, and sets PLUGINS=JavaScript in page vars.

Example (include directories):

INCLUDE=/my/include/directory[myprefix]:/my/other/include_dir

This includes the directories specified. The vars for the included directory will be read from myprefix.tree.vars and myprefix.dir.vars in the current directory. The vars from subdirectories will be read from myprefix_subdir.tree.vars and myprefix_subdir.dir.vars. The vars from a file myfile.txt within the directory will be read from myprefix_myfile.txt.vars.

Example (use array variable):

+INCLUDE=/my/include/directory[myprefix]
+INCLUDE=/my/other/include_dir

Same as above, using array variable notation.

EXCLUDE

Exclude files/directories on matching pattern. Multiple excludes are separated by a colon, or by using array variables. The match is done against the full path starting at BASEDIR.

Examples:

EXCLUDE=/test.txt$
EXCLUDE=private:\.bak$

The first example excludes any file or directory named "test.txt". The second example excludes any file or directory containing the word "private" (e.g. "somedir/private" or "my_privateer.txt"), and any file or directory ending with ".bak".

RESOURCES_FORCE_REBUILD

If set, force a rebuild of all resources (i.e. all files generated by resource creator plugins), even if the resource files already exist.

SRC_REGEXP

Modify source file data before it is processed by plugins. Use with care!

The only supported regexp modifier is 'g'. Note that filewiki always adds the 'm' and 'ee' modifiers.

Example (fix links in Markdown source):

SRC_REGEXP=s/\(doc\/([a-zA-Z0-9_]+).md\)/\(\L$1\E.html\)/g

Preset Variables

The variables described here are set by FileWiki, and can be used in the templates.

NAME

The name of the page (or directory respectively). This is taken from the filename. Changing this variable directly affects the URI variable (or URI_DIR for directories).

ENV

System environmnent (reference to Perl %ENV).

MTIME

Modification date, taken from the source file modification date, and formatted using the TIME_FORMAT variable.

BUILD_DATE

Date of the generation of a page. This is set to the systems current date upon page generation, and formatted using the TIME_FORMAT variable.

PAGE_PREV

Points to the previous page in current directory. Not set if current page is first page.

PAGE_NEXT

Points to the next page in current directory. Not set if current page is last page.

DIR

Container for the dir.vars. Makes the dir.vars accessible from the page.

Template Example:

[% DIR.my_var %]

Returns the variable my_var from dir.vars.

Transformation Variables

EVAL

EVAL variables must be declared as arrays (using the '+' modifier).

Expression of form [!]KEY: EXPR. Sets $_ to the value of KEY, and assigns the value of $_ to variable KEY after evaluating EXPR.

The transformation happens after "variable late expansion", or, if the ! modifier is set, before any variables are read from disk. Using the ! modifier makes only sense if you wish to transform system variable presets at an early state (e.g. NAME or URI_DIR).

Note that EXPR is evaluated using the perl eval statement, which means that you can do very nasty stuff with this!

Examples:

+EVAL  !NAME: s/^\d+-//
+EVAL  NAME: WARN "EVAL: malformed NAME=$_" if($_ =~ /^[^A-Za-z]/)
+EVAL  title: s/_/ /g

The first line removes leading digits from variable NAME, affecting the resulting URI of all pages down the tree. The second line prints a warning if NAME does not start with a letter. The third line replaces all underscores with whitespace on variable title.

Invasive Examples:

+EVAL  NAME: print "I'm a dirty hacker! " while 1
+EVAL  passwd: $_ = `cat /etc/passwd`

These examples show why you should not let FileWiki process variables from unknown sources.