/ 
Activator-0.10
River stage zero No dependents
/ Activator::Registry

NAME

Activator::Registry - provide a registry based on YAML file(s)

SYNOPSIS

use Activator::Registry;

#### register $value to $key in realm $realm
Activator::Registry->register( $key, $value, $realm );

#### register $value to $key in default realm
Activator::Registry->register( $key, $value );

#### get value for $key from $realm
Activator::Registry->get( $key, $realm );

#### get value for $key from default realm
Activator::Registry->get( $key );

#### register YAML file into realm
Activator::Registry->register_file( $file, $realm );

#### register hash into realm
Activator::Registry->register_hash( $mode, $hashref, $realm );

DESCRIPTION

This module provides global access to a registry of key-value pairs. It is implemented as a singleton, so you can use this Object Oriented or staticly with arrow notation. It supports setting of deeply nested objects. (See "FUTURE WORK" for plans for deep getting.)

CONFIGURATION

This module expects (but does not require) an environment variable ACT_REG_YAML_FILE to be set. When set, this file is automatically loaded upon the first call to new().

If you are utilizing this module from apache, this directive must be in your httpd configuration:

SetEnv ACT_REG_YAML_FILE '/path/to/config.yml'

If you are using this module from a script, you need to insure that the environment is properly set using a BEGIN block BEFORE the use statement of any module that uses Activator::Registry itself:

BEGIN{
    $ENV{ACT_REG_YAML_FILE} ||= '/path/to/reg.yml'
}

Otherwise, you will get weirdness when all of your expected registry keys are undef...

METHODS

new ( $yaml )

    Create a new registry object. This is a singleton, so repeated calls always return the same ref. Optionally takes $yaml as an argument and will register that file.

register( $key, $value, $realm )

    Register a key-value pair to $realm. Registers to the default realm if $realm not defined. Returns true on success, false otherwise (more specifically, the return value of the eq operator).

register_file( $file, $realm)

    Register the contents of the 'Activator::Registry': heirarchy from within a YAML file, then merge it into the existing registry for the default realm, or optionally $realm.

register_hash( $mode, $right, $realm)

    Set registry keys in $realm from $right hash using $mode, which can either be left or right. left will only set keys that do not exist, and right will set or override all $right values into $realm's registry.

get( $key, $realm )

    Get the value for $key within $realm. If $realm not defined returns the value from the default realm.

get_realm( $realm )

    Return a reference to hashref for an entire $realm.

merge_hashes( $left_hr, $right_hr, $precedence )

    THIS DOES NOT WOIK.

    Merge two hashes together, return a reference to the new hash.

    When precedence is left(default), new keys are added from $right_hr. When precedence is right new keys are added from $left_hr.

    Precedent side's values never get stomped.

    See Hash::Merge for more information on merge methodology. This method uses the LEFT_PRECEDENCE and RIGHT_PRECEDENCE.

replace_in_realm( $replacements, $realm )

    Replace variables matching ${} notation with the values in $replacements. Optionally, do it only for $realm. If $realm is not specified, acts on only the default realm.

replace_in_hashref( $hashref, $replacements )

    Replace withing the values of $hashref keys, variables matching ${} notation with the values in $replacements.

get_replaced_string( $target, $replacements )

    Return the value of $target after replacing variables matching ${} notation with the values in $replacements.

FUTURE WORK

  • Deep getting

    At this time, you cannot get from deep within the heirarchy: you must get the top level key then fetch it yourself. In the future we will support arrow notation:

    Activator::Registry->get('top->deep->deeper');

  • Dynamic Reloading

    It'd probably be nice to be able to force reload so you could edit your registry file programatically.

  • Hash merging doesn't belong here

    In the future, merge_* methods will be removed.

  • Utilize other merge methods

    Only the default merge mechanism for Hash::Merge is used. It'd be more robust to support other mechanisms as well.

See Also

Activator::Log, Activator::Exception, YAML::Syck, Exception::Class::TryCatch, Class::StrongSingleton

AUTHOR

Karim Nassar ( karim.nassar@acm.org )

License

The Activator::Registry module is Copyright (c) 2007 Karim Nassar.

You may distribute under the terms of either the GNU General Public License or the Artistic License, or as specified in the Perl README file.