Positron/Environment.pm

filter: Statementstmt 100% 39 / 39 Branchbran 100% 16 / 16 Conditioncond 100% 11 / 11 MC/DCmcdc 100% 6 / 6 Subroutinesub 100% 9 / 9 Podpod 100% 3 / 3 totaltotal 100% 84 / 84 CC 14 SCAR 14.3
CC
14
Cov
100%
get
6.0
new
5.0
set
5.0
CRAP 4.2
« Positron/Template.pm ↑ Summary Positron/Handler/ArrayRef.pm »
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 //= {}
l!l
158295
MC/DC100%1/1
$options //= {}
$options
Truth table100%2/2
A
A= $options
Aresult
11
00
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 // {}
l!l
44013
$options->{"immutable"} // 0
l!l
55398
$options->{"parent"} // undef
l!l
142311
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
Aresult
11
00
Truth table100%2/2
A
A= $options->{"immutable"}
Aresult
11
00
Truth table100%2/2
A
A= $options->{"parent"}
Aresult
11
00
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
BranchTrueFalseTotal
if ($key eq "_") 14 602 616
123 14 return $self->{'data'};
124 }
125 602 ▶ if (ref($self->{'data'}) eq 'HASH' and exists $self->{'data'}->{$key}) {
Branch: 3 branches
BranchTrueFalseTotal
if (ref $self->{'data'} eq 'HASH' and exists $self->{'data'}{$key}) { } 503 99 602
elsif (ref $self->{'data'} eq 'ARRAY') { } 4 95 99
elsif ($self->{'parent'}) { } 58 37 95
Condition100%3/3
ref $self->{"data"} eq "HASH" and exists $self->{"data"}{$key}
!ll&&!rl&&r
594503
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}
ABresult
0X0
100
111
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
BranchTrueFalseTotal
if $self->{"immutable"} 3 34 37
158 34 ▶ if ($key eq '_') {
Branch: 3 branches
BranchTrueFalseTotal
if ($key eq '_') { } 2 32 34
elsif (ref $self->{'data'} eq 'ARRAY') { } 4 28 32
elsif (ref $self->{'data'} eq 'HASH') { } 27 1 28
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__
« Positron/Template.pm ↑ Summary Positron/Handler/ArrayRef.pm »