NAME

Advanced::Config - Perl module reads configuation files from various sources.

SYNOPSIS

use Advanced::Config;
   or 
require Advanced::Config;

DESCRIPTION

Advanced::Config is an enhanced implementation of a config file manager that allows you to manage almost any config file as a true object with a common interface. It allows you to configure for almost any look and feel inside your config files.

You will need to create one object per configuration file that you wish to manipulate. And any updates you make to the object in memory will not make it back into the config file itself.

It also has options for detecting if the data in the config file has been updated since you loaded it into memory and allows you to refresh the configuration object. So that your long running programs never have to execute against stale configuration data.

This module supports config file features such as variable substitution, sourcing in other config files, comments, breaking your configuration data up into sections, encryping/decrypting individual tag values, and even more ...

So feel free to experiment with this module on the best way to access your data in your config files. And never have to worry about having multiple versions of your config files again for Production vs Development vs QA vs different OS, etc.

NOTES ON FUNCTIONS WITH MULTIPLE RETURN VALUES

Whenever a function in this module or one if it's helper modules says it can have multiple return values and you ask for them in scalar mode, it only returns the first return value. The other return values are tossed. Not the count of return values as some might expect.

This is because in most cases these secondary return values only have meaning in specical cases. So usually there's no need to grab them unless you plan on using them.

For a list of the related helper modules see the SEE ALSO section at the end of this POD. These helper modules are not intended for general use.

CONSTRUCTORS

To use this module, you must call new() to create the Advanced::Config object you wish to work with. All it does is create an empty object for you to reference and returns the Advanced::Config object created. Once you have this object reference you are good to go! You can either load an existing config file into memory or dynamically build your own virtual config file or even do a mixure of both!

$cfg = Advanced::Config->new( [$filename[, \%read_opts[, \%get_opts[, \%date_opts]]]] );

It takes four arguments, any of which can be omitted or undef during object creation!

$filename is the optional name of the config file to read in. It can be a relative path. The absolute path to it will be calcuated for you if a relative path was given.

\%read_opts is an optional hash reference that controls the default parsing of the config file as it's being read into memory. Feel free to leave as undef if you're satisfied with this module's default behaviour.

\%get_opts is an optional hash reference that defines the default behaviour when this module looks something up in the config file. Feel free to leave as undef if you're satisfied with this module's default behaviour.

\%date_opts is an optional hash reference that defines the default formatting of the special date variables. Feel free to leave as undef if you're satisfied with the default formatting rules.

See the POD under Advanced::Config::Options for more details on what options these hash references support! Look under the The Read Options, The Get Options, and The Date Formatting Options sections of the POD.

It returns the Advanced::Config object created.

Here's a few examples:

# Sets up an empty object.
$cfg = Advanced::Config->new();

# Just specifies the config file to use ...
$cfg = Advanced::Config->new("MyFile.cfg");

# Overrides some of the default featurs of the module ...
$cfg = Advanced::Config->new("MyFile.cfg",
                             { "assign" => ":=", "comment" => ";" },
                             { "required" => 1 },
                             { "date_language" => "German" } );

THE METHODS

Once you have your Advanced::Config object initialized, you can manipulate your obect in many ways. You can access individual components of your config file, modify it's contents, refresh it's contents and even organize it in different ways.

Here are your exposed methods to help with this manipulation.

Loading the Config file into memory.

These methods are used to initialize the contents of an Advanced::Config object.

$cfg = $cfg->load_config ( [$filename[, %override_read_opts]] );

This method reads the current $filename into memory and converts it into an object so that you may refrence it's contents. The $filename must be defined either here or in the call to new().

Each time you call this method, it wipes the contents of the object and starts you from a clean slate again. Making it safe to call multiple times if needed.

The %override_read_opts options apply just to the current call to load_config and will be forgotten afterwards. If you want these options to persist between calls, set the option via the call to new(). This argument can be passed either by value or by reference. Either way will work. See Advanced::Config::Options for more details.

On success, it returns a reference to itself so that it can be initialized separately or as a single unit.

Ex: $cfg = Advanced::Config->new(...)->load_config (...);

On failure it returns undef or calls die if option croak is set!

WARNING: If basename($filename) is a symbolic link and your config file contains encrypted data, please review the encryption options about special considerations.

