NAME

configit -- Tool for generating files from configuration and templates.

SYNOPSIS

  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.

DESCRIPTION

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.

Configuration

Overall syntax

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:

void

This is used to refer to non-value. No value may be specified.

identifier

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.

(Note: The prefix regex is really (((file)en)coding|fenc)[[:=]\s*)

string

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.

dns name

ASCII alphanumerics and dashes.

dns zone

DNS names separated with dots.

ipv4

Doted decimal IPv4 address. Only 4-byte notation is supported.

port

Number from 0 to 65535.

ipv4_port

ipv4:port

ipv4_mask

ipv4 followed by a slash and a number from 0 to 32.

mac

Six pairs of hex digits separated by colons.

path

Path, such as used in templates to select config elements. See below.

pair

Two values of types given, separated by whitespace.

list

Any number of values of types given, separated by whitespace.

nested_list

A list enclosed in square brackets ([]), that can contain values of type specified or sublists (again in square brackets).

perlcode

A block of perl code in curly braces ({}). The perlcode will be evaluated in Config::Maker::Eval module.

Metaconfig

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).

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:

template

This block directive defines a template to be processed for a given configuration. It has no value and 4 subdirectives.

mandatory src

This takes one string value, the name of template file.

optional out

This takes one string value, the name of output file.

optional 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.

optional cache

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.

optional 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.

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).

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.

Config

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.

Path

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.

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.

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:.

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

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: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.

Template

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.

[{perl code}]

A perl code is replaced by everything it prints and it's result. The code will again be evaluated in Config::Maker::Eval module.

[+key+]

A key can be either type or value. It returns type resp. value of current option.

[+key:path+]

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 path$] text [$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 (perlcode) $] text [$endmap$]

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 path $] text else-or-endif

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.

[$if (perlcode) $] text else-or-endif

This one expands text if and only if the perlcode returns true (as understood by perl). Otherwise it expands the else-or-endif.

else-or-endif is one of:

[$elsif test path $] text else-or-endif

[$elsif (perlcode) $] text else-or-endif

Just like if, but expanded only if the previsous if section was not.

[$else$] text [$endif$]

The text is expanded -- provided the previsous if block was not, of course.

[$endif$]

Ends the if chain. Nothing more is expanded.

[$output keyword$] text [$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.

Utilities

There are some utilities, that may be useful for generating various kinds of configs.

Currently the following are provided:

Config::Maker::Eval::DNSSerial

This one generates serial numbers for SOA records of DNS zone files.

AUTHOR

Jan Hudec <bulb@ucw.cz>

COPYRIGHT AND LICENSE

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.

SEE ALSO

perl(1), Config::Maker(3pm), Config::Maker::Eval(3pm).

cpanm Config::Maker

perl -MCPAN -e shell
install Config::Maker