view release on metacpan or  search on metacpan

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

you can avoid global variables.  Defaults to an empty hash reference.

B<source_cb> - An optional callback routine called each time your config file
sources in another config file.  It's main use is when the I<Read Options>
and/or I<Date Format Options> required to parse each config file change between
files.  It's automatically called right before the sourced in file is opened up
for parsing.

Once the new file is sourced in, it inherits most of the options currently used
unless you override them.  The only ones not inherited deal with decryption.

Here is the callback function's expected definition:

  my ($rOpts, $dOpts) = source_callback_func ($file[, $cbOpts]);

  $file --> The file being sourced in.

  $cbOpts --> A hash reference containing values needed by your callback
              function to decide what options are required to source in the
              requested file.  You may update the contents of this hash to
              preserve info between calls.  This module will "never" examine
              the contents of this hash!

  $rOpts --> A reference to the "Read Options" hash used to parse the file
             you want to source in.  Returns "undef" if the options don't
             change.  The returned options override what's currently in use by
             "load_config" when loading the current file.

  $dOpts --> A reference to the "Date Formatting Options" hash used to tell how
             to format the special date variables.  Returns "undef" if the
             options don't change.  The returned options override what's
             currently in use by "load_config" when loading the current file.

=back

=head2 Parse Read Options

