Pipeline/Output/Memory.pm

filter: Statementstmt 100% 34 / 34 Branchbran 66.6% 4 / 6 Conditioncond n/a MC/DCmcdc n/a Subroutinesub 100% 10 / 10 Podpod 100% 3 / 3 totaltotal 96.2% 51 / 53 CC 4 SCAR 6.6
CC
4
Cov
95%
write
4.0
BEGIN
1.0
BEGIN
1.0
CRAP 1.9
« Pipeline/Input/Xml.pm ↑ Summary Pipeline/Output/UnitTest.pm »
1 =pod
2
3 =head1 NAME
4
5 ETL::Pipeline::Output::Memory - Store records in memory
6
7 =head1 SYNOPSIS
8
9 # Save the records into a giant list.
10 use ETL::Pipeline;
11 ETL::Pipeline->new( {
12 input => ['UnitTest'],
13 mapping => {First => 'Header1', Second => 'Header2'},
14 output => ['Memory']
15 } )->process;
16
17 # Save the records into a hash, keyed by an identifier.
18 use ETL::Pipeline;
19 ETL::Pipeline->new( {
20 input => ['UnitTest'],
21 mapping => {First => 'Header1', Second => 'Header2'},
22 output => ['Memory', key => 'First']
23 } )->process;
24
25 =head1 DESCRIPTION
26
27 B<ETL::Pipeline::Output::Memory> writes the record into a Perl data structure,
28 in memory. The records can be accessed later in the same script. This output
29 destination comes in useful when processing multiple input files.
30
31 B<ETL::Pipeline::Output::Memory> offers two ways of storing the records - in
32 a hash or in a list. B<ETL::Pipeline::Output::Memory> always put records into
33 the list. If the L</key> attribute is set, then B<ETL::Pipeline::Output::Memory>
34 also saves records into the hash.
35
36 The hash can be used for faster look-up. Use L</key> when the record contains an
37 identifier.
38
39 =cut
40
41 package ETL::Pipeline::Output::Memory;
42
43 1 ▶use 5.014000;
Subroutine BEGIN: called CC=1 SCAR=0.0
44 1 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
45
46 1 ▶use Moose;
Subroutine BEGIN: called CC=1 SCAR=0.0
47 1 ▶use String::Util qw/hascontent/;
Subroutine BEGIN: called CC=1 SCAR=0.0
48
49
50 1 our $VERSION = '2.00';
51
52
53 =head1 METHODS & ATTRIBUTES
54
55 =head2 Arguments for L<ETL::Pipeline/output>
56
57 =head3 key
58
59 Optional. If you want to store the records in a hash, then this is the field
60 name whose value becomes the key. When set, records go into L</hash>.
61
62 If you don't specify a B<key>, then records are stored in an unsorted array -
63 L</list>.
64
65 =cut
66
67 1 has 'key' => (
68 default => '',
69 is => 'ro',
70 isa => 'Str',
71 );
72
73
74 =head2 Attributes
75
76 =head3 hash
77
78 Hash reference used when L</key> is set. The key is the value of the field
79 identified by L</key>. The value is an array reference. The array contains all
80 of the records with that same key.
81
82 =cut
83
84 has 'hash' => (
85 2 ▶ default => sub { {} },
Subroutine __ANON__: called CC=1 SCAR=0.0
86 1 handles => {
87 _add_to_id => 'set',
88 number_of_ids => 'count',
89 with_id => 'get',
90 },
91 is => 'ro',
92 isa => 'HashRef[ArrayRef[HashRef[Any]]]',
93 traits => [qw/Hash/],
94 );
95
96
97 =head3 list
98
99 B<list> is an array reference that stores records. The records are saved in
100 same order as they are read from the input source. Each list element is a
101 hash reference (the record).
102
103 B<list> always has a complete set of records, whether L</key> is set or not.
104
105 =cut
106
107 has 'list' => (
108 2 ▶ default => sub { [] },
Subroutine __ANON__: called CC=1 SCAR=0.0
109 1 handles => {
110 _add_record => 'push',
111 number_of_records => 'count',
112 records => 'elements',
113 },
114 is => 'ro',
115 isa => 'ArrayRef[HashRef[Any]]',
116 traits => [qw/Array/],
117 );
118
119
120 =head2 Methods
121
122 =head3 close
123
124 This method doesn't do anything. There's nothing to close or shut down.
125
126 =cut
127
128 2 ▶sub close {}
Subroutine close: called CC=1 SCAR=0.0
Pod documented
129
130
131 =head3 number_of_ids
132
133 Count of unique identifiers. This may not be the same as the number of records.
134 One key may have multiple records.
135
136 B<number_of_ids> only works if the L</key> attribute was set.
137
138
139 =cut
140
141 # This method is defined by the "hash" attribute.
142
143
144 =head3 number_of_records
145
146 Count of records currently in storage.
147
148 =cut
149
150 # This method is defined by the "list" attribute.
151
152
153 =head3 open
154
155 This method doesn't do anything. There's nothing to open or setup.
156
157 =cut
158
159 2 ▶sub open {}
Subroutine open: called CC=1 SCAR=0.0
Pod documented
160
161
162 =head3 records
163
164 Returns a list of all the records currently in storage. The list contains hash
165 references - one reference for each record.
166
167 =cut
168
169 # This method is defined by the "list" attribute.
170
171
172 =head3 with_id
173
174 B<with_id> returns a list of records for a given key. Pass in a value for the
175 key and B<with_id> returns an array reference of records.
176
177 B<with_id> only works if the L</key> attribute was set.
178
179 =cut
180
181 # This method is defined by the "hash" attribute.
182
183
184 =head3 write
185
186 Save the current record into memory. Your script can access the records after
187 calling L<ETL::Pipeline/process> like this - C<$etl->output->records>.
188 Both L</records> and L</with_id> can be used.
189
190 If L</key> is set, B<write> saves the record in both L</hash> and L</list>.
191 We're storing a reference, not a copy, so there's very little cost. And it
192 allows methods such as L</number_of_records> to work.
193
194 B<WARNING:> This method stores a I<reference> to the original record. If the
195 input source re-uses the hash or embedded references, it will update all of the
196 currently stored values too. B<ETL::Pipeline::Output::Memory> does not make a
197 copy.
198
199 =cut
200
201 4 ▶sub write {
Subroutine write: called CC=4 SCAR=13.9
Pod documented
202 4 my ($self, $etl, $record) = @_;
203 4 my $key = $self->key;
204
205 # Key field = hash
206 # No key field = list
207 4 my $list;
208 4 ▶ if (hascontent( $key )) {
Branch: 1 branch
BranchTrueFalseTotal
if (hascontent($key)) 2 2 4
209 # NULL is an invalid key. Empty strings are okay, though. If the data
210 # has NULLs, then your script should translate them.
211 2 my $id = $record->{$key};
212 2 ▶ return $etl->log( 'ERROR', "The field '$key' was undefined" )
Branch: 1 branch
BranchTrueFalseTotal
unless defined $id 0 2 2
213 unless defined $id;
214
215 2 $list = $self->with_id( $id );
216 2 ▶ unless (defined $list) {
Branch: 1 branch
BranchTrueFalseTotal
unless (defined $list) 2 0 2
217 2 $list = [];
218 2 $self->_add_to_id( $id, $list );
219 }
220 2 push @$list, $record;
221 }
222 4 $self->_add_record( $record );
223 }
224
225
226 =head1 SEE ALSO
227
228 L<ETL::Pipeline>, L<ETL::Pipeline::Output>
229
230 =cut
231
232 1 with 'ETL::Pipeline::Output';
233
234
235 =head1 AUTHOR
236
237 Robert Wohlfarth <robert.j.wohlfarth@vumc.org>
238
239 =head1 LICENSE
240
241 Copyright 2021 (c) Vanderbilt University
242
243 This program is free software; you can redistribute it and/or modify it under
244 the same terms as Perl itself.
245
246 =cut
247
248 1 ▶no Moose;
Subroutine BEGIN: called CC=1 SCAR=0.0
249 1 __PACKAGE__->meta->make_immutable;
« Pipeline/Input/Xml.pm ↑ Summary Pipeline/Output/UnitTest.pm »