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. -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 describes which configuration should be loaded, which templates should be expanded using that configuration and where the results should be placed.
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.
;
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:
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.
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 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 directve takes one string value, a path where output files specified with relative paths should be placed.
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.
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.
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.
[+
+]
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.
[$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 no, 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.
no
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
[$slsif (
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.
Template refers 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, otherwise it is the current option (as set eg. by map directive).
/
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.
(
)
$_
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.
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).
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.