$cfg = $cfg->load_string ( $string[, %override_read_opts] );

This method takes the passed $string and treats it's value as the contents of a config file. Modifying the $string afterwards will not affect things. You can use this as an alternative to load_config.

Each time you call this method, it wipes the contents of the object and starts you from a clean slate again. Making it safe to call multiple times if needed.

The %override_read_opts options apply just to the current call to load_string and will be forgotten afterwards. If you want these options to persist between calls, set the option via the call to new(). This argument can be passed either by value or by reference. Either way will work. See Advanced::Config::Options for more details.

If you plan on decrypting any values in the string, you must use the alias option in order for them to be successfully decrypted.

On success, it returns a reference to itself so that it can be initialized separately or as a single unit.

$boolean = $cfg->merge_config ( $filename[, %override_read_opts] );

Provides a way to merge multiple config files into a single Advanced::Config object. Useful when the main config file can't source in the passed config file due to different %read_opts settings, or when a shared config file can't be modified to source in a sub-config file, or if for some reason you can't use the source_cb Read Option during the initial load.

Be aware that any tags in common with what's in this file will override the tag/value pairs from any previous calls to load_config or merge_config. You may also reference any tags in the previous loads as variables during this load. And if you have sections in common, it will merge each section's tag/value pairs as well.

Just be aware that %override_read_opts is overriding the default options set during the call to new, not necessarily the same options being used by load_config. See Advanced::Config::Options for more details on what options are available.

And finally if $filename is a relative path, it's relative to the current directory, not relative to the location of the config file its being merged into.

Returns 1 if the config file was loaded and merged. Else 0.

$boolean = $cfg->merge_string ( $string[, %override_read_opts] );

Provides a way to merge multiple strings into a single Advanced::Config object. Modifying the $string afterwards will not affect this object.

Be aware that any tags in common with what's in this string will override the tag/value pairs from any previous calls to load things into this object.

Just be aware that %override_read_opts is overriding the default options set during the call to new, not necessarily the same options being used by load_config or load_string. See Advanced::Config::Options for more details on what options are available.

Returns 1 if the string was merged into the object. Else 0.

$boolean = $cfg->refresh_config ( %refresh_opts );

This boolean function detects if your config file or one of it's dependancies has been updated. If your config file sources in other config files, those config files are checked for changes as well.

These changes could be to the config file itself or to any referenced variables in your config file whose value has changed.

If it detects any updates, then it will reload the config file into memory, tossing any customizations you may have added via calls to set_value(). It will keep the current Read options unchanged.

Supported Refresh Options Are:

"test_only => 1" - It will skip the reloading of the config file even if it detects something changed. And just tell you if it detected any changes.

"force => 1" - It will assume you know better and that something was updated. It will almost always return true (1) when used.

It returns true (1) if any updates were detected or the force option was used. It will return false (0) otherwise.

It will also return false (0) if you never called load_conifg() or load_string() against this configuration object. In which case there is nothing to refresh.

Accessing the contents of an Advanced::Config object.

These methods allow you to access the data loaded into this object.

They all look in the current section for the tag and if the tag couldn't be found in this section and the inherit option was also set, it will then look in the parent/main section for the tag. But if the inherit option wasn't set it wouldn't look there.

If the requested tag couldn't be found, they return undef. But if the required option was used, it may call die instead!

But normally they just return the requested tag's value.

They all use %override_get_opts, passed by value or by reference, as an optional argument that overrides the default options provided in the call to new(). The inherit and required options discussed above are two such options. In most cases this hash argument isn't needed. So leave it off if you are happy with the current defaults!

See the POD under Advanced::Config::Options, The Get Options for more details on what options you may override.

Only the get_value function was truly needed. But the other get methods were added for a couple of reasons. First to make it clear in your code what type of value is being returned and provide the ability to do validation of the tag's value without having to validate it yourself! Another benifit was that it drastically reduced the number of exposed Get Options needed for this module. Making it easier to use.

Finally when these extra methods apply their validation, if the tag's value fails the test, it treats it as a tag not found situation as described above.

$value = $cfg->get_value ( $tag[, %override_get_opts] );

This function looks up the requested tag's value and returns it. See common details above.

$value = $cfg->get_integer ( $tag[, $rt_flag[, %override_get_opts]] );

