Inside Configuration Services
new (@parms)emergency ()readconfig ()readfile ($file)_initialize ($host, $script_path, $firstseg, $confpath)treeurl ($group, $global)
allvariables ()variable ($var, $val)vardefault ($var)vardescription ($var, $val)varrange ($var)varexpand ($exp)value ($var)AUTOLOAD (@parms)mappath ($path, @args)unmappath ($path, @args)
_ensuredirexists ($chkdir)
This module contains the API to the configuration file. It is responsible for reading the file, locating the parameter group for the current source-tree and presenting an abstract interface to the 'variables'.
new (@parms)Method new creates a new configuration object.
@parms
the paramaters array (just passed "as is" to _initialize)
emergency ()Method emergency returns whatever can be retrieved from the configuration file.
It is intended to allow editing user-friendly error message when a catastrophic event occurred during initialisation.
readconfig ()Method readconfig returns the content of the configuration file as a list.
Note:
This method should only be used in cases when it is relevant to make distinction between the different blocks (such as showconfig or the need to create links to other trees). In all other circumstances, the configuration file should only be accessed through the public methods.
readfile ($file)Function readfile returns the content of the designated file as a list of "words" ("words" are delimited by spaces).
$file
a string containing the file name, relative to the LXR root directory or absolute
Note:
This is not a "method", it is a standard function. Its main goal is to provide an easy way to initialize the configuration 'variables' by reading the set of values from a text file.
_initialize ($host, $script_path, $firstseg, $confpath)Internal method _initialize does the real object initialization.
$host
a string containing the host name
$script_path
a string containing the hierarchical web path to the script (truncated at the invoking script)
$firstseg
a string containing the first segment of the path into the source-trees, possibly the tree name (may be empty if single-tree context)
CAUTION! It may also be a first-level directory!
$confpath
a string containing the path of an alternate configuration file (either relative to the LXR root directory or absolute)
If $confpath is not defined, use the internal $confname.
If $host, $script_path is not defined, try to extract something meaningful from the invoking URL.
CAVEAT!
This sub is also used by genxref. genxref is an ordinary script, operating in OS environment. Remember then that HTTP environment does not exist and there is no URL. Consequently, the last two arguments must be explicitly given.
treeurl ($group, $global)Method treeurl returns a URL for the tree described by parameter group $group. This URL tries to match the present hostname used to invoke LXR.
$group
a reference to the tree-specific parameter group
$global
a reference to the global parameter group to provide default values for parameters not present in the tree-specific group
Parameters 'host_names' and 'virtroot' are retrieved to build a URL to launch LXR on that tree.
It compares the hosts (in a list composed of 'host_names' from the tree-specific or global parameter group) + 'virtroot' to 'script_path' (with the script name removed).
If a match is found, undef is returned, meaning that an HTML-relative URL may be used.
If no match, a second attempt is made with the hosts only to test for a target tree different from the current one.
If a host matches, an HTML-absolute URL is returned.
Otherwise, the first hostname in the list is selected for the returned HTML-absolute URL.
Potential problems:
Presently, only parameter 'host_names' is used because the automatic configurator does not use 'baseurl' nor 'baseurl_aliases', which are deprecated.
If file lxr.conf is 'baseurl' based, the returned URL will contain garbage.
The LXR server may be accessed simultaneously under different names, e.g. localhost on the computer, a short name on the LAN and a full URL from the Net.
Choosing the first name in 'host_names' may not give the correct name for the current user (localhost instead of a fully qualified URL). But extracting the hostname from the page URL is not guaranteed to be the correct choice in all circumstances.
This might be solved with a more complex structure in 'host_names' made of 2 lists, one for "local" mode, the other for "remote" mode. But, once again, how to chose reliably and automatically the correct option?
With these two lists, an approach could be to note the index of the hostname for the successfully identified trees. If it is always the same, then determine if this is a local or remote hostname and use the first hostname in the corresponding list for the unknown tree.
allvariables ()Method allvariables returns the list of all defined variables.
variable ($var, $val)Method variable returns the current value of the designated variable.
$var
a string containing the name of the variable
$val
optional value; if present, replaces the current value
If no current value has already been set, the default value is returned.
vardefault ($var)Method vardefault returns the default value of the designated variable.
$var
a string containing the name of the variable
If no default value has been defined, the first value in 'range' is returned.
vardescription ($var, $val)Method vardescription returns the description of the designated variable.
$var
a string containing the name of the variable
$val
optional value; if present, replaces the description
Note:
Don't be confused! The word "description" is human semantic meaning for this data. It is stored in the 'name' element of the hash representing the variable and its state.
varrange ($var)Method varrange returns the set of values of the designated variable.
$var
a string containing the name of the variable
varexpand ($exp)Method varexpand returns its argument with all occurrences of $xxx replaced by the current value of variable 'xxx'.
$exp
a string to expand
value ($var)Method value returns the value of a configuration parameter with occurrences of $xxx replaced by the current value of variable 'xxx'.
$var
a string containing the configuration parameter name
AUTOLOAD (@parms)Magical Perl method AUTOLOAD to instantiate unknown barewords.
@parms
optional arguments array passed to instantiated function
When a bareword is encountered in a construct like $config->bareword, this method is called. It tries to get the expanded value of configuration parameter 'bareword' with method value. If the value itself is a function, that function is called with the parameters provided to bareword.
The final value is returned to the caller.
mappath ($path, @args)Method mappath returns its argument path transformed by the 'maps' rules.
$path
a string containing the path to transform
@args
an array containing strings of the form var=value forcing a context in which the 'maps' rules are applied
Note:
The rules are applied once only in the path. Should they be globally applied (with flag g on the regexp)? Does this make sense?
unmappath ($path, @args)Method unmappath attempts to undo the effects of mappath. It returns an abstract path suitable for a new processing by mappath with a new set of variables values.
$path
a string containing the file path to "invert".
@args
an array containing strings of the form var=value defining the context in which the 'maps' rules were applied.
'maps' rules are given as pattern => replacement where replacement may itself contain $var markers asking for substitution by the designated variable value.
Tentatively inverting mappath processing means applying "inverse" 'maps' rules in reverse order.
Note:
From a theoretical point of view, this problem has no general solution. It can be solved only under restrictive conditions, i.e. information has not been irremediably lost after rule application (consider what happens if you completely remove a path fragment and its delimiter).
The generated "inverted" rule has the following form:
transformed replacement => transformed pattern
transformed replacement
$num elements become .+?, i.e. "match something, but not too much" to avoid "swallowing" what is described after this sub-pattern.
Note:
It could be possible to be more specific through parsing this original pattern and analysing the associated parenthesised sequence. However, this could be time-expensive and the final advantage might not be worth the trouble. Even the known 'maps' rules for kernel cross-referencing do not use $num.
$var are replaced by the designated variable value.
If the original pattern had ^ (start) or $ (end) position anchors, these are transfered.
transformed pattern
Optional quantifiers ? or * (and variants suffixed with ? or +)
If there is one, process the sequence from beginning to the quantifier to remove the preceding ( ) parenthesised block (proceeding carefully from innermost pair of parenthesis to outermost), [ ] character range or single character.
Caveat:
When a character is checked, care is taken to cope with \-escaped characters but no effort is done to manage longer escape sequences such as \000, \x00 or any other multi-character sequence. Consequently, the above transformation WILL FAIL if any such sequence is present in the original pattern.
The sub-pattern is entirely removed because the corresponding string can be omitted from the file path. We then do not bother with creating a sensible string since it is optional.
Repeating quantifier + (and variants suffixed with ? or +)
Quantifier is merely removed to leave a single occurrence of the matching string.
( ) groups
Proceeding from innermost group to outermost, the first alternative is kept and the others deleted. The parentheses, now useless and, matter of fact, harmful, are erased.
[ ] character ranges
Only the first character is kept.
If the specification is an exclusion range [^ ], the range is replaced by character %, without further parsing, in the hope it does not appear in the range.
\ escaped characters
Depending on the character, the sequence is erased, replaced by a conventional character (think of character classes) or by the designator letter without the backslash.
Caveat:
No effort is done to manage longer escape sequences such as \000, \x00 or any other multi-character sequence on the ground that this escape sequence is also valid in the replacement part of an s/// instruction.
However some multi-character sequences (e.g. \P) are not valid and will ruin the "inverse" rule but they are thought to be rather rare in LXR context.
The generated rule is then applied to $path.
The effect is cumulated on all "inverse" rules and the final $path is returned as the value of this sub.
_ensuredirexists ($chkdir)Internal function _ensuredirexists checks that directory $dir exists and creates it if not in a way similar to "mkdir -p".
$chkdir
a string containing the directory path.
"Manual" algorithm replaced by a call to File::Path::make_path().
Every component of the path is checked from left to right. Both OS-absolute or relative paths are accepted, though the latter form would probably not make sense in LXR context.