view release on metacpan or  search on metacpan

lib/Config/Model/Manual/ModelCreationIntroduction.pod  view on Meta::CPAN

C<status>: is C<obsolete>, C<deprecated> or C<standard>
(default). Warnings are shown when using a deprecated element and an exception
is raised when an obsolete element is used.

=back

See L<Config::Model/Configuration_class> for details.

=head2 Leaf elements

Leaf element is the most common type to represent configuration data.
A leaf element represents a specific configuration parameter.

In more details, a leaf element have the following attributes (See 
L<Config::Model::Value/Value_model_declaration> doc):

=over

=item type

Set to C<leaf> (mandatory)

=item value_type

Either C<boolean>, C<integer>, C<number>, C<enum>, C<string>,
C<uniline> (i.e. a string without "\n") (mandatory)

=item min

Minimum value (for C<integer> or C<number>)

=item max

Maximum value (for C<integer> or C<number>)

=item choice

Possible values for an enum

=item mandatory

Whether the value is mandatory or not

=item default

Default value that must be written in the configuration file

=item upstream_default

Default value that is known by the target application and thus does
not need to be written in the configuration file.

=back

To know which attributes to use, you should read the
documentation of the target application.

For instance, C<AddressFamily> parameter (sshd_config(5)) is specified
with: I<Specifies which address family should be used by sshd(8).
Valid arguments are "any", "inet" (use IPv4 only), or "inet6" (use
IPv6 only).  The default is "any".>

For Config::Model, C<AddressFamily> is a type C<leaf> element,
value_type C<enum> and the application falls back to C<any> if this
parameter is left blank in C<sshd_config> file.

Thus the model of this element is :

 AddressFamily => {
   type             => 'leaf',
   value_type       => 'enum',
   upstream_default => 'any',
   description      => 'Specifies which address family should be used by sshd(8).',
   choice           => [ 'any', 'inet', 'inet6' ]
 }

=head2 Simple list or hash element

Some configuration parameters are in fact a list or a hash of
parameters. For instance, C<approx.conf> can feature a list of remote
repositories:

 # remote repositories
 debian     http://ftp.fr.debian.org/debian
 multimedia http://www.debian-multimedia.org

These repositorie URLs must be stored as a hash where the key is
I<debian> or I<multimedia> and the associated value is a URL. But
this hash must have something which is not explicit in C<approx.conf>
file: a parameter name. Approx man page mentions that:
I<The name/value pairs [not beginning with '$' are used to map distribution names to remote repositories.>.
So let's use C<distribution> as a parameter name.

The example is stored this way in the configuration tree:

 root
 |--distribution(debian)=http://ftp.fr.debian.org/debian
 `--distribution(multimedia)=http://www.debian-multimedia.org

The model needs to declare that C<distribution> is:

=over

=item *

a type C<hash> parameter

=item *

the hash key is a string

=item *

the values of the hash are of type C<leaf> and value_type C<uniline>

=back

 distribution => {
                   type => 'hash',
                   index_type => 'string',
                   cargo => {
                              type => 'leaf',
                              value_type => 'uniline',
                            },
                   summary => 'remote repositories',
                   description => 'The other name/value pairs are ...',
                 }

For more details on list and hash elements, see
L<hash or list model declaration|Config::Model::AnyId/Hash_or_list_model_declaration> man page.

=head2 node element

A node element is necessary if the configuration file has more than a