NAME

SYNOPSIS

    use Badger::Config::Filesystem;

    my $config = Badger::Config::Filesystem->new(
        root => 'path/to/some/dir'
    );

    # Fetch the data in user.[yaml|json] in above dir
    my $user = $config->get('user')
        || die "user: not found";

    # Fetch sub-data items using dotted syntax
    print $config->get('user.name');
    print $config->get('user.emails.0');

DESCRIPTION

Consider a directory that contains the following files and sub-directories:

    config/
        site.yaml
        style.yaml
        pages.yaml
        pages/
            admin.yaml
            developer.yaml

We can create a Badger::Config::Filesystem object to read the configuration data from the files in this directory like so:

    my $config = Badger::Config::Filesystem->new(
        root => 'config'
    );

Reading the data from "site.yaml" is as simple as this:

    my $site = $config->get('site');

Note that the file extension is not required. You can have either a "site.yaml" or a "site.json" file in the directory and the module will load whichever one it finds first. It's possible to add other data codecs if you want to use something other than YAML or JSON.

You can also access data from within a configuration file. If the "site.yaml" file contains the following:

    name:    My Site
    version: 314
    author:
      name:  Andy Wardley
      email: abw@wardley.org

Then we can read the version and author name like so:

    print $config->get('site.version');
    print $config->get('author.name');

If the configuration directory contains a sub-directory with the same name as the data file being loaded (minus the extension) then any files under that directory will also be loaded. Going back to our earlier example, the "pages" item is such a case:

    config/
        site.yaml
        style.yaml
        pages.yaml
        pages/
            admin.yaml
            developer.yaml

There are three files relevant to "pages" here. Let's assume the content of each is as follow:

pages.yaml:

    one:        Page One
    two:        Page Two

pages/admin.yaml:

    three:      Page Three
    four:       Page Four

pages/developer.yaml:

    five:       Page Five

When we load the "pages" data like so:

    my $pages = $config->get('pages');

We end up with a data structure like this:

    {
        one   => 'Page One',
        two   => 'Page Two',
        admin => {
            three => 'Page Three',
            four  => 'Page Four',
        },
        developer => {
            five  => 'Page Five',
        },
    }

Note how the "admin" and "developer" items have been nested into the data. The filename base (e.g. "admin", "developer") is used to define an entry in the "parent" hash array containing the data in the "child" data file.

The "tree_type" option can be used to change the way that this data is merged. To use this option, put it in a "schema" section in the top level configuration file, e.g. the "pages.yaml":

pages.yaml:

    one:        Page One
    two:        Page Two
    schema:
      tree_type: flat

If you don't want the data nested at all then specify a "flat" value for "tree_type". This would return the following data:

    {
        one   => 'Page One',
        two   => 'Page Two',
        three => 'Page Three',
        four  => 'Page Four',
        five  => 'Page Five',
    }

The "join" type collapses the nested data files by joining the file path (without extension) onto the data items contain therein. e.g.

    {
        one             => 'Page One',
        two             => 'Page Two',
        admin_three     => 'Page Three',
        admin_four      => 'Page Four',
        developer_five  => 'Page Five',
    }

You can specify a different character sequence to join paths via the "tree_joint" option, e.g.

    schema:
      tree_type:  join
      tree_joint: '-'

That would producing this data structure:

    {
        one             => 'Page One',
        two             => 'Page Two',
        admin-three     => 'Page Three',
        admin-four      => 'Page Four',
        developer-five  => 'Page Five',
    }

The "uri" type is a slightly smarter version of the "join" type. It joins path elements with the "/" character to create URI paths.

    {
        one             => 'Page One',
        two             => 'Page Two',
        admin/three     => 'Page Three',
        admin/four      => 'Page Four',
        developer/five  => 'Page Five',
    }

What makes it special is that it follows the standard rules for URI resolution and recognises a path with a leading slash to be absolute rather than relative to the current location.

For example, the pages/admin.yaml file could contain something like this:

pages/admin.yaml:

    three:      Page Three
    /four:      Page Four

The "three" entry is considered to be relative to the "admin" file so results in a final path of "admin/three" as before. However, "/four" is an absolute path so the "admin" path is ignored. The end result is a data structure like this:

    {
        one             => 'Page One',
        two             => 'Page Two',
        admin/three     => 'Page Three',
        /four           => 'Page Four',
        developer/five  => 'Page Five',
    }

In this example we've ended up with an annoying inconsistency in that our "/four" path has a leading slash when the other items don't. The "uri_paths" option can be set to "relative" or "absolute" to remove or add leading slashes respectively, effectively standardising all paths as one or the other.

    schema:
      tree_type:  uri
      uri_paths:  absolute

The data would then be returned like so:

    {
        /one            => 'Page One',
        /two            => 'Page Two',
        /admin/three    => 'Page Three',
        /four           => 'Page Four',
        /developer/five => 'Page Five',
    }

CONFIGURATION OPTIONS

    my $config = Badger::Config::Filesystem->new(
        dir => 'path/to/config/dir'
    );

    my $config = Badger::Config::Filesystem->new(
        dir  => 'path/to/config/dir'
        data => {
            name  => 'Arthur Dent',
            email => 'arthur@dent.org',
        },
    );

    my $config = Badger::Config::Filesystem->new(
        dir        => 'path/to/config/dir'
        extensions => ['str'],
        codecs     => {
            str    => 'storable',
        }
    );

    my $config = Badger::Config::Filesystem->new(
        dir        => 'path/to/config/dir'
        extensions => ['str'],
        codecs     => {
            str    => 'storable',   # *.str files loaded via storable codec
        }
    );

    foo/bar + baz  = foo/bar/baz
    foo/bar + /bam = /bam

METHODS

INTERNAL METHODS

    # returns a reference to the nest_binder() method
    my $binder = $config->tree_binder('nest');

AUTHOR

COPYRIGHT

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