Inside Template Expansion
gettemplate ($who, $surrogate)expandtemplate ($templ, %expfunc)
targetexpand ($templ, $who)captionexpand ($templ, $who)bannerexpand ($templ, $who)titleexpand ($templ, $who)stylesheet ($templ)altstyleexpand ($templ, $who)
thisurl ()baseurl ()dotdoturl ()forestexpand ($templ, $who)
treesexpand ($templ, $who, $var)
urlexpand ($templ, $who)
modeexpand ($templ, $who)
varlinks ($templ, $who, $var)
varmenuexpand ($var)varbtnaction ($templ, $who)varexpand ($templ, $who)
displayindexstate ($who)
devinfo ($templ)atticlink ($templ)makeheader ($who), $tmplpfxmakefooter ($who)makeerrorpage ($who)This module is the template expansion engine shared by the various scripts to display their results in a customisable HTML page.
gettemplate ($who, $surrogate)Function gettemplate returns the contents of the designated template. In case the template name has not been defined in lxr.conf or if the target file does not exist, a replacement template is returned.
$who
a string containing the template name
$surrogate
a string containing the replacement template
Caveat:
A warning message may be issued with a warn statement and get caught elsewhere.
expandtemplate ($templ, %expfunc)Function expandtemplate returns a string where occurrences of simple template variables and template function parameter blocks are replaced by their expanded values.
$templ
a string containing the template
%expfunc
a hash where the key is the variable/function name and the value is a sub returning the expanded text
The template may contain substitution requests which are special sequences of characters in the form:
$name
This is a simple variable. $name will be substituted in the template by the value returned by the corresponding sub in %expfunc.
$name{ ... }
This is a function. The fragment between the braces (hereafter called the argument) is passed as an argument to the corresponding sub in %expfunc. The returned value is substituted for the whole construct.
Notes:
There is no space between the $ sign and the variable/function name.
There is no space between the function name and the opening brace {.
The name can contain uppercase and lowercase letters, digits and underscores.
The content of a function argument is arbitrary. It may even contain substitution requests as variables or nested functions. The only restriction concerns the closing brace }: it cannot appear inside an argument because it would match the nearest unmatched opening brace {. No escape mechanism is presently implemented. Note, however, that if you are generating HTML you can use entity literals & #125; or & #x7D; (without spaces between & and the number sign #).
Notes:
If the argument contains substitution requests, it is the sub responsability to interpret them.
The sub may call expandtemplate with the argument as the new template providing the replacement rules in the new %expfunc.
The sub is free to do whatever it deems appropriate with the argument.
It can repeateadly call expandtemplate with changed replacement rules and return the concatenation of the results. For instance, the replacement rules could scan a set of values to return the full set of substitutions.
$templ is repeatedly explored to replace matching { } (not containing other { }) which are preceded by a single { by characters \x01 and \x02 respectively.
It proceeds thus from the innermost block to the outermost, leaving only unnested variables, unnested function calls and stray unnested braces.
Then, the %expfunc subs are called based on the name of the variables or functions. Variable subs receive an undef argument, while function subs receive the block argument with its braces restored (or undef if it is empty). If the variable or function has no corresponding key in %expfunc, the variable or function call (including its argument) is left unchanged.
Finally, the leftover \x01 and \x02 are converted back into { and }.
Note:
This algorithm is implemented through Perl pattern-matching which is not the most efficient. A better solution would be a left-to-right parser, avoiding thus backtracking and the { } to/from \x01 \x02 fiddling.
HTML comments are removed from the template. However, SSI comments (coded as HTML comments) must not be removed lest the template would lose its functionality. Consequently, comments have two forms:
Normal verbose comments
The opening delimiter (<!-- ) MUST be followed by a spacer, i.e. a space, tab or newline. The closing delimiter (-->) should also be preceded by a spacer. These comments will be removed.
Sticky comments
The start delimiter (<!--) is immediately followed by a significant character. These comments (most notably SSI commands) will be left in the expanded template.
Note that the licence statement in the standard template is written as verbose comment. The licence is removed when the template is expanded because the generated page consists mostly of your private data (either replaced text or displayed source lines) which certainly are under a different licence than that of LXR.
targetexpand ($templ, $who)Function targetexpand is a "$variable" substitution function. It returns a string representative of the displayed tree. The "name" of the tree is extracted from the URL (script-name component) according to the routing technique.
$templ
a string containing the template
Presently, the template is equal to undef, which is the template value for a variable substitution request.
$who
a string containing the script name (i.e. source, sourcedir, diff, ident or search) requesting this substitution
Note:
Tree information may be found in different parts of the URL. Configuration parameter 'routing' is a reminder for the tree location. If it does not exist, configuration file was created by an earlier version and, as a compatibility measure, 'embedded' routing mode is assumed. If this is not the case, or the configuration file was manually crafted without 'routing' parameter, inconsistent display will likely result.
In the 'embedded' case, tree name is extracted with the help of 'treeextract' configuration pattern which, by default, takes the segment preceding the script name in SCRIPT_NAME. This convention can be defeated by anyone prefering something else. It is hoped that the 'treeextract' parameter mecanism is powerful enough to cope with any convention.
Should also this parameter be renamed to have some similarity with this sub? 'targetextract' ?
captionexpand ($templ, $who)Function captionexpand is a "$variable" substitution function. It returns an HTML-safe string that can be used in a header as a caption for the page.
$templ
a string containing the template
Presently, the template is equal to undef, which is the template value for a variable substitution request.
$who
a string containing the script name (i.e. source, sourcedir, diff, ident or search) requesting this substitution
bannerexpand ($templ, $who)Function bannerexpand is a "$variable" substitution function. It returns an HTML string displaying the path to the current file ($pathname) with < A > links in every portion of the path to allow quick access to the intermediate directories.
$templ
a string containing the template
Presently, the template is equal to undef, which is the template value for a variable substitution request.
$who
a string containing the script name (i.e. source, sourcedir, diff, ident or search) requesting this substitution
titleexpand ($templ, $who)Function titleexpand is a "$variable" substitution function. It returns an HTML-safe string suitable for use in a < TITLE > element.
$templ
a string containing the template
Presently, the template is equal to undef, which is the template value for a variable substitution request.
$who
a string containing the script name (i.e. source, sourcedir, diff, ident or search) requesting this substitution
stylesheet ($templ)Function thisurl is a "$variable" substitution function. It returns an HTML-encoded string suitable for use as the target href of a < LINK rel="stylesheet" > tag.
$templ
a string containing the template (i.e. argument)
Presently, the template is equal to undef, which is the template value for a variable substitution request.
The string comes from configuration parameter 'stylesheet'.
altstyleexpand ($templ, $who)Function altstyleexpand is a "$function" substitution function. It returns an HTML string which is the concatenation of its expanded argument applied to all the alternate stylesheet definitions found in the configuration file.
$templ
a string containing the template (i.e. argument)
$who
a string containing the script name (i.e. source, sourcedir, diff, ident or search) requesting this substitution; it is here considered as the "mode"
It retrieves the configuration array 'alternate_stylesheet' if it exists.
The argument template is then expanded through expandtemplate for each URL argument with a replacement rule for its name and value.
thisurl ()Function thisurl is a "$variable" substitution function. It returns an HTML-encoded string suitable for use as the target href of an < A > tag.
The string is the URL used to access the current page (complete with the ?query string).
baseurl ()Function baseurl is a "$variable" substitution function. It returns an HTML-encoded string suitable for use as the target href of a < A > or < BASE > tag.
The string is the base URL used to access the LXR server.
dotdoturl ()Function dotdoturl is a "$variable" substitution function. It returns an HTML-encoded string suitable for use as the target href of an < A > or < BASE > tag.
The string is the ancestor of the base URL used to access the LXR server.
Caveat:
Implementation is faulty: it does not check there is really an ancestor in the base URL (e.g. case when base URL is already at the root of document hierarchy).
forestexpand ($templ, $who)Function forestexpand is a "$function" substitution function. It returns an HTML string which contains links to the shareable trees of the configuration file.
$templ
a string containing the template (i.e. argument)
$who
a string containing the script name (i.e. source, sourcedir, diff, ident or search) requesting this substitution
It reads the configuration file into an array.
The elements, except the first (index 0), are scanned to see if parameter 'shortcaption' is defined, which means this tree is shareable.
If none is found, the template is not expanded. The returned string is void, thus avoiding any stray legend in the page.
Otherwise, the argument template is then expanded through expandtemplate with a replacement rule for the 'treelinks' attribute.
treesexpand ($templ, $who, $var)Function treesexpand is a "$function" substitution function. It returns an HTML string which is the concatenation of its expanded argument applied to all the shareable trees of the configuration file.
$templ
a string containing the template (i.e. argument)
$who
a string containing the script name
$confgroups
a array containing a copy of the configuration file
It uses the copy of the configuration file passed as an array argument.
The elements, except the first (index 0), are scanned to see if parameter 'shortcaption' is defined, which means this tree is shareable.
Depending on the result of Config.pm's treeurl, a mere highlighting of the name or a full link is generated.
The argument template is then expanded through expandtemplate with a replacement rule for each attribute.
The result is the concatenation of the repeated expansion.
urlexpand ($templ, $who)Function urlexpand is a "$function" substitution function. It returns an HTML string which is the concatenation of its expanded argument applied to all the URL arguments of the current page.
$templ
a string containing the template (i.e. argument)
$who
a string containing the script name (i.e. source, sourcedir, diff, ident or search) requesting this substitution; it is here considered as the "mode"
It makes use of sub urlargs to retrieve the filtered list of variables values. If necessary, other URL arguments may be added depending on the mode (known from $who).
The argument template is then expanded through expandtemplate for each URL argument with a replacement rule for its name and value.
modeexpand ($templ, $who)Function modeexpand is a "$function" substitution function. It returns an HTML string which is the concatenation of its expanded argument applied to all the LXR modes.
$templ
a string containing the template (i.e. argument)
$who
a string containing the script name (i.e. source, sourcedir, diff, ident or search) requesting this substitution; it is here considered as the "mode"
It first constructs a list (Perl @vector) of hashes describing the state of the mode: its name, selection state, link or action, CSS class.
The argument template is then expanded through expandtemplate for each mode with a replacement rule for each attribute.
The result is the concatenation of the repeated expansion.
varlinks ($templ, $who, $var)Function varlinks is a "$function" substitution function. It returns an HTML string which is the concatenation of its expanded argument applied to all the values of $var.
$templ
a string containing the template (i.e. argument)
$who
a string containing the script name
$var
a string containing the name of a configuration variable (defined in the 'variables' configuration parameter)
It first constructs a list (Perl @vector) made of HTML fragments describing the values of the variable (with an indication of the current value).
The argument template is then expanded through expandtemplate for each value with a replacement rule allowing the inclusion of the HTML fragment.
The result is the concatenation of the repeated expansion.
varmenuexpand ($var)Function varmenuexpand is a "$function" substitution function. It returns an HTML string which is the concatenation of < OPTION > tags, each one corresponding to the values defined in variable $var's 'range'.
$templ
a string containing the template (i.e. argument)
$var
a string containing the variable name
To handle CVS case where directories are not managed version-wise, the value any variable has on entry is kept, even if this value is not listed in its 'range' attribute. Thus, the current version, for instance, is not lost through a directory display.
varbtnaction ($templ, $who)Function varbtnaction is a "$variable" substitution function. It returns a string suitable for use in the action attribute of a < FORM > tag.
$templ
a string containing the template (i.e. argument)
$who
a string containing the script name
varexpand ($templ, $who)Function varexpand is a "$function" substitution function. It returns an HTML string which is the concatenation of its expanded argument applied to all configuration variables (those defined in the 'variables' configuration parameter).
$templ
a string containing the template (i.e. argument)
$who
a string containing the script name
All variables are considered one after the other and template expansion is requested through expandtemplate with adequate replacement rules for the properties.
Some variables may be "conditional". They then have a 'when' attribute which value is a boolean expression. If the expression evaluates true, the block will be expanded for this variable; otherwise, the variable is skipped.
The expression is most useful to display variables only when others have a given value.
The result is the concatenation of the repeated expansion.
displayindexstate ($who)Function displayindexstate is a "$variable" substitution function. It returns a HTML
element containing the indexing state of the current version.
$who
a string containing the caller script name
The times table record pertaining to the current version of the tree is read in and the various genxref's milestone dates are scanned to deduce the state.
devinfo ($templ)Function devinfo is a "$variable" substitution function. It returns a string giving information about the LXR modules.
This is a developer debugging substitution. It is not meaningful for the average user.
$templ
a string containing the template
Presently, the template is equal to undef, which is the template value for a variable substitution request.
atticlink ($templ)Function atticlink is a "$variable" substitution function. It returns an HTML-string containing an < A > link to display/hide CVS files in the "attic" directory.
$templ
a string containing the template
Presently, the template is equal to undef, which is the template value for a variable substitution request.
$who
a string containing the script name
makeheader ($who), $tmplpfxFunction makeheader outputs the HTML sequence for the top part of the page (a header) so that all pages have a similar appearance. It uses a template whose name is derived from the scriptname.
$who
a string containing the script name
$tmplpfx
an optional string containing the template prefix (by default, equal to script name)
In case the template is not found, an internal elementary template is generated to display something. An error is also logged for the administrator.
makefooter ($who)Function makefooter outputs the HTML sequence for the bottom part of the page (a footer) so that all pages have a similar appearance. It uses a template whose name is derived from the scriptname.
$who
a string containing the script name
In case the template is not found, an internal elementary template is generated to display something. An error is also logged for the administrator.
makeerrorpage ($who)Function makeerrorpage outputs an HTML error page when an incorrect URL has been submitted: no corresponding source-tree could be found in the configuration. It is primarily aimed at giving feedback to the user.
$who
a string containing the template name
In case the template is not found, an internal elementary template is generated to display something.
No assumption is made about the existence of other templates, e.g. header or footer, since they can be defined merely in the tree section without being defined in the global section. Consequently, there is no call to makeheader() or makefooter().
HTTP headers may or may not have been already emitted. Caller is responsible for checking that and eventually emit minimal HTTP headers for error page display.