NAME

Advanced::Config::Options - Options manager for Advanced::Config.

SYNOPSIS

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

DESCRIPTION

Advanced::Config::Options is a helper module to Advanced::Config. So it should be very rare to directly call any methods defined by this module.

It's main job is to help manage the settings of the Read, Get and Date options hashes. It was implemented as a separate module to make it simpler to document the various supported options without cluttering up the POD of the main module. So you are not expected to ever call any of these methods yourself. It's here mainly as an FYI.

If you don't specify the options below, this module will assume you wish to use the default behaviour for that option. So only override what you need to. Also all options are in lower case. But you may provide them in mixed case if you wish. This module will auto downshift them for you.

If an option is mispelled, or you don't provide a valid value, a warning will be written to the screen and that option will be ignored.

==================================================================

The Read Options

In most cases the defaults should do nicely for you. But when you share config files between applications, you may not have any control over the config file's format. This may also apply if your organization requires a specific format for its config files.

So this section deals with the options you can use to override how it parses and interprets the config file when it is loaded into memory. None of these options below allows leading or trailing spaces in the option's value. And if any are found, they will be automatically trimmed off before their value is used. Internal spaces are OK when non-numeric values are expected. In most cases values with a length of 0 or undef are not allowed.

Just be aware that some combinations of Read options may result in this module being unable to parse the config file. If you encounter such a combination open a CPAN ticket and I'll see what I can do about it. But some combinations may just be too ambiguous to handle.

Also note that some Read options have left and right variants. These options are used in pairs and both must anchor the target in order for the rule to be applied to it. These start/end anchors can be set to the same string or different strings. Your choice.

Tag(s) Best Set in Call to the Constructor new().

While not required to set these options during the call to new, changing their settings later on can cause unexpected issues if you are not careful.

But it's still recommended that most Read Options be set during the call to new to avoid having to keep on resetting them all the time and limit these later changes to handle exceptions to your defaults.

tag_case - Config files are made up of tag/value pairs. This option controls whether the tags are case sensitive (0, the default) or case insensitive (1). IE do tags ABC and abc represent the same tag or not? So if set, all tags are assumed to be in lower case for the get/set methods!

Generic Read Options

These options are also usually set during the call to new, but setting them later on doesn't produce strange behavior if you change the settings later on.

croak - This controls what happens when a function hits an unexpected error while parsing the config file. Set to 0 to return an error code (default), -1 to return an error code and print a warning to your screen, 1 to call die and terminate your program.

export - Tells if we should export all tag/value pairs to perl's %ENV hash or not. The default is 0 for No. Set to 1 if you want this to happen. But if set, it reverses the meaning of the export_lbl option defined later on.

use_utf8 - Defaults to 0. Set to 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.

disable_quotes - Defaults to 0. Set to 1 if you want to disallow the stripping of balanced quotes in your config files.

disable_variables - Defaults to 0. Set to 1 if you want to disable variable expansion in your config files when they are loaded into memory.

disable_variable_modifiers - Defaults to 0. Set to 1 if you want to disable this feature. See 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. Automtaically disabled when variables are disabled. Usefull when you put a lot of special chars into your variable names.

disable_decryption - Defaults to 0. Set to 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.

trap_recursion - Defaults to 0. Set to 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.

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 varibles. Defaults to an empty hash reference.

source_cb - An optional callback routine called each time your config file sources in another config file. It's main use is when the Read Options and/or 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
            perserve 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.

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.)

assign - Defaults to =. You may use this option to override what string of characters make up the assignemnt 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 \\s since the interface doesn't allow whitespace as a value.

comment - Defaults to #. 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)

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

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

variable_left & 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 ${ and }. If you override these anchors to both have the same value, then the optional variable modifiers are not supported nor are nested variables.

quote_left & 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 " or ' 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.

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 "# Please EXPORT me.", but won't match "# 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 recomended 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.

export_lbl - Defaults to "EXPORT". Tells this module to export this particular tag/value pair to perl's %ENV hash. If the 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.

hide_lbl - Defaults to "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.

encrypt_lbl - Defaults to "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.

decrypt_lbl - Defaults to "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.

source_file_section_lbl - Defaults to "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.

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 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 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 weeken the results.

These options are ignored if you've disabled decryption.

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

