view release on metacpan or  search on metacpan

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

See I<The Read Options> section of L<Advanced::Config::Options> for what options
are available for customizing how your configuration files gets parsed.

While I<The Get Options> section covers options for looking up the value for
a given tag generated.

=head1 ENCRYPTING VALUES IN YOUR CONFIG FILE

This module has hooks to allow the encryption/decryption of values in your
config file.  It can do it in two levels.  Simple obscuring of the tag's value
or true encryption/decryption.  See L<Advanced::Config::Options> for more
details on how to do this.

=head1 CONFIG FILE EXAMPLES

=over 4

=item A VERY SIMPLE CONFIG FILE. (simple.cfg)

   # This is a comment

   tag1 = abc       # A simple assignment.

   # The balanced quotes will automatically be removed from the value ...
      tag2="efg"    # See we put surrounding quotes around the value.

   tag3 = 'l m n'   # The alternate quotes.

   tag4 = p q r     # See quotes are completely optional.

   tag5 = ${tag1}   # Performs variable substitution, same as: tag5 = "abc".

   tag1     =     xyz  # See I've overridden tag1's original value to "xyz".
   TAG1 = 123       # tag1 is still xyz, tags are case sensitive.

To load it into memory do:

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

=item A SLIGHTLY MORE COMPLEX CONFIG FILE.  (complex.cfg)

   # Merge in this config file.  Looks in the same directory as
   # this config file is in.  Not the program's current directory.
   . simple.cfg

   # Sourcing in another config file.  (contents not shown)
   # Offset is from the same directory this config file is in.
   # Not the program's current directory!
   . ../Alt-Config/relative.cfg

   # See I'm referencing variables defined in simple.cfg!
   tag1 = ${tag1} ${tag3} ${tag1}   # tag1 now equals: "xyz l m n xyz".

   tag 6 = abc = 7     # "tag 6" now contains:  "abc = 7".
   tag 6 = ${TAG1}     # "tag 6" is now:  123

   messy = "I have a # in my value"  # See comment symbol in the value.

   # A neat little trick ...
   # Implements:  a = $ENV{test} ? "TRUE" : "FALSE";
   a = ${test:+TRUE}   # Set to TRUE if $ENV{test} is set, else undef
   a = ${a:-FALSE}     # Set to FALSE if ${a} is undef, else set to ${a}.

   # 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