/ 
Badger-0.16
River stage one • 4 direct dependents • 7 total dependents
/ Badger::Config::Filesystem

NAME

Badger::Config::Filesystem - reads configuration files in a directory

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

This module is a subclass of Badger::Config for reading data from configuration files in a directory.

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

root / directory / dir

The root (or directory or dir if you prefer) option must be provided to specify the directory that the module should load configuration files from. Directories can be specified as absolute paths or relative to the current working directory.

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

data

Any additional configuration data can be provided via the data named parameter:

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

encoding

The character encoding of the configuration files. Defaults to utf8.

extensions

A list of file extensions to try in addition to yaml and json. Note that you may also need to define a codecs entry to map the file extension to a data encoder/decoder module.

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

codecs

File extensions like .yaml and .json are recognised by Badger::Codecs which can then provide the appropriate Badger::Codec module to handle the encoding and decoding of data in the file. The codecs options can be used to provide mapping from other file extensions to Badger::Codec modules.

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

You may need to write a simple codec module yourself if there isn't one for the data format you want, but it's usually just a few lines of code that are required to provide the Badger::Codec wrapper module around whatever other Perl module or custom code you've using to load and save the data format.

schemas

TODO: document specification of item schemas. The items below (tree_type through uri_paths) must now be defined in a schema. Support for a default schema has temporarily been disabled/broken.

tree_type

This option can be used to sets the default tree type for any configuration items that don't explicitly declare it by other means. The default tree type is nest.

NOTE: this has been changed. Don't trust these docs.

The following tree types are supported:

nest

This is the default tree type, creating nested hash arrays of data.

flat

Creates a flat hash array by merging all nested hash array of data into one.

join

Joins data paths together using the tree_joint string which is _ by default.

uri

Joins data paths together using slash characters to create URI paths. An item in a sub-directory can have a leading slash (i.e. an absolute path) and it will be promoted to the top-level data hash.

e.g.

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

none

No tree is created. No sub-directories are scanned. You never saw me. I wasn't here.

tree_joint

This option can be used to set the default character sequence for joining paths

uri_paths

This option can be used to set the default uri_paths option for joining paths as URIs. It should be set to relative or absolute. It can be over-ridden in a schema section of a top-level configuration file.

METHODS

The module inherits all methods defined in the Badger::Config and Badger::Workplace base classes.

INTERNAL METHODS

The following methods are defined for internal use.

init($config)

This overrides the default initialisation method inherited from Badger::Config. It calls the init_config() method to perform the base class Badger::Config initialisation and then the init_filesystem() method to perform initialisation specific to the Badger::Config::Filesystem module.

init_filesystem($config)

This performs the initialisation of the object specific to the filesystem object.

head($item)

This redefines the head() method in the Badger::Config base class. The method is called by get() to fetch a top-level data item (e.g. user in $config->get('user.name')). This implementation looks for existing data items as usual, but additionally falls back on a call to fetch($item) to load additional data (or attempt to load it).

tail($item, $data)

This is a do-nothing stub for subclasses to redefine. It is called after a successful call to fetch().

fetch($item)

This is the main method called to load a configuration file (or tree of files) from the filesystem. It looks to see if a configuration file (with one of the known extensions appended, e.g. "$item.yaml", "$item.json", etc) exists and/or a directory named $item.

If the file exists but the directory doesn't then the configuration data is read from the file. If the directory exists

config_tree($item, $file, $dir)

This scans a configuration tree comprising of a configuration file and/or a directory. The $file and $dir arguments are optional and are only supported as an internal optimisation. The method can safely be called with a single $item argument and the relevant file and directory will be determined automatically.

The configuration file is loaded (via scan_config_file()). If the directory exists then it is also scanned (via scan_config_dir()) and the files contained therein are loaded.

scan_config_file($file, $data, $path, $schema, $binder)

Loads the data in a configuration $file and merges it into the common $data hash under the $path prefix (a reference to an array). The $schema contains any schema rules for this data item. The $binder is a reference to a tree_binder() method to handle the data merge.

scan_config_dir($dir, $data, $path, $schema, $binder)

Scans the diles in a configuration directory, $dir and recursively calls scan_config_dir() for each sub-directory found, and scan_config_file() for each file.

tree_binder($name)

This method returns a reference to one of the binder methods below based on the $name parameter provided.

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

If no $name is specified then it uses the default tree_type of nest. This can be changed via the tree_type configuration option.

nest_tree_binder($parent, $path, $child, $schema)

This handles the merging of data for the nest tree_type.

flat_tree_binder($parent, $path, $child, $schema)

This handles the merging of data for the flat tree_type.

uri_tree_binder($parent, $path, $child, $schema)

This handles the merging of data for the uri tree_type.

join_tree_binder($parent, $path, $child, $schema)

This handles the merging of data for the join tree_type.

config_file($name)

This method returns a Badger::Filesystem::File object representing a configuration file in the configuration directory. It will automatically have the correct filename extension added (via a call to config_filename) and the correct codec and encoding parameters set (via a call to config_filespec) so that the data in the configuration file can be automatically loaded (see config_data($name)).

config_file_data($name)

This method fetches a configuration file via a call to config_file() and then returns the data contained therein.

config_filespec($params)

Returns a reference to a hash array containing appropriate initialisation parameters for Badger::Filesystem::File objects created to read general and resource-specific configuration files. The parameters are constructed from the codecs (default: yaml) and encoding (default: utf8) configuration options. These can be overridden or augmented by extra parameters passed as arguments.

AUTHOR

Andy Wardley http://wardley.org/

COPYRIGHT

Copyright (C) 2008-2014 Andy Wardley. All Rights Reserved.

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