/ 
Config-Maker-0.005
River stage zero No dependents
/ configit

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.
	-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 describes which configuration should be loaded, which templates should be expanded using that configuration and where the results should be placed.

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.

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:

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.

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 ({}).

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

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

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.

[+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.

[$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 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.

[$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
[$slsif (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.

Path

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

means just host options on the top-level. For functions that can be used in the condition see Config::Maker::Option.

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