نديم ابن ﺤﻣﻮﺪﺓ الخمير - Nadim Khemir > Config-Hierarchical > Config::Hierarchical

Download:
Config-Hierarchical-0.13.9.tar.gz

Dependencies

Annotate this POD

CPAN RT

New  1
Open  0
View/Report Bugs
Module Version: 0.13   Source  

NAME ^

 Config::Hierarchical - Hierarchical configuration container

SYNOPSIS ^

  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() ;

DESCRIPTION ^

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.

DOCUMENTATION ^

I'll start by giving a usage example. In a build system, configuration variables can have different source.

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/METHODS ^

Subroutines that are not part of the public interface are marked with [p].

new(@named_arguments)

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

GetInformation()

Arguments - None

Returns

[p] Setup

Helper sub called by new. This shall not be used directly.

[p] SetInteractionDefault

Sets {INTERACTION} fields that are not set by the user.

[p] SetupCategories

Helper sub called by new.

AddValidator(CATEGORY_NAMES => \@categories, NAMES => \@names, VALIDATORS => \%validators)

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

Arguments

Returns - Nothing

Config::Hierarchical will warn you if you override a validator.

[p] AddValidators

[p] AddVariableValidator

[p] SetCategoryAlias

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.

Arguments

[p] CreateCustomGetFunctions

Creates custom Get* functions.

[p] CheckOptionNames

Verifies the options passed to the members of this class. Calls {INTERACTION}{DIE} in case of error.

Set(@named_arguments)

  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

History

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.

Using EVAL instead for VALUE

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:

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.

[p] CheckSetArguments

Checks input to Set.

[p] CheckHigherPriorityCategories

Check if a config variable setting overrides a higher priority category.

[p] CheckVariableInCategory

[p] OverrideVariable

[p] CheckLowerPriorityCategories

Check if a config variable setting takes precedence over a lower priority category.

[p] CheckAndSetVariable

Set the variable in its category, verify lock, etc..

SetAttribute(NAME => $variable_name, ATTRIBUTE => $attribute, CATEGORY => $category)

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') ;

Arguments

Returns - Nothing

GetAttribute(NAME => $variable_name)

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') ;

Arguments

Returns - a list

Exceptions - This sub will raise an exception if you query a variable that does not exists.

[p] Validate

Get(@named_arguments)

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

Arguments

Returns

If GET_CATEGORY is not set:

If GET_CATEGORY is set:

Warnings

This function verifies its calling context and will generate a warning if it is called in void context.

[p] CheckCategoriesOrder

SetMultiple(\%options, \@variable_to_set, \@variable_to_set, ...)

Set multiple configuration in one call.

  $config->SetMultiple
        (
        {FORCE_LOCK => 1},
        
        [NAME => 'CC', VALUE => 'gcc', SILENT_OVERRIDE => 1],
        [NAME => 'LD', VALUE => 'ld'],
        ) ;

Arguments

Returns - Nothing

see Set.

GetMultiple(\%options, @variables_to_get)

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'
                        ) ;

Arguments

Option GET_CATEGORY will be ignored in this sub.

Returns - Nothing

see Get.

GetKeys()

  my @keys = $config->GetKeys() ;

Returns the names of the element in the config object.

Arguments

Returns

The list of variables contained in the Config::Hierarchical object.

Warnings

A warning will be generated if GetKeys is called in void context.

GetKeyValueTuples()

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

Returns

GetHashRef()

  my $hash_ref = $config->GetHashRef() ;

Arguments - None

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.

Warnings

GetHashRef will generate a warning if:

SetDisplayExplicitCategoryWarningOption($boolean)

  $config->SetDisplayExplicitCategoryWarningOption(1) ;
  $config->SetDisplayExplicitCategoryWarningOption(0) ;

Arguments

Return - Nothing

SetDisableSilentOptions($boolean)

  $config->SetDisableSilentOptions(1) ;
  $config->SetDisableSilentOptions(0) ;