This function looks up the requested tag's value and returns it if its an integer. If the tag's value is a floating point number (ex 3.6), then the value is either truncated or rounded up based on the setting of the rt_flag.

If rt_flag is set, it will perform truncation, so 3.6 becomes 3. If the flag is undef or zero, it does rounding, so 3.6 becomes 4. Meaning the default is rounding.

Otherwise if the tag doesn't exist or its value is not numeric it will return undef unless it's been marked as required. In that case die may be called instead.

$value = $cfg->get_numeric ( $tag[, %override_get_opts] );

This function looks up the requested tag's value and returns it if its value is numeric. Which means any valid integer or floating point number!

If the tag doesn't exist or its value is not numeric it will return undef unless it's been marked as required. In that case die may be called instead.

$value = $cfg->get_boolean ( $tag[, %override_get_opts] );

Treats the tag's value as a boolean value and returns undef, 0 or 1.

Sometimes you just want to allow for basically a true/false answer without having to force a particualar usage in the config file. This function converts the tag's value accoringly.

So it handles pairs like: Yes/No, True/False, Good/Bad, Y/N, T/F, G/B, 1/0, On/Off, etc. and converts them into a boolean value. This test is case insensitive. It never returns what's actually in the config file.

If it doesn't recognize something it always returns 0.

$date = $cfg->get_date ( $tag[, $language[, %override_get_opts]] );

This function looks up the requested tag's value and returns it if its value contains a valid date. The returned value will always be in YYYY-MM-DD format no matter what format or language was actually used in the config file for the date.

If the tag doesn't exist or its value is not a date it will return undef unless it's been marked as required. In that case die may be called instead.

If $language is undefined, it will use the default language defined in the call to new for parsing the date. (English if not overriden.) Otherwise it must be a valid language defined by Date::Language. If it's a wrong or bad language, your date might not be recognized as valid.

Unlike most other get options, when parsing the tag's value, it's not looking to match the entire string. It's looking for a date portion inside the value and ignores any miscellanious information. There was just too many semi-valid potential surrounding data to worry about parsing that info as well.

So Tues "January 3rd, 2017" at 6:00 PM returns "2017-01-03".

There are also a few date related options for %override_get_opts to use that you may find useful.

See Advanced::Config::Date for more details.

$value = $cfg->get_filename ( $tag[, $access[, %override_get_opts]] );

Treats the tag's value as a filename. If the referenced file doesn't exist it returns undef instead, as if the tag didn't exist.

access defines the minimum access required. If that minimum access isn't met it returns undef instead, as if the tag didn't exist. access may be undef to just check for existance.

The access levels are r for read, w for write and x for execute. You may also combine them if you wish in any order. Ex: rw, xwr, rx ...

$value = $cfg->get_directory ( $tag[, $access[, %override_get_opts]] );

Treats the tag's value as a directory. If the referenced directory doesn't exist it returns undef instead, as if the tag didn't exist.

access defines the minimum access required. If that minimum access isn't met it returns undef instead, as if the tag didn't exist. access may be undef to just check for existance.

The access levels are r for read and w for write. You may also combine them if you wish in any order. Ex: rw or wr.

Accessing the contents of an Advanced::Config object in LIST mode.

These methods allow you to access the data loaded into each tag in list mode. Splitting the tag's data up into arrays and hashes. Otherwise these functions behave similarly to the one's above.

Each function asks for a pattern used to split the tag's value into an array of values. If the pattern is undef it will use the default split_pattern specified during he call to new(). Otherwise it can be either a string or a RegEx. See Perl's split function for more details. After the value has been split, it will perform any requested validation and most functions will return undef if even one element in the list fails it's edits. It was added as its own arguement, instad of just relying on the override option hash, since this option is probably the one that gets overidden most often.

They also support the same inherit and required options described for the scalar functions as well.

They also all allow %override_get_opts, passed by value or by reference, as an optional argument that overrides the default options provided in the call to new(). If you should use both option split_pattern and the pattern argument, the pattern argument takes precedence. So leave this optional hash argument off if you are happy with the current defaults.

$array_ref = $cfg->get_list_values ( $tag[, $pattern[, $sort[, %override_get_opts ]]] );

This function looks up the requested tag's value and then splits it up into an array and returns a reference to it.

