# NAME

Config::Path

# VERSION

version 0.13

# SYNOPSIS

    use Config::Path;

    my $conf = Config::Path->new(
        files => [ 't/conf/configA.yml', 't/conf/configB.yml' ]
    );

    # Or, if you want to load all files in a directory

    my $dconf = Config::Path->new(
        directory => 'myapp/conf'
    );

    # If you *DON'T* want to convert empty hashes and arrays to undef
    # (XML parsing will return <foo></foo> as {})
    my $conf2 = Config::Path->new(
        convert_empty_to_undef => 0
    );

# DESCRIPTION

Config::Path is a Yet Another Config module with a few twists that were desired
for an internal project:

- Multiple files merged into a single, flat hash
- Path-based configuration value retrieval
- Support for loading all config files in a directory
- Sane precedence for key collisions
- Clean, simple implementation

## Multiple-File Merging

If any of your config files contain the same keys, the "right" file wins, using
[Hash::Merge](http://search.cpan.org/perldoc?Hash::Merge)'s RIGHT_PRECEDENT setting.  In other words, later file's keys
will have precedence over those loaded earlier.

Note that when a full directory of files are loaded the files are sorted via
Perl's `sort` before merging so as to remove any amigiuity about the order
in which they will be loaded.

## Directory Slurping

If you specify a value for the `directory` attribute, rather than the `files`
attribute then Config::Path will attempt to load all the files in the supplied
directory via Config::Any.  __The files will be merged in alphabetical order
so that there is no ambiguity in the event of a key collision.  Files later
in the alphabet will override keys of their predecessors.__

## Arrays

Arrays can be accessed with paths like `foo/0/bar`.  Just use the array index
to descend into that element.  If you attempt to treat a hash like an array
or an array like hash you will simply get `undef` back.

# NAME

Config::Path - Path-like config API with multiple file support, directory
loading and arbitrary backends from Config::Any.

# ATTRIBUTES

## config_options

HashRef of options passed to Config::Any.

## directory

A directory in which files should be searched for.  Note that this option is
mutually-exclusive to the `files` attribute.  Only set one of them.

## files

The list of files that will be parsed for this configuration.  Note that this
option is mutually-exclusive to the `files` attribute.  Only set one of them.

## convert_empty_to_undef

Defaults to true, if this option is set to false then entities
fetched that are {} or [] will be kept in tact.

Otherwise Config::Path converts these to undef.

# METHODS

## add_file ($file)

Adds the supplied filename to the list of files that will be loaded.  Note
that adding a file after you've already loaded a config will not change
anything.  You'll need to call `reload` if you want to reread the
configuration and include the new file.

## clear_mask

Clear all values covered by `mask`.

## fetch ($path)

Get a value from the config file.  As per the name of this module, fetch takes
a path argument in the form of `foo/bar/baz`.  This is effectively a
shorthand way of expressing a series of hash keys.  Whatever value is on
the end of the keys will be returned.  As such, fetch might return undef,
scalar, arrayref, hashref or whatever you've stored in the config file.

  my $foo = $config->fetch('baz/bar/foo');

Note that leading slashes will be automatically stripped, just in case you
prefer the idea of using them.  They are effectively useless though.

## mask ('path/to/value', 'newvalue')

Override the specified key to the specified value. Note that this only changes
the path's value in this instance. It does not change the config file. This is
useful for tests.  Note that `exists` is used so setting a path to undef
will not clear the mask.  If you want to clear masks use `clear_mask`.

## reload

Rereads the config files specified in `files`.  Well, actually it just blows
away the internal state of the config so that the next call will reload the
configuration. Note that this also clears any `mask`ing you've done.

# AUTHOR

Cory G Watson, `<gphat at cpan.org>`

# ACKNOWLEDGEMENTS

 Jay Shirley
 Mike Eldridge

# COPYRIGHT & LICENSE

Copyright 2010 Magazines.com

This program is free software; you can redistribute it and/or modify it
under the terms of either: the GNU General Public License as published
by the Free Software Foundation; or the Artistic License.

See http://dev.perl.org/licenses/ for more information.

# AUTHOR

Cory G Watson <gphat@cpan.org>

# COPYRIGHT AND LICENSE

This software is copyright (c) 2012 by Cold Hard Code, LLC.

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