Detailed Information

Template related
Configuration file work
Data verification and manipulation
Misc file and directory functions

CHANGES
BUGS
COPYRIGHT

NAME

elwomis.pm - a do-it-all module...

DESCRIPTION

Here comes a detailed description of the functions of this module.

Function overview

Template related

strict_commentparsing: Set comment parsing behaviour
append_template_sub (internal use only): sub routine for append_template (does the most of the work)
append_template: appends data constructed from a template and a hash of variables to a file
print_template: prints data constructed from a template and a hash of variables to a filehandle (e.g. stdout)
string_template: replace all varialbes in a string acting as a template
template2var: read a file template file into a variable, replacing variables by their values

Configuraion file work

parse_config: parse configuration file, replacing variables
dump_config: write a configuration file (complete)
save_config: write a configuration file (leaving out values from other files)

Data verification and manipulation

check_var: checks whether config variables are defined properly
check_config: checks whether config variables in a hash are defined properly

Misc file and directory functions

walk_dirs: get all the directories that must be walked through
findfiles: gets all config files of a specific type (definded by a pattern) in a specific directory
append_file_to_file: appends file1 to file2
extract_dir_from_path: extracts the directory part out of a path specification.
empty_file: Empty a file or create it if it does not exist.

Detailed Information

Template related

Variables and Functions:

${<VARNAME>}

insert variable called <VARNAME> here Undefined variables are replaced by a null string

Special variables:

${DATETIME}: is replaced by the local time string
${TIME}: is replaced by the time at the moment of parsing (time in seconds since 1/1/70, 0:0:0)
${~TMPL_TEMPLATEFILE}: template file given to append_template, print_template and template2var.
${~TMPL_CALLERFILE}: the themplate that included the current one (available only in append_template and print_template).
${~TMPL_ACTFILE}: file name of current template (available only in append_template and print_template).

\$[<FORMAT>]{<VARNAME>}

variable, using formatted output:

x output width in characters l align to left (default) c centered (won't work at the moment) r align to right

\${<VARNAME>}

escaped variable, will become ${<VARNAME>}

#{<VARNAME>}

if construction: only if <VARNAME> is defined, the contents of this line are used, else the output is an empty string

#!{<VARNAME>}

if not construction - see also if construction

&SWAP

Swaps the contents of the variable at the ``.'''s e.g. the order of the numbers of an ip adress is reversed in order to be able to build the in-addr.arpa address. Usage:

&SWAP(<delimiter-char>, $<variable to insert here swapped>)

#@{filename} (append_template only)

Inserts the template from filename at the current position (this directive must be the only thing in one line) - caution: this is recursive, so make sure that the template does not insert itself or another template with an include of the actual one, as this would cause a never-ending loop The line is piped through string_template before executing the insert, so filename can consist of one or more variables, too.

e.g. #@{${MYTEMPLATE}} will insert the file specified in MYTEMPLATE Path names are relative to the path of the template containing this command.

strict_commentparsing

Short description:: set comment parsing behaviour
Long description:: If set 0, comment parsing will be loose, meaning that comments are even allowed in middle of line (e.g. after a var. declaration) If set 1, comments are only accepted at beginning of line (but having whitespaces ignored).
Return value:: none
Syntax: void parse_config(boolean mode)

append_template_sub (internal use only)

Short description:: sub routine for append_template (does the most of the work)
Long description:: reads the template-file line by line and pipes it through string_template. Then it check's if there is an include command in the line. If there is one, it call's itself recursivly to insert the given include file.
Syntax: append_template_sub (string template_name, filehandle OUTPUTFILE, string path_to_templates, hash variables)

append_template

Short description:: appends data constructed from a template and a hash of variables to a file
Long description:: reads the file line per line, feeding the data into string_template and appends the string_template output to the given file
Syntax:: append_template (string template_file, string output_file, hash variables)

print_template

Short description:: prints data constructed from a template and a hash of variables to a filehandle (e.g. stdout)
Long description:: reads the file line per line, feeding the data into string_template and prints it to the given filehandle
Syntax:: print_template (string template_file, hash variables)

string_template

Short description:

replace all varialbes in a string acting as a template

Long description:

Reads a string searching for variables and creates a new string were all the variables are exchanged by their values. Some special functions are known as well (e.g. if). Non-existing or empty variables are replaced by an empty string.

Return value:

Returns the newly created string or undef on error.

Syntax:

        string string_template (string template, hash %variables)

template2var

Short description:: read a file template file into a variable, replacing variables by their values
Return value:: Returns true (!0) on success and false (0) on error
Syntax:: bool template2var (string $filename, string \$variable, hash %data);

Configuration file work

parse_config

Short description:

parse configuration file, replacing variables

Long description:

Will parse a configuration file, variables are replaced by their values. If a hash is given as second argument, the contents of it are used as replacement material if the new hash does not contain any data for the named variable.

Return value:

undef on error, a config hash in all the other cases


=item Syntax:

%config parse_config(string $filename, [hash @configvalues])

dump_config

Short description:

write a configuration file (complete)

Long description:

dump_config will save the contents of a configuration hash to a file. In opposite to save_config it will write down all the keys/values contained in the hash, as it does no comparison to the upper level hash. If the file exists, it will be overwritten!

NOTE: Usually you shold prefer the use of save_config.

Return value:

returns the number of keys/values (each pair counted once) written to the file or -1 on error

Syntax:

int dump_config(string $filename, \%hash) int dump_config(string $filename, %hash)

See also:

save_config();, parse_config();

save_config

Short description:

write a configuration file (leaving out values from other files)

Long description:

save_config will save the contents of a configuration hash to a file. During this process it will compare the values to the values to the next upper config hash and will skip a value which was overtaken from the upper level.

The old configuration file will be read and this function tries to keep the layout. Also variables set in the file with the same value as in the upper hash will be written in order to keep the file more similar to the original.

NOTE: If the file exists, it will be overwritten!

Return value:

returns the number of keys/values (each pair counted once) written to the file or -1 on error

Syntax:

int save_config(string $filename, \%hash, \%upperhash)

See also:

dump_config();, parse_config();

Data verification and manipulation

check_var

Short description:

checks whether config variables are defined properly

Long description:

This function checks a variable in order to assure that all variables needed by the program are defined properly. It will be checked against a list of flags which specify the valid contents. The checking can be manipulated by giving tags as the contents of the check definition hash variables.

Some flags cause manipulation of the data in the variable - in the following overview of standard flags, they will be marked with an asterisk (*):

def: Fail if variable is not defined/is undef
critical: If the variable check fails, the function will croak, so that the programm excecution is aborted with a die command - without this flag, only warnings will be shown.
----- the following checks include a def(ined) check:
exist: Fails if the variable does not contain the path to a valid filesystem node
dir (*): Check if the variable can describe a directory. If there is no trailing slash in the variable, it will be added.
file: Check whether the variable contents CAN describe a file
exec is the var a executable file/dir?
regexp <pat>: Do a pattern match on the variable contents, warn/die if the match fails.
create [<owner> [<mode>]]: Create the node if it does not exist. If node is a directory, even parent dirs are created. Owner is a UID (numeric) if a GID should be given specify UID:GID. Mode is a file mode in octal notation.

Return value:

returns the number of errors found in scalar context or the number of errors found and a variable which is true if one of the errors was critical.

Syntax:

boolean check_var (string $varname, sring-ref $configvalref,
 string $checkflags[, string $runmode]);

See also:

check_var();

Note:

The $runmode specification is for library-internal use only. It is used by the check_config function and should not be used by hand.

check_config

Short description:

checks whether config variables in a hash are defined properly

Long description:

This function checks a hash in order to assure that all variables needed by the program are defined properly. This is done by checking the contents of the hash variables. The variables that will be checked are defined in a hash.

For the checking, check_var is called, whose behaviour can be modified by flags. Please have a look at the check_var description to get more information about them. =item Return value:

returns the number of errors found.

Syntax:

boolean check_config (hashref \%config, hashref \%check_against);

See also:

check_var();

Misc file and directory functions

walk_dirs

Short description:: get all the directories that must be walked through
Long description:: Reads all directory entries of rootdir, and calls itself for every one matching needed pattern and in same time not matching exclude-pattern. If a value is given for recursive, the function will eigther rerun itself for each subdirectory or only push the directory name to the array. If no value is given, the function will work as if 1 was the number, so a recursive search will be done. Each such entry is appended to an array which is returned to the initial caller.
Return value:: Array containing all the directory paths on success and undef on error
Sytax:: @dirs walk_dirs(rootdir, needed-pattern, exclude-pattern[, recursive={0|1}]);

findfiles

Short description:: gets all config files of a specific type (definded by a pattern) in a specific directory
Long description:: Reads all files in a given directory and matches them to the given pattern. If the pattern matches, the path is prepended to the filename and the result is saved in an array which is returned to the caller.
Return value:: Returns an array containing all matching files or undef on error.
Syntax:: @files find_files(string directory, string pattern);

append_file_to_file

Short description:: appends file1 to file2
Return value:: returns true (!0) on success and false (0) on error
Syntax:: bool append_file_to_file(string filename1, string filename2);

extract_dir_from_path

Short description:: extracts the directory part out of a path specification.
Syntax:: $path = extract_dir_from_path (string filename);

empty_file

Short description:: Empty a file or create it if it does not exist.
Return value:: returns true (!0) on success and false (0) on error
Syntax:: bool empty_file(string filename);

CHANGES

(version 0.1.2)

Change the calling syntax of append_template_sub.
Added dynamical set variables ~tmpl_templatefile, ~tmpl_callerfile, ~tmpl_actfile

Re-structuring from JUZ.pm to elwomis.pm (version 0.1.1)

Removed init-function and %config-hash
The function read a configuration file and asked the user to enter a name. All this information was saved in a hash named %config. Because these two symbols weren't used in quite some programs which used JUZ.pm we thought that it would be better to remove them, as it was a function which had to be called before using any other.
Created POD documentation
Changed dump_config syntax
Before this, dump_config had to be called using a reference to a hash. Because we don't like references, we modified the source and made it possible to call the function either with a reference or with the hash directly.
Renamed cfgfiles to findfiles, empty to empty_file, append to append_file_to_file and file2var to template2var
The name changement was made in order to match the functionality of that subroutines.
string_template: added support for formatted output (for strings)
We introduced a notation $[wa]{variable} which can be used to create an output of a specified width w and align the variable to a (l, c, r).

BUGS

At the moment, we only know about one problem using this module.

Case of variable names when using templates
Although the variable names are case-insensitive in the templates, the functions will only insert variables that have all lower-case names in the hash of data. This ``bug'' was introduced intendedly, as it makes it possible to use an algorith which is about three times faster as the old one, which was really case-indifferent.

If you find any bugs in the latest version, please send us a mail to code@juz-kirchheim.de, please include a description of the environment and the problem.

COPYRIGHT

This program is copyrighted by its authors Walter Werther and Baltasar Cevc. It is free software - use annd distribute under the terms of the GPL (GNU Public License, Version 2, or at your choice any later version).