# NAME

Property::Lookup - multi-layer object property lookup

# SYNOPSIS

    use Property::Lookup;

    my %opt;
    GetOptions(\%opt, '...');

    my $config = Property::Lookup->new;
    $config->add_layer(file => 'conf.yaml');
    $config->add_layer(hash => \%opt);
    $config->default_layer({
        foo => 23,
    });

    my $foo = $config->foo;

    # ...

    use Property::Lookup::Local;
    local %Property::Lookup::Local::opt = (bar => 'baz');

# DESCRIPTION

This module provides a way to look up an object property in a layer of
objects. The user can define various layers; when the user asks this main
object to look up a key, it will ask each layer in turn whether it has a value
for the given key. When a layer responds, that answer will be returned to the
user and no more layers will be asked.

This is useful in application configuration. Suppose you have a configuration
file, which is your primary mechanism for configuring the application. But the
user should also be able to override individual values using command line
arguments. And even if a key is found neither on the command line nor in the
configuration file, you want to provide a default.

This scenario is easy to implement with this module.

Because application configuration is the primary intended use, this module is
a singleton.

# METHODS

- `new`

Creates the singleton object.

- `instance`

Synonymous for `new`.

- `init`

Called when the object is constructed, it initializes the local and default layers.

- `local_layer`

    local %Property::Lookup::Local::opt = (bar => 'baz');

This is initialized as a [Property::Lookup::Local](http://search.cpan.org/search?mode=module&query=Property::Lookup::Local) object. It can be used to
temporarily override lookup values; if you use `local`, the values will
automatically forgotten at the end of the current scope. When a property is
looked up via `AUTOLOAD`, this layer is always checked first.

- `default_layer`

    my $config = Property::Lookup->new;
    $config->default_layer({ foo => 42 });

This is initialized as a [Property::Lookup::Hash](http://search.cpan.org/search?mode=module&query=Property::Lookup::Hash) object. It can be used to
set default values. When a property is looked up via `AUTOLOAD`, this layer
is always checked last.

- `add_layer`

This method adds a layer to the singleton lookup object. The first argument
determines which kind of layer is added; the rest are arguments passed to the
layer. The first argument can be `file` to construct a file lookup layer, or
`hash` to construct a hash lookup layer.

    my $config = Property::Lookup->new;
    $config->add_layer(file => 'conf.yaml');

With `file`, a layer of class [Property::Lookup::File](http://search.cpan.org/search?mode=module&query=Property::Lookup::File) is constructed. The
second argument is the name of the YAML file from which values are taken.

    my $config = Property::Lookup->new;
    $config->add_layer(hash => \%opt);

With `hash`, a layer of class [Property::Lookup::Hash](http://search.cpan.org/search?mode=module&query=Property::Lookup::Hash) is constructed. The
second argument is the name of the YAML file from which values are taken.

If the layer-specific arguments are wrong, or the layer type is not one of the
names given above, an exception occurs.

- `AUTOLOAD`

Determines which method was called, then asks every layer in turn. It returns
the first defined answer it finds. The local layer is special - it always
comes first, no matter which layers have been specified. Likewise for the
default layer, which always comes last.

- `DEFAULTS`

This accessor is used by [Class::Accessor::Constructor](http://search.cpan.org/search?mode=module&query=Class::Accessor::Constructor). It is defined as an
empty list here so `AUTOLOAD` won't try to handle it.

- `FIRST_CONSTRUCTOR_ARGS`

This accessor is used by [Class::Accessor::Constructor](http://search.cpan.org/search?mode=module&query=Class::Accessor::Constructor). It is defined as an
empty list here so `AUTOLOAD` won't try to handle it.

# BUGS AND LIMITATIONS

No bugs have been reported.

Please report any bugs or feature requests through the web interface at
<http://rt.cpan.org>.

# INSTALLATION

See perlmodinstall for information and options on installing Perl modules.

# AVAILABILITY

The latest version of this module is available from the Comprehensive Perl
Archive Network (CPAN). Visit <http://www.perl.com/CPAN/> to find a CPAN
site near you. Or see <http://search.cpan.org/dist/Property-Lookup/>.

The development version lives at <http://github.com/hanekomu/property-lookup/>.
Instead of sending patches, please fork this project using the standard git
and github infrastructure.

# AUTHORS

Marcel Gr&uuml;nauer, `<marcel@cpan.org>`

# COPYRIGHT AND LICENSE

Copyright 2009 by Marcel Gr&uuml;nauer

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