| 1 | package Positron::Environment; | ||||||||||||||||||||||||||||||||||||
| 2 | 37 | our $VERSION = 'v0.1.3'; # VERSION | |||||||||||||||||||||||||||||||||||
| 3 | |||||||||||||||||||||||||||||||||||||
| 4 | =head1 NAME | ||||||||||||||||||||||||||||||||||||
| 5 | |||||||||||||||||||||||||||||||||||||
| 6 | Positron::Environment - container class for template parameters | ||||||||||||||||||||||||||||||||||||
| 7 | |||||||||||||||||||||||||||||||||||||
| 8 | =head1 VERSION | ||||||||||||||||||||||||||||||||||||
| 9 | |||||||||||||||||||||||||||||||||||||
| 10 | version v0.1.3 | ||||||||||||||||||||||||||||||||||||
| 11 | |||||||||||||||||||||||||||||||||||||
| 12 | =head1 SYNOPSIS | ||||||||||||||||||||||||||||||||||||
| 13 | |||||||||||||||||||||||||||||||||||||
| 14 | use Positron::Environment; | ||||||||||||||||||||||||||||||||||||
| 15 | my $env = Positron::Environment->new({ key1 => 'value 1', key2 => 'value 2'}); | ||||||||||||||||||||||||||||||||||||
| 16 | my $child = Positron::Environment->new({ key1 => 'value 3'}, { parent => $env }); | ||||||||||||||||||||||||||||||||||||
| 17 | |||||||||||||||||||||||||||||||||||||
| 18 | say $env->get('key1'); # value 1 | ||||||||||||||||||||||||||||||||||||
| 19 | say $env->get('key2'); # value 2 | ||||||||||||||||||||||||||||||||||||
| 20 | say $child->get('key1'); # value 3 | ||||||||||||||||||||||||||||||||||||
| 21 | say $child->get('key2'); # value 2 | ||||||||||||||||||||||||||||||||||||
| 22 | |||||||||||||||||||||||||||||||||||||
| 23 | $child->set( key2 => 'value 4' ); | ||||||||||||||||||||||||||||||||||||
| 24 | say $child->get('key2'); # value 4 | ||||||||||||||||||||||||||||||||||||
| 25 | say $env->get('key2'); # value 2 | ||||||||||||||||||||||||||||||||||||
| 26 | |||||||||||||||||||||||||||||||||||||
| 27 | =head1 DESCRIPTION | ||||||||||||||||||||||||||||||||||||
| 28 | |||||||||||||||||||||||||||||||||||||
| 29 | C<Positron::Environment> is basically a thin wrapper around hashes (key-value mappings) | ||||||||||||||||||||||||||||||||||||
| 30 | with hierarchy extensions. It is used internally by the C<Positron> template systems | ||||||||||||||||||||||||||||||||||||
| 31 | to store template variables. | ||||||||||||||||||||||||||||||||||||
| 32 | |||||||||||||||||||||||||||||||||||||
| 33 | C<Positron::Environment> provides getters and setters for values. It can also optionally | ||||||||||||||||||||||||||||||||||||
| 34 | refer to a parent environment. If the environment does not contain anything for an | ||||||||||||||||||||||||||||||||||||
| 35 | asked-for key, it will ask its parent in turn. | ||||||||||||||||||||||||||||||||||||
| 36 | Note that if a key refers to C<undef> as its value, this counts as "containing something", | ||||||||||||||||||||||||||||||||||||
| 37 | and the parent will not be asked. | ||||||||||||||||||||||||||||||||||||
| 38 | |||||||||||||||||||||||||||||||||||||
| 39 | Getting or setting the special key C<_> (a single underscore) accesses the entire data, | ||||||||||||||||||||||||||||||||||||
| 40 | i.e. the hash that was used in the constructor. | ||||||||||||||||||||||||||||||||||||
| 41 | These requests are never passed to any parents. | ||||||||||||||||||||||||||||||||||||
| 42 | |||||||||||||||||||||||||||||||||||||
| 43 | =head2 Non-hash data | ||||||||||||||||||||||||||||||||||||
| 44 | |||||||||||||||||||||||||||||||||||||
| 45 | Although C<Positron::Environment> is built for hashes, it can also be used with plain | ||||||||||||||||||||||||||||||||||||
| 46 | scalar data (strings, numbers, C<undef>) or array references. | ||||||||||||||||||||||||||||||||||||
| 47 | Calling C<get> when the data is a string results in C<undef> being returned. | ||||||||||||||||||||||||||||||||||||
| 48 | Calling C<set> when the data is a string results in a warning, and returns C<undef>, | ||||||||||||||||||||||||||||||||||||
| 49 | but currently does not raise an exception. Just don't expect to get that value back | ||||||||||||||||||||||||||||||||||||
| 50 | again. | ||||||||||||||||||||||||||||||||||||
| 51 | |||||||||||||||||||||||||||||||||||||
| 52 | Calling C<get> or C<set> when the data is an array (reference) works by first converting | ||||||||||||||||||||||||||||||||||||
| 53 | the key to an integer via the builtin C<int> function. | ||||||||||||||||||||||||||||||||||||
| 54 | This means that alphabetic keys will be coerced to the number C<0> (with the regular | ||||||||||||||||||||||||||||||||||||
| 55 | Perl warning) and floating point values get rounded towards 0. | ||||||||||||||||||||||||||||||||||||
| 56 | On the other hand, this means that negative keys will start counting from the back of | ||||||||||||||||||||||||||||||||||||
| 57 | the array. | ||||||||||||||||||||||||||||||||||||
| 58 | |||||||||||||||||||||||||||||||||||||
| 59 | =cut | ||||||||||||||||||||||||||||||||||||
| 60 | |||||||||||||||||||||||||||||||||||||
| 61 | 37 | ▶ | use v5.10; | ||||||||||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||||||||||
| 62 | 37 | ▶ | use strict; | ||||||||||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||||||||||
| 63 | 37 | ▶ | use warnings; | ||||||||||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||||||||||
| 64 | 37 | ▶ | use Carp qw(croak carp); | ||||||||||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||||||||||
| 65 | |||||||||||||||||||||||||||||||||||||
| 66 | =head1 CONSTRUCTOR | ||||||||||||||||||||||||||||||||||||
| 67 | |||||||||||||||||||||||||||||||||||||
| 68 | =head2 new | ||||||||||||||||||||||||||||||||||||
| 69 | |||||||||||||||||||||||||||||||||||||
| 70 | my $env = Positron::Environment->new( \%data, \%options ); | ||||||||||||||||||||||||||||||||||||
| 71 | |||||||||||||||||||||||||||||||||||||
| 72 | Creates a new environment which serves the data passed in a hash reference. The following options are supported: | ||||||||||||||||||||||||||||||||||||
| 73 | |||||||||||||||||||||||||||||||||||||
| 74 | =over 4 | ||||||||||||||||||||||||||||||||||||
| 75 | |||||||||||||||||||||||||||||||||||||
| 76 | =item immutable | ||||||||||||||||||||||||||||||||||||
| 77 | |||||||||||||||||||||||||||||||||||||
| 78 | If set to a true value, the constructed environment will be immutable; calling the | ||||||||||||||||||||||||||||||||||||
| 79 | C<set> method will raise an exception. | ||||||||||||||||||||||||||||||||||||
| 80 | |||||||||||||||||||||||||||||||||||||
| 81 | =item parent | ||||||||||||||||||||||||||||||||||||
| 82 | |||||||||||||||||||||||||||||||||||||
| 83 | A reference to another environment. If the newly constructed environment does not | ||||||||||||||||||||||||||||||||||||
| 84 | contain a key when asked with C<get>, it will ask this parent environment (which | ||||||||||||||||||||||||||||||||||||
| 85 | can have a parent in turn). | ||||||||||||||||||||||||||||||||||||
| 86 | |||||||||||||||||||||||||||||||||||||
| 87 | =back | ||||||||||||||||||||||||||||||||||||
| 88 | |||||||||||||||||||||||||||||||||||||
| 89 | =cut | ||||||||||||||||||||||||||||||||||||
| 90 | |||||||||||||||||||||||||||||||||||||
| 91 | 453 | ▶ | sub new { | ||||||||||||||||||||||||||||||||||
|
Subroutine
new: called CC=5 SCAR=16.1
Pod
documented
| |||||||||||||||||||||||||||||||||||||
| 92 | 453 | my($class, $data, $options) = @_; | |||||||||||||||||||||||||||||||||||
| 93 | 453 | ▶ | $options //= {}; | ||||||||||||||||||||||||||||||||||
|
Condition100%2/2
$options //= {}
MC/DC100%1/1
$options //= {}
$options
Truth table100%2/2
A
A= $options
| |||||||||||||||||||||||||||||||||||||
| 94 | my $self = { | ||||||||||||||||||||||||||||||||||||
| 95 | data => $data // {}, | ||||||||||||||||||||||||||||||||||||
| 96 | immutable => $options->{'immutable'} // 0, | ||||||||||||||||||||||||||||||||||||
| 97 | # We don't need to weaken, since we are always pointing upwards only! | ||||||||||||||||||||||||||||||||||||
| 98 | 453 | ▶ | parent => $options->{'parent'} // undef, | ||||||||||||||||||||||||||||||||||
|
Condition100%6/6
$data // {}
$options->{"immutable"} // 0
$options->{"parent"} // undef
MC/DC100%1/1
$data // {}
$data
MC/DC100%1/1
$options->{"immutable"} // 0
$options->{"immutable"}
MC/DC100%1/1
$options->{"parent"} // undef
$options->{"parent"}
Truth table100%2/2
A
A= $data
Truth table100%2/2
A
A= $options->{"immutable"}
Truth table100%2/2
A
A= $options->{"parent"}
| |||||||||||||||||||||||||||||||||||||
| 99 | }; | ||||||||||||||||||||||||||||||||||||
| 100 | 453 | return bless($self, $class); | |||||||||||||||||||||||||||||||||||
| 101 | } | ||||||||||||||||||||||||||||||||||||
| 102 | |||||||||||||||||||||||||||||||||||||
| 103 | =head1 METHODS | ||||||||||||||||||||||||||||||||||||
| 104 | |||||||||||||||||||||||||||||||||||||
| 105 | =head2 get | ||||||||||||||||||||||||||||||||||||
| 106 | |||||||||||||||||||||||||||||||||||||
| 107 | my $value = $env->get('key'); | ||||||||||||||||||||||||||||||||||||
| 108 | |||||||||||||||||||||||||||||||||||||
| 109 | Returns the value stored under the key C<key> in the data of this environment. | ||||||||||||||||||||||||||||||||||||
| 110 | This is very much like a standard hash ref. If this environment does not know | ||||||||||||||||||||||||||||||||||||
| 111 | about this key (i.e. it does not exist in the data hash), it returns C<undef>, | ||||||||||||||||||||||||||||||||||||
| 112 | unless a parent environment is set. In this case, it will recursively query | ||||||||||||||||||||||||||||||||||||
| 113 | its parent for the key. | ||||||||||||||||||||||||||||||||||||
| 114 | |||||||||||||||||||||||||||||||||||||
| 115 | The special key C<_> returns the entire data of this environment, never | ||||||||||||||||||||||||||||||||||||
| 116 | querying the parent. | ||||||||||||||||||||||||||||||||||||
| 117 | |||||||||||||||||||||||||||||||||||||
| 118 | =cut | ||||||||||||||||||||||||||||||||||||
| 119 | |||||||||||||||||||||||||||||||||||||
| 120 | 616 | ▶ | sub get { | ||||||||||||||||||||||||||||||||||
|
Subroutine
get: called CC=6 SCAR=17.9
Pod
documented
| |||||||||||||||||||||||||||||||||||||
| 121 | 616 | my ($self, $key) = @_; | |||||||||||||||||||||||||||||||||||
| 122 | 616 | ▶ | if ($key eq '_') { | ||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||
| 123 | 14 | return $self->{'data'}; | |||||||||||||||||||||||||||||||||||
| 124 | } | ||||||||||||||||||||||||||||||||||||
| 125 | 602 | ▶ | if (ref($self->{'data'}) eq 'HASH' and exists $self->{'data'}->{$key}) { | ||||||||||||||||||||||||||||||||||
|
Branch: 3 branches
Condition100%3/3
ref $self->{"data"} eq "HASH" and exists $self->{"data"}{$key}
MC/DC100%2/2
ref $self->{"data"} eq "HASH" and exists $self->{"data"}{$key}
ref $self->{"data"} eq "HASH"
exists $self->{"data"}{$key}
Truth table100%3/3
A and B
A= ref $self->{"data"} eq "HASH"B= exists $self->{"data"}{$key}
| |||||||||||||||||||||||||||||||||||||
| 126 | 503 | return $self->{'data'}->{$key}; | |||||||||||||||||||||||||||||||||||
| 127 | } elsif (ref($self->{'data'}) eq 'ARRAY') { | ||||||||||||||||||||||||||||||||||||
| 128 | # What about parents with array refs? | ||||||||||||||||||||||||||||||||||||
| 129 | 37 | ▶ | no warnings 'numeric'; # all else is 0, that's ok. | ||||||||||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||||||||||
| 130 | 4 | return $self->{'data'}->[int($key)]; | |||||||||||||||||||||||||||||||||||
| 131 | # N.B.: other scalars (non-refs, objects) never perform subqueries, always 'undef' | ||||||||||||||||||||||||||||||||||||
| 132 | } elsif ($self->{'parent'}) { | ||||||||||||||||||||||||||||||||||||
| 133 | 58 | return $self->{'parent'}->get($key); | |||||||||||||||||||||||||||||||||||
| 134 | } | ||||||||||||||||||||||||||||||||||||
| 135 | 37 | return undef; # always scalar | |||||||||||||||||||||||||||||||||||
| 136 | } | ||||||||||||||||||||||||||||||||||||
| 137 | |||||||||||||||||||||||||||||||||||||
| 138 | =head2 set | ||||||||||||||||||||||||||||||||||||
| 139 | |||||||||||||||||||||||||||||||||||||
| 140 | my $value = $env->set('key', 'value'); | ||||||||||||||||||||||||||||||||||||
| 141 | |||||||||||||||||||||||||||||||||||||
| 142 | Sets the key to the given value in this environment's data hash. | ||||||||||||||||||||||||||||||||||||
| 143 | This call will croak if the environment has been marked as immutable. | ||||||||||||||||||||||||||||||||||||
| 144 | Setting the value to C<undef> will effectively mask any parent; a C<get> | ||||||||||||||||||||||||||||||||||||
| 145 | call will return C<undef> even if the parent has a defined value. | ||||||||||||||||||||||||||||||||||||
| 146 | |||||||||||||||||||||||||||||||||||||
| 147 | The special key C<_> sets the entire data of this environment. | ||||||||||||||||||||||||||||||||||||
| 148 | |||||||||||||||||||||||||||||||||||||
| 149 | Returns the value again I<(this may change in future versions)>. | ||||||||||||||||||||||||||||||||||||
| 150 | |||||||||||||||||||||||||||||||||||||
| 151 | =cut | ||||||||||||||||||||||||||||||||||||
| 152 | |||||||||||||||||||||||||||||||||||||
| 153 | # Why do we need this, again? | ||||||||||||||||||||||||||||||||||||
| 154 | # TODO: Should this delete if no value is passed? | ||||||||||||||||||||||||||||||||||||
| 155 | 37 | ▶ | sub set { | ||||||||||||||||||||||||||||||||||
|
Subroutine
set: called CC=5 SCAR=16.1
Pod
documented
| |||||||||||||||||||||||||||||||||||||
| 156 | 37 | my ($self, $key, $value) = @_; | |||||||||||||||||||||||||||||||||||
| 157 | 37 | ▶ | croak "Immutable environment being changed" if $self->{'immutable'}; | ||||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||||
| 158 | 34 | ▶ | if ($key eq '_') { | ||||||||||||||||||||||||||||||||||
|
Branch: 3 branches
| |||||||||||||||||||||||||||||||||||||
| 159 | 2 | $self->{'data'} = $value; | |||||||||||||||||||||||||||||||||||
| 160 | } elsif (ref($self->{'data'}) eq 'ARRAY') { | ||||||||||||||||||||||||||||||||||||
| 161 | 37 | ▶ | no warnings 'numeric'; | ||||||||||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||||||||||
| 162 | 4 | $self->{'data'}->[int($key)] = $value; | |||||||||||||||||||||||||||||||||||
| 163 | } elsif (ref($self->{'data'}) eq 'HASH') { | ||||||||||||||||||||||||||||||||||||
| 164 | 27 | $self->{'data'}->{$key} = $value; | |||||||||||||||||||||||||||||||||||
| 165 | } else { | ||||||||||||||||||||||||||||||||||||
| 166 | 1 | carp "Setting an environment which is neither hash nor array"; | |||||||||||||||||||||||||||||||||||
| 167 | } | ||||||||||||||||||||||||||||||||||||
| 168 | 34 | return $value; | |||||||||||||||||||||||||||||||||||
| 169 | } | ||||||||||||||||||||||||||||||||||||
| 170 | |||||||||||||||||||||||||||||||||||||
| 171 | 37 | 1; # End of Positron::Environment | |||||||||||||||||||||||||||||||||||
| 172 | |||||||||||||||||||||||||||||||||||||
| 173 | __END__ | ||||||||||||||||||||||||||||||||||||