alias - Defaults to the empty string. (Meaning no alias provided.) This option is used to override using the file's basename as one of the encrytion/decryption keys with the basename of the value you provide here.

If you encrypt a file with no alias, and then rename the config file, you must set the alias to the original filename to be able to decrypt anything. If you encrypt a file with an alias, you must use the same 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.

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.

inherit_pass_phrase - Defaults to 0 (no). Set to 1 if you want to use the same pass_pharase when you source in a sub-file in your config files.

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 encryted the file can decrypt it.

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.

encrypt_cb - An optional callback function to provide hooks for 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 perserve info between calls.  This
               module will "never" examine the contents of this hash!

==================================================================

The Get Options

This section deals with the options you can use to override how the 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, new(), or for individual get_... calls if you don't like the defaults for individual calls.

But it is strongly recomended that the inherit option only be set in the constructor and not changed elsewhere. Changing it's value beween 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.

inherit - Defaults to 0 where each section is independent, the tag either exists or it doesn't in the section. Set to 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.

required - This controls what happens when the requested tag doesn't exist in your Advanced::Config object. Set to 0 to return undef (default), -1 to return undef and write a warning to your screen, 1 to call die and terminate your program.

vcase - Controls what case to force all values to. Defaults to 0 which says to preserve the case as entered in the config file. Use 1 to convert everything to upper case. Use -1 to convert everything to lower case.

split_pattern - Defaults to qr /\s+/. The pattern to use when splitting a tag's value into an array via perl's split function. It can be a string or a regular expression. For example to split on a comma separated string you could do: qr /\s*,\s*/.

date_language - Defaults to English. Tells what language get_date() should use when converting the date into a standard format. Can be almost any language supported by Date::Language.

date_language_warn - Defaults to 0 (no). Should Advanced::Config::Date methods print out warnings?

date_enable_yy - Defaults to 0 (no). When parsing dates, should we enable recognizing two digit years as valid?

date_format - Numeric dates are inherently ambiguous so hints are required in order to eliminate ambiguities. For example is 01/02/03 Jan 2, 2003 (USA) or Feb 1, 2003 (European) or even 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.

date_dl_conversion - Defaults to 0 (no). When parsing dates, should we be using Date::Language, if it's installed, for additional parsing of dates if nothing else works?

There are many other Get Options not exposed in the POD. They are only set via the specialized get_... functions. So they are not documented here.

==================================================================

The Special Date Variable Formatting Options

This module allows for special predefined date related variables for use in your config files. These options deal with how to format these dates when these variables are referenced. These formatting rules apply to all of the special date variables.

date_order - Used to define the ordering of the parts of the dates. 0 - YMD (ISO), 1 - MDY (American), 2 - DMY (European). The default is 0.

date_sep - The separator to use with the date. Defaults to "-".

month_type - How to display the month variables. 0 - numeric, 1 - abbreviate names, 2 - full names. The default is 0.

month_language - What language to use when using month names. Defaults to English.

use_gmt - How to calculate the date values. 0 - use localtime, 1 - use gmtime. The default is 0.

==================================================================

FUNCTIONS

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

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

$ropts = get_read_opts ( [\%user_opts[, \%current_opts]] )

This method takes the user's options that override the behaviour for reading in your config file by this module and merges it into the current options. If no current options hash reference is given, it will use the module's defaults instead.

It returns a hash reference of all applicable "Read" options.

$gopts = get_get_opts ( [\%user_opts[, \%current_opts]] )

This method takes the user's options that override the behaviour of get methods for this module and merges it into the current options. If no current options hash reference is given, it will use the module's defaults instead.

It returns a hash reference of all applicable "Get" options.

$dopts = get_date_opts ( [\%user_opts[, \%current_opts]] )

This method takes the user's options that override the behaviour of date foramtting for this module and merges it into the current options. If no current options hash reference is given, it will use the module's defaults instead.

It returns a hash reference of all applicable "Date" formatting options.

$ref = apply_get_rules ( $tag, $section, $val1, $val2, $wide, $getOpts )

Returns an updated hash reference containing the requested data value after all the $getOpts rules have been applied. If the $tag doesn't exist then it will return undef instead or die if it's required.

$val1 is the DATA hash value from the specified section.

$val2 is the DATA hash value from the parent section. This value is ignored unless the inherit option was specified via $getOpts.

