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.

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.

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.

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.