If sort is 1 it does an ascending sort. If sort is -1, it will do a descending sort instead. By default it will do no sort.

See the common section above for more details.

$hash_ref = $cfg->get_hash_values ( $tag[, $pattern[, $value[, \%merge[, %override_get_opts]]]] );

This method is a bit more complex than get_list_values. Like that method it splits up the tag's value into an array. But it then converts that array into the keys of a hash whose value for each entry is set to value.

Then if the optional merge hash reference was provided, and that key isn't present in that hash, it adds the missing value to the merge hash. It never overrides any existing entries in the merge hash!

It always returns the hash reference based on the tag's split value or an empty hash if the tag doesn't exist or has no value.

$array_ref = $cfg->get_list_integer ( $tag[, $rt_flag[, $pattern[, $sort[, %override_get_opts]]]] );

This is the list version of get_integer. See that function for the meaning of $rt_flag. See get_list_values for the meaning of $pattern and $sort.

$array_ref = $cfg->get_list_numeric ( $tag[, $pattern[, $sort[, %override_get_opts]]] );

This is the list version of get_numeric. See get_list_values for the meaning of $pattern and $sort.

$array_ref = $cfg->get_list_boolean ( $tag[, $pattern[, %override_get_opts]] );

This is the list version of get_boolean. See get_list_values for the meaning of $pattern.

$array_ref = $cfg->get_list_date ( $tag, $pattern[, $language[, %override_get_opts]] );

This is the list version of get_date. See get_list_values for the meaning of $pattern. In this case $pattern is a required option since dates bring unique parsing challenges and the default value usually isn't good enough.

$array_ref = $cfg->get_list_filename ( $tag[, $access[, $pattern[, %override_get_opts]]] );

This is the list version of get_filename. See that function for the meaning of $access. See get_list_values for the meaning of $pattern.

$array_ref = $cfg->get_list_directory ( $tag[, $access[, $pattern[, %override_get_opts]]] );

This is the list version of get_directory. See that function for the meaning of $access. See get_list_values for the meaning of $pattern.

Manipulating the contents of an Advanced::Config object.

These methods allow you to manipulate the contents of an Advanced::Config object in many ways. They all just update what's in memory and not the contents of the config file itself.

So should the contents of this module get refreshed, you will loose any changes made by these 4 methods.

$ok = $cfg->set_value ( $tag, $value );

Adds the requested $tag and it's $value to the current section in the Advanced::Config object.

If the $tag already exists, it will be overriden with it's new $value.

It returns 1 on success or 0 if your request was rejected! It will also print a warning if it was rejected.

$bool = $cfg->rename_tag ( $old_tag, $new_tag );

Renames the tag found in the current section to it's new name. If the $new_tag already exists it is overwritting by $old_tag. If $old_tag doesn't exist the rename fails.

Returns 1 on success, 0 on failure.

$bool = $cfg->move_tag ( $tag, $new_section[, $new_tag] );

This function moves the tag from the current section to the specified new section. If $new_tag was provided that will be the tag's new name in the new section. If the tag already exists in the new section it will be overwritten.

If the tag or the new section doesn't exist, the move will fail! It will also fail if the new section is the current section.

Returns 1 on success, 0 on failure.

$bool = $cfg->delete_tag ( $tag );

This function removes the requested $tag found in the current section from the configuration data in memory.

Returns 1 on success, 0 if the $tag didn't exist.

Breaking your Advanced::Config object into Sections.

Defining sections allow you to break up your configuration files into multiple independent parts. Or in advanced configuations using sections to override default values defined in the main/unlabled section.

$section = $cfg->get_section ( [$section_name[, $required]] );

Returns the Advanced::Config object for the requested section in your config file. If the $section_name doesn't exist, it will return undef. If $required is set, it will call die instead.

If no $section_name was provided, it returns the default main section.

$name = $cfg->section_name ( );

This function returns the name of the current section $cfg points to.

$scfg = $cfg->create_section ( $name );

Creates a new section called $name within the current Advanced::Config object $cfg. It returns the Advanced::Config object that it created. If a section of that same name already exists it will return undef.

There is no such thing as sub-sections, so if $cfg is already points to a section, then it looks up the parent object and associates the new section with the parent object instead.

Searching the contents of an Advanced::Config object.

