Config::Hierarchical - Hierarchical configuration container
use Config::Hierarchical ; my $config = new Config::Hierarchical(); # or my $config = new Config::Hierarchical ( NAME => 'some_namespace', VERBOSE => 0, DISABLE_SILENT_OPTIONS => 0, CATEGORY_NAMES => ['<CLI>', '<PBS>', 'PARENT', 'LOCAL', 'CURRENT'], DEFAULT_CATEGORY => 'CURRENT', WARN_FOR_EXPLICIT_CATEGORY => 0, GET_CATEGORIES => { Inheritable => ['CLI', 'PBS', 'PARENT', 'CURRENT'], }, INTERACTION => { INFO => \&sub, WARN => \&sub, DIE => \&sub, DEBUG => \&sub, }, SET_VALIDATOR => \&my_set_validator, VALIDATORS => [ { CATEGORY_NAMES => ['CLI', 'CURRENT',] , NAMES => ['CC', 'LD'], VALIDATORS => { alphanumeric => \&alphanumeric, other_validator => \&other_validator, }, }, { CATEGORY_NAMES => ['CURRENT',] , NAMES => ['CC',], VALIDATORS => {only_gcc => \&only_gcc,}, }, ], INITIAL_VALUES => [ { CATEGORY => 'PBS', ALIAS_CATEGORY => $pbs_config, HISTORY => ...., COMMENT => ...., }, {CATEGORY => 'CLI', NAME => 'CC', VALUE => 1,}, {CATEGORY => 'CLI', NAME => 'LD', VALUE => 2, LOCK => 1}, {CATEGORY => 'CURRENT', NAME => 'CC', VALUE => 3, OVERRIDE => 1}, {CATEGORY => 'CURRENT', NAME => 'AS', VALUE => 4,}, {CATEGORY => 'CURRENT', NAME => 'VARIABLE_WITH_HISTORY', VALUE => $previous_value, HISTORY => $history }, ] , LOCKED_CATEGORIES => ['CLI'], ) ; $config->Set(NAME => 'CC', VALUE => 'gcc') ; $config->Set(NAME => 'CC', VALUE => 'gcc', CATEGORY => 'CLI') ; $config->Set(NAME => 'CC', VALUE => 'gcc', FORCE_LOCK => 1) ; $config->Set(NAME => 'CC', VALUE => 'gcc', SILENT_OVERRIDE => 1, COMMENT => 'we prefer gcc') ; $config->Exists(NAME => 'CC') ; $config->GetKeyValueTuples() ; $config->SetMultiple ( {FORCE_LOCK => 1} {NAME => 'CC', VALUE => 'gcc', SILENT_OVERRIDE => 1}, {NAME => 'LD', VALUE => 'ld'}, ) ; $config->Set(CC => 'gcc') ; $value = $config->Get(NAME => 'CC') ; $value = $config->Get(NAME => 'NON_EXISTANT', SILENT_NOT_EXISTS => 1) ; @values = $config->GetMultiple(@config_variables_names) ; @values = $config->GetMultiple({SILENT_NOT_EXISTS => 1}, @config_variables_names) ; $hash_ref = $config->GetHashRef() ; # no warnings $config->GetInheritable() ; $config->SetDisableSilentOptions(1) ; $config->LockCategories('PBS') ; $config->UnlockCategories('CLI', 'PBS') ; $config->IsCategoryLocked('PBS') ; $config->Lock(NAME => 'CC') ; $config->Unlock(NAME => 'CC', CATEGORY => 'CLI') ; $config->IsLocked(NAME => 'CC') ; $history = $config->GetHistory(NAME => 'CC') ; $dump = $config->GetDump() ;
This module implements a configuration variable container. The container has multiple categories which are declared in decreasing priority order.
A variable can exist in multiple categories within the container. When queried for a variable, the container will return the variable in the category with the highest priority.
When setting a variable, the container will display a warning message if it is set in a category with lower priority than a category already containing the same variable.
Priority overriding is also possible.
I'll start by giving a usage example. In a build system, configuration variables can have different source.
the build tool
the command line
the parent build file (in a hierarchical build system)
the current build file
It is likely that a configuration variable set on the command line should be used regardless of a local setting. Also, a configuration variable set by the build tool itself should have the highest priority.
Among the most difficult errors to find are configuration errors in complex build systems. Build tools generally don't help much when variables are overridden. it's also difficult to get a variable's history.
This module provides the necessary functionality to handle most of the cases needed in a modern build system.
Test t/099_cookbook.t is also a cookbook you can generate with POD::Tested. It's a nice complement to this documentation.
Subroutines that are not part of the public interface are marked with [p].
Create a Config::Hierarchical .
my $config = new Config::Hierarchical() ;
Arguments
The arguments are named. All argument are optional. The order is not important.
my $config = new Config::Hierarchical(NAME => 'some_namespace', VERBOSE => 1) ;
NAME
A string that will be used in all the dumps and interaction with the user.
CATEGORY_NAMES
A list of category names. The first named category has the highest priority. Only categories listed in this list can be manipulated. Using an unregistered category in a Set or Get operation will generate an error.
Set
Get
my $config = new Config::Hierarchical ( CATEGORY_NAMES => ['CLI', '<PBS>', 'PARENT', 'CURRENT', 'LOCAL'], DEFAULT_CATEGORY => 'CURRENT', ) ;
A category can be protected by enclosing its name in angle bracket, IE: <PBS>. Protected categories will not be overridden by lesser priority categories even if the OVERRIDE option is used.
If no category names are given, 'CURRENT' will be used and DEFAULT_CATEGORY will be set accordingly.
DEFAULT_CATEGORY
The name of the category used when Set is called without a CATEGORY argument.
If the CATEGORY_NAMES list contains more than one entry, DEFAULT_CATEGORY must be set or an error will be generated.
DIE_NOT_EXISTS
my $config = new Config::Hierarchical(..., DIE_NOT_EXISTS => 0) ;
Calling Get on an unexisting variable will generate an exception when this option is set. The option is not set by default.
DISABLE_SILENT_OPTIONS
my $config = new Config::Hierarchical(NAME => 'some_namespace', DISABLE_SILENT_OPTIONS => 1) ;
When this option is set, SILENT_OVERRIDE and SILENT_NOT_EXISTS will be ignored and Config::Hierarchical will display a warning.
GET_CATEGORIES
This option allows you to define functions that fetch variables in a specific category list and in a specific order.
my $config = new Config::Hierarchical ( CATEGORY_NAMES => ['CLI', '<PBS>', 'PARENT', 'CURRENT', 'LOCAL'], GET_CATEGORIES => { Inheritable => ['CLI', 'PBS', 'PARENT', 'CURRENT'], } ... ) ; my $value = $config->GetInheritable(NAME => 'CC') ; my $hash_ref = $config->GetInheritableHashRef() ;
In the example above, the LOCAL category will not be used by GetInheritable.
WARN_FOR_EXPLICIT_CATEGORY
if set, Config::Hierarchical will display a warning if any category is specified in Get or Set.
VERBOSE
This module will display information about its actions when this option is set.
See INTERACTION and SetDisplayExplicitCategoryWarningOption.
SetDisplayExplicitCategoryWarningOption
INTERACTION
Lets you define subs used to interact with the user.
my $config = new Config::Hierarchical ( INTERACTION => { INFO => \&sub, WARN => \&sub, DIE => \&sub, DEBUG => \&sub, } ) ;
This sub will be used when displaying verbose information.
This sub will be used when a warning is displayed. e.g. a configuration that is refused or an override.
Used when an error occurs. E.g. a locked variable is set.
If this option is set, Config::Hierarchical will call the sub before and after acting on the configuration. This can act as a breakpoint in a debugger or allows you to pinpoint a configuration problem.
The functions default to:
INFO => CORE::print
WARN => Carp::carp
DIE => Carp::confess
FILE and LINE
These will be used in the information message and the history information if set. If not set, the values returned by caller will be used. These options allow you to write wrapper functions that report the callers location properly.
INITIAL_VALUES
Lets you initialize the Config::Hierarchical object. Each entry will be passed to Set.
my $config = new Config::Hierarchical ( ... EVALUATOR => \&sub, INITIAL_VALUES => [ { # aliased category CATEGORY => 'PBS', ALIAS_CATEGORY => $pbs_config, HISTORY => ...., COMMENT => ...., }, {CATEGORY => 'CLI', NAME => 'CC', VALUE => 1}, {CATEGORY => 'CLI', NAME => 'LD', VALUE => 2, LOCK => 1}, {CATEGORY => 'CURRENT', NAME => 'CC', VALUE => 3, OVERRIDE => 1}, {CATEGORY => 'CURRENT', NAME => 'AS', VALUE => 4,}, } , ) ;
See Set for options to INITIAL_VALUES and a details explanation about EVALUATOR.
Aliased categories allow you to use a category to refer to an existing Config::Hierarchical object. The referenced object is read only. This is because multiple configurations might alias to the same Config::Hierarchical object.
Variables from aliased category can still be overridden.
LOG_ACCESS
If this set, Config::Hierarchical will log all access made through Get.
LOCKED_CATEGORIES
Lets you lock categories making them read only. Values in INITIAL_VALUES are used before locking the category.
my $config = new Config::Hierarchical(..., LOCKED_CATEGORIES => ['CLI', 'PBS']) ;
See LockCategories and IsCategoryLocked.
LockCategories
IsCategoryLocked
SET_VALIDATOR
This gives you full control over what gets into the config. Pass a sub reference that will be used to check the configuration variable passed to the subroutine Set.
Argument passed to the subroutine reference:
The configuration object. Yous should use the objects interaction subs for message display.
The options passed to Set.
The location where Set was called. Useful when displaying an error message.
sub my_set_validator { my ($config, $options, $location) = @_ ; # eg, check the variable name if($options->{NAME} !~ /^CFG_[A-Z]+/) { $config->{INTERACTION}{DIE}->("$config->{NAME}: Invalid variable name '$options->{NAME}' at at '$location'!") } # all OK, let Config::Hierarchical handle variable setting } my $config = new Config::Hierarchical(SET_VALIDATOR => \&my_set_validator) ;
VALIDATORS
my $config = new Config::Hierarchical ( ... VALIDATORS => [ { CATEGORY_NAMES => ['CURRENT', 'OTHER'] , NAMES => ['CC', 'LD'], VALIDATORS => { validator_name => \&PositiveValueValidator, other_validator => \&SecondValidator }, }, ], ) ;
Let you add validation subs to Config::Hierarchical for specific variables.
Each variable in NAMES in each category in CATEGORY_NAMES will be assigned the validators defined in Validators.
The example above will add a validator PositiveValueValidator and validator SecondValidator to CURRENT::CC, CURRENT::LD, OTHER::CC and OTHER::LD.
A validator is sub that will be called every time a value is assigned to a variable. The sub is passed a single argument, the value to be assigned to the variable. If false is returned by any of the validators, an Exception will be raised through INTERACTION::DIE.
see AddValidator.
AddValidator
Arguments - None
Returns
The configuration name
The configuration object's creation location
Helper sub called by new. This shall not be used directly.
Sets {INTERACTION} fields that are not set by the user.
Helper sub called by new.
$config->AddValidator ( CATEGORY_NAMES => ['CLI'] , NAMES => ['CC', 'LD'], VALIDATORS => {positive_value => \&PositiveValueValidator}, ) ;
You can add validators after creating a configuration and even after adding variables to your configuration. The existing variables will be checked when the validators are added.
CATEGORY_NAMES => \@catagories - A reference to an array containing the names of the categories to add the validators to
NAMES => \@names - A reference to an array containing the names of the variables that will be validated
VALIDATORS => \%validators - A reference to a hash where keys are validator_names and values are validator code references
Returns - Nothing
Config::Hierarchical will warn you if you override a validator.
Used to handle category aliases.
my $pbs_config = new Config::Hierarchical(...) ; my $config = new Config::Hierarchical ( NAME => 'some_namespace', CATEGORY_NAMES => ['<CLI>', '<PBS>', 'PARENT', 'LOCAL', 'CURRENT'], INITIAL_VALUES => [ { CATEGORY => 'PBS', ALIAS_CATEGORY => $pbs_config, HISTORY => ...., COMMENT => ...., }, {NAME => 'CC1', VALUE => 'gcc'}, ... ] , ) ;
CATEGORY and ALIAS_CATEGORY must be passed as arguments. See new for details about aliased categories.
new
HISTORY
COMMENT
CHECK_LOWER_LEVEL_CATEGORIES
Creates custom Get* functions.
Verifies the options passed to the members of this class. Calls {INTERACTION}{DIE} in case of error.
my $config = new Config::Hierarchical() ; $config->Set(NAME => 'CC', VALUE => 'gcc') ; $config->Set ( NAME => 'CC', VALUE => 'gcc', # options HISTORY => $history, COMMENT => 'we like gcc' CATEGORY => 'CLI', VALIDATORS => {positive_value => \&PositiveValueValidator,} FORCE_LOCK => 1, LOCK => 1, OVERRIDE => 1, SILENT_OVERRIDE => 1, ATTRIBUTE => 'some attribute', FILE => 'some_file', LINE => 1, CHECK_LOWER_LEVEL_CATEGORIES => 1, ) ;
ARGUMENTS
NAME - The variable's name. MANDATORY
EVAL - Can be used instead for NAME. See 'Using EVAL instead for VALUE'
VALUE - A scalar value associated with the 'NAME' variable. MANDATORY
The argument passed is kept in the configuration variable. You can pass any scalar variable; Config::Hierarchical will not manipulate this information.
See GetHistory.
GetHistory
A comment that will be added to the variable history.
CATEGORY
The name of the category where the variable resides. If no CATEGORY is given, the default category is used.
ATTRIBUTE
Set the configuration variable's attribute to the passed argument. See <SetAttribute>.
Configuration validators that will only be used during this call to Set. The SET_VALIDATOR set in the constructor will not be called if this option is set. This lets you add configuration variable from different source and check them with specialized validators.
Extra validators that will only be used during this call to Set.
FORCE_LOCK
If a variable is locked, trying to set it will generate an error. It is possible to temporarily force the lock with this option. A warning is displayed when a lock is forced.
LOCK
Will lock the variable if set to 1, unlock if set to 0.
OVERRIDE
This allows the variable in a category to override the variable in a category with higher priority. Once a variable is overridden, it's value will always be the override value even if it is set again.
my $config = new Config::Hierarchical ( NAME => 'Test config', CATEGORY_NAMES => ['PARENT', 'CURRENT'], DEFAULT_CATEGORY => 'CURRENT', INITIAL_VALUES => [ {NAME => 'CC', CATEGORY => 'PARENT', VALUE => 'parent'}, ] , ) ; $config->Set(NAME => 'CC', CATEGORY => 'CURRENT', OVERRIDE => 1, VALUE => 'current') ; $config->Set(NAME => 'CC', CATEGORY => 'PARENT', VALUE => 'parent') ; $config->Get(NAME => 'CC') ; # will return 'current'
SILENT_OVERRIDE
Disables the warning displayed when overriding a variable.
See FILE and LINE in new.
Config::Hierarchical display warnings about all the collisions with higher priority categories. If this option is set, warnings will also be displayed for lower priority categories.
Config::Hierarchical will keep a history of all the setting you make. The history can be retrieved with GetHistory. The history is also part of the dump generated by GetDump.
GetDump
Quite often configuration variables values are base on other configuration variable values. A typical example would be a set of paths.
my $config = new Config::Hierarchical() ; $config->Set(NAME => 'BASE', VALUE => '/somewhere') ; $config->Set(NAME => 'MODULE', VALUE => 'module') ; $config->Set(NAME => 'CONFIG_FILE', VALUE => 'my_config') ;
If you wanted to set a variable to the full path of your config file you have to write:
$config->Set ( NAME => 'PATH_TO_CONFIG_FILE', VALUE => $config->Get(NAME => 'BASE') . '/' . $config->Get(NAME => 'MODULE') . '/' . $config->Get(NAME => 'CONFIG_FILE'), ) ;
If you have many variables that are based on other variables, you code get messy quite fast. With a little work, Config::Hierarchical let's you write code like this:
$config->Set(NAME => 'PATH_TO_CONFIG_FILE', EVAL => q~ "$BASE/$MODULE/$CONFIG_FILE" ~) ;
To achieve this, Config::Hierarchical let's you implement an "EVALUATOR", a subroutine responsible for handling EVAL. It is set during the call to new or Set. The subroutine is passed the following arguments:
$config - A reference to the Config::Hierarchical object
$arguments - A hash reference containing the arguments passed to Set
Below is an example using Eval::Context. See t/020_eval.t for a complete example.
sub eval_engine { my ($config, $arguments) = @_ ; my $hash_ref = $config->GetHashRef() ; my $context = new Eval::Context ( INSTALL_VARIABLES => [ map {["\$$_" => $hash_ref->{$_} ]} keys %$hash_ref ], INTERACTION => { EVAL_DIE => sub { my($self, $error) = @_ ; croak $error; }, } ) ; my $value = eval {$context->eval(CODE => $arguments->{EVAL})} ; if($@) { $config->{INTERACTION}{DIE}-> ( "Error: Config::Hierarchical evaluating variable '$arguments->{NAME}' " . "at $arguments->{FILE}:$arguments->{LINE}:\n\t". $@ ) ; } return $value ; } my $config = new Config::Hierarchical(EVALUATOR => \&eval_engine, ...) ;
EVAL can be used in Set and in INITIAL_VALUES.
Checks input to Set.
Check if a config variable setting overrides a higher priority category.
Check if a config variable setting takes precedence over a lower priority category.
Set the variable in its category, verify lock, etc..
This sub allows you to attach an attribute per variable (the attribute you set is per category) other than a value. It will raise an exception if you try to set a variable that does not exists or if you try to set an attribute to a variable in an aliased category.
$config->SetAttribute(NAME => 'CC', ATTRIBUTE => 'attribute') ; # or directly in the 'Set' call $config->Set(NAME => 'CC', VALUE => 'CC', ATTRIBUTE => 'attribute') ; my ($attribute, $attribute_exists) = $config->GetAttribute(NAME => 'CC') ;
NAME => $variable_name - The variable name
ATTRIBUTE => $attribute - A scalar attribute
CATEGORY => $category - Category in which you want to set the attribute.
This sub returns the attribute as well as the existence of the attribute. If the attribute didn't exist, the value is set to undef. No warnings are displayed if you query the attribute of a variable that does not have an attribute.
A warning message is displayed if you call this sub in void or scalar context.
my ($attribute, $attribute_exists) = $config->GetAttribute(NAME => 'CC') ;
NAME => $variable_name - The name of the variable you want to get the attribute for
Returns - a list
The attribute
A boolean. Set if the attribute existed
Exceptions - This sub will raise an exception if you query a variable that does not exists.
Returns the value associated with the variable passed as argument. If more than one category contains the variable, the variable from the category with the highest priority, which is not overridden, will be used.
If the variable doesn't exist in the container, a warning is displayed and undef is returned.
my $config = new Config::Hierarchical(INITIAL_VALUES => [{NAME => 'CC', VALUE => 'gcc'}]) ; my $cc = $config->Get(NAME => 'CC') ; my $ld = $config->Get(NAME => 'LD', SILENT_NOT_EXISTS => 1) ;
SILENT_NOT_EXISTS
Setting this option will disable the warning generated when the variable doesn't exist in the container.
CATEGORIES_TO_EXTRACT_FROM
If set, Get will only search in the specified categories. A warning is displayed if the categories are not in the same order as passed to the constructor.
GET_CATEGORY
If this option is set, Get will return the value _and_ the category it it comes from.
If GET_CATEGORY is not set:
The variable's value
If GET_CATEGORY is set:
The category the value comes from
Warnings
This function verifies its calling context and will generate a warning if it is called in void context.
Set multiple configuration in one call.
$config->SetMultiple ( {FORCE_LOCK => 1}, [NAME => 'CC', VALUE => 'gcc', SILENT_OVERRIDE => 1], [NAME => 'LD', VALUE => 'ld'], ) ;
\%options - An optional hash reference with options applied to each Set call
\@variable_to_set - An array reference containing the parameter for the Set call
Multiple \@variable_to_set can be passed.
see Set.
Get multiple configuration in one call.
my $config = new Config::Hierarchical(INITIAL_VALUES => [{NAME => 'CC', VALUE => 'gcc'}]) ; my @values = $config->GetMultiple('CC') ; my @other_values = $config->GetMultiple ( {SILENT_NOT_EXISTS => 1}, 'CC', 'AR' ) ;
\%options - An optional hash reference with options applied to each Get call
@variable_to_get - A list containing the names of the variables to get.
Option GET_CATEGORY will be ignored in this sub.
see Get.
my @keys = $config->GetKeys() ;
Returns the names of the element in the config object.
Optional, CATEGORIES_TO_EXTRACT_FROM
if set, GetKeys will only search in the specified categories.
The list of variables contained in the Config::Hierarchical object.
A warning will be generated if GetKeys is called in void context.
Returns a list of hash references containing the name and the value of each configuration variable contained in the object. This can be useful when you you create config objects from data in other objects.
my $config_1 = new Config::Hierarchical(.....) ; my $config_2 = new Config::Hierarchical ( NAME => 'config 2', CATEGORY_NAMES => ['PARENT', 'CURRENT'], DEFAULT_CATEGORY => 'CURRENT', INITIAL_VALUES => [ # Initializing a category from another config map ({ { NAME => $_->{NAME}, VALUE => $_->{VALUE}, CATEGORY => 'PARENT', LOCK => 1, HISTORY => $config_1->GetHistory(NAME => $_->{NAME}), } } $config_1->GetKeyValueTuples()), {NAME => 'CC', VALUE => 1,}, ] ) ;
Argument
If set, GetKeyValueTuples will only search in the specified categories.
A list of hash references. Each hash has a NAME and VALUE key.
my $hash_ref = $config->GetHashRef() ;
This function will generate an error if any argument is passed to it.
Returns - A hash reference containing a copy of all the elements in the container.
GetHashRef will generate a warning if:
GetHashRef
it is called in void context
it is called in array context
$config->SetDisplayExplicitCategoryWarningOption(1) ; $config->SetDisplayExplicitCategoryWarningOption(0) ;
$boolean - controls if messages are displayed if an explicit category is used in Get or Set.
Return - Nothing
$config->SetDisableSilentOptions(1) ; $config->SetDisableSilentOptions(0) ;
$boolean - controls if messages are displayed regardless of local warning disabling options
This is useful when debugging your configuration as it forces all the warning to be displayed.
Locks the categories passed as argument. A variable in a locked category can not be set. An attempt to set a locked variable will generate an error. FORCE_LOCK has no effect on locked categories.
$config->LockCategories('PARENT', 'OTHER') ;
@categories - a list of categories to lock
Exceptions - An exception is generated if you try to lock a category that doesn't exist.
See UnlockCategories.
UnlockCategories
Locks a variable in the default category or an explicit category. A locked variable can not be set.
To set a locked variable, FORCE_LOCK can be used. FORCE_LOCK usually pinpoints a problem in your configuration.
$config->Lock(NAME => 'CC') ; $config->Lock(NAME => 'CC', CATEGORY => 'PARENT') ;
NAME => $variable_name - Name of the variable to lock
CATEGORY => $category - Name of the category containing the variable
Exceptions - An exception is generated if you try to lock a variable that doesn't exist.
See Set.
Unlocks the categories passed as argument.
$config->UnlockCategories('PARENT', 'OTHER') ;
@categories - a list of categories to unlock
See LockCategories.
Unlocks a variable in the default category or an explicit category.
$config->Unlock(NAME => 'CC') ; $config->Unlock(NAME => 'CC', CATEGORY => 'PARENT') ;
NAME => $variable_name - Name of the variable to unlock
Exceptions - An exception is generated if you pass a category that doesn't exist.
See Lock.
Lock
Query the lock state of a category.
$config->IsCategoryLocked('PARENT') ;
$category - Name of the category containing to query
Returns - A boolean
Exceptions - Querying the lock state of a category that doesn't exist generates an exception.
Query the lock state of a variable.
$config->IsLocked(NAME => 'CC') ; $config->IsLocked(NAME => 'CC', CATEGORY => 'PARENT') ;
NAME => $variable_name - Name of the variable to query
Optional, CATEGORY => $category - Name of the category containing the variable
Exceptions - Querying the lock state of a variable that doesn't exist does not generate an exception.
$config->Exists(NAME => 'CC') ;
Returns true if the variable exist, false otherwise. All the categories are checked.
NAME => $variable_name - Name of the variable to check
CATEGORIES_TO_EXTRACT_FROM => \@categories - list of category names
Returns a variable history.
$history = $config->GetHistory(NAME => 'CC') ; $history = $config->GetHistory(NAME => 'CC', CATEGORIES_TO_EXTRACT_FROM => ['PARENT']) ;
Returns - Returns a reference to the variable's history or an empty list if the variable doesn't exist.
my $config = new Config::Hierarchical ( NAME => 'Test config', CATEGORY_NAMES => ['PARENT', 'CURRENT'], DEFAULT_CATEGORY => 'CURRENT', INITIAL_VALUES => [ {NAME => 'CC', CATEGORY => 'PARENT', VALUE => 'parent'}, ] , ) ; $config->Set(NAME => 'CC', OVERRIDE => 1, VALUE => 'override value') ; my($value, $category) = $config->Get(NAME => 'CC', GET_CATEGORY => 1) ; my $title = "'CC' = '$value' from category '$category':" ; print DumpTree($config->GetHistory(NAME=> 'CC'), $title, DISPLAY_ADDRESS => 0) ;
Would print as:
'CC' = 'override value' from category 'CURRENT': |- 0 | |- EVENT = . CREATE AND SET. value = 'parent', category = 'PARENT' at 'nadim2.pl:21', status = OK. | `- TIME = 0 `- 1 |- EVENT = value = CREATE AND SET, OVERRIDE. 'override value', category = 'CURRENT' at 'nadim2.pl:34', status = | Overriding 'PARENT::CC' (existed, value was different).OK. `- TIME = 1
while
my($value, $category) = $config->Get(NAME => 'CC', GET_CATEGORY => 1, CATEGORIES_TO_EXTRACT_FROM => ['PARENT']) ; my $title = "'CC' = '$value' from category '$category':" ; print DumpTree($config->GetHistory(NAME=> 'CC', CATEGORIES_TO_EXTRACT_FROM => ['PARENT']), $title, DISPLAY_ADDRESS => 0) ;
'CC' = 'parent' from category 'PARENT': `- 0 |- EVENT = value = CREATE AND SET. 'parent', category = 'PARENT' at 'nadim2.pl:21', status = OK. `- TIME = 0
If you passed a HISTORY or a COMMENT when you created or modified a variable, that information will be included in the history structure returned by GetHistory.
my $config3 = new Config::Hierarchical ( NAME => 'config3', ... INITIAL_VALUES => [ { COMMENT => "history and value from category 2", NAME => 'CC', CATEGORY => 'PARENT', VALUE => $value2, HISTORY => $history2, }, ] , ... ) ; my($value3, $category3) = $config3->Get(NAME => 'CC', GET_CATEGORY => 1) ; my $title3 = "'CC' = '$value3' from category '$category3':" ; my $history3 = $config3->GetHistory(NAME=> 'CC') ; print DumpTree($history3, $title3, DISPLAY_ADDRESS => 0) ;
'CC' = '3' from category 'PARENT': |- 0 | |- COMMENT = history and value from config 2 | |- EVENT = CREATE, SET HISTORY AND SET. value = '3', category = 'PARENT' at 'history.pl:56', status = OK. | |- HISTORY | | |- 0 ...
if you used an aliased category, The history structure returned by GetHistory will automatically include the history of the aliased config.
my $config0 = (...) ; my $config1 = (...) ; my $config2 = new Config::Hierarchical ( ... INITIAL_VALUES => [ { CATEGORY => 'PBS', ALIAS_CATEGORY => $config1, HISTORY => ...., COMMENT => ...., }, ... ) ; ... print DumpTree $config_3->GetHistory( NAME => 'CC1'), 'CC1', DISPLAY_ADDRESS => 0;
CC1 |- 0 | |- HISTORY FROM ALIASED CATEGORY 'config 1' | | |- 0 | | | |- HISTORY FROM ALIASED CATEGORY 'config 0' | | | | `- 0 | | | | |- EVENT = CREATE AND SET. value = '1', category = 'CURRENT' at 'nadim.pl:21', status = OK. | | | | `- TIME = 0 | | | `- TIME = 2 | | |- 1 | | | |- EVENT = CREATE AND SET. value = '1', category = 'A' at 'nadim.pl:33', status = OK. | | | `- TIME = 3 | | `- 2 | | |- EVENT = Set. value = '1.1', category = 'A' at 'nadim.pl:50', status = OK. | | `- TIME = 6 | `- TIME = 3 |- 1 | |- EVENT = CREATE AND SET, OVERRIDE. value = 'A', category = 'A' at 'nadim.pl:64', status = OK. | `- TIME = 4 `- 2 |- EVENT = SET, OVERRIDE. value = 'A2', category = 'A' at 'nadim.pl:65', status = OK. `- TIME = 5
Given the following Data::TreeDumper filter
sub Compact { my ($s, $level, $path, $keys, $setup, $arg) = @_ ; if('ARRAY' eq ref $s) { my ($index, @replacement, @keys) = (0) ; for my $entry( @$s) { if(exists $entry->{EVENT}) { push @replacement, $entry->{EVENT} ; #. 'time: ' . $entry->{TIME}; push@keys, $index++ ; } else { my ($aliased_history_name) = grep {$_ ne 'TIME'} keys %$entry ; push @replacement, $entry->{$aliased_history_name} ; push@keys, [$index, "$index = $aliased_history_name"] ; $index++ ; } } return('ARRAY', \@replacement, @keys) ; } } print DumpTree $config_2->GetHistory( NAME => 'CC1'), 'CC1', DISPLAY_ADDRESS => 0, FILTER => \&Compact ;
the above output becomes:
CC1 |- 0 = HISTORY FROM ALIASED CATEGORY 'config 1' | |- 0 = HISTORY FROM ALIASED CATEGORY 'config 0' | | `- 0 = CREATE AND SET. value = '1', category = 'CURRENT' at 'nadim.pl:21', status = OK. | |- 1 = CREATE AND SET. value = '1', category = 'A' at 'nadim.pl:33', status = OK. | `- 2 = SET. value = '1.1', category = 'A' at 'nadim.pl:50', status = OK. |- 1 = CREATE AND SET, OVERRIDE. value = 'A', category = 'A' at 'nadim.pl:64', status = OK. `- 2 = SET, OVERRIDE. value = 'A2', category = 'A' at 'nadim.pl:65', status = OK.
Note that comments are also removed.
This shall not be used directly. Use GetHistory.
Returns a dump, of the variable history, generated by Data::TreeDumper::DumpTree.
$dump = $config->GetHistoryDump(NAME => 'CC') ; $dump = $config->GetHistoryDump(CATEGORIES_TO_EXTRACT_FROM => ['A', 'B'], NAME => 'CC', DATA_TREEDUMPER_OPTIONS => []) ;
Optional, CATEGORIES_TO_EXTRACT_FROM => \@categories - list of category names
See Data::TreeDumper.
Returns a list of all the Config::Hierarchical accesses.
my $config = new Config::Hierarchical( LOG_ACCESS => 1, ...) ; my $value = $config->Get(NAME => 'A') ; $value = $config->Get(NAME => 'B') ; $value = $config->Get(NAME => 'A', CATEGORIES_TO_EXTRACT_FROM => ['PARENT']) ; my $access_log = $config->GetAccessLog() ;
would return the following structure :
access log: |- 0 | |- FILE = test.pl | |- LINE = 28 | `- NAME = A |- 1 | |- FILE = test.pl | |- LINE = 29 | `- NAME = B `- 2 |- CATEGORIES_TO_EXTRACT_FROM | `- 0 = PARENT |- FILE = test.pl |- LINE = 30 `- NAME = A
Returns - An array reference containing all the read accesses.
If LOG_ACCESS was not set, an empty array reference is returned.
$dump = $config->GetDump(@data_treedumper_options) ; $dump = $config->GetDump(@data_treedumper_options) ;
@data_treedumper_options - A list of options forwarded to Data::TreeDumper::DumpTree.
A dump, of the Config::Hierarchical object, generated by Data::TreeDumper::DumpTree.
None so far.
Khemir Nadim ibn Hamouda CPAN ID: NKH mailto:nadim@khemir.net
Copyright 2006-2007 Khemir Nadim. All rights reserved.
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
You can find documentation for this module with the perldoc command.
perldoc Config::Hierarchical
You can also look for information at:
AnnoCPAN: Annotated CPAN documentation
http://annocpan.org/dist/Config-Hierarchical
RT: CPAN's request tracker
Please report any bugs or feature requests to L <bug-config-hierarchical@rt.cpan.org>.
We will be notified, and then you'll automatically be notified of progress on your bug as we make changes.
Search CPAN
http://search.cpan.org/dist/Config-Hierarchical
Config::Hierarchical::Tie::ReadOnly
Config::Hierarchical::Delta
To install Config::Hierarchical, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Config::Hierarchical
CPAN shell
perl -MCPAN -e shell install Config::Hierarchical
For more information on module installation, please visit the detailed CPAN module installation guide.