Advanced-Config
view release on metacpan or search on metacpan
# The Change Log for Advanced::Config
# The basic algorithm was initially an attempt to allow Perl and Unix shell
# scripts to share common configuration files. And it just grew with a life
# of it's own since then.
# --------------------------------------------------------------------
# Developer's Note:
# By default, fish is turned off. To turn it on do the following:
# 1) On Unix: export ADVANCED_CONFIG_FISH=1
# 2) On Windows: set ADVANCED_CONFIG_FISH=1
# This is done by most of the test cases that use this module.
# See the README files for more details on this.
#
# To turn fish back off, reset this variable to zero!
# --------------------------------------------------------------------
Version - YYYY/MM/DD
---------------------
$begin_special_vars{'0'} = ($0 eq "-e") ? "perl" : $0;
$begin_special_vars{'$'} = $$;
$begin_special_vars{'^O'} = $^O; # MSWin32, aix, etc ...
# ---------------------------------------------
# Start of the "rule 6" initialization ...
# ---------------------------------------------
$begin_special_vars{PID} = $$;
$begin_special_vars{user} = Advanced::Config::Options::_get_user_id ();
$begin_special_vars{hostname} = hostname ();
$begin_special_vars{flavor} = os_type (); # Windows, Unix, etc...
# ---------------------------------------------
# Get the Parent PID if available ... (PPID)
# ---------------------------------------------
eval {
$begin_special_vars{PPID} = getppid ();
};
if ( $@ ) {
DBUG_PRINT ("INFO", "Cheating to get the PPID. It may be wrong!");
# We can't easily get the parent process id for Windows.
# Then you need to turn on Fred::Fish::DBUG tracing used by Advanced::Config.
# This will generate the log file to attach to the CPAN ticket.
# -----------------------------------------------------------------------------
This module uses Fred::Fish::DBUG for logging the activity of this module.
But this logging is disabled by default, even if you are using Fred::Fish::DBUG
to trace your own code!
So here's a list of steps needed to turn this tracing on.
1) Set this special environment variable to 1. (tells my module to enable fish.)
a) Unix: export ADVANCED_CONFIG_FISH=1
b) Windows: set ADVANCED_CONFIG_FISH=1
c) You can also set this variable in your test program's BEGIN block:
$ENV{ADVANCED_CONFIG_FISH} = 1;
Just make sure your BEGIN block appears before you source in
Advanced::Config via: eval "use Advanced::Config";
2) In your code source in the Fred::Fish::DBUG module.
use Fred::Fish::DBUG;
3) Turn on fish logging at the start of your test program:
lib/Advanced/Config/Examples.pm view on Meta::CPAN
In many cases it's just easier to show an example instead of trying
to put things into words. So this module is just some POD text to document
what this module is expecting to load into memory as your config file.
Just be aware that it's possible to override many of the operators defined in
the config file. So for example the B<=> operator could be B<:=> and the
B<#> operator could have been B<CMT:>.
=head1 HISTORY
This module started out as a parser of unix shell script data files so that
shell scripts and perl programs could share the same config files. Hence the
support of shell script variables, quotes and the sourcing in of sub-files.
Allowing for limited logic in your config files.
From there it just grew to support non-unix features such as windows batch
files and more generic configuration features. Such as being able handle
various formatting of config files and the ability to obscure or encrypt values
from casual snooping. Or the addition of sections to allow the same config
file to be used on multiple servers and OS.
So today it's a powerful tool that turns your config files into objects your
perl code can reference and manipulate.
=head1 SURROUNDING A VALUE WITH QUOTES IN YOUR CONFIG FILE
lib/Advanced/Config/Options.pm view on Meta::CPAN
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.
lib/Advanced/Config/Options.pm view on Meta::CPAN
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
lib/Advanced/Config/Options.pm view on Meta::CPAN
# ==============================================================
# 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 ( @_ );
lib/Advanced/Config/Reader.pm view on Meta::CPAN
# ==============================================================
# No fish please ... (called way too often)
# This method is called in 2 ways:
# 1) By parse_line() to determine if ${ln} is a tag/value pair.
# 2) By everyone else to parse a known tag/value pair in ${ln}.
#
# ${ln} is in one of these 3 formats if it's a tag/value pair.
# tag = value
# export tag = value # Unix shell scripts
# set tag = value # Windows Batch files
sub _split_assign
{
my $rOpts = shift; # The read options ...
my $ln = shift; # The value to split ...
my $skip = shift; # Skip massaging the tag?
my ( $tag, $value );
if ( is_assign_spaces ( $rOpts ) ) {
lib/Advanced/Config/Reader.pm view on Meta::CPAN
If a line was too badly mangled to be parsed, it will be ignored and a warning
will be written to your screen.
It returns B<1> on success and B<0> on failure.
Please note that comments are just thrown away by this process and only
tag/value pairs remain afterwards. Everything else is just instructions to
the parser or how to group together these tag/value pairs.
If it sees something like: export tag = value, it will export tag's value
to the %ENV hash for you just like it does in a Unix shell script!
Additional modifiers can be found in the comments after a tag/value pair
as well.
=cut
# ==============================================================
sub read_config
{
DBUG_ENTER_FUNC ( @_ );
lib/Advanced/Config/Reader.pm view on Meta::CPAN
DBUG_PRINT ("LINE", "Last ditch effort to remove the comment from the line ...");
DBUG_RETURN ( $tv_pair_flag, $line, $cmts, "", "");
}
# ==============================================================
=item ($v[, $h]) = expand_variables ( $config, $string[, $file[, $sensitive[, trim]]] )
This function takes the provided I<$string> and expands any embedded variables
in this string similar to how it's handled by a Unix shell script.
The optional I<$file> tells which file the string was read in from.
The optional I<$sensitive> when set to a non-zero value is used to disable
B<fish> logging when it's turned on because the I<$string> being passed contains
sensitive information.
The optional I<$trim> tells if you may trim the results before it's returned.
It returns the new value $v, once all the variable substitution(s) have
t/config/13-alt-get-tests.cfg view on Meta::CPAN
file_2 = ${dir_2}${sep}10-simple.cfg
file_bad_1 = ${dir_1}${sep}no_such_file.txt # No such dir or file!
file_bad_2 = ${dir_2} # It's a directory, not a file!
file_list_1 = ${file_1} ${file_2} ${file_1}
file_list_2 = ${file_1} ${file_bad_1} ${file_2} ${file_bad_2}
# ----------------------------------------------------------------------
# Used in the Special file/directory tests ...
# ----------------------------------------------------------------------
special_1 = /dev/null # Unix special file/dir name
special_2 = NUL # Windows version of /dev/null
special_3 = ~ # Unix home dir.
special_4 = ~test # Unix home dir for user "test".
special_5 = ~/test # File/dir "test" under my home dir.
# ----------------------------------------------------------------------
# Used to test the get_date() & get_list_date() functions ...
# Format used for tag names: date_<test #>_<answer>
# ----------------------------------------------------------------------
date_000_bad = not a date
date_101_2017-12-25 = December 25th, 2017
date_102_2017-12-24 = December 24th 2017
( run in 1.294 second using v1.01-cache-2.11-cpan-df04353d9ac )