Advanced-Config
view release on metacpan or search on metacpan
lib/Advanced/Config/Options.pm view on Meta::CPAN
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
disabled. Useful when you put a lot of special chars into your variable
names.
B<disable_decryption> - Defaults to B<0>. Set to B<1> if you want to disable
decrypting values that have been marked as encrypted. If a variable references
an encrypted value while disable_decription is active, that variable isn't
expanded.
=cut
# B<enable_backquotes> - Defaults to B<0>. Set to B<1> if you want to enable
# this feature. It's disabled by default since it can be considered a security
# hole if an unauthorized user can modify your config file or your code.
=pod
B<trap_recursion> - Defaults to B<0>. Set to B<1> if you want to treat
recursion as a fatal error when loading a config file. By default it just
ignores the recursion request to prevent infinite loops.
B<source_cb_opts> - A work area for holding values between calls to the
callback function. This is expected to be a hash reference to provide any
needed configuration values needed to parse the next config file. This way
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".
lib/Advanced/Config/Options.pm view on Meta::CPAN
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
case.
=over 4
B<alias> - Defaults to the empty string. (Meaning no alias provided.) This
option is used to override using the file's I<basename> as one of the
encryption/decryption keys with the I<basename> of the value you provide here.
If you encrypt a file with no I<alias>, and then rename the config file, you
must set the I<alias> to the original filename to be able to decrypt anything.
If you encrypt a file with an I<alias>, you must use the same I<alias> to
decrypt things again.
If your config file is a symbolic link to another name, it will auto set this
option for you using the file's real name as the alias if you don't override
it by setting the alias yourself.
B<pass_phrase> - Defaults to the empty string. If you used a pass phrase to
encrypt the value, then you need to use the same pass phrase again when
decrypting each tag's value.
B<inherit_pass_phrase> - Defaults to 0 (no). Set to 1 if you want to use the
same B<pass_pharase> when you source in a sub-file in your config files.
B<encrypt_by_user> - Defaults to 0 (no). Set to 1 if you want use the user
name you are running the program under as part of the encryption key. So only
the user who encrypted the file can decrypt it.
B<encrypt_cb_opts> - A work area for holding values between calls to the
callback function. This is expected to be a hash reference to provide any
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.
lib/Advanced/Config/Options.pm view on Meta::CPAN
@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.
$default_read_opts{disable_quotes} = 0; # Don't disable balanced quotes.
$default_read_opts{disable_variables} = 0; # Don't disable variables!
$default_read_opts{disable_variable_modifiers} = 0; # Don't disable variable modifiers!
$default_read_opts{disable_decryption} = 0; # Don't disable decryption!
# $default_read_opts{enable_backquotes} = 0; # Don't allow random command execution.
$default_read_opts{trap_recursion} = 0; # Recursion is ignored, not fatal
$default_read_opts{source_cb} = __PACKAGE__->can ("_source_callback_stub");
$default_read_opts{source_cb_opts} = \%src_empty;
# The file parsing options ...
$default_read_opts{assign} = '='; # The assignment operator
$default_read_opts{comment} = '#'; # The comment symbol
$default_read_opts{source} = '.'; # The file source symbol
$default_read_opts{section_left} = '['; # The start section string
$default_read_opts{section_right} = ']'; # The end section string
$default_read_opts{variable_left} = '${'; # The start variable string
$default_read_opts{variable_right} = '}'; # The end variable string
# Unlikely default values due to security concerns.
# $default_read_opts{backquote_left} = '`'x101; # The start backquote string
# $default_read_opts{backquote_right} = '`'x102; # The end backquote string
# The quote chars ... (Special case doesn't work for anything else.)
# See using_default_quotes() if this changes ...
$default_read_opts{quote_left} = $default_read_opts{quote_right} = "['\"]";
# The tag/value modifiers. These labels are found inside the comments!
$default_read_opts{export_lbl} = "EXPORT"; # Label for a single %ENV.
$default_read_opts{hide_lbl} = "HIDE"; # Mark as sensitive.
$default_read_opts{encrypt_lbl} = "ENCRYPT"; # Pending encryption.
$default_read_opts{decrypt_lbl} = "DECRYPT"; # Already encrypted.
$default_read_opts{source_file_section_lbl} = "DEFAULT"; # Override default.
# The Encrypt/Decrypt options ... (Encode/Decode)
my %empty_encrypt;
$default_read_opts{alias} = "";
$default_read_opts{pass_phrase} = "";
$default_read_opts{inherit_pass_phrase} = 0;
$default_read_opts{encrypt_by_user} = 0;
$default_read_opts{encrypt_cb} = __PACKAGE__->can ("_encryption_callback_stub");
$default_read_opts{encrypt_cb_opts} = \%empty_encrypt;
# Special undocumented test prog option for overriding fish in parse_line().
$default_read_opts{dbug_test_use_case_parse_override} = 0; # Always off.
# Special undocumented test prog option for overriding fish in read_config().
$default_read_opts{dbug_test_use_case_hide_override} = 0; # Always off.
# ---------------------------------------------------------------------
DBUG_PRINT ("INFO", "Initializing the GET options global hash ...");
# Should always be set in the constructor ...
$default_get_opts{inherit} = 0; # Can inherit from the parent section.
# The generic options ... Who cares where set!
$default_get_opts{required} = 0; # Return undef by default.
$default_get_opts{vcase} = 0; # Case of the value. (0 = as is)
$default_get_opts{split_pattern} = qr /\s+/; # Space separated lists.
# Used in parsing dates for get_date() ...
$default_get_opts{date_language} = "English"; # The language to use in parsing dates.
$default_get_opts{date_language_warn} = 0; # Disable warnings in Date.pm.
$default_get_opts{date_dl_conversion} = 0; # 1-Enable 0-Disable using Date::Language for parsing.
$default_get_opts{date_enable_yy} = 0; # 1-Enable 0-Disable using 2 digit years in a date!
$default_get_opts{date_format} = 3; # Hints are 0 to 8.
# These special case options not to show up in the POD ...
# All associated with special "get_*()" functions that will auto set if needed.
$default_get_opts{numeric} = 0; # 0-no, 1-integer (truncate), 2-integer (round), 3-real.
$default_get_opts{auto_true} = 0; # Don't return as boolean.
$default_get_opts{filename} = 0; # Tag doesn't do a file test.
$default_get_opts{directory} = 0; # Tag doesn't do a directory test.
$default_get_opts{split} = 0; # Don't split the value.
$default_get_opts{sort} = 0; # Don't sort the split value. (1 - sort, -1 - reverse sort)
$default_get_opts{date_active} = 0; # 0-No, 1-Yes expecing it to be a date.
# ---------------------------------------------------------------------
DBUG_PRINT ("INFO", "Initializing the DATE formatting options global hash ...");
$default_date_opts{date_order} = 0; # 0 - YMD, 1 - MDY, 2 - DMY
$default_date_opts{date_sep} = "-"; # Separator to format dates with.
$default_date_opts{month_type} = 0; # 0 - numeric, 1 - abbreviate, 2 - full.
$default_date_opts{month_language} = "English"; # See Date::Language.
$default_date_opts{use_gmt} = 0; # 0 - localtime, 1 - gmtime.
# $default_date_opts{timestamp} = ?; # Special case can't set directly.
# ---------------------------------------------------------------------
DBUG_VOID_RETURN ();
}
# ==============================================================
# A private helper method ... (not exported)
sub _get_opt_base
{
DBUG_ENTER_FUNC ( @_ );
my $user_opts = shift;
my $defaults = shift; # Which default hash to validate against ...
# Make own copy of the defaults hash ...
my %result = %{$defaults};
# Must warn about invalid key values ...
foreach ( sort keys %{$user_opts} ) {
my $k = lc ($_);
my $val = $user_opts->{$_};
unless ( exists $defaults->{$k} ) {
warn "Unknown option '$k'. Option ignored.\n";
next;
}
# -------------------------------------
# Trim it to make sure it's valid ...
# -------------------------------------
my $no_spaces_allowed = 1;
if ( defined $val ) {
if ( $k eq "date_sep" ) {
$no_spaces_allowed = 0;
} else {
$val =~ s/^\s+//;
$val =~ s/\s+$//;
}
} else {
if ( defined $defaults->{$k} ) {
warn "Option '$k' has no defined value. Override ignored.\n";
} else {
$result{$k} = undef;
}
next;
}
# Making sure never undef for easier comparisons later on ...
my $expect = ( defined $defaults->{$k} ) ? $defaults->{$k} : "";
# -------------------------------------
# Is this a call back reference ...
( run in 2.918 seconds using v1.01-cache-2.11-cpan-39bf76dae61 )