The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Config-Hierarchical-0.13.9
River stage zero No dependents
++
/ Config::Hierarchical::Delta

NAME

 Config::Hierarchical::Delta - Comparator for hashes and Config::Hierarchical objects

SYNOPSIS

        # comparing hashes:
        
        use Config::Hierarchical ; 
        use Config::Hierarchical::Delta qw (GetConfigDelta GetConfigHierarchicalDelta DumpConfigHierarchicalDelta Get_NoIdentical_Filter) ; 
        
        my $delta = GetConfigDelta
                                (
                                {name   => {A => 1, COMMON => 0}},
                                {name_2 => {B => 2, COMMON => 0}}
                                ) ;

$delta is a reference to the following hash:

        {
        'in \'name\' only'   => {'A' => 1},
        'in \'name_2\' only' => {'B' => 2},
        'identical'          => {'COMMON' => 0},
        },

        # comparing Config Hierarchical objects:
        
        my $config_0 = new Config::Hierarchical
                                (
                                NAME => 'config 0',
                                INITIAL_VALUES  =>
                                        [
                                        {NAME => 'CC1', VALUE => '1'},
                                        {NAME => 'CC2', VALUE => '2'},
                                        ] ,
                                ) ;
                                
        my $config_1 = new Config::Hierarchical
                                (
                                NAME => 'config 1',
                                CATEGORY_NAMES   => ['A', 'B',],
                                DEFAULT_CATEGORY => 'A',
                                
                                INITIAL_VALUES  =>
                                        [
                                        {CATEGORY => 'B', ALIAS => $config_0},
                                        
                                        {NAME => 'CC1', VALUE => '1'},
                                        {NAME => 'CC2', VALUE => '2'},
                                        {NAME => 'CC3', VALUE => '3'},
                                        ] ,
                                ) ;
                                
        $config_1->Set(NAME => 'CC1', VALUE => '1.1') ;
        
        my $config_2 = new Config::Hierarchical
                                (
                                NAME => 'config 2',
                                
                                CATEGORY_NAMES   => ['<A>', 'B',],
                                DEFAULT_CATEGORY => 'A',
                                INITIAL_VALUES   =>
                                        [
                                        {CATEGORY => 'B', ALIAS => $config_1},
                                        ] ,
                                ) ;
        
        $config_2->Set(CATEGORY => 'A', NAME => 'CC1', VALUE => 'A', OVERRIDE => 1) ;
        $config_2->Set(CATEGORY => 'A', NAME => 'XYZ', VALUE => 'xyz') ;
        
        my $dump = DumpConfigHierarchicalDelta($config_2, $config_0) ;

$dump contains the following string:

        Delta between 'config 2' and 'config 0'':
        |- different 
        |  `- CC1 
        |     |- config 0 = 1 
        |     `- config 2 = A 
        |- identical 
        |  `- CC2 = 2 
        `- in 'config 2' only 
           |- CC3 = 3 
           `- XYZ = xyz

DESCRIPTION

This module lets you compare hashes and Config::Hierarchical objects.

DOCUMENTATION

SUBROUTINES/METHODS

GetConfigDelta

        my $delta = GetConfigDelta
                                (
                                {name   => {A => 1, COMMON => 0}},
                                {name_2 => {B => 2, COMMON => 0}}
                                ) ;

GetConfigDelta compares two hashes and returns a reference to a hash containing up to 4 elements. It takes as argument two hash reference which contain a single element. The key is used as name for the hash while the value is a reference to the hash to be compared.

Returned elements:

  • identical

    Contains all the elements that are identical in both hashes as well as the value they have

  • different

    Contains the elements that are common in both hashes but with different values

  • in 'lhs' only

    Contains the elements that exists in the first hash but not in the second hash .

  • in 'rhs' only

    Contains the elements that exists in the first hash but not in the second hash .

GetConfigHierarchicalDelta

        my $config_1 = new Config::Hierarchical(...) ;
        my $config_2 = new Config::Hierarchical(...) ;
        
        GetConfigHierarchicalDelta($config_1, $config_2) ;

Compares two Config::Hierarchical objects and returns a reference to hash containing the delta between the objects. See GetConfigDeleta for a description of the returned hash.

The name of the Config::Variable object is extracted from the objects.

DumpConfigHierarchicalDelta

        my $config_1 = new Config::Hierarchical(...)
        my $config_2 = new Config::Hierarchical(...) ;
        
        print DumpConfigHierarchicalDelta($config_1, $config_2, QUOTE_VALUES => 1) ;

The first two arguments a Config::Hierarchical objects, the rest of the arguments are passed as is to Data::TreeDumper.

This sub returns a string containing the dump of the delta. See Synopsis for an output example.

Get_NoIdentical_Filter

Dumping a config delta with:

        print  DumpConfigHierarchicalDelta($config_2, $config_0) ;

Gives:

        $expected_dump = <<EOD ;
        Delta between 'config 2' and 'config 0'':
        |- different 
        |  `- CC1 
        |     |- config 0 = 1 
        |     `- config 2 = A 
        |- identical 
        |  `- CC2 = 2 
        `- in 'config 2' only 
           |- CC3 = 3 
           `- XYZ = xyz

if you do not want to display the configuration variables that are identical, use:

        print  DumpConfigHierarchicalDelta($config_2, $config_0, Get_NoIdentical_Filter()) ;

which gives:

        my $expected_dump = <<EOD ;
        Delta between 'config 2' and 'config 0'':
        |- different 
        |  `- CC1 
        |     |- config 0 = 1 
        |     `- config 2 = A 
        `- in 'config 2' only 
           |- CC3 = 3 
           `- XYZ = xyz 
        EOD

Returns a Data::TreeDumper filter you can use to remove the 'identical' element from the delta hash.

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