$wide tells if UTF-8 dates are allowed.

$boolean = is_assign_spaces ( $ropts )

Tells if the assignment operator selected is the special case of using spaces to separate the tag/value pair. Only returns true if it's \\s.

$boolean = using_default_quotes ( $ropts )

This function tells if you are currently using the default quotes. This is the only case where there can be multiple values for the quote string anchors. All other cases allow only for a single value for each of the quote string anchors.

$str = convert_to_regexp_string ( $string[, $no_logs] )

Converts the passed string that may contain special chars for a Perl RegExp into something that is a literal constant value to Perl's RegExp engine by turning these problem chars into escape sequences.

It then returns the new string.

If $no_logs is set to a non-zero value, it won't write anything to the logs.

$str = convert_to_regexp_modifier ( $string )

Similar to convert_to_regexp_string except that it doesn't convert all the wild card chars.

Leaves the following RegExp wild card's unescaped! (*, ?, [, and ])

Used when processing variable modifier rules.

$sensitive = should_we_hide_sensitive_data ( $tag )

Checks the tag against an internal list of patterns to see if there is a match. This check is done in a case insensitive way.

If there is a match it will return true and the caller should take care about writing anything about this tag to any log files.

If there is no match it will return false, and you can write what you please to your logs.

See make_it_sensitive to add additional patterns to the list.

make_it_sensitive ( @patterns )

Add these pattern(s) to the internal list of patterns that this module considers sensitive. Should any tag contain this pattern, that tag's value will be masked when written to this module's internal logs. Leading/trailing spaces will be ignored in the pattern. Wild cards are not honored.

The 3 default patterns are password, pass, and pwd.

This pattern affects all Advanced::Config objects loaded into memory. Not just the current one.

$cnt = sensitive_cnt ( )

Returns a count of how many sensitive patterns are being used.

@ret = croak_helper ($opts, $croak_message, @croak_return_vals)

This helper method helps standardises what to do on fatal errors when reading the config file or what to do if you can't find the tag on lookups.

It knows \%opts is a "Read" option hash if croak is a member and it's a "Get" option hash if required is a member. Both options use the same logic when called.

See croak and required on what these options do.

Returns whatever @croak_return_vals references. It may be a single value or an array of values.

It calls warn or die with the message passed.

$lvl = set_special_date_vars ( $date_opts_ref, $date_hash_ref[, $old_hash_ref] )

The $date_opts_ref contains the special date variable formatting options used to control the formattiong of the data returned via $date_hash_ref. The relevant tags are: date_order, date_sep, month_type, use_gmt and month_language. Any missing hash key and it's default is used.

This function populates the following date keys in $date_hash_ref for use by the config object using the current date/time. These keys are also defined as the date variables available for use by your config files.

The keys set are: (Shown using the default formats)

today, yesterday, tomorrow -- A formatted date in YYYY-MM-DD format.
this_month, last_month, next_month -- The Month.
this_year, last_year, next_year -- A 4 digit year.
this_period, last_period, next_period -- The YYYY-MM part of a date.
dow -- The day of the week  (Sunday to Saturday or 1..7).
doy -- The day of the year (1..365 most years, 1..366 in leap years).
dom -- The day of the month. (1..31)
timestamp -- The time used to generate the above variables with. [time()]

The $old_hash_ref contains the values from the previous call to this function. If missing, assumes 1st time called. If provided and the date options for this call doesn't match what was used to create this hash the return value is unreliable.

Returns the level of what changed in ${date_hash_ref}:

0 -- Nothing changed from previous call or it's the 1st time called.
1 -- Just the day of month changed.
2 -- The month also changed.
3 -- The year also changed.

change_special_date_vars ( $timestamp, $date_opts_ref, $date_hash_ref )

Same as set_special_date_vars except it uses the specified date/time to convert.

COPYRIGHT

Copyright (c) 2007 - 2025 Curtis Leach. All rights reserved.

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

SEE ALSO

Advanced::Config - The main user of this module. It defines the Config object.

Advanced::Config::Date - Handles date parsing for get_date().

Advanced::Config::Reader - Handles the parsing of the config file.

Advanced::Config::Examples - Provides some sample config files and commentary.

cpanm Advanced::Config

perl -MCPAN -e shell
install Advanced::Config