view release on metacpan or  search on metacpan

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

values needed by your encryption efforts.  So you can avoid global variables
and having to figure out the correct context of the call.  Defaults to an empty
hash reference.

B<encrypt_cb> - An optional callback function to provide hooks for B<true
encryption> or an additional layer of masking.  It defaults to no callback
function used.  This callback function is called in addition to any obscuring
work done by this module.

Here is the callback function's expected definition:

  my $new_value = encrypt_callback_func ($mode, $tag, $value, $file[, $cbOpts]);

     $mode  ==> 1 - Encrypt this value, 0 - Decrypt this value.

     $tag   ==> The name of the tag whose value is being encrypted/decrypted.

     $value ==> The value to encrypt/decrypt.

     $file  ==> The basename of the file the tag/value pair came from.  If the
                "alias" option was used, the basename of that "alias" is
                passed as "$file" instead.

     $cbOpts ==> A hash reference containing values needed by your function to
                 do it's custom encrypt/decrypt duties.  You may update the
                 contents of this hash to preserve info between calls.  This
                 module will "never" examine the contents of this hash!

=back

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

=head2 Z<>

=head1 The Get Options

This section deals with the options you can use to override how the I<B<get>>
methods behave when you try to access the values for individual tags.  None
of the options below allows leading or trailing spaces in it's value.  If any
are found, they will be automatically trimmed off before their value is used.
Internal spaces are OK.

These options can be set as global defaults via the call to the constructor,
B<new()>, or for individual B<get_...> calls if you don't like the defaults
for individual calls.

But it is strongly recommended that the B<inherit> option only be set in the
constructor and not changed elsewhere.  Changing its value between calls can
cause strange behavior if you do so.  Since it globally affects how this
module locates the requested tag and affects variable lookups when the
config file is parsed.

After that, where to set the other options is more a personal choice than
anything else.

=over 4

B<inherit> - Defaults to B<0> where each section is independent, the tag either
exists or it doesn't in the section.  Set to B<1> if each section should be
considered an override for what's in the main section.  IE if tag "abc" doesn't
exist in the current section, it next looks in the main section for it.

B<required> - This controls what happens when the requested tag doesn't exist
in your I<Advanced::Config> object.  Set to B<0> to return B<undef> (default),
B<-1> to return B<undef> and write a warning to your screen, B<1> to call
die and terminate your program.

B<vcase> - Controls what case to force all values to.  Defaults to B<0> which
says to preserve the case as entered in the config file.  Use B<1> to convert
everything to upper case.  Use B<-1> to convert everything to lower case.

B<split_pattern> - Defaults to B<qr /\s+/>.  The pattern to use when splitting
a tag's value into an array via perl's C<split> function.  It can be a string
or a regular expression.  For example to split on a comma separated string
you could do:  B<qr /\s*,\s*/>.

B<date_language> - Defaults to I<English>.  Tells what language I<get_date()>
should use when converting the date into a standard format.  Can be almost any
language supported by I<Date::Language>.

B<date_language_warn> - Defaults to B<0> (no). Should I<Advanced::Config::Date>
methods print out warnings?

B<date_enable_yy> - Defaults to B<0> (no). When parsing dates, should we
enable recognizing two digit years as valid?

B<date_format> - Numeric dates are inherently ambiguous so hints are required
in order to eliminate ambiguities.  For example is 01/02/03 I<Jan 2, 2003> (USA)
or I<Feb 1, 2003> (European) or even I<Feb 3, 2001> (ISO).  To a lesser extent
this is also true when you use 4-digit years.  So this option was added for
you to provide parsing hints on the order to try out.

      0 - ISO only
      1 - USA only
      2 - European only
      3 - ISO, USA, European  (default)
      4 - ISO, European, USA
      5 - USA, European, ISO
      6 - USA, ISO, European
      7 - European, USA, ISO
      8 - European, ISO, USA
If you provide an invalid choice, it will assume the default format.

B<date_dl_conversion> - Defaults to B<0> (no).  When parsing dates, should we
be using L<Date::Language>, if it's installed, for additional parsing of dates
if nothing else works?

There are many other I<Get Options> not exposed in the POD.  They are only set
via the specialized B<get_...> functions.  So they are not documented here.

=back

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

=head2 Z<>

=head1 The Special Date Variable Formatting Options

This module allows for special predefined date related variables for use in your
config files.  These options deal with how to format these dates when these
variables are referenced.  These formatting rules apply to all of the special