NAME

App::Reference - a Perl reference, blessed so it can be accessed with methods

SYNOPSIS

   use App::Reference;

   $ref = App::Reference->new();
   $ref = App::Reference->new("file" => $file);
   print $ref->dump(), "\n";   # use Data::Dumper to spit out the Perl representation

   # accessors
   $property_value = $ref->get($property_name);
   $branch = $ref->get_branch($branch_name,$create_flag);  # get hashref
   $ref->set($property_name, $property_value);

   # on-demand loading helper methods (private methods)
   $ref->overlay($ref2);        # merge the two structures using overlay rules
   $ref->overlay($ref1, $ref2);  # merge $ref2 onto $ref1
   $ref->graft($branch_name, $ref2);  # graft new structure onto branch

DESCRIPTION

App::Reference is a very thin class which wraps a few simple methods around a perl reference which may contain a multi-level data structure.

Class: App::Reference

    * Throws: App::Exception
    * Since:  0.01

Requirements

The App::Reference class satisfies the following requirements.

    o Minimum performance penalty to access perl data
    o Ability to bless any reference into this class
    o Ability to handle ARRAY and HASH references

Constructor Methods:

new()

This constructor is used to create Reference objects. Customized behavior for a particular type of Reference is achieved by overriding the _init() method.

    * Signature: $ref = App::Reference->new($array_ref)
    * Signature: $ref = App::Reference->new($hash_ref)
    * Signature: $ref = App::Reference->new("array",@args)
    * Signature: $ref = App::Reference->new(%named)
    * Param:     $array_ref          []
    * Param:     $hash_ref           {}
    * Return:    $ref                App::Reference
    * Throws:    App::Exception
    * Since:     0.01

    Sample Usage:

    use "App::Reference";

    $ref = App::Reference->new("array", "x", 1, -5.4, { pi => 3.1416 });
    $ref = App::Reference->new( [ "x", 1, -5.4 ] );
    $ref = App::Reference->new(
        arg1 => 'value1',
        arg2 => 'value2',
    );

Public Methods:

get()

    * Signature: $property_value = $ref->get($property_name);
    * Param:     $property_name    string
    * Return:    $property_value   string
    * Throws:    App::Exception
    * Since:     0.01

    Sample Usage: 

    $dbi    = $ref->get("Repository.default.dbi");
    $dbuser = $ref->get("Repository.default.dbuser");
    $dbpass = $ref->get("Repository.default.dbpass");

get_branch()

    * Signature: $branch = $ref->get_branch($branch_name);
    * Param:     $branch_name  string
    * Return:    $branch       {}
    * Throws:    App::Exception
    * Since:     0.01

    Sample Usage: 

    $branch_name = "Repository.default";
    $branch = $ref->get_branch($branch_name);
    foreach $key (keys %$branch) {
        $property = "${branch_name}.${key}";
        print $property, "=", $branch->{$key}, "\n";
    }
    $dbi    = $branch->{dbi};
    $dbuser = $branch->{dbuser};
    $dbpass = $branch->{dbpass};

set()

    * Signature: $ref->get($property_name, $property_value);
    * Param:     $property_name    string
    * Param:     $property_value   string
    * Throws:    App::Exception
    * Since:     0.01

    Sample Usage: 

    $dbi    = $ref->get("Repository.default.dbi");
    $dbuser = $ref->get("Repository{default}{dbuser}");
    $dbpass = $ref->get("Repository.default{dbpass}");

overlay()

    * Signature: $ref->overlay($ref2);
    * Signature: $ref->overlay($ref1, $ref2);
    * Param:     $ref1      {}
    * Param:     $ref2      {}
    * Return:    void
    * Throws:    App::Exception
    * Since:     0.01

    Sample Usage: 

    # merge the two config structures using overlay rules
    $ref->overlay($ref2);

    # merge $ref2 onto $ref1
    $ref->overlay($ref1, $ref2);

NOTE: right now, this just copies top-level keys of a hash reference from one hash to the other.

TODO: needs to nested/recursive overlaying

graft()

    * Signature: $ref->graft($branch_name, $ref2);
    * Param:     $branch_name   string
    * Param:     $ref2       {}
    * Return:    void
    * Throws:    App::Exception
    * Since:     0.01

    Sample Usage: 

    # graft new config structure onto branch
    $ref->graft($branch_name, $ref2);

dump()

    * Signature: $perl = $ref->dump();
    * Param:     void
    * Return:    $perl      text
    * Throws:    App::Exception
    * Since:     0.01

    Sample Usage: 

    $ref = $context->config();
    print $ref->dump(), "\n";

print()

    * Signature: $ref->print();
    * Param:     void
    * Return:    void
    * Throws:    App::Exception
    * Since:     0.01

    Sample Usage: 

    $context->print();

Protected Methods:

The following methods are intended to be called by subclasses of the current class.

create()

The create() method is used to create the Perl structure that will be blessed into the class and returned by the constructor. It may be overridden by a subclass to provide customized behavior.

    * Signature: $ref = App::Reference->create("array", @args)
    * Signature: $ref = App::Reference->create($arrayref)
    * Signature: $ref = App::Reference->create($hashref)
    * Signature: $ref = App::Reference->create($hashref, %named)
    * Signature: $ref = App::Reference->create(%named)
    * Param:     $hashref            {}
    * Param:     $arrayref           []
    * Return:    $ref                ref
    * Throws:    App::Exception
    * Since:     0.01

    Sample Usage:

_init()

The _init() method is called from within the standard Reference constructor. The _init() method in this class does nothing. It allows subclasses of the Reference to customize the behavior of the constructor by overriding the _init() method.

    * Signature: _init($named)
    * Param:     $named        {}    [in]
    * Return:    void
    * Throws:    App::Exception
    * Since:     0.01

    Sample Usage: 

    $ref->_init($args);

Private Methods:

The following methods are intended to be called only within this class.

ACKNOWLEDGEMENTS

    * Author:  Stephen Adkins <spadkins@gmail.com>
    * License: This is free software. It is licensed under the same terms as Perl itself.

SEE ALSO

none

cpanm App::Context

perl -MCPAN -e shell
install App::Context