These options deal with how to parse the config file itself.  All values are
literal values.  No regular expressions are supported.  If you don't want to
allow a particular option to be supported in your config file, and there is
no disable option, feel free to set it to some unlikely long string of
characters that will never match anything in your config files.  Such as
"#"x100.  (A string of 100 #'s.)

=over 4

B<assign> - Defaults to B<=>.  You may use this option to override what string
of characters make up the assignment operator.  It's used to split a line
into a tag/value pair.  If you want the special case of no separator, IE the
first space separates a tag/value pair, try setting it to B<\\s> since the
interface doesn't allow whitespace as a value.

B<comment> - Defaults to B<#>.  This is the comment symbol used when parsing
your config file and everything after it is ignored in most cases.  The first
case is when it appears between balanced quotes as part of a tag's value, it's
not considered the start of a comment.  The other case is when you put one
of the labels in the comments to override default behavior.  (See next section)

B<source> - Defaults to "B<.>".  When followed by a file name, this is an
instruction to source in another config file (similar to how it works in a
I<Unix> shell script.)  Another common setting for this option is "include".

B<section_left> & B<section_right> - This pair is used to anchor breaking
your config file into multiple independent sections.  The defaults are B<[>
and B<]>.

B<variable_left> & B<variable_right> - This pair is used to anchor a variable
definition.  Any value between these anchors will be a variable name and it's
value will be used instead, unless you've disabled this expansion.  The defaults
are B<${> and B<}>.  If you override these anchors to both have the same value,
then the optional variable modifiers are not supported nor are nested variables.

B<quote_left> & B<quote_right> - This pair is used to define what balanced
quotes look like in your config file.  By default, it allows you to use either
B<"> or B<'> as a matching pair.  But if you override one of them you must
override both.  And in that case it can only be with literal values.  If the
quotes surrounding a tag's value are balanced, the quotes will be automatically
removed from the value.  If they are unbalanced the quotes will not be removed.

=cut

# B<backquote_left> & B<backquote_right> - This pair is used to surround a command
# you wish to run, just like in Perl itself.  What the command writes to STDOUT
# becomes the tag's value.  Assumes the command takes nothing from STDIN.  Due to
# security concerns you must explicitly set these values yourself before they are
# usable.  A good value is the backqoute itself (B<`>).  But use something else
# if you don't want to be so obvious about it.

=pod

=back

=head2 Modifiers in the trailing Comments for tag/value pairs.

In some cases we need to handle exceptions to the rule.  So we define labels
to tell this module that we need to apply special rules to this tag/value pair.
These labels may appear anywhere in the comment.  So when looking for "EXPORT",
it will match "B<# Please EXPORT me.>", but won't match "B<# EXPORTED>".  This
allows you to put multiple labels in a single comment if needed.

As long as the text is surrounded by white space or punctuation a match will
be found.  It is strongly recommended that you don't use punctuation in your
label when you override one with values of your own.

Here are the labels you may override.

=over 4

B<export_lbl> - Defaults to "B<EXPORT>".  Tells this module to export this
particular tag/value pair to perl's B<%ENV> hash.  If the I<export> option
was also set, it inverts the meaning of this label to mean don't export it!
You can also gain the same functionality by doing one of the following
instead:

    export tag = value    # Optional unix type shell script prefix.

    set tag = value       # Optional windows type batch file prefix.

These prefixes allow you to easily use shell/batch files as config files if
they contain no logic.

B<hide_lbl> - Defaults to "B<HIDE>".  Tells this module that this tag's value
contains sensitive information.  So when fish logging is turned on, this module
will never write it to these logs.  If the parser thinks a tag's name suggests
it's a password, it will assume that you put this label in the comment.  This
is what triggers the sensitive/mask arguments and return values that some
methods use.

B<encrypt_lbl> - Defaults to "B<ENCRYPT>".  Tells this module that you are
waiting for this tag's value to be encrypted in the config file.  It assumes
the value is still in clear text.  When present it assumes the value is
sensitive as well.

B<decrypt_lbl> - Defaults to "B<DECRYPT>".  Tells this module that this value
has already been encrypted and needs to be decrypted before it is used.  When
present it assumes that the value is sensitive as well.

B<source_file_section_lbl> - Defaults to "B<DEFAULT>".  Tells this module to
use the current section as the default/unlabeled section in the file being
source in.  This new value will be inherited should the sourced in file source
in any further files.

=back

=head2 Encryption/Decryption options.  (or Encode/Decode options.)

The following options deal with the encryption/decryption of the contents of a
config file.  Only the encryption of a tag's value is supported.  And this is
triggered by the appropriate label in the comment on the same line after the
value.

Unless you use the B<encrypt_cb> option, this module isn't using true
encryption.  It's more a complex obscuring of the tag's value making it very
difficult to retrieve a tag's value without using this module to examine the
config file's contents.  It's main use is to prevent casual browsers of your
file system from being able to examine your config files using their favorite
editor to capture sensitive data from your config files.

By default, the I<basename> of the config file's name and the tag's name are the
keys used to encode each value in the config file.  This means that each tag's
value in the config file uses a different key to obscure it.  But by using just
the defaults, anyone using this module may automatically decode everything in
the config file just by writing a perl program that uses this module.

But by using the options below, you gain additional security even without using
true encryption.  Since if you don't know the options used, you can't easily
decode each tag's value even by examining the code.  Just be aware that using
too many keys with too similar values could cancel each other out and weaken
the results.

These options are ignored if you've disabled decryption.

When you source in another file in your config files, the current values
for B<alias>, B<pass_phrase> and B<encrypt_by_user> are not inherited.  But the
remaining options are.  See option B<source_cb> if you need to set them in this

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

=head1 FUNCTIONS

As a reminder, there is no need to directly call any of the following functions.
They are documented mostly for the benefit of the developer who uses them to
implement the internals to L<Advanced::Config>.

Most of them are too specialized to be of much use to you.

=over 4

=cut 

package Advanced::Config::Options;

use strict;
use warnings;

use vars qw( @ISA @EXPORT @EXPORT_OK $VERSION );
use Exporter;

$VERSION = "1.14";
@ISA = qw( Exporter );

@EXPORT = qw( get_read_opts  get_get_opts  get_date_opts
              apply_get_rules
              is_assign_spaces
              using_default_quotes
              convert_to_regexp_string
              convert_to_regexp_modifier
              should_we_hide_sensitive_data
              make_it_sensitive
              sensitive_cnt
              croak_helper
              set_special_date_vars
              change_special_date_vars
            );

@EXPORT_OK = qw( );

use Advanced::Config::Date;
use Fred::Fish::DBUG 2.09 qw / on_if_set  ADVANCED_CONFIG_FISH /;

# The name of the default section ... (even if no sections are defined!)
use constant DEFAULT_SECTION_NAME => "main";    # Must be in lower case!

my %default_read_opts;
my %default_get_opts;
my %default_date_opts;
my @hide_from_fish;


# ==============================================================
# Get who you're currrently logged in as.
# Put here to avoid circular references between modules.
sub _get_user_id
{
   DBUG_ENTER_FUNC ( @_ );
   my $user = "??";
   eval {
      # Mostly used on unix like systms.
      $user = getpwuid ($<) || "??";
   };
   if ( $@ ) {
      # Can't use on unix due to sudo issue returns wrong user.
      $user = getlogin () || "??";
   }
   DBUG_RETURN ($user);
}

# ==============================================================
# A stub of the source callback function ...
sub _source_callback_stub
{
   DBUG_ENTER_FUNC ( @_ );
   my $file = shift;
   my $opts = shift;
   DBUG_RETURN ( undef, undef );
}


# ==============================================================
# A stub of the encryption/decryption callback function ...
sub _encryption_callback_stub
{
   DBUG_MASK_NEXT_FUNC_CALL (2);   # Mask $value!
   DBUG_ENTER_FUNC ( @_ );
   my $mode   = shift;
   my $tag    = shift;
   my $value  = shift;   # Clear text sensitive value ...
   my $file   = shift;
   my $cbOpts = shift;
   DBUG_MASK ( 0 );
   DBUG_RETURN ( $value );
}


# ==============================================================
# Initialize the global hashes with their default values ...
BEGIN
{
   DBUG_ENTER_FUNC ();

   # ---------------------------------------------------------------------
   # Make sure no hash value is undef !!!
   # ---------------------------------------------------------------------

   # You can only add to this list, you can't remove anything from it!
   # See should_we_hide_sensitive_data () on how this list is used.
   DBUG_PRINT ("INFO", "Initializing the tag patterns to hide from fish ...");
   push ( @hide_from_fish, "password" );
   push ( @hide_from_fish, "pass" );
   push ( @hide_from_fish, "pwd" );

   # ---------------------------------------------------------------------

   DBUG_PRINT ("INFO", "Initializing the READ options global hash ...");
   # Should always be set in the constructor ...
   $default_read_opts{tag_case}   = 0;         # Case sensitive tags.

   # The generic options ...
   my %src_empty;
   $default_read_opts{croak}      = 0;         # Don't croak by default.
   $default_read_opts{export}     = 0;         # Don't export any tag/val pairs.
   $default_read_opts{use_utf8}   = 0;         # Doesn't support utf8/Unicode/Wide Chars.