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 );

  #### get a deep value for $key from default realm
  #### this form throws exception for invalid keys
  $key = 'top->deep->deeper';
  try eval {
     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 );

  #### use ${} syntax in your registry for variables
  Activator::Registry->replace_in_realm( 'default', $replacements_hashref );

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 getting and setting of deeply nested objects. Setting can be done via YAML configuration files.

CONFIGURATION FILES

Configuration files are YAML files.

Registry Within Another Configuration File

You can have a registry be a stand alone file, or live within a configuration file used for other purposes. If you wish your registry to be only a subset of a larger YAML file, put the desired hierarchy in a top level key Activator::Registry. If that key exists, only that part of the YAML file will be registered.

Default Configuration File

Often, your project will have a central configuration file that you always want to use. In these cases set the environment variable ACT_REG_YAML_FILE. All calls to "new()", "load()" and "reload()" will register this file first, then any files passed as arguments to those subroutines.

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 ensure that the environment is properly set. This my require that you utilize 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()

Returns a reference to a registry object. This is a singleton, so repeated calls always return the same ref. This will load the file specified by $ENV{ACT_REG_YAML_FILE}, then $yaml_file. If neither are valid YAML files, you will have an object with an empty registry. If the registry has already been loaded, DOES NOT RELOAD it. use "reload()" for that.

load()

Load a YAML file into the registry. Throws exception if the file has already been successfully loaded.

reload()

Reloads a specific configuration file. This nukes the existing registry.

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 when testing the set value to the value passed in).

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. $key can refer to a deeply nested element. Returns undef if the key does not exist, or you try to seek into an array. Some examples:

With a YAML config that produces:

  deep_list:
    level_1:
      - level_2_a
      - level_2_b
  key: value

You will get this behavior:

  Activator::Registry->get( 'key' );                           # returns 'value'
  Activator::Registry->get( 'deep_list' );                     # returns hashref
  Activator::Registry->get( 'deep_lost' );                     # returns undef
  Activator::Registry->get( 'deep_list->level_1' );            # returns arrayref
  Activator::Registry->get( 'deep_list->level_1->level_2_a' ); # returns undef
  Activator::Registry->get( 'deep_list->level_one' );          # returns undef

get_realm( $realm )

Return a reference to hashref for an entire $realm.

set_default_realm( $realm )

Use $realm instead of 'default' for default realm calls.

replace_in_realm( $realm, $replacements )

Replace variables matching ${} notation with the values in $replacements. $realm must be specified. Use 'default' for the default realm. Keys that refer to other keys in the realm are processed AFTER the passed in $replacements are processed.

replace_in_hashref( $hashref, $replacements )

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

do_replacements ( $string, $replacements )

Helper subroutine to allow recursive replacements of ${} notation with values in $replacements. Returns the new value.

get_replaced_string( $target, $replacements )

In scalar context, return the value of $target after replacing variables matching ${} notation with the values in $replacements. If a variable exists, but there is no replacement value, it is not changed. In list context, returns the string and the number of replacements.

FUTURE WORK

• Fix warning messages

  If you create a script that uses this module (or some other activator module that depends on this module), the warning messages are rather arcane. This script:

    #!/usr/bin/perl
    use strict;
    use warnings;
    use Activator::DB;
    Activator::DB->getrow( 'select * from some_table', [],  connect->'default');

  Run this way:

    ./test.pl

  Produces this error:

    activator_db_config missing You must define the key "Activator::DB" or "Activator->DB" in your project configuration

  Probably should say something about the fact that you should have run it like this:

    ACT_REG_YAML_FILE=/path/to/registry.yml ./test.pl

• 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 A. Nassar ( karim.nassar@acm.org )

License

The Activator::Registry module is Copyright (c) 2007 Karim A. 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.

cpanm Activator

perl -MCPAN -e shell
install Activator