/ 
Positron-v0.1.2
River stage zero No dependents
/ Positron::Environment

NAME

Positron::Environment - container class for template parameters

VERSION

version v0.1.2

SYNOPSIS

use Positron::Environment;
my $env   = Positron::Environment->new({ key1 => 'value 1', key2 => 'value 2'});
my $child = Positron::Environment->new({ key1 => 'value 3'}, { parent => $env });

say $env->get('key1');   # value 1
say $env->get('key2');   # value 2
say $child->get('key1'); # value 3
say $child->get('key2'); # value 2

$child->set( key2 => 'value 4' );
say $child->get('key2'); # value 4
say $env->get('key2');   # value 2

DESCRIPTION

Positron::Environment is basically a thin wrapper around hashes (key-value mappings) with hierarchy extensions. It is used internally by the Positron template systems to store template variables.

Positron::Environment provides getters and setters for values. It can also optionally refer to a parent environment. If the environment does not contain anything for an asked-for key, it will ask its parent in turn. Note that if a key refers to undef as its value, this counts as "containing something", and the parent will not be asked.

Getting or setting the special key _ (a single underscore) accesses the entire data, i.e. the hash that was used in the constructor. These requests are never passed to any parents.

Non-hash data

Although Positron::Environment is built for hashes, it can also be used with plain scalar data (strings, numbers, undef) or array references. Calling get when the data is a string results in undef being returned. Calling set when the data is a string results in a warning, and returns undef, but currently does not raise an exception. Just don't expect to get that value back again.

Calling get or set when the data is an array (reference) works by first converting the key to an integer via the builtin int function. This means that alphabetic keys will be coerced to the number 0 (with the regular Perl warning) and floating point values get rounded towards 0. On the other hand, this means that negative keys will start counting from the back of the array.

CONSTRUCTOR

new

my $env = Positron::Environment->new( \%data, \%options );

Creates a new environment which serves the data passed in a hash reference. The following options are supported:

immutable

If set to a true value, the constructed environment will be immutable; calling the set method will raise an exception.

parent

A reference to another environment. If the newly constructed environment does not contain a key when asked with get, it will ask this parent environment (which can have a parent in turn).

METHODS

get

my $value = $env->get('key');

Returns the value stored under the key key in the data of this environment. This is very much like a standard hash ref. If this environment does not know about this key (i.e. it does not exist in the data hash), it returns undef, unless a parent environment is set. In this case, it will recursively query its parent for the key.

The special key _ returns the entire data of this environment, never querying the parent.

set

my $value = $env->set('key', 'value');

Sets the key to the given value in this environment's data hash. This call will croak if the environment has been marked as immutable. Setting the value to undef will effectively mask any parent; a get call will return undef even if the parent has a defined value.

The special key _ sets the entire data of this environment.

Returns the value again (this may change in future versions).

AUTHOR

Ben Deutsch, <ben at bendeutsch.de>

BUGS

None known so far, though keep in mind that this is alpha software.

Please report any bugs or feature requests to bug-positron at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Positron. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

This module is part of the Positron distribution.

You can find documentation for this distribution with the perldoc command.

perldoc Positron

You can also look for information at:

LICENSE AND COPYRIGHT

Copyright 2013 Ben Deutsch. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See http://dev.perl.org/licenses/ for more information.