view release on metacpan or  search on metacpan

lib/Advanced/Config/Examples.pm  view on Meta::CPAN

   # Does variables within variables ...
   # Implements:  b = $ENV{test} ? $y : $z;
   y = YES
   z = NO
   b = ${test:+${y}}   # Set to ${y} if $ENV{test} is set, else undef
   b = ${b:-${z}}      # Set to ${z} if ${b} is undef, else set to ${b}.

   # So (a,b) = (TRUE,YES) or (FALSE,NO).

   # How about testing for a specific value for $ENV{test}?  This can be
   # done in a limited way.
   message_abc = I know my abc's.
   message_123 = I know my 123's
   message_hello = Hello World!
   msg = ${message_${test}:-Unknown Message.}

   # So if test is "abc", "123" or "hello" it will use the appropriate
   # value for tag msg.  Otherwise it will be "Unknown Message.".

   # This shows that you can put some logic in your config files so that
   # your config files can be shared across platforms without having
   # to have multiple versions of that config file or add complex platform
   # specific logic into your perl code.

To load it into memory do:

   my $cfg = Advanced::config->new ("complex.cfg")->load_config();

=item BREAKING YOUR CONFIG FILE INTO SECTIONS (section.cfg)

   abc = lmn     # Has no section, so considered in section "main".
   user = me
   pwd = nope!

   [ host 1 ]
   abc = xyz
   pwd = password1

   [host 2]
   abc=abc
   pwd = password2

   [ HOST 3 ]
   abc = 123
   pwd = password3

   [ HOST 2 ]
   efg = repeat    # Section "host 2" has 3 tags in it.  "abc", "efg" & "pwd".

   [ Host 4 ]
   user = you

Please note that section names are case insensitive and the tag abc's value
depends on what section of the config file you are currently looking at.  This
way you may repeat tags between sections and know that each section is
independent of each other.  As if each section was in its own config file.

Or you can interpret each section as overrides to tags in the main section
using the B<inherit> option.  Where if a tag isn't defined in the current
section, it then looks in the main section for it.  Say you're on host 1 and
you want to log into your application.  You need both a user & pwd pair to do
this.  When you look up the pwd, you find it in host 1, but when you try to
look up the user, it can't find it in the current section, so it looks in the
main section for it instead.  In effect all 4 sections have all variables from
main included in each section.  With the local tags overriding what's in main.
A neat way to handle minor differences that would otherwise require you to
have multiple config files you'd need to keep in sync.

To load it into memory do:

   my $cfg = Advanced::config->new ("section.cfg")->load_config();
              or
   my $cfg = Advanced::config->new ("section.cfg", {inherit => 1})->load_config();

=item SOURCING IN FILES WITH SECTIONS (src_sect.cfg)

By default, when sourcing in another config file it's default section is
also called "B<main>".  This is true even when you are sourcing in a file
inside a named section block.  That name isn't inherited by default.

And if that config file also uses sections, those section names are preserved.

But sometimes you'd like to source in a sub-file as if any tag appearing
outside a section was defined in the original file's current section.  In
that case follow the file name with the appropriate label.  Which by default
is B<DEFAULT>.

    . simple.cfg   # All variables appear in the main section.

    [ section 1 ]
    . simple.cfg   # All variables appear in the main section as well.

    [ section 2 ]
    . simple.cfg   # DEFAULT - all variables from this config file will appear as members of "section 2".

    [ section 3 ]
    . section.cfg  # DEFAULT - tags abc, user & pwd are now in 'section 3', while everything else stays in it's defined section.

To load it into memory do:

   my $cfg = Advanced::config->new ("src_sect.cfg")->load_config();

=item USING STRANGE LOOKING CONFIG FILES (product-1.cfg)

Sometimes you want to look at a config file owned by another product that
doesn't follow the formatting expected by this module by default.  So this
module allows you a way to provide new rules for parsing a config file to
make these differences irrelevant.

Lets assume this config file used ";", not "#" as the comment char, "::", not
"=" as it's assignment operator, and finally used "include", not "." when
sourcing in another config file.  So you'd get something like the following:

   ; This is a comment ...
   include  product-2.cfg

   abc :: xyz      ; Tag "abc" now equals "xyz"!

The possibilities are practically endless!  You can even write your own wrapper
config file and use the "source_cb" callback option to redefine the parsing
rules for a particular config file being sourced in if the parsing rules
are different!