Arguments

Return - Nothing

LockCategories(@categories)

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') ;

Arguments

Returns - Nothing

Exceptions - An exception is generated if you try to lock a category that doesn't exist.

See UnlockCategories.

Lock(NAME => $variable_name, CATEGORY => $category)

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') ;

Arguments

Returns - Nothing

Exceptions - An exception is generated if you try to lock a variable that doesn't exist.

See Set.

UnlockCategories(@categories)

Unlocks the categories passed as argument.

        $config->UnlockCategories('PARENT', 'OTHER') ;

Arguments

Returns - Nothing

See LockCategories.

Unlock(NAME => $variable_name, CATEGORY => $category)

Unlocks a variable in the default category or an explicit category.

  $config->Unlock(NAME => 'CC') ;
  $config->Unlock(NAME => 'CC', CATEGORY => 'PARENT') ;

Arguments

Returns - Nothing

Exceptions - An exception is generated if you pass a category that doesn't exist.

See Lock.

IsCategoryLocked($category)

Query the lock state of a category.

        $config->IsCategoryLocked('PARENT') ;

Arguments

Returns - A boolean

Exceptions - Querying the lock state of a category that doesn't exist generates an exception.

IsLocked(NAME => $variable_name, CATEGORY => $category)

Query the lock state of a variable.

  $config->IsLocked(NAME => 'CC') ;
  $config->IsLocked(NAME => 'CC', CATEGORY => 'PARENT') ;

Arguments

Returns - A boolean

Exceptions - Querying the lock state of a variable that doesn't exist does not generate an exception.

Exists(NAME => $variable_name, CATEGORIES_TO_EXTRACT_FROM => \@categories)

  $config->Exists(NAME => 'CC') ;

Returns true if the variable exist, false otherwise. All the categories are checked.

Arguments

Returns - A boolean

Exceptions - An exception is generated if you pass a category that doesn't exist.

GetHistory(NAME => $variable_name, CATEGORIES_TO_EXTRACT_FROM => \@categories)

Returns a variable history.

  $history = $config->GetHistory(NAME => 'CC') ;
  $history = $config->GetHistory(NAME => 'CC', CATEGORIES_TO_EXTRACT_FROM => ['PARENT']) ;

Arguments

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

Would print as:

        'CC' = 'parent' from category 'PARENT':
        `- 0 
           |- EVENT = value = CREATE AND SET. 'parent', category = 'PARENT' at 'nadim2.pl:21', status = OK. 
           `- TIME = 0 

Explicit history and comments

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

Would print as:

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

Aliased category history

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;

Would print as:

        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

Compact display

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.

[p] GetVariableHistory

This shall not be used directly. Use GetHistory.

GetHistoryDump(@named_arguments)

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 => []) ;

Arguments

Returns - Returns a reference to the variable's history or an empty list if the variable doesn't exist.

See Data::TreeDumper.

GetAccessLog()

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 

Arguments - None

Returns - An array reference containing all the read accesses.

If LOG_ACCESS was not set, an empty array reference is returned.

GetDump()

  $dump = $config->GetDump(@data_treedumper_options) ;
  $dump = $config->GetDump(@data_treedumper_options) ;

Arguments

Returns

A dump, of the Config::Hierarchical object, generated by Data::TreeDumper::DumpTree.

See Data::TreeDumper.

BUGS AND LIMITATIONS ^

None so far.

AUTHOR ^

        Khemir Nadim ibn Hamouda
        CPAN ID: NKH
        mailto:nadim@khemir.net

LICENSE AND COPYRIGHT ^

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.

SUPPORT ^

You can find documentation for this module with the perldoc command.

    perldoc Config::Hierarchical

You can also look for information at:

SEE ALSO ^

Config::Hierarchical::Tie::ReadOnly

Config::Hierarchical::Delta

syntax highlighting: