configit -- Tool for generating files from configuration and templates.
configit [OPTIONS] <metacofnig...> Options: -h, --help Display this help message. -m, --man Display manual page. -n, --dry-run Don't install the built files. -f, --force Install all output, even if equal to cache. -v, --verbose Print more progress info. -q, --quiet Don't print any progress info. -D, --debug Print debugging infromation. -T, --trace Trace the parsers.
This program generates files from a metaconfig, configuration and templates.
The metaconfiguration file contains two important pieces of information – the schema, which says how the config should be parsed and the description of config files and templates to process.
The config file contains data in a simple hierarchical form.
The templates are text interleaved with special directives. These directives can select items (directives) from the config and insert their contents. It is possible to check whether directives are present and iterate over them. And when that's too weak, it allows insering snippets of Perl code.
The configuration file (both metaconfig and configuration) have the same syntax. Each config file is composed of directives. Simple directives are optionaly followed by a value and a semicolon (;). Group directives are optionaly followed by a value and then a block in curly braces is given, that can contain further directives. Each directive specifies how the value should look and what directives are allowed in it's block.
;
A directive or a block can be replaced by filename in angle brackets (<>). Contents of that file will be inserted in that place, or used as content of the block respectively. The file must be a valid config file on it's own (ie. all the directives must be closed).
<>
Comments start with a # and extend to the end of line. They are syntacticaly equivalent to a whitespace.
#
The directives take several types of values:
This is used to refer to non-value. No value may be specified.
Starts with a letter and continues with alphanumerics, dashes and underscores. Unicode letters are recognized and valid.
In perl 5.8 and later, the program internaly operates in unicode. It assumes all input files are in encoding specified by LC_CTYPE locale variable, but if they contain a comment near beginning or end (first/last 250 bytes) with encoding: or fenc= followed by encoding name, they are assumed to be in that encoding. In perl 5.6 (and 5.7) recoding is not available and the program will warn if it encounters encoding specifications.
LC_CTYPE
encoding:
fenc=
(Note: The prefix regex is really (((file)en)coding|fenc)[[:=]\s*)
(((file)en)coding|fenc)[[:=]\s*
A string can be either a bareword (of alphanumerics and some common non-special characters), or a single or double-quoted string. In double-quoted string, common \ escape sequences and environment variables are expanded.
\
ASCII alphanumerics and dashes.
DNS names separated with dots.
Doted decimal IPv4 address. Only 4-byte notation is supported.
Number from 0 to 65535.
ipv4:port
:
ipv4 followed by a slash and a number from 0 to 32.
Six pairs of hex digits separated by colons.
Path, such as used in templates to select config elements. See below.
Two values of types given, separated by whitespace.
Any number of values of types given, separated by whitespace.
A list enclosed in square brackets ([]), that can contain values of type specified or sublists (again in square brackets).
[]
A block of perl code in curly braces ({}). The perlcode will be evaluated in Config::Maker::Eval module.
{}
The metaconfig specifies a which configuration files and templates should be processed and a schema for configuration directives contained in them.
search-path
This simple directive takes a (possibly empty) list of string values. Files specified with relative paths are searched in these directories.
ouput-dir
This simple directive takes one string value, a path where output files specified with relative paths should be placed.
cache-dir
This simple directive takes one string value, a path where cache files specified with relative patch should be placed (see cache directive below).
cache
config
This group directive defines a configuration and what should be done with it. It has a string value -- name of the config file. The block can contain following directives:
string
template
This block directive defines a template to be processed for a given configuration. It has no value and 4 subdirectives.
src
This takes one string value, the name of template file.
out
This takes one string value, the name of output file.
command
This takes one string value, the shell command to run. This command will be parsed by the shell and it will get the result on standard input. Either out or command directive must be specified, both may be.
This takes one string value, the name of cache file. The cache file keeps a copy of output for purpose of comparing. If cache exists, output file is only installed and command only runs if the output differs from the cache. Templates that don't have cache defined are instantiated always.
enc
Encoding of the output file. If not specified, encoding of the template is used.
schema
This block directive takes no value and a block of suboptions.
type
This declares a directive type. It has two variants. If used directly in schema, it takes just one argument, the identifier for the directive, and a block. If used inside other type, it takes a pair, where the first value is one of none, opt, one, mand or any and the second is the desired identifier. And the block, of course.
none
opt
one
mand
any
The first argument in two argument form means, how many instances are allowed in given context. none means none is allowed, opt means zero or one, one means exactly one must be present, mand means at least one and any means no restrictions.
contains
This can be used inside type to specify that it can contain other type. The first argument is one of none, opt, one, mand or any (like in type) and the other is a name of type, that was specified directly in schema.
toplevel
This can be used inside type to specify, that it can appear on top-level. It takes no value.
simple
anon_group
named_group
These are used inside type to define format for arguments. anon_group takes no value, the others take nested list defining the value format.
Value format is one of the formats listed above in "Overall syntax" or void for none. The list formats are followed by arguments for the subvalues. The pair format is followed by two bracketed specifications. For more details see Config::Maker::Type(3pm).
void
action
This takes a perlcode, that is run whenever that option is parsed. The action for block option is run after all the actions for it's suboptions.
The config can contain any directives described by the schema in the metaconfig. It's completely up the the user what he wants to have there.
Templates refer to the values from config using paths.
Path is a list of components separated by /-es. Each component matches a list of options (like a wildcard matches a list of files). Result of a whole path is then obtained by searching the rest from all the options matched by the first component.
/
If the path starts with a /, starting point is the config root.
If the path starts with a special keyword META: (case-sensitive), the starting point is a special meta-root.
META:
Otherwise the starting point is the current option, as set by eg. the map directive. At the start of the template, the current option is the root. It is actually Perl current topic ($_), so it can be affected by localizing that variable.
map
$_
Generic syntax for a component is type:value(condition). The type is a wildcard matching type of the option and value is a wildcard matching the value. The condition is a perl expression, that will get processed option in current topic ($_) and should return true if that option should match. It will be evaluated in the Config::Maker::Eval module.
(
)
Wildcards are like shell ones and csh-style curlies {} are understood. Regular expressions can be used instead by prefixing them with RE:.
RE:
Components can be ommited. Shorthand notations allowed are: type, :value, type(condition) and :value(condition).
A special component ** is allowed which means all options recursively. So:
**
/**/host
means all host options anywhere in the configuration, while
host
/host
means just host options on the top-level. For functions that can be used in the condition see Config::Maker::Option.
In the special meta-tree, following values are available when processing a template:
META:meta
The meta-configuration, as a whole.
META:template
The contents of currently active template directive. Note, that it points back to the actual meta-configuration, so META:template/.. is the name of the current config.
META:template/..
META:output
Qualified name of the output file, so you can access it without having to do the search based on META:template/out and META:meta/output-dir.
META:template/out
META:meta/output-dir
The template is a text file, that can contain special directives. Text outside directives is copied through to the output.
Directives are generaly enclosed in square brackets. A square bracket can be inserted in text by doubling it.
Following directives are recognized:
[#...#]
A comment. It is replaced by an empty string.
[{
}]
A perl code is replaced by everything it prints and it's result. The code will again be evaluated in Config::Maker::Eval module.
[+
+]
A key can be either type or value. It returns type resp. value of current option.
value
Like above, but returns type resp. value of option with given path. Exactly one such option must exist.
[<filename>]
This includes specified file in given place. The included file is processed like a template and has to be valid on it's own (ie. all block directives must be closed).
[$map
$]
[$endmap$]
This expands text for all options that match path. All whitespace up to and including newline after both opening and closing directive is stripped.
[$map (
) $]
This expands text for all elements returned by perlcode. Most directives expect the elements will be options, but of course with [{}] directives any value can be used.
[{}]
[$if
Test is one of none, unique, one, exists or any. They mean the path should match none, at most one, exactly one, at least one and any number of option. If the test succeeds, the text is expanded, otherwise the else-or-endif is expanded.
unique
exists
[$if (
This one expands text if and only if the perlcode returns true (as understood by perl). Otherwise it expands the else-or-endif.
[$elsif
[$elsif (
Just like if, but expanded only if the previsous if section was not.
[$else$]
[$endif$]
The text is expanded -- provided the previsous if block was not, of course.
Ends the if chain. Nothing more is expanded.
[$output
[$endoutput$]
This allows ommiting some output from cache or from output. Eg. a serial number (like in DNS zone files) can only be written to output, so if the number differs, but contents is otherwise identical, it is not replaced.
keyword can be one of:
all
both
Text will be generated in both the cache and the output (as normal).
only-cache
no-out
Text will only be written to cache.
only-out
no-cache
Text will only be written to output.
There are some utilities, that may be useful for generating various kinds of configs.
Currently the following are provided:
This one generates serial numbers for SOA records of DNS zone files.
Jan Hudec <bulb@ucw.cz>
Copyright 2004 Jan Hudec. All rights reserved.
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
perl(1), Config::Maker(3pm), Config::Maker::Eval(3pm).
3 POD Errors
The following errors were encountered while parsing the POD:
You forgot a '=back' before '=head1'
'=item' outside of any '=over'
To install Config::Maker, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Config::Maker
CPAN shell
perl -MCPAN -e shell install Config::Maker
For more information on module installation, please visit the detailed CPAN module installation guide.