view release on metacpan or  search on metacpan

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

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!

In fact, one of the test cases does just this!  (t/30-alt_symbols_cfg.t)

To load it into memory do:

   my $cfg = Advanced::config->new ("product-1.cfg",
                   { "assign => "::", "comment" => ";", "source" => "include" }
                                   )->load_config();


=item ENCRYPTING/DECRYPTING CONFIG FILES

Sometimes you need to protect sensitive information inside your config files.
Such as the user names and passwords that your application requires to run.
This module allows this at the individual tag/value pair level.  Not at the
file level!

The 1st example shows tags whose values are pending the encryption process.
While the 2nd example shows what happens after it's been encrypted.  You can
have config files that have both pending and encrypted tags in it.  As well
as tags whose values are never encrypted.  It is controlled by having the
appropriate label in the comment after the tag/value pair.

   # Waiting to encrypt these values ...
   my_username_1 = "anonymous"                   # ENCRYPT
   my_password_1 = "This is too much fun!"       # ENCRYPT me ...

   # They've already been encrypted!
   my_username_2 = '4aka54D3eZ4aea5'             # DECRYPT
   my_password_2 = '^M^Mn1\pmeaq>n\q?Z[x537z3A'  # DECRYPT me ...

   # This value will never be encrypted/decrypted ...
   dummy = "Just some strange value that is always in clear text."

The encrypted value is automatically decrypted for you when the config file
is loaded into memory.  So it's already in clear text when C<get_value()> is
called.  See L<Advanced::Config::Options> for more details on the options
used to control the encrypt/decrypt process.  See C<encrypt_config_file()> in
L<Advanced::Config> for how to encrypt the contents of the config file itself.

You can use C<decrypt_config_file()> to reverse the process if needed.

=item PLUS MUCH, MUCH, MORE ...

I could go on and on with many more examples.  I'll add more in the future as
I consider more significant issues to cover.  In the mean time you can find
many more examples from the build under:  I<t/config/*.cfg> 

=back

=head1 COPYRIGHT

Copyright (c) 2015 - 2026 Curtis Leach.  All rights reserved.

This program is free software.  You can redistribute it and/or modify it under
the same terms as Perl itself.

=head1 SEE ALSO

L<Advanced::Config::Options> - Covers the options that allow you to modify
how a config file gets parsed.  It defines the controls allowing the various
examples shown above.

L<Advanced::Config::Date> - Handles date parsing for get_date().

L<Advanced::Config::Reader> - Handles the parsing of the config file per the
options defined above.

L<Advanced::Config> - Defines the configuration object that you wish to
manipulate.

=cut