Substitute(3)

NAME
Text::Substitute - hash based text substitution with conditional

SYNOPSIS
Text::Substitute can be used to substitute the contents of a hash into a file or text variable. It includes a limited set of conditionals, looping, and the ability to include other files. It was designed primarily for generating web content.

DESCRIPTION

  Standard Exports
The following routines will be exported into your namespace if you use the Text::Substitute module:

substitute(DATA, SUBVARS, OPTS);
    substitute() processes then returns DATA. SUBVARS is a reference to a hash of key/value pairs, and OPTS contains optional parameters, and some return data.

substitute_file(FILE, SUBVARS, OPTS);
    substitute_file() reads the contents of FILE (relative to 'templateroot' and combinations of 'templatepath' and 'templatesearch', and then calls substitute();

substitute_filename(FILE, OPTS);
    substitute_filename() returns the filename that substitute_file() would use, based on the templateroot, templatepath, and templatesearch in OPTS. If no file is found returns undef.

Substitute tags are of the form ${...}. Note the ':' in all except the simple ${var} case:

${var}
    Replace with the contents of $SUBVARS->{var}.

${include:file}
    Include the contents of 'file'. If the file begins with a '/' it starts from the templateroot and ignores templatepath.

${sinclude:file}
    Attempt to include 'file', but fail silently.

${loop:arrayvar} ${endloop:}
    $SUBVARS->{arrayvar} must be a reference to an array. The data between ${loop:arrayvar} and ${endloop:} is processed for each entry in the array, with ${loop} set to the loop number (starting at 0).

    If $SUBVARS->{arrayvar} is an array of scalars, then ${loopvar} will be set to each value.

    If $SUBVARS->{arrayvar} is an array of references to hashes, then values in each hash will override the values in $SUBVARS.

    Currently ${loop:} can only be nested one level deep.

${if:expr} ${else:} ${endif:}
    If 'expr' is true, include the text between ${if:expr} and either ${else:} or ${endif:}. If ${if:expr} is false and an ${else:} is present, include the text between ${else:} and ${endif:}.

    'expr' can contain variable names in the form $var. If 'expr' is a single variable name then it is true is that variable is not blank.

    WARNING: ${if:} statements are 'eval'ed by perl. This allows you to do just about anything, so do not allow external data into a substituted file without sanitizing it.

${set:var=value}
    Set variable 'var' to 'value'. 'value' can contain any character except '}'.

${set:var=testvar?setvalue:nosetvalue}
    If testvar is not '', set var to setvalue, else to nosetvalue.

The following options can be set in OPTS:

'maxincludes'
    Maximum includes to permit (default: 100)

'maxsub'
    Maximum substitutions to permit (default: 100000)

'specific'
    When reading any file, check for a version with .'specific' first. DEPRECATED - use templatesearch.

'prefix'
    When reading any file, check for a file with prefix 'prefix' first. DEPRECATED - use templatesearch.

'templatedebug'
    Display debug information regarding the use of templatepath, templateroot, and templatesearch.

'templatedir'
    Override the template directory within templateroot (default: '.'). DEPRECATED - use templatepath.

'templatepath'
    Override the template directory within templateroot (default: '.'). Can be a reference to a search list.

'templateroot'
    Set the 'root' for all template operations. (default: 'template') Can be reference to a search list.

'templatesearch'
    Single entry, or reference to list of entries to check for files, both in substitute_file(), and in any ${include:FILE} operations. (default: the filename given).

    If a search entry contains ${file} then it will be checked by substituting in the requested file, otherwise it is assumed to be a directory possibly containing the requested file. For example, to check for files with a '.bob' extension first, use ('${file}.bob', '.')

    Note: Path entries should be permitted to also contain other ${variable} substitutions. Hopefully this will happen in future.

'unresolved'
    Substitute the value given for any unresolved variables.

The following values will be set in OPTS upon return:

'numincludes'
    The number of includes processed.

'numsub'
    The number of substitutions processed (includes ${if:}, ${loop:}, ${include:} and ${set:}).

'unresolvedlist'

List of unresolved variables.

'fail'
    If for any reason the substituion fails (invalid include, too many substitutions, etc) both the returned data and the $OPTS->{fail} will be set to the failure reason.

Additional notes:

Nesting of variables is not currently supported.
Trailing whitespace up the the next \n after any ${:} tag except ${include:} automatically stripped.
Nesting of ${loop:} within ${loop:} beyond one level is not currently supported
The 'expr' parsing for ${if:} needs to be expanded