view release on metacpan or  search on metacpan

lib/Config/General/Hierarchical.pm  view on Meta::CPAN

=item am

This is the tipical B<m> use.

=item au

A reference to an ARRAY is returned, empty if the value is B<undefined>.

=back

=head1 BACKSLASH ESCAPEING

The B<get> method before performing the B<syntax constraint> check parses the value in order
to escape the backslashes. The following backslasch sequences are recognised.

=over

=item \\ backslash

=item \$ dollar

=item \a beel

=item \b backspace

=item \f form feed

=item \n new line

=item \r carriage return

=item \t horizontal tabulator

=item \v vertical tabulator

=back

A backslash at the end of the line makes the following line to be concatenated with the
current one, this is a L<Config::General> feature. In the following example I<$value>
contains the value 'valuecontinued'.

 # config file
 variable value\
 continued

 #code
 my $value = $cfg->variable;

=head1 INLINE VARIABLE SUBSTITUTION

If a B<value> contains the following syntax

 ${variable_name}

this token is substituted with the B<value> of C<variable_name>. The I<inline variable
substitution> is made at get time, so the B<value> substituted is the final one of the
variable. The B<value> of C<variable_name> is obtained by a C<get()> call, so the B<syntax
constraiant> check is performed on it before the substitution.

To do the I<inline variable substituition> is necessary that a reference to the B<root
node> is still alive, otherwise a C<die()> is called. Anyway, it is possible to call the
C<check()> method on the B<node> before loosing the B<root node> reference in order to
cache all the values. It can be called explicitally on a B<node> of implicitally by
the C<new()> methed using the C<check> parameter with a true value.

 # config.conf file
 <node>
  key ${var}
 </node>
 var value

In the following exaple a C<die()> is called

 my $node = get_node;
 $node->_key; # this generates a die call
 #
 sub get_node {
   my $cfg = Config::General::Hierarchical->new( file => 'config.conf' );
   return $cfg->_node;
 }

This can be prevented by this way

 my $node = get_node;
 $node->_key;
 #
 sub get_node {
   my $cfg = Config::General::Hierarchical->new( file => 'config.conf', check => 1 );
   return $cfg->_node;
 }

or by this way (more efficient than previous).

 my $node = get_node;
 $node->_key;
 #
 sub get_node {
   my $cfg  = Config::General::Hierarchical->new( file => 'config.conf' );
   return $cfg->_node->check;
 }

When an C<undef> variable is requested during I<inline variable substitution>, its value is
substituted with an empty string.

The syntax to access the B<value> of a B<subkey> while in I<inline variable substitution> is
C<< -> >> ; in the following example C<< $cfg->_var >> will return C<'abc'> .

 # configuration
 <node>
  key b
 <node>
 var a${node->key}c

=head1 DUMPING CONFIGURATION

The module L<Config::General::Hierachical::Dump> offers a simple and usefull way to I<dump>
configurration files.

=head1 EXAMPLE

Using many of the features of C<Config::General::Hierarchical> it is possible to do so.