This section deals with the methods available for searching for content within your Advanced::Config object.

@list = $cfg->find_tags ( $pattern[, $override_inherit] );

It returns a list of all tags whose name contains the passed pattern.

If the pattern is undef or the empty string, it will return all tags in the curent section. Otherwise it does a case insensitive comparison of the pattern against each tag to see if it should be returned or not.

If override_inherit is provided it overrides the current inherit option's setting. If undef it uses the current inherit setting. If inherit evaluates to true, it looks in the current section and the main section for a match. Otherwise it just looks in the current section.

The returned list of tags will be sorted in alphabetical order.

@list = $cfg->find_values ( $pattern[, $override_inherit] );

It returns a list of all tags whose values contains the passed pattern.

If the pattern is undef or the empty string, it will return all tags in the curent section. Otherwise it does a case insensitive comparison of the pattern against each tag's value to see if it should be returned or not.

The returned list of tags will be sorted in alphabetical order.

@list = $cfg->find_sections ( $patern );

It returns a list of all section names which match this pattern.

If the pattern is undef or the empty string, it will return all the section names. Otherwise it does a case insensitive comparison of the pattern against each section name to see if it should be returned or not.

The returned list of section names will be sorted in alphabetical order.

Miscellaneous methods against Advanced::Config object.

These methods while useful don't really fall into a category of their own. So they are collected here in the miscellaneous section.

$file = $cfg->filename ( );

Returns the fully qualified file name used to load the config file into memory.

($ropts, $gopts, $dopts) = $cfg->get_cfg_settings ( );

This method returns references to copies of the current options used to manipulate the config file. It returns copies of these hashes so feel free to modify them without fear of affecting the behaviour of this module.

$cfg->export_tag_value_to_ENV ( $tag, $value );

Used to export the requested tag/value pair to the %ENV hash. If it's also marked as an %ENV tag the config file depends on, it updates internal bookkeeping so that it won't trigger false refreshes.

Once it's been promoted to the %ENV hash the change can't be backed out again.

$sensitive = $cfg->chk_if_sensitive ( $tag[, $override_inherit] );

This function looks up the requested tag in the current section of the config file and returns if this module thinks the existing value is senitive (1) or not (0).

If the tag doesn't exist, it will always return that it isn't sensitive. (0)

An existing tag references sensitive data if one of the following is true. 1) Advanced::Config::Options::should_we_hide_sensitive_data() says it is or it says the section the tag was found in was sensitive. 2) The config file marked the tag in it's comment to HIDE it. 3) The config file marked it as being encrypted. 4) It referenced a variable that was marked as sensitive.

$encrypted = $cfg->chk_if_still_encrypted ( $tag[, $override_inherit] );

This function looks up the requested tag in the current section of the config file and returns if this module thinks the existing value is still encrypted (1) or not (0).

If the tag doesn't exist, it will always return 0!

This module always automatically decrypts everything unless the "Read" option disable_decryption was used. In that case this method was added to detect which tags still needed their values decrypted before they were used.

$bool = $cfg->chk_if_still_uses_variables ( $tag[, $override_inherit] );

This function looks up the requested tag in the current section of the config file and returns if the tag's value contained variables that failed to expand when the config file was parsed. (1 - has variable, 0 - none.)

If the tag doesn't exist, or you called set_value to create it, this function will always return 0 for that tag!

There are only two cases where it can ever return true (1). The first case is when you used the disable_variables option. The second case is if you used the disable_decryption option and you had a variable that referenced a tag that is still encrypted. But use of those two options should be rare.

