NAME

    Config::Entities - An multi-level overridable perl based configuration
    module

VERSION

    version 1.02

SYNOPSIS

        use Config::Entities;
    
        # Assuming this directory structure:
        #
        # /project/config/entities
        # |_______________________/a
        # |_________________________/b.pm
        # | { e => 'f' }
        # |
        # |_______________________/c.pm
        # | { g => 'h' }
        # |
        # |_______________________/c
        # |_________________________/d.pm
        # | { i => 'j' };
        my $entities = Config::Entities->new( '/project/config/entities' );
        my $abe = $entities->{a}{b}{e};    # 'f'
        my $ab = $entities->{a}{b};        # '{e=>'f'}
        my $ab_e = $ab->{e};               # 'f'
        my $cg = $entities->{c}{g};        # 'h'
        my $cd = $entities->{c}{d};        # {i=>'j'}
        my $cdi = $entities->{c}{d}{i};    # 'j'
        my $c = $entities->{c};            # {g=>'h',d=>{i=>'j'}}
    
        # Entities can be constructed with a set of properties to be used by configs.
        # Assuming this directory structure:
        #
        # /project/config/entities
        # |_______________________/a.pm
        # | { 
        # |     file => $Config::Entities::properties->{base_folder}
        # |         . '/sub/folder/file.txt'
        # | }
        my $entities = Config::Entities->new( '/project/config/entities',
            { properties => { base_folder => '/project' } } );
        my $file = $entities->{a}{file}; # /project/sub/folder/file.txt
    
        # You can also supply multiple entities folders
        # Assuming this directory structure:
        #
        # /project/config
        # |______________/entities
        # |_______________________/a.pm
        # | { b => 'c' } 
        # |
        # |______________/more_entities
        # |____________________________/d.pm
        # | { e => $Config::Entities::properties->{f} } 
        my $entities = Config::Entities->new( 
            '/project/config/entities',
            '/project/config/more_entities',
            { properties => {f => 'g'} } );     # { b => 'c', e => 'g' }
        
        # You can also specify a properties file  
        # Assuming this directory structure:
        #
        # /project/config
        # |______________/entities
        # |_______________________/a.pm
        # | { b => $Config::Entities::properties->{e} } 
        # |
        # |______________/properties.pl
        # | { e => 'f' } 
        my $entities = Config::Entities->new( 
            '/project/config/entities',
            { properties_file => '/project/config/properties.pl } );
        my $ab = $entities->{a}{b}; # 'f'
        
        # Assuming:
        #
        # {
        #     a => {
        #         b => {
        #             c => 'd',
        #             e => 'f'
        #         },
        #         g => 'h'
        #     }       
        # }
        #
        # You can use dotted notation to refer to entities using get_entity
        my $ab = $entities->get_entity( 'a.b' );    # {c=>'d',e=>'f'}
        # You can fill a hash with many values at once using fill
        my $ab_abc_abe = $entities->fill( 'a.b', 
            {c=>undef, e=>undef} );                 # {c=>'d',e=>'f'}
        # Perhaps the most useful approach is filling a hash from a coordinate
        # or its parents
        my $ab_abc_abe_ag = $entities->fill( 'a.b',
            {c=>undef, e=>undef, g=>undef}, 
            ancestry => 1 );                        # {c=>'d',e=>'f',g=>'h'}

DESCRIPTION

    In essense, this module will recurse a directory structure, running do
    FILE for each entry and merging its results into the Entities object
    which can be treated as a hash. Given that it runs do FILE, each config
    node is a fully capable perl script.

CONSTRUCTORS

 new( $entities_root_dir [, $entities_root_dir, ...] \%options )

    Recurses into each $entities_root_dir loading its contents into the
    entities map. The filesystem structure will be propagated to the map,
    each sub folder representing a sub hash. If both Xxx.pm and a folder
    Xxx are found, the Xxx.pm will be loaded first then the recursion will
    enter Xxx and merge its results over the top of what is already in the
    map. If properties are provided via properties or properties_file, they
    can be accessed using Config::Entities::properties in the individual
    config files. The currently available options are:

    entity

      A hashref containing configuration. Will be overriden by the contents
      of any $entities_root_dir's that are passed in.

    properties

      Properties to be loaded into Config::Entities::properties. Will
      override any properties with the same name loaded by properties_file.

    properties_file

      A file that will be loaded into Config::Entities::properties using do
      FILE

METHODS

 fill( $coordinate, $hashref, [%options] )

    Will iterate through the keys of $hashref setting the associated value
    to the value found at the same key in the entity matching $coordinate.
    If the supplied $hashref has a key whose value is
    'Config::Entities::entity' and the key is not found in the entity at
    $coordinate the value in $hashref will be set to the entity itself. The
    currently available options are:

    ancestry

      If true, the search will continue up the ancestry until it finds a
      match.

 get_entity( $coordinate, [%options] )

    A simple dotted notation for indexing into the map. For example,
    $entities-get_entity( 'a.b.c' )> is equivalent to $entities-{a}{b}{c}.
    The currently available options are:

    ancestry

      If true, a list will be returned where the first element is the
      matching entity, and each successive entity is its parent, all the
      way up to $self.

AUTHOR

    Lucas Theisen <lucastheisen@pastdev.com>

COPYRIGHT AND LICENSE

    This software is copyright (c) 2014 by Lucas Theisen.

    This is free software; you can redistribute it and/or modify it under
    the same terms as the Perl 5 programming language system itself.