view release on metacpan or  search on metacpan

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

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

package Advanced::Config::Examples;

use strict;
use warnings;

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

use Fred::Fish::DBUG 2.09  qw / on_if_set  ADVANCED_CONFIG_FISH /;

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


# Required if module is included w/ require command;
1;

# =============================================================================
# Only POD text appears below this line!
# =============================================================================

=head1 NAME

Advanced::Config::Examples - Defines sample config files supported by this
module.  Sourcing this module in does nothing for you.

=head1 SYNOPSIS

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

If you surround a value with balanced quotes, those quotes are automatically
removed before that value is assigned to it's tag.  Quotes are supported mostly
for readability and as a way to allow comment symbols in your value.  Or a way
to force leading and trailing spaces to your value.  Where without quotes those
spaces are stripped off.

=head1 VARIABLE SUBSTITUTIONS

All config files support variable substitution.  A variable can be any B<tag>
that appears above it in the config file.  If not defined there, it will check
if it's defined as an environment variable in the B<%ENV> hash instead.  If
still not found it will check for several predefined special variables for this
module.  If it can't find a variable it's value is always the empty string.

By default variables are in the format of B<${>...B<}>.  Where ... is your
variable's name and the B<${> & B<}> strings are the default surrounding anchors
that define it as a variable.

For more on this see the following link on Parameter Expansion:
L<https://web.archive.org/web/20200309072646/https://wiki.bash-hackers.org/syntax/pe>
This module supports most of the parameter expansions listed in the link except
for those dealing with arrays.  Other modifier rules may be added upon request.

Things get a bit more complex evaluating variables if you've defined sections
in your config file.

See the POD for B<lookup_one_variable>() in L<Advanced::Config> for step by step
instructions on expanding a variable's name.

For a list of special variables try calling:
S<Advanced::Config-E<gt>print_special_vars();>

=head1 SOURCING IN OTHER CONFIG FILES

It's possible to source multiple config files together as if they were one big
config file.  You can either use absolute paths to each config file, or more
likely relative paths.

Sourcing in sub-config files using relative paths works a little different than
you might expect.  It's the relative path from the location of the config file
doing the sourcing, not the current directory your program is running in.

This way the writer of the config file, not the programmer, controls which
config file gets sourced in.  Of course the config file writer can give control
back to the programmer by using variables as part of the name of the config