$string = $cfg->toString ( [$addEncryptFlags[, \%override_read_opts] );

This function converts the current object into a string that is the equivalant of the config file loaded into memory without any comments.

If $addEncryptFlags is set to a non-zero value, it will add the needed comment to the end of each line saying it's waiting to be encrypted. So that you may later call encrypt_string to encrypt it.

If you provide %override_read_opts it will use the information in that hash to format the string. Otherwise it will use the defaults from new().

$hashRef = $cfg->toHash ( [$dropIfSensitive] );

This function converts the current object into a hash reference that is the equivalant of the config file loaded into memory. Modifying the returned hash reference will not modify this object's content.

If a section has no members, it will not appear in the hash.

If $dropIfSensitive is set to a non-zero value, it will not export any data to the returned hash reference that this module thinks is sensitive.

The returned hash reference has the following keys. $hash_ref->{section}->{tag}.

Encryption/Decryption of your config files.

The methods here deal with the encryption/decryption of your config file before you use this module to load it into memory. They allow you to make the contents of your config files more secure.

$status = $cfg->encrypt_config_file ( [$file[, $encryptFile[, \%rOpts]]] );

This function encrypts all tag values inside the specified confg file that are marked as ready for encryption and generates a new config file with everything encrypted. If a tag/value pair isn't marked as ready for encryption it is left alone. By default this label is ENCRYPT.

After a tag's value has been encrypted, the label in the comment is updated from ENCRYPT to DECRYPT in the config file.

If you are adding new ENCRYPT tags to an existing config file that already has DECRYPT tags in it, you must use the same encryption related options in %rOpts as the last time. Otherwise you won't be able to decrypt all encrypted values.

Finally if you provide argument $encryptFile, it will write the encrypted file to that new file instead of overwriting the current file. But if you do this, you will require the use of the alias option to be able to decrypt it again using the new name. This file only gets created if the return status is 1.

If you leave off the $file and \%rOpts, it will instead use the values inherited from the call to new.

This method ignores any request to source in other config files. You must encrypt each file individually.

It is an error if basename($file) is a symbolic link and you didn't provide $encryptFile.

Returns: 1 if something was encrypted. -1 if nothing was encrypted. Otherwise 0 on error.

$status = $cfg->decrypt_config_file ( [$file[, $decryptFile[, \%rOpts]]] );

This function decrypts all tag values inside the specified confg file that are marked as ready for decryption and generates a new config file with everything decrypted. If a tag/value pair isn't marked as ready for decryption it is left alone. By default this label is DECRYPT.

After a tag's value has been decrypted, the label in the comment is updated from DECRYPT to ENCRYPT in the config file.

For this to work, the encryption related options in \%rOpts must match what was used in the call to encrypt_config_file or the decryption will fail.

Finally if you provide argument $decryptFile, it will write the decrypted file to that new file instead of overwriting the current file. This file only gets created if the return status is 1.

If you leave off the $file and \%rOpts, it will instead use the values inherited from the call to new.

This method ignores any request to source in other config files. You must decrypt each file individually.

It is an error if basename($file) is a symbolic link and you didn't provide $decryptFile.

Returns: 1 if something was decrypted. -1 if nothing was decrypted. Otherwise 0 on error.

$out_str = $cfg->encrypt_string ( $string, $alias[, \%rOpts] );

This method takes the passed $string and treats it's value as the contents of a config file, comments and all. Modifying the $string afterwards will not affect things.

Since there is no filename to work with, it requires the $alias to assist with the encryption. And since it's required its passed as a separate argument instead of being burried in the optional %rOpts hash.

It takes the $string and encrypts all tag/value pairs per the rules defined by encrypt_config_file. Once the contents of I$<string> has been encrypted, the encrypted string is returned as $out_str. It will return undef on failure.

You can tell if something was encrypted by comparing $string to $out_str.

$out_str = $cfg->decrypt_string ( $string, $alias[, \%rOpts] );

This method takes the passed $string and treats it's value as the contents of an encrypted config file, comments and all. Modifying the $string afterwards will not affect things.

Since there is no filename to work with, it requires the $alias to assist with the decryption. And since it's required its passed as a separate argument instead of being burried in the optional %rOpts hash.

It takes the $string and decrypts all tag/value pairs per the rules defined by decrypt_config_file. Once the contents of I$<string> has been decrypted, the decrypted string is returned as $out_str. It will return undef on failure.

You can tell if something was decrypted by comparing $string to $out_str.

Handling Variables in your config file.

These methods are used to resolve variables defined in your config file when it gets loaded into memory by this module. It is not intended for general use except as an explanation on how variables work.

($value, $status) = $cfg->lookup_one_variable ( $variable_name );

This method takes the given $variable_name and returns it's value.

It returns undef if the given variable doesn't exist. And the optional 2nd return value tells us about the status of the 1st return value.

If the status is -1, the returned value is still encrypted. If set to 1, the value is considered sensitive. In all other cases this status flag is set to 0.

This method is frequently called internally if you define any variables inside your config files when they are loaded into memory.

Variables in the config file are surrounded by anchors such as ${name}. But it's passed as name without any anchors when this method is called.

The precedence for looking up a variable's value to return is as follows:

0. Is it the special "shft3" variable or one of it's variants?
1. Look for a tag of that same name previously defined in the current section.
2. If not defined there, look for the tag in the "main" section.
3. Special Case, see note below about periods in the variable name.
4. If not defined there, look for a value in the %ENV hash.
5. If not defined there, does it represent a special Perl variable?
6. If not defined there, is it a predefined Advanced::Config variable?
7. If not defined there, is it some predefined special date variable?
8. If not defined there, the result is undef.

If a variable was defined in the config file, it uses the tag's value when the line gets parsed. But when you call this method in your code after the config file has been loaded into memory, it uses the final value for that tag.

The special ${shft3} variable is a way to insert comment chars into a tag's value in the config file when you can't surround it with quotes. This variable is always case insensive and if you repeat the 3 in the name, you repeat the comment chars in the substitution.

* a = ${shft3}    - Returns "#" for a.
* b = ${SHFT33}   - Returns "##" for b.
* c = ${ShFt333}  - Returns "###" for c.
* etc ...

And since this variable has special meaning, if you try to define one of the SHFT3 variants as a tag in your config file, or call set_value with it, it will be ignored and a warning will be printed to your screen!

If the variable had a period (.) in it's name, and it doesn't match anything (rules 0 to 2), it follows rule 3 and it treats it as a reference to a tag in another section. So see rule_3_section_lookup for details on how this works.

This module provides you special predefined variables (rules 5, 6 & 7) to help make your config files more dynamic without the need of a ton of code on your end. If you want to override the special meaning for these variables, all you have to do is define a tag in the config file of the same name to override it. Or just don't use these variables in the 1st place.

For rule 5, the special Perl variables you are allowed to reference are: $$, $0, and $^O. (Each must appear in the config file as: ${$}, ${0} or ${^O}.)

For rule 6, the predefined module variables are: ${PID}, ${PPID}, ${user}, ${hostname}, ${program}, ${flavor} and ${sep} (The ${flavor} is defined by Perl::OSType and ${sep} is the path separator defined by File::Spec for your OS.) The final variable ${section} tells which section this variable was used in.

Finally for rule 7 it provides some special date variables. See Advanced::Config::Options::set_special_date_vars for a complete list of what date related variables are defined. The most useful being ${today} and ${yesterday} so that you can dynamically name your log files /my_path/my_log.${today}.txt and you won't need any special date roll logic to start a new log file.

($value, $sens, $encrypt) = $cfg->rule_3_section_lookup ( $variable_name );

When a variable has a period (.) in it's name, it could mean that this variable is referencing a tag from another section of the config file. So this helper method to lookup_one_variable exists to perform this complex check.

For example, a variable called ${xxx.extra} would look in Section "xxx" for tag "extra".

Here's another example with multiple .'s in it's name this time. It would look up variable ${one.two.three} in Section "one.two" for tag "three". And if it didn't find it, it would next try Section "one" for tag "two.three".

If it found such a variable, it returns it's value. If it didn't find anything it returns undef. The optional 2nd and 3rd values tells you more about the returned value.

$sens is a flag that tells if the data value should be considered sensitive or not.

$encrypt is a flag that tells if the value still needs to be decrypted or not.

$cfg->print_special_vars ( [\%date_opts] );

This function is for those individuals who don't like to read the POD too closely, but still need a quick and dirty way to list all the special config file variables supported by this module.

It prints to STDERR the list of these special variables and their current values. These values can change based on the options used in the call to new() or what OS you are running under. Or even what today's date is.

Please remember it is possible to override most of these variables if you first define them in your own config file or with an environment variable of the same name. But this function doesn't honor any overrides. It just provides this list on an FYI basis.

The optional date_opts hash allows you to play with the various date formats available for the special date vars. See The Special Date Variable Formatting Options section of the Options module for what these options are. Used to override what was set in the call to new().

ENVIRONMENT

Expects PERL5LIB to point to the root of the custom Module directory if not installed in Perl's default location.

COPYRIGHT

This program is free software. You can redistribute it and/or modify it under the same terms as Perl itself.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)