NAME

LCFG::Template - substitute LCFG resources in template

SYNOPSYS

use LCFG::Template;

# Load resources for 'foo' and 'bar' from adaptor profile
$result = LCFG::Template::Substitute($template,$target,$mode,@res);

# Set delimiters
LCFG::Template::Delimiters($left,$right,[option...]);

DESCRIPTION

This routine takes the name of a template file and substitutes LCFG resource values into the template from the given list of resource tables. The return status indicates whether the target file has been changed by the operation (1) or not (0). The mode option can be used to specify the following bit flags: if <mode>&1 is non-zero, then then the file is never modified, but the return status indicates whether or not it would have been. If <mode>&2 is non-zero, then no backup files are created. If <mode>&4 is non-zero, then the template is processed using the Perl Template module instead of the built-in template processor.

The resources tables are in the same format as generated by the LCFG::Resources module, without the name of the component at the top level of the structure:

{
  'resource1' => {
     VALUE => value,
     TYPE => type,
     DERIVE = > derivation,
     AU = > authors,
     CONTEXT => context
  },
  'resource2' => {
     VALUE => value,
     TYPE => type,
     DERIVE = > derivation,
     AU = > authors,
     CONTEXT => context
  },
  ......
}

If an error occurs, then the routine returns undef and the variable $@ contains the error message.

The Delimiters routine can be used to change the default delimiter strings and the options to the Perl template processor.

TEMPLATE LANGUAGE

The following constructions are supported by the builtin template processor:

<%resource%>

Substitute the value of the named resource. The resource name my be preceeded by a # in which case the "derivation" of the resource will be substituted instead of the value. This can be usefully used to generate comments in the generated configuration file indicating the source of the various parameters. The delimiters <%{%> and <%}%> (see below) are useful when substituting derivations in comments to prevent a reconfiguraion being flagged if only the derivations (and not the values) change.

Note that the LCFG client component will only notify components of changes to the value of resources -- if only derivations change, then the component is not automatically reconfigured, and values of substituted derivations may be out of date.

<%if: expr%> text <%else:%> text <%end:%>

If the expr is non-null, then substitute the first text, otherwise substitute the second text. The else part is optional.

<%perl: expression%>

Substitute the result of the Perl expresssion.

<%shell: command%>

Substitute the result of the Shell command.

<%ifdef: resource%> text <%else:%> text <%end:%>

If the resource is defined, then substitute the first text, otherwise substitute the second text. The else part is optional.

<%for: var=expr%> text <%end:%>

Substitute one copy of the specified text for each item in the space-separated list expr. During substitution of the text, the value of the variable var may be referenced as <%var%>. (Any resource with the same name as var will be inaccessible during the scope of the statement).

<%set: var=expr%>

Set a global variable to the given value. The global variable can be accessed as <%var%> at any subsequent point in the program. Any resource with the same name will be inacessible.

<%include: filename%>

Include the contents of the specified template file, evaluating it in the current context.

<%\%>

Delete any following white space. This allows complex template expressions to span multiple lines, while still generating output on a single line.

<%/*%> ... <%*/%>

Text between these delimiters is treated as a comment in the template and is not copied to the output file.

<%{%> ... <%}%>

Text between these delimiters is treated as insignificant. The text is still copied to the output file (evaluating any expressions), but changes to this text are not sufficient for the return status to indicate that the file has changed. This is useful for placing changing comments in the output (for example indicating the generation date) without triggering reconfiguration of the component unless something significant has changed. Eg:

#<%{%> Generated on <%shell: date%> <%}%>

All the above elements except var may contain nested statements.

PLATFORMS

ScientificLinux6, EnterpriseLinux7, Debian

AUTHOR

Stephen Quinney <squinney@inf.ed.ac.uk>