view release on metacpan or  search on metacpan

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

###
###  Copyright (c) 2007 - 2026 Curtis Leach.  All rights reserved.
###
###  Module: Advanced::Config::Options

=head1 NAME

Advanced::Config::Options - Options manager for L<Advanced::Config>.

=head1 SYNOPSIS

 use Advanced::Config::Options;
 or 
 require Advanced::Config::Options;

=head1 DESCRIPTION

F<Advanced::Config::Options> is a helper module to L<Advanced::Config>.  So it
should be very rare to directly call any methods defined by this module.

It's main job is to help manage the settings of the B<Read>, B<Get> and B<Date>
options hashes.  It was implemented as a separate module to make it simpler to
document the various supported options without cluttering up the POD of the main
module.  So you are not expected to ever call any of these methods yourself.
It's here mainly as an FYI.

If you don't specify the options below, this module will assume you wish to use
the default behavior for that option.  So only override what you need to.
Also all options are in lower case.  But you may provide them in mixed case if
you wish.  This module will auto downshift them for you.

If an option is misspelled, or you don't provide a valid value, a warning will
be written to the screen and that option will be ignored.

=head1 ==================================================================

=head2 Z<>

=head1 The Read Options

In most cases the defaults should do nicely for you.  But when you share config
files between applications, you may not have any control over the config file's
format.  This may also apply if your organization requires a specific format
for its config files.

So this section deals with the options you can use to override how it parses and
interprets the config file when it is loaded into memory.  None of these options
below allows leading or trailing spaces in the option's value.  And if any are
found, they will be automatically trimmed off before their value is used.
Internal spaces are OK when non-numeric values are expected.  In most cases
values with a length of B<0> or B<undef> are not allowed.

Just be aware that some combinations of I<Read> options may result in this
module being unable to parse the config file.  If you encounter such a
combination open a CPAN ticket and I'll see what I can do about it.  But some
combinations may just be too ambiguous to handle.

Also note that some I<Read> options have B<left> and B<right> variants.  These
options are used in pairs and both must anchor the target in order for the rule
to be applied to it.  These start/end anchors can be set to the same string or
different strings.  Your choice.

=head2 Tag(s) Best Set in Call to the Constructor new().

While not required to set these options during the call to B<new>, changing
their settings later on can cause unexpected issues if you are not careful.

But it's still recommended that most I<Read> Options be set during the call to
B<new> to avoid having to keep on resetting them all the time and limit these
later changes to handle exceptions to your defaults.

=over 4

B<tag_case> - Config files are made up of tag/value pairs.  This option controls
whether the tags are case sensitive (B<0>, the default) or case insensitive
(B<1>).  IE do tags B<ABC> and B<abc> represent the same tag or not?  So if set,
all tags are assumed to be in lower case for the get/set methods!

=back

=head2 Generic Read Options

These options are also usually set during the call to B<new>, but setting them
later on doesn't produce strange behavior if you change the settings later on.

=over 4

B<croak> - This controls what happens when a function hits an unexpected error
while parsing the config file.  Set to B<0> to return an error code (default),
B<-1> to return an error code and print a warning to your screen, B<1> to call
die and terminate your program.

B<export> - Tells if we should export all tag/value pairs to perl's %ENV hash
or not.  The default is B<0> for I<No>.  Set to B<1> if you want this to happen.
But if set, it reverses the meaning of the B<export_lbl> option defined later
on.

B<use_utf8> - Defaults to B<0>.  Set to B<1> if the config file was created
using utf8 encoding.  (IE Unicode or Wide Characters.)  Guessing this
setting wrong means the file will be unusable as a config file.

B<disable_quotes> - Defaults to B<0>.  Set to B<1> if you want to disallow
the stripping of balanced quotes in your config files.

B<disable_variables> - Defaults to B<0>.  Set to B<1> if you want to disable
variable expansion in your config files when they are loaded into memory.

B<disable_variable_modifiers> - Defaults to B<0>.  Set to B<1> if you want to
disable this feature.  See L<http://wiki.bash-hackers.org/syntax/pe> for more
details.  This feature allows you to put logic into your config files via
your variable definitions.  Automatically disabled when variables are