blib/lib/Catmandu/Fix.pm

filter: Statementstmt 90.2% 397 / 440 Branchbran 82.1% 115 / 140 Conditioncond 87.5% 35 / 40 MC/DCmcdc 72.7% 16 / 22 Subroutinesub 95.3% 61 / 64 Podpod 77.7% 21 / 27 totaltotal 87.9% 645 / 733 CC 86 SCAR 19.9
CC
86
Cov
88%
emit_set_key
25.1
emit_delete_key
18.2
_emit_create_path
12.0
CRAP 7.3
« blib/lib/Catmandu/Paged.pm ↑ Summary blib/lib/Catmandu/Cmd/run.pm »
1 package Catmandu::Fix;
2  
3 120 ▶use Catmandu::Sane;
Subroutine BEGIN: called CC=1 SCAR=0.0
4  
5 119 our $VERSION = '1.0201_02';
6  
7 120 ▶use Catmandu;
Subroutine BEGIN: called CC=1 SCAR=0.0
8 119 ▶use Catmandu::Util qw(:is :string :misc);
Subroutine BEGIN: called CC=1 SCAR=0.0
9 119 ▶use Clone qw(clone);
Subroutine BEGIN: called CC=1 SCAR=0.0
10  
11 sub _eval_emit {
12 119 ▶ use warnings FATAL => 'all';
Subroutine BEGIN: called CC=1 SCAR=0.0
13 327 ▶ eval $_[0];
Subroutine _eval_emit: called CC=1 SCAR=0.0
Subroutine BEGIN: called CC=1 SCAR=0.0
14 }
15  
16 119 ▶use Moo;
Subroutine BEGIN: called CC=1 SCAR=0.0
17 119 ▶use Catmandu::Fix::Parser;
Subroutine BEGIN: called CC=1 SCAR=0.0
18 119 ▶use File::Slurp::Tiny ();
Subroutine BEGIN: called CC=1 SCAR=0.0
19 119 ▶use File::Spec ();
Subroutine BEGIN: called CC=1 SCAR=0.0
20 119 ▶use File::Temp ();
Subroutine BEGIN: called CC=1 SCAR=0.0
21 119 ▶use B ();
Subroutine BEGIN: called CC=1 SCAR=0.0
22 119 ▶use Text::Hogan::Compiler;
Subroutine BEGIN: called CC=1 SCAR=0.0
23  
24 119 with 'Catmandu::Logger';
25  
26 119 has parser => (is => 'lazy');
27 119 has fixer => (is => 'lazy', init_arg => undef);
28 has _num_labels =>
29 327 ▶ (is => 'rw', lazy => 1, init_arg => undef, default => sub {0});
Subroutine __ANON__: called CC=1 SCAR=0.0
30 has _num_vars =>
31 330 ▶ (is => 'rw', lazy => 1, init_arg => undef, default => sub {0});
Subroutine __ANON__: called CC=1 SCAR=0.0
32 has _captures =>
33 330 ▶ (is => 'ro', lazy => 1, init_arg => undef, default => sub {+{}});
Subroutine __ANON__: called CC=1 SCAR=0.0
34 119 has var =>
35 (is => 'ro', lazy => 1, init_arg => undef, builder => 'generate_var');
36 0 ▶has _fixes => (is => 'ro', init_arg => 'fixes', default => sub {[]});
Subroutine __ANON__: not called CC=1 SCAR=1.2
37 119 has fixes =>
38 (is => 'ro', lazy => 1, init_arg => undef, builder => '_build_fixes');
39 410 ▶has _reject => (is => 'ro', init_arg => undef, default => sub {+{}});
Subroutine __ANON__: called CC=1 SCAR=0.0
40 119 has _reject_var => (
41 is => 'ro',
42 lazy => 1,
43 init_arg => undef,
44 builder => '_build_reject_var'
45 );
46 119 has _reject_label =>
47 (is => 'ro', lazy => 1, init_arg => undef, builder => 'generate_label');
48 119 has _fixes_var =>
49 (is => 'ro', lazy => 1, init_arg => undef, builder => '_build_fixes_var');
50 119 has _current_fix_var => (
51 is => 'ro',
52 lazy => 1,
53 init_arg => undef,
54 builder => '_build_current_fix_var'
55 );
56 119 has preprocess => (is => 'ro');
57 119 has _hogan =>
58 (is => 'ro', lazy => 1, init_arg => undef, builder => '_build_hogan');
59 119 has _hogan_vars => (is => 'ro', init_arg => 'variables');
60  
61 sub _build_parser {
62 119 ▶ Catmandu::Fix::Parser->new;
Subroutine _build_parser: called CC=1 SCAR=0.0
63 }
64  
65 sub _build_fixes {
66 330 ▶ my ($self) = @_;
Subroutine _build_fixes: called CC=10 SCAR=23.0
67 330 my $fixes_arg = $self->_fixes;
68 330 my $fixes = [];
69  
70 330 for my $fix (@$fixes_arg) {
71  
72 329 ▶ if (is_code_ref($fix)) {
Branch: 5 branches
BranchTrueFalseTotal
if (Ref::Util::XS::is_plain_coderef($fix)) { } 8 321 329
elsif (ref $fix and ref($fix) =~ /^IO::/) { } 1 320 321
elsif (Ref::Util::XS::is_plain_globref($fix)) { } 1 319 320
elsif (ref $fix) { } 202 117 319
elsif (is_string($fix)) { } 117 0 117
73 8 push @$fixes, require_package('Catmandu::Fix::code')->new($fix);
74 }
75 ▶ elsif (ref $fix && ref($fix) =~ /^IO::/) {
Condition100%3/3
ref $fix and ref($fix) =~ /^IO::/
!ll&&!rl&&r
1172031
MC/DC100%2/2
ref $fix and ref($fix) =~ /^IO::/
ref $fix ref($fix) =~ /^IO::/
Truth table100%3/3
A and B
A= ref $fixB= ref($fix) =~ /^IO::/
ABresult
0X0
100
111
76 1 my $txt = Catmandu::Util::read_io($fix);
77 1 $txt = $self->_preprocess($txt);
78 1 push @$fixes, @{$self->parser->parse($txt)};
79 }
80 elsif (is_glob_ref($fix)) {
81 1 my $fh = Catmandu::Util::io $fix , binmode => ':encoding(UTF-8)';
82 1 my $txt = Catmandu::Util::read_io($fh);
83 1 $txt = $self->_preprocess($txt);
84 1 push @$fixes, @{$self->parser->parse($txt)};
85 }
86 elsif (ref $fix) {
87 202 push @$fixes, $fix;
88 }
89 elsif (is_string($fix)) {
90 117 ▶ if ($fix =~ /[^\s]/ && $fix !~ /\(/) {
Branch: 1 branch
BranchTrueFalseTotal
if ($fix =~ /[^\s]/ and not $fix =~ /\(/) 6 111 117
Condition66%2/3
$fix =~ /[^\s]/ and not $fix =~ /\(/
!ll&&!rl&&r
01116
MC/DC50%1/2
$fix =~ /[^\s]/ and not $fix =~ /\(/
$fix =~ /[^\s]/ not $fix =~ /\(/
Truth table66%2/3
A and not(B)
A= $fix =~ /[^\s]/B= not $fix =~ /\(/
ABresult
0X0
100
111
91 6 $fix = File::Slurp::Tiny::read_file($fix,
92 binmode => ':encoding(UTF-8)');
93 }
94 117 $fix = $self->_preprocess($fix);
95 117 push @$fixes, @{$self->parser->parse($fix)};
96 }
97 }
98  
99 327 $fixes;
100 }
101  
102 sub _build_fixer {
103 330 ▶ my ($self) = @_;
Subroutine _build_fixer: called CC=2 SCAR=7.1
104 330 local $@;
105 330 ▶ _eval_emit($self->emit, $self->_captures) or Catmandu::Error->throw($@);
Branch: 1 branch
BranchTrueFalseTotal
_eval_emit($self->emit, $self->_captures) or "Catmandu::Error"->throw($@) 0 327 327
106 }
107  
108 sub _build_reject_var {
109 330 ▶ my ($self) = @_;
Subroutine _build_reject_var: called CC=1 SCAR=0.0
110 330 $self->capture($self->_reject);
111 }
112  
113 sub _is_reject {
114 1168 ▶ my ($self, $data) = @_;
Subroutine _is_reject: called CC=2 SCAR=6.9
115 1168 ▶ ref $data && $data == $self->_reject;
Branch: 1 branch
BranchTrueFalseTotal
ref $data and $data == $self->_reject 1161 7 1168
116 }
117  
118 sub _build_fixes_var {
119 326 ▶ my ($self) = @_;
Subroutine _build_fixes_var: called CC=1 SCAR=0.0
120 326 $self->capture($self->fixes);
121 }
122  
123 sub _build_current_fix_var {
124 330 ▶ my ($self) = @_;
Subroutine _build_current_fix_var: called CC=1 SCAR=0.0
125 330 $self->generate_var;
126 }
127  
128 sub _build_hogan {
129 1 ▶ Text::Hogan::Compiler->new;
Subroutine _build_hogan: called CC=1 SCAR=0.0
130 }
131  
132 sub _preprocess {
133 119 ▶ my ($self, $text) = @_;
Subroutine _preprocess: called CC=4 SCAR=14.2
134 119 ▶ return $text unless $self->preprocess || $self->_hogan_vars;
Branch: 1 branch
BranchTrueFalseTotal
unless $self->preprocess or $self->_hogan_vars 118 1 119
Condition66%2/3
$self->preprocess or $self->_hogan_vars
l!l&&r!l&&!r
10118
MC/DC50%1/2
$self->preprocess or $self->_hogan_vars
$self->preprocess $self->_hogan_vars
Truth table66%2/3
A or B
A= $self->preprocessB= $self->_hogan_vars
ABresult
1X1
011
000
135 1 ▶ $self->_hogan->compile($text)->render($self->_hogan_vars || {});
Condition50%1/2
$self->_hogan_vars || {}
l!l
10
MC/DC0%0/1
$self->_hogan_vars || {}
$self->_hogan_vars
Truth table50%1/2
A
A= $self->_hogan_vars
Aresult
11
00
136 }
137  
138 sub fix {
139 437 ▶ my ($self, $data) = @_;
Subroutine fix: called CC=8 SCAR=20.8
Pod documented
140  
141 437 my $fixer = $self->fixer;
142  
143 434 ▶ if (is_hash_ref($data)) {
Branch: 1 branch
BranchTrueFalseTotal
if (Ref::Util::XS::is_plain_hashref($data)) 401 33 434
144 401 my $d = $fixer->($data);
145 399 ▶ return if $self->_is_reject($d);
Branch: 1 branch
BranchTrueFalseTotal
if $self->_is_reject($d) 9 390 399
146 390 return $d;
147 }
148  
149 33 ▶ if ( is_instance($data)
Branch: 1 branch
BranchTrueFalseTotal
if (is_instance($data) and is_able($data, "does") and $data->does("Catmandu::Iterable")) 7 26 33
Condition83%5/6
is_instance($data) and is_able($data, "does") and $data->does("Catmandu::Iterable")
!ll&&!rl&&r
2607
is_instance($data) and is_able($data, "does")
!ll&&!rl&&r
2517
MC/DC66%2/3
is_instance($data) and is_able($data, "does") and $data->does("Catmandu::Iterable")
is_instance($data) is_able($data, "does") $data->does("Catmandu::Iterable")
Truth table75%3/4
A and B and C
A= is_instance($data)B= is_able($data, "does")C= $data->does("Catmandu::Iterable")
ABCresult
0XX0
10X0
1100
1111
150 && is_able($data, 'does')
151 && $data->does('Catmandu::Iterable'))
152 {
153 20 ▶ return $data->map(sub {$fixer->($_[0])})
Subroutine __ANON__: called CC=1 SCAR=0.0
154 7 ▶ ->reject(sub {$self->_is_reject($_[0])});
Subroutine __ANON__: called CC=1 SCAR=0.0
155 }
156  
157 26 ▶ if (is_code_ref($data)) {
Branch: 1 branch
BranchTrueFalseTotal
if (Ref::Util::XS::is_plain_coderef($data)) 10 16 26
158 return sub {
159 733 ▶ while (1) {
Subroutine __ANON__: called CC=3 SCAR=11.0
160 733 ▶ my $d = $fixer->($data->() // return);
Condition100%2/2
&$data() // (return)
l!l
7258
MC/DC100%1/1
&$data() // (return)
&$data()
Truth table100%2/2
A
A= &$data()
Aresult
11
00
161 725 ▶ next if $self->_is_reject($d);
Branch: 1 branch
BranchTrueFalseTotal
if $self->_is_reject($d) 0 725 725
162 725 return $d;
163 }
164 10 };
165 }
166  
167 16 ▶ if (is_array_ref($data)) {
Branch: 1 branch
BranchTrueFalseTotal
if (Ref::Util::XS::is_plain_arrayref($data)) 15 1 16
168 15 return [grep {!$self->_is_reject($_)} map {$fixer->($_)} @$data];
169 }
170  
171 Catmandu::BadArg->throw(
172 1 "must be hashref, arrayref, coderef or iterable object");
173 }
174  
175 sub generate_var {
176 2452 ▶ my ($self) = @_;
Subroutine generate_var: called CC=1 SCAR=0.0
Pod documented
177 2452 my $n = $self->_num_vars;
178 2452 $self->_num_vars($n + 1);
179 2452 "\$__$n";
180 }
181  
182 sub generate_label {
183 327 ▶ my ($self) = @_;
Subroutine generate_label: called CC=1 SCAR=0.0
Pod undocumented
184 327 my $n = $self->_num_labels;
185 327 $self->_num_labels($n + 1);
186 327 my $addr = Scalar::Util::refaddr($self);
187 327 "__FIX__${addr}__${n}";
188 }
189  
190 sub capture {
191 892 ▶ my ($self, $capture) = @_;
Subroutine capture: called CC=1 SCAR=0.0
Pod documented
192 892 my $var = $self->generate_var;
193 892 $self->_captures->{$var} = $capture;
194 892 $var;
195 }
196  
197 sub emit {
198 330 ▶ my ($self) = @_;
Subroutine emit: called CC=5 SCAR=17.1
Pod undocumented
199 330 my $var = $self->var;
200 330 my $err = $self->generate_var;
201 330 my $captures = $self->_captures;
202 330 my $reject_var = $self->_reject_var;
203 330 my $current_fix_var = $self->_current_fix_var;
204 330 my $perl = "";
205  
206 330 $perl .= "sub {";
207 330 $perl .= $self->emit_declare_vars($current_fix_var);
208 330 $perl .= $self->emit_declare_vars($var, '$_[0]');
209 330 $perl .= "eval {";
210  
211 # Loop over all the fixes and emit their code
212 330 $perl .= $self->emit_fixes($self->fixes);
213  
214 327 $perl .= "return ${var};";
215 327 $perl .= $self->_reject_label . ": return ${reject_var};";
216 327 $perl .= "} or do {";
217 327 $perl .= $self->emit_declare_vars($err, '$@');
218 327 $perl .= "${err}->throw if is_instance(${err},'Throwable::Error');";
219 327 $perl
220 .= "Catmandu::FixError->throw(message => ${err}, data => ${var}, fix => ${current_fix_var});";
221 327 $perl .= "};";
222 327 $perl .= "};";
223  
224 327 ▶ if (%$captures) {
Branch: 1 branch
BranchTrueFalseTotal
if (%$captures) 327 0 327
225 my @captured_vars = map {
226 327 $self->emit_declare_vars($_,
227 '$_[1]->{' . $self->emit_string($_) . '}');
228 } keys %$captures;
229 327 $perl = join '', @captured_vars, $perl;
230 }
231  
232 327 ▶ if ($self->log->is_debug && $ENV{CATMANDU_PERLTIDY}) {
Branch: 1 branch
BranchTrueFalseTotal
if ($self->log->is_debug and $ENV{"CATMANDU_PERLTIDY"}) 0 327 327
Condition66%2/3
$self->log->is_debug and $ENV{"CATMANDU_PERLTIDY"}
!ll&&!rl&&r
32610
MC/DC0%0/2
$self->log->is_debug and $ENV{"CATMANDU_PERLTIDY"}
$self->log->is_debug $ENV{"CATMANDU_PERLTIDY"}
Truth table66%2/3
A and B
A= $self->log->is_debugB= $ENV{"CATMANDU_PERLTIDY"}
ABresult
0X0
100
111
233 0 my $fh = File::Temp->new;
234 0 binmode($fh, ':utf8');
235 0 $fh->printflush($perl);
236 0 my $path = $fh->filename;
237 0 my $tidy_perl = `perltidy -utf8 -npro -st -se $path`;
238 0 ▶ unless ($?) {
Branch: 1 branch
BranchTrueFalseTotal
unless ($?) 0 0 0
239 0 $perl = $tidy_perl;
240 }
241 }
242  
243 327 $self->log->debug($perl);
244  
245 327 $perl;
246 }
247  
248 # Emit an array of fixes
249 sub emit_fixes {
250 473 ▶ my ($self, $fixes) = @_;
Subroutine emit_fixes: called CC=2 SCAR=6.9
Pod documented
251 473 my $perl = '';
252  
253 473 ▶ for (my $i = 0; $i < @{$fixes}; $i++) {
Branch: 1 branch
BranchTrueFalseTotal
if ($i < @{$fixes;}) 452 473 925
254 452 my $fix = $fixes->[$i];
255 452 $perl
256 .= $self->_current_fix_var . " = "
257 . $self->_fixes_var
258 . "->[${i}];";
259 452 $perl .= $self->emit_fix($fix);
260 }
261  
262 473 $perl;
263 }
264  
265 sub emit_reject {
266 31 ▶ my ($self) = @_;
Subroutine emit_reject: called CC=1 SCAR=0.0
Pod documented
267 31 "goto " . $self->_reject_label . ";";
268 }
269  
270 sub emit_fix {
271 558 ▶ my ($self, $fix) = @_;
Subroutine emit_fix: called CC=2 SCAR=6.9
Pod documented
272 558 my $perl;
273  
274 558 ▶ if ($fix->can('emit')) {
Branch: 1 branch
BranchTrueFalseTotal
if ($fix->can('emit')) { } 540 18 558
275 $perl = $self->emit_block(
276 sub {
277 540 ▶ my ($label) = @_;
Subroutine __ANON__: called CC=1 SCAR=0.0
278 540 $fix->emit($self, $label);
279 }
280 540 );
281 }
282 else {
283 18 my $var = $self->var;
284 18 my $ref = $self->generate_var;
285 18 $self->_captures->{$ref} = $fix;
286 18 $perl = "${var} = ${ref}->fix(${var});";
287 }
288  
289 558 $perl;
290 }
291  
292 sub emit_block {
293 564 ▶ my ($self, $cb) = @_;
Subroutine emit_block: called CC=1 SCAR=0.0
Pod documented
294 564 my $n = $self->_num_labels;
295 564 $self->_num_labels($n + 1);
296 564 my $label = "__FIX__${n}";
297 564 my $perl = "${label}: {";
298 564 $perl .= $cb->($label);
299 564 $perl .= "};";
300 564 $perl;
301 }
302  
303 sub emit_clear_hash_ref {
304 3 ▶ my ($self, $var) = @_;
Subroutine emit_clear_hash_ref: called CC=1 SCAR=0.0
Pod documented
305 3 "undef %{${var}} if is_hash_ref(${var});";
306 }
307  
308 sub emit_value {
309 166 ▶ my ($self, $val) = @_;
Subroutine emit_value: called CC=3 SCAR=11.0
Pod documented
310  
311 # Number should look like number and don't start with a 0 (no support for octals)
312 166 ▶ is_number($val) && $val !~ /^0+/ ? $val : $self->emit_string($val);
Branch: 1 branch
BranchTrueFalseTotal
is_number($val) && !($val =~ /^0+/) ? : 12 154 166
Condition100%3/3
is_number($val) and not $val =~ /^0+/
!ll&&!rl&&r
151312
MC/DC100%2/2
is_number($val) and not $val =~ /^0+/
is_number($val) not $val =~ /^0+/
Truth table100%3/3
A and not(B)
A= is_number($val)B= not $val =~ /^0+/
ABresult
0X0
100
111
313 }
314  
315 sub emit_string {
316 1672 ▶ my ($self, $str) = @_;
Subroutine emit_string: called CC=1 SCAR=0.0
Pod documented
317 1672 B::perlstring($str);
318 }
319  
320 sub emit_match {
321 17 ▶ my ($self, $pattern) = @_;
Subroutine emit_match: called CC=1 SCAR=0.0
Pod undocumented
322 17 $pattern =~ s/\//\\\//g;
323 17 $pattern =~ s/\\$/\\\\/; # pattern can't end with an escape in m/.../
324 17 "m/$pattern/";
325 }
326  
327 sub emit_substitution {
328 3 ▶ my ($self, $pattern, $replace) = @_;
Subroutine emit_substitution: called CC=1 SCAR=0.0
Pod undocumented
329 3 $pattern =~ s/\//\\\//g;
330 3 $pattern =~ s/\\$/\\\\/; # pattern can't end with an escape in m/.../
331 3 $replace =~ s/\//\\\//g;
332 3 $replace =~ s/\\$/\\\\/; # pattern can't end with an escape in m/.../
333 3 "s/$pattern/$replace/";
334 }
335  
336 sub emit_declare_vars {
337 2076 ▶ my ($self, $var, $val) = @_;
Subroutine emit_declare_vars: called CC=4 SCAR=13.9
Pod documented
338 2076 ▶ $var = "(" . join(", ", @$var) . ")" if ref $var;
Branch: 1 branch
BranchTrueFalseTotal
if ref $var 2 2074 2076
339 2076 ▶ $val = "(" . join(", ", @$val) . ")" if ref $val;
Branch: 1 branch
BranchTrueFalseTotal
if ref $val 2 2074 2076
340 2076 ▶ if (defined $val) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined $val) 1717 359 2076
341 1717 return "my ${var} = ${val};";
342 }
343 359 "my ${var};";
344 }
345  
346 sub emit_new_scope {
347 0 ▶ "{";
Subroutine emit_new_scope: not called CC=1 SCAR=6.9
Pod undocumented
348 }
349  
350 sub emit_end_scope {
351 0 ▶ "};";
Subroutine emit_end_scope: not called CC=1 SCAR=6.9
Pod undocumented
352 }
353  
354 sub emit_foreach {
355 17 ▶ my ($self, $var, $cb) = @_;
Subroutine emit_foreach: called CC=1 SCAR=0.0
Pod documented
356 17 my $perl = "";
357 17 my $v = $self->generate_var;
358 17 $perl .= "foreach (\@{${var}}) {";
359 17 $perl .= $self->emit_declare_vars($v, '$_');
360 17 $perl .= $cb->($v);
361 17 $perl .= "}";
362 17 $perl;
363 }
364  
365 sub emit_foreach_key {
366 7 ▶ my ($self, $var, $cb) = @_;
Subroutine emit_foreach_key: called CC=1 SCAR=0.0
Pod documented
367 7 my $perl = "";
368 7 my $v = $self->generate_var;
369 7 $perl .= "foreach (keys(\%{${var}})) {";
370 7 $perl .= $self->emit_declare_vars($v, '$_');
371 7 $perl .= $cb->($v);
372 7 $perl .= "}";
373 7 $perl;
374 }
375  
376 sub emit_walk_path {
377 306 ▶ my ($self, $var, $keys, $cb) = @_;
Subroutine emit_walk_path: called CC=2 SCAR=6.9
Pod documented
378  
379 306 $keys = [@$keys]; # protect keys
380  
381 306 ▶ if (@$keys) { # protect $var
Branch: 1 branch
BranchTrueFalseTotal
if (@$keys) { } 61 245 306
382 61 my $v = $self->generate_var;
383 61 $self->emit_declare_vars($v, $var)
384 . $self->_emit_walk_path($v, $keys, $cb);
385 }
386 else {
387 245 $cb->($var);
388 }
389 }
390  
391 sub _emit_walk_path {
392 156 ▶ my ($self, $var, $keys, $cb) = @_;
Subroutine _emit_walk_path: called CC=6 SCAR=20.5
393  
394 156 ▶ @$keys || return $cb->($var);
Branch: 1 branch
BranchTrueFalseTotal
@$keys or return &$cb($var) 61 95 156
395  
396 95 my $key = shift @$keys;
397 95 my $str_key = $self->emit_string($key);
398 95 my $perl = "";
399  
400 95 ▶ if ($key =~ /^\d+$/) {
Branch: 2 branches
BranchTrueFalseTotal
if ($key =~ /^\d+$/) { } 0 95 95
elsif ($key eq '*') { } 17 78 95
401 0 $perl .= "if (is_hash_ref(${var})) {";
402 0 $perl .= "${var} = ${var}->{${str_key}};";
403 0 $perl .= $self->_emit_walk_path($var, [@$keys], $cb);
404 0 $perl .= "} elsif (is_array_ref(${var}) && \@{${var}} > ${key}) {";
405 0 $perl .= "${var} = ${var}->[${key}];";
406 0 $perl .= $self->_emit_walk_path($var, [@$keys], $cb);
407 0 $perl .= "}";
408 }
409 elsif ($key eq '*') {
410 17 my $v = $self->generate_var;
411 17 $perl .= "if (is_array_ref(${var})) {";
412 $perl .= $self->emit_foreach(
413 $var,
414 sub {
415 17 ▶ return $self->_emit_walk_path(shift, $keys, $cb);
Subroutine __ANON__: called CC=1 SCAR=0.0
416 }
417 17 );
418 17 $perl .= "}";
419 }
420 else {
421 78 ▶ if ($key eq '$first') {
Branch: 2 branches
BranchTrueFalseTotal
if ($key eq '$first') { } 0 78 78
elsif ($key eq '$last') { } 0 78 78
422 0 $perl .= "if (is_array_ref(${var}) && \@{${var}}) {";
423 0 $perl .= "${var} = ${var}->[0];";
424 }
425 elsif ($key eq '$last') {
426 0 $perl .= "if (is_array_ref(${var}) && \@{${var}}) {";
427 0 $perl .= "${var} = ${var}->[\@{${var}} - 1];";
428 }
429 else {
430 78 $perl .= "if (is_hash_ref(${var})) {";
431 78 $perl .= "${var} = ${var}->{${str_key}};";
432 }
433 78 $perl .= $self->_emit_walk_path($var, $keys, $cb);
434 78 $perl .= "}";
435 }
436  
437 95 $perl;
438 }
439  
440 sub emit_create_path {
441 147 ▶ my ($self, $var, $keys, $cb) = @_;
Subroutine emit_create_path: called CC=1 SCAR=0.0
Pod documented
442 147 $self->_emit_create_path($var, [@$keys], $cb);
443 }
444  
445 sub _emit_create_path {
446 354 ▶ my ($self, $var, $keys, $cb) = @_;
Subroutine _emit_create_path: called CC=12 SCAR=24.8
447  
448 354 ▶ @$keys || return $cb->($var);
Branch: 1 branch
BranchTrueFalseTotal
@$keys or return &$cb($var) 152 202 354
449  
450 202 my $key = shift @$keys;
451 202 my $str_key = $self->emit_string($key);
452 202 my $perl = "";
453  
454 202 ▶ if ($key =~ /^\d+$/) {
Branch: 2 branches
BranchTrueFalseTotal
if ($key =~ /^\d+$/) { } 4 198 202
elsif ($key eq '*') { } 1 197 198
455 4 my $v1 = $self->generate_var;
456 4 my $v2 = $self->generate_var;
457 4 $perl .= "if (is_hash_ref(${var})) {";
458 4 $perl .= "my ${v1} = ${var};";
459 4 $perl
460 .= $self->_emit_create_path("${v1}->{${str_key}}", [@$keys], $cb);
461 4 $perl .= "} elsif (is_maybe_array_ref(${var})) {";
462 4 $perl .= "my ${v2} = ${var} //= [];";
463 4 $perl .= $self->_emit_create_path("${v2}->[${key}]", [@$keys], $cb);
464 4 $perl .= "}";
465 }
466 elsif ($key eq '*') {
467 1 my $v1 = $self->generate_var;
468 1 my $v2 = $self->generate_var;
469 1 $perl .= "if (is_array_ref(${var})) {";
470 1 $perl .= "my ${v1} = ${var};";
471 1 $perl .= "for (my ${v2} = 0; ${v2} < \@{${v1}}; ${v2}++) {";
472 1 $perl .= $self->_emit_create_path("${v1}->[${v2}]", $keys, $cb);
473 1 $perl .= "}";
474 1 $perl .= "}";
475 }
476 else {
477 197 my $v = $self->generate_var;
478 197 ▶ if ( $key eq '$first'
Branch: 1 branch
BranchTrueFalseTotal
if ($key eq '$first' or $key eq '$last' or $key eq '$prepend' or $key eq '$append') { } 22 175 197
Condition100%9/9
$key eq "\$first" or $key eq "\$last" or $key eq "\$prepend" or $key eq "\$append"
l!l&&r!l&&!r
319175
$key eq "\$first" or $key eq "\$last" or $key eq "\$prepend"
l!l&&r!l&&!r
21194
$key eq "\$first" or $key eq "\$last"
l!l&&r!l&&!r
11195
MC/DC100%4/4
$key eq "\$first" or $key eq "\$last" or $key eq "\$prepend" or $key eq "\$append"
$key eq "\$first" $key eq "\$last" $key eq "\$prepend" $key eq "\$append"
Truth table100%5/5
A or B or C or D
A= $key eq "\$first"B= $key eq "\$last"C= $key eq "\$prepend"D= $key eq "\$append"
ABCDresult
1XXX1
01XX1
001X1
00011
00000
479 || $key eq '$last'
480 || $key eq '$prepend'
481 || $key eq '$append')
482 {
483 22 $perl .= "if (is_maybe_array_ref(${var})) {";
484 22 $perl .= "my ${v} = ${var} //= [];";
485 22 ▶ if ($key eq '$first') {
Branch: 4 branches
BranchTrueFalseTotal
if ($key eq '$first') { } 1 21 22
elsif ($key eq '$last') { } 1 20 21
elsif ($key eq '$prepend') { } 1 19 20
elsif ($key eq '$append') { } 19 0 19
486 1 $perl .= $self->_emit_create_path("${v}->[0]", $keys, $cb);
487 }
488 elsif ($key eq '$last') {
489 1 $perl .= "if (\@${v}) {";
490 1 $perl .= $self->_emit_create_path("${v}->[\@${v} - 1]",
491 [@$keys], $cb);
492 1 $perl .= "} else {";
493 1 $perl .= $self->_emit_create_path("${v}->[0]", [@$keys], $cb);
494 1 $perl .= "}";
495 }
496 elsif ($key eq '$prepend') {
497 1 $perl .= "if (\@${v}) {";
498 1 $perl .= "unshift(\@${v}, undef);";
499 1 $perl .= "}";
500 1 $perl .= $self->_emit_create_path("${v}->[0]", $keys, $cb);
501 }
502 elsif ($key eq '$append') {
503 19 $perl
504 .= $self->_emit_create_path("${v}->[\@${v}]", $keys, $cb);
505 }
506 22 $perl .= "}";
507 }
508 else {
509 175 $perl .= "if (is_maybe_hash_ref(${var})) {";
510 175 $perl .= "my ${v} = ${var} //= {};";
511 175 $perl
512 .= $self->_emit_create_path("${v}->{${str_key}}", $keys, $cb);
513 175 $perl .= "}";
514 }
515 }
516  
517 202 $perl;
518 }
519  
520 sub emit_get_key {
521 180 ▶ my ($self, $var, $key, $cb) = @_;
Subroutine emit_get_key: called CC=6 SCAR=17.9
Pod documented
522  
523 180 ▶ return $cb->($var) unless defined $key;
Branch: 1 branch
BranchTrueFalseTotal
unless defined $key 10 170 180
524  
525 170 my $str_key = $self->emit_string($key);
526 170 my $perl = "";
527  
528 170 ▶ if ($key =~ /^\d+$/) {
Branch: 4 branches
BranchTrueFalseTotal
if ($key =~ /^\d+$/) { } 2 168 170
elsif ($key eq '$first') { } 1 167 168
elsif ($key eq '$last') { } 1 166 167
elsif ($key eq '*') { } 15 151 166
529 2 $perl .= "if (is_hash_ref(${var}) && exists(${var}->{${str_key}})) {";
530 2 $perl .= $cb->("${var}->{${str_key}}");
531 2 $perl .= "} elsif (is_array_ref(${var}) && \@{${var}} > ${key}) {";
532 2 $perl .= $cb->("${var}->[${key}]");
533 2 $perl .= "}";
534 }
535 elsif ($key eq '$first') {
536 1 $perl .= "if (is_array_ref(${var}) && \@{${var}}) {";
537 1 $perl .= $cb->("${var}->[0]");
538 1 $perl .= "}";
539 }
540 elsif ($key eq '$last') {
541 1 $perl .= "if (is_array_ref(${var}) && \@{${var}}) {";
542 1 $perl .= $cb->("${var}->[\@{${var}} - 1]");
543 1 $perl .= "}";
544 }
545 elsif ($key eq '*') {
546 15 my $i = $self->generate_var;
547 15 $perl .= "if (is_array_ref(${var})) {";
548 15 $perl .= "for (my ${i} = 0; ${i} < \@{${var}}; ${i}++) {";
549 15 $perl .= $cb->("${var}->[${i}]", $i);
550 15 $perl .= "}}";
551 }
552 else {
553 151 $perl .= "if (is_hash_ref(${var}) && exists(${var}->{${str_key}})) {";
554 151 $perl .= $cb->("${var}->{${str_key}}");
555 151 $perl .= "}";
556 }
557  
558 170 $perl;
559 }
560  
561 sub emit_set_key {
562 61 ▶ my ($self, $var, $key, $val) = @_;
Subroutine emit_set_key: called CC=8 SCAR=32.2
Pod documented
563  
564 61 ▶ return "${var} = $val;" unless defined $key;
Branch: 1 branch
BranchTrueFalseTotal
unless defined $key 0 61 61
565  
566 61 my $perl = "";
567 61 my $str_key = $self->emit_string($key);
568  
569 61 ▶ if ($key =~ /^\d+$/) {
Branch: 6 branches
BranchTrueFalseTotal
if ($key =~ /^\d+$/) { } 0 61 61
elsif ($key eq '$first') { } 0 61 61
elsif ($key eq '$last') { } 0 61 61
elsif ($key eq '$prepend') { } 0 61 61
elsif ($key eq '$append') { } 0 61 61
elsif ($key eq '*') { } 0 61 61
570 0 $perl .= "if (is_hash_ref(${var})) {";
571 0 $perl .= "${var}->{${str_key}} = $val;";
572 0 $perl .= "} elsif (is_array_ref(${var})) {";
573 0 $perl .= "${var}->[${key}] = $val;";
574 0 $perl .= "}";
575 }
576 elsif ($key eq '$first') {
577 0 $perl .= "if (is_array_ref(${var})) {";
578 0 $perl .= "${var}->[0] = $val;";
579 0 $perl .= "}";
580 }
581 elsif ($key eq '$last') {
582 0 $perl .= "if (is_array_ref(${var})) {";
583 0 $perl .= "${var}->[\@{${var}} - 1] = $val;";
584 0 $perl .= "}";
585 }
586 elsif ($key eq '$prepend') {
587 0 $perl .= "if (is_array_ref(${var})) {";
588 0 $perl .= "unshift(\@{${var}}, $val);";
589 0 $perl .= "}";
590 }
591 elsif ($key eq '$append') {
592 0 $perl .= "if (is_array_ref(${var})) {";
593 0 $perl .= "push(\@{${var}}, $val);";
594 0 $perl .= "}";
595 }
596 elsif ($key eq '*') {
597 0 my $i = $self->generate_var;
598 0 $perl .= "if (is_array_ref(${var})) {";
599 0 $perl .= "for (my ${i} = 0; ${i} < \@{${var}}; ${i}++) {";
600 0 $perl .= "${var}->[${i}] = $val;";
601 0 $perl .= "}}";
602 }
603 else {
604 61 $perl .= "if (is_hash_ref(${var})) {";
605 61 $perl .= "${var}->{${str_key}} = $val;";
606 61 $perl .= "}";
607 }
608  
609 61 $perl;
610 }
611  
612 sub emit_delete_key {
613 15 ▶ my ($self, $var, $key, $cb) = @_;
Subroutine emit_delete_key: called CC=18 SCAR=29.0
Pod documented
614  
615 15 my $str_key = $self->emit_string($key);
616 15 my $perl = "";
617 15 my $vals;
618 15 ▶ if ($cb) {
Branch: 1 branch
BranchTrueFalseTotal
if ($cb) 5 10 15
619 5 $vals = $self->generate_var;
620 5 $perl = $self->emit_declare_vars($vals, '[]');
621 }
622  
623 15 ▶ if ($key =~ /^\d+$/) {
Branch: 2 branches
BranchTrueFalseTotal
if ($key =~ /^\d+$/) { } 2 13 15
elsif ($key eq '$first' or $key eq '$last' or $key eq '*') { } 3 10 13
624 2 $perl .= "if (is_hash_ref(${var}) && exists(${var}->{${str_key}})) {";
625 2 ▶ $perl .= "push(\@{${vals}}, " if $cb;
Branch: 1 branch
BranchTrueFalseTotal
if $cb 0 2 2
626 2 $perl .= "delete(${var}->{${str_key}})";
627 2 ▶ $perl .= ")" if $cb;
Branch: 1 branch
BranchTrueFalseTotal
if $cb 0 2 2
628 2 $perl .= ";";
629 2 $perl .= "} elsif (is_array_ref(${var}) && \@{${var}} > ${key}) {";
630 2 ▶ $perl .= "push(\@{${vals}}, " if $cb;
Branch: 1 branch
BranchTrueFalseTotal
if $cb 0 2 2
631 2 $perl .= "splice(\@{${var}}, ${key}, 1)";
632 2 ▶ $perl .= ")" if $cb;
Branch: 1 branch
BranchTrueFalseTotal
if $cb 0 2 2
633 }
634 ▶ elsif ($key eq '$first' || $key eq '$last' || $key eq '*') {
Condition100%6/6
$key eq "\$first" or $key eq "\$last" or $key eq "*"
l!l&&r!l&&!r
2110
$key eq "\$first" or $key eq "\$last"
l!l&&r!l&&!r
1111
MC/DC100%3/3
$key eq "\$first" or $key eq "\$last" or $key eq "*"
$key eq "\$first" $key eq "\$last" $key eq "*"
Truth table100%4/4
A or B or C
A= $key eq "\$first"B= $key eq "\$last"C= $key eq "*"
ABCresult
1XX1
01X1
0011
0000
635 3 $perl .= "if (is_array_ref(${var}) && \@{${var}}) {";
636 3 ▶ $perl .= "push(\@{${vals}}, " if $cb;
Branch: 1 branch
BranchTrueFalseTotal
if $cb 0 3 3
637 3 ▶ $perl .= "splice(\@{${var}}, 0, 1)" if $key eq '$first';
Branch: 1 branch
BranchTrueFalseTotal
if $key eq "\$first" 1 2 3
638 3 ▶ $perl .= "splice(\@{${var}}, \@{${var}} - 1, 1)" if $key eq '$last';
Branch: 1 branch
BranchTrueFalseTotal
if $key eq "\$last" 1 2 3
639 3 ▶ $perl .= "splice(\@{${var}}, 0, \@{${var}})" if $key eq '*';
Branch: 1 branch
BranchTrueFalseTotal
if $key eq "*" 1 2 3
640 3 ▶ $perl .= ")" if $cb;
Branch: 1 branch
BranchTrueFalseTotal
if $cb 0 3 3
641 }
642 else {
643 10 $perl .= "if (is_hash_ref(${var}) && exists(${var}->{${str_key}})) {";
644 10 ▶ $perl .= "push(\@{${vals}}, " if $cb;
Branch: 1 branch
BranchTrueFalseTotal
if $cb 5 5 10
645 10 $perl .= "delete(${var}->{${str_key}})";
646 10 ▶ $perl .= ")" if $cb;
Branch: 1 branch
BranchTrueFalseTotal
if $cb 5 5 10
647 }
648 15 $perl .= ";";
649 15 $perl .= "}";
650 15 ▶ if ($cb) {
Branch: 1 branch
BranchTrueFalseTotal
if ($cb) 5 10 15
651 5 $perl .= $cb->($vals);
652 }
653  
654 15 $perl;
655 }
656  
657 sub emit_retain_key {
658 8 ▶ my ($self, $var, $key) = @_;
Subroutine emit_retain_key: called CC=6 SCAR=17.9
Pod documented
659  
660 8 my $perl = "";
661  
662 8 ▶ if ($key =~ /^\d+$/) {
Branch: 4 branches
BranchTrueFalseTotal
if ($key =~ /^\d+$/) { } 2 6 8
elsif ($key eq '$first') { } 1 5 6
elsif ($key eq '$last') { } 1 4 5
elsif ($key eq '*') { } 2 2 4
663 2 $perl .= "if (is_hash_ref(${var})) {";
664 $perl .= $self->emit_foreach_key(
665 $var,
666 sub {
667 2 ▶ my $v = shift;
Subroutine __ANON__: called CC=1 SCAR=0.0
668 2 "delete(${var}->{${v}}) if ${v} ne ${key};";
669 }
670 2 );
671 2 $perl .= "} elsif (is_array_ref(${var})) {";
672 2 $perl .= "if (\@{${var}} > ${key}) {";
673 2 ▶ $perl .= "splice(\@{${var}}, 0, ${key});" if $key > 0;
Branch: 1 branch
BranchTrueFalseTotal
if $key > 0 2 0 2
674 2 $perl .= "splice(\@{${var}}, 1, \@{${var}} - 1);";
675 2 $perl .= "} else {";
676 2 $perl .= "splice(\@{${var}}, 0, \@{${var}});";
677 2 $perl .= "}";
678 2 $perl .= "}";
679 }
680 elsif ($key eq '$first') {
681 1 $perl .= "if (is_array_ref(${var}) && \@{${var}} > 1) {";
682 1 $perl .= "splice(\@{${var}}, 1, \@{${var}} - 1);";
683 1 $perl .= "}";
684 }
685 elsif ($key eq '$last') {
686 1 $perl .= "if (is_array_ref(${var}) && \@{${var}} > 1) {";
687 1 $perl .= "splice(\@{${var}}, 0, \@{${var}} - 1);";
688 1 $perl .= "}";
689 }
690 elsif ($key eq '*') {
691  
692 # retain everything
693 }
694 else {
695 2 $key = $self->emit_string($key);
696 2 $perl .= "if (is_hash_ref(${var})) {";
697 $perl .= $self->emit_foreach_key(
698 $var,
699 sub {
700 2 ▶ my $v = shift;
Subroutine __ANON__: called CC=1 SCAR=0.0
701 2 "if ($v ne ${key}) {" . "delete(${var}->{${v}});" . "}";
702 }
703 2 );
704 2 $perl .= "}";
705 }
706  
707 8 $perl;
708 }
709  
710 sub emit_clone {
711 1 ▶ my ($self, $var) = @_;
Subroutine emit_clone: called CC=1 SCAR=0.0
Pod documented
712 1 "$var = clone($var);";
713 }
714  
715 sub split_path {
716 450 ▶ my ($self, $path) = @_;
Subroutine split_path: called CC=1 SCAR=0.0
Pod documented
717 450 return [split /[\/\.]/, trim($path)];
718 }
719  
720 119 1;
721  
722 __END__
723  
724 =pod
725  
726 =head1 NAME
727  
728 Catmandu::Fix - a Catmandu class used for data transformations
729  
730 =head1 SYNOPSIS
731  
732 # From the command line
733  
734 $ catmandu convert JSON --fix 'add_field(foo,bar)' < data.json
735 $ catmandu convert YAML --fix 'upcase(job); remove_field(test)' < data.yml
736 $ catmandu convert CSV --fix 'sort_field(tags)' < data.csv
737 $ catmandu run /tmp/myfixes.txt
738 $ catmandu convert OAI --url http://biblio.ugent.be/oai --fix /tmp/myfixes.txt
739  
740 # From Perl
741  
742 use Catmandu;
743  
744 my $fixer = Catmandu->fixer('upcase(job)','remove_field(test)');
745 my $fixer = Catmandu->fixer('/tmp/myfixes.txt');
746  
747 # Convert data
748 my $arr = $fixer->fix([ ... ]);
749 my $hash = $fixer->fix({ ... });
750 my $importer = Catmandu->importer('YAML', file => 'data.yml');
751 my $fixed_importer = $fixer->fix($importer);
752  
753 # Inline fixes
754 use Catmandu::Fix::upcase as => 'my_upcase';
755 use Catmandu::Fix::remove_field as => 'my_remove';
756  
757 my $hash = { 'job' => 'librarian' , deep => { nested => '1'} };
758  
759 my_upcase($hash,'job');
760 my_remove($hash,'deep.nested');
761  
762 =head1 DESCRIPTION
763  
764 A Catmandu::Fix is a Perl package that can transform data. These packages are used
765 for easy data manipulation by non programmers. The main intention is to use fixes
766 on the command line or in Fix scripts. A small DSL language is available to execute
767 many Fix command on a stream of data.
768  
769 When a C<fix> argument is given to a L<Catmandu::Importer>, L<Catmandu::Exporter> or
770 L<Catmandu::Store> then the transformations are executed on every item in the stream.
771  
772 =head1 FIX LANGUAGE
773  
774 A Fix script is a collection of one or more Fix commands. The fixes are executed
775 on every record in the dataset. If this command is executed on the command line:
776  
777 $ catmandu convert JSON --fix 'upcase(title); add_field(deep.nested.field,1)' < data.json
778  
779 then all the title fields will be upcased and a new deeply nested field will be added:
780  
781 { "title":"foo" }
782 { "title":"bar" }
783  
784 becomes:
785  
786 { "title":"FOO" , "deep":{"nested":{"field":1}} }
787 { "title":"BAR" , "deep":{"nested":{"field":1}} }
788  
789 Using the command line, Fix commands need a semicolon (;) as separator. All these commands can
790 also be written into a Fix script where semicolons are not required:
791  
792 $ catmandu convert JSON --fix script.fix < data.json
793  
794 where C<script.fix> contains:
795  
796 upcase(title)
797 add_field(deep.nested.field,1)
798  
799 Conditionals can be used to provide the logic when to execute fixes:
800  
801 if exists(deep.nested.field)
802 add_field(nested,"ok!")
803 end
804  
805 unless all_match(title,"PERL")
806 add_field(is_perl,"noooo")
807 end
808  
809 Binds are used to manipulate the context in which Fixes are executed. E.g.
810 execute a fix on every item in a list:
811  
812 # 'demo' is an array of hashes
813 do list(path:demo)
814 add_field(foo,bar)
815 end
816  
817 To delete records from a stream of data the C<reject> Fix can be used:
818  
819 reject() # Reject all in the stream
820  
821 if exists(foo)
822 reject() # Reject records that contain a 'foo' field
823 end
824  
825 reject exists(foo) # Reject records that contain a 'foo' field
826  
827 The opposite of C<reject> is C<select>:
828  
829 select() # Keep all records in the stream
830  
831 select exists(foo) # Keep only the records that contain a 'foo' field
832  
833 Comments in Fix scripts are all lines (or parts of a line) that start with a hash (#):
834  
835 # This is ignored
836 add_field(test,123) # This is also a comment
837  
838 =head1 PATHS
839  
840 Most of the Fix commandsuse paths to point to values
841 in a data record. E.g. 'foo.2.bar' is a key 'bar' which is the 3-rd value of the
842 key 'foo'.
843  
844 A special case is when you want to point to all items in an array. In this case
845 the wildcard '*' can be used. E.g. 'foo.*' points to all the items in the 'foo'
846 array.
847  
848 For array values there are special wildcards available:
849  
850 * $append - Add a new item at the end of an array
851 * $prepend - Add a new item at the start of an array
852 * $first - Syntactic sugar for index '0' (the head of the array)
853 * $last - Syntactic sugar for index '-1' (the tail of the array)
854  
855 E.g.
856  
857 # Create { mods => { titleInfo => [ { 'title' => 'a title' }] } };
858 add_field('mods.titleInfo.$append.title', 'a title');
859  
860 # Create { mods => { titleInfo => [ { 'title' => 'a title' } , { 'title' => 'another title' }] } };
861 add_field('mods.titleInfo.$append.title', 'another title');
862  
863 # Create { mods => { titleInfo => [ { 'title' => 'foo' } , { 'title' => 'another title' }] } };
864 add_field('mods.titleInfo.$first.title', 'foo');
865  
866 # Create { mods => { titleInfo => [ { 'title' => 'foo' } , { 'title' => 'bar' }] } };
867 add_field('mods.titleInfo.$last.title', 'bar');
868  
869 =head1 OPTIONS
870  
871 =head2 fixes
872  
873 An array of fixes. L<Catmandu::Fix> which will execute every fix in consecutive
874 order. A fix can be the name of a Catmandu::Fix::* routine, or the path to a
875 plain text file containing all the fixes to be executed. Required.
876  
877 =head2 preprocess
878  
879 If set to C<1>, fix files or inline fixes will first be preprocessed as a
880 moustache template. See C<variables> below for an example. Default is C<0>, no
881 preprocessing.
882  
883 =head2 variables
884  
885 An optional hashref of variables that are used to preprocess the fix files or
886 inline fixes as a moustache template. Setting the C<variables> option also sets
887 C<preprocess> to 1.
888  
889 my $fixer = Catmandu::Fix->new(
890 variables => {x => 'foo', y => 'bar'},
891 fixes => ['add_field({{x}},{{y}})'],
892 );
893 my $data = {};
894 $fixer->fix($data);
895 # $data is now {foo => 'bar'}
896  
897 =head1 METHODS
898  
899 =head2 fix(HASH)
900  
901 Execute all the fixes on a HASH. Returns the fixed HASH.
902  
903 =head2 fix(ARRAY)
904  
905 Execute all the fixes on every element in the ARRAY. Returns an ARRAY of fixes.
906  
907 =head2 fix(Catmandu::Iterator)
908  
909 Execute all the fixes on every item in an L<Catmandu::Iterator>. Returns a
910 (lazy) iterator on all the fixes.
911  
912 =head2 fix(sub {})
913  
914 Executes all the fixes on a generator function. Returns a new generator with fixed data.
915  
916 =head2 log
917  
918 Return the current logger. See L<Catmandu> for activating the logger in your main code.
919  
920 =head1 CODING
921  
922 One can extend the Fix language by creating own custom-made fixes. Two methods are
923 available to create an own Fix function:
924  
925 * Quick and easy: create a class that implements a C<fix> method.
926 * Advanced: create a class that emits Perl code that will be evaled by the Fix module.
927  
928 Both methods will be explained shortly.
929  
930 =head2 Quick and easy
931  
932 A Fix function is a Perl class in the C<Catmandu::Fix> namespace that implements a C<fix> method.
933 The C<fix> methods accepts a Perl hash as input and returns a (fixed) Perl hash as output. As
934 an example, the code belows implements the C<meow> Fix which inserts a 'meow' field with value 'purrrrr'.
935  
936 package Catmandu::Fix::meow;
937  
938 use Moo;
939  
940 sub fix {
941 my ($self,$data) = @_;
942 $data->{meow} = 'purrrrr';
943 $data;
944 }
945  
946 1;
947  
948 Given this Perl class, the following fix statement can be used in your application:
949  
950 # Will add 'meow' = 'purrrrr' to the data
951 meow()
952  
953 Use the quick and easy method when your fixes are not dependent on reading or writing data
954 from/to a JSON path. Your Perl classes need to implement their own logic to read or write data
955 into the given Perl hash.
956  
957 Fix arguments are passed as arguments to the C<new> function of the Perl class. As in
958  
959 # In the fix file...
960 meow('test123', -count => 4)
961  
962 # ...will be translated into this pseudo code
963 my $fix = Catmandu::Fix::meow->new('test123', '-count', 4);
964  
965 Using L<Moo> these arguments can be catched with L<Catmandu::Fix::Has> package:
966  
967 package Catmandu::Fix::meow;
968  
969 use Catmandu::Sane;
970 use Moo;
971 use Catmandu::Fix::Has;
972  
973 has msg => (fix_arg => 1); # required parameter 1
974 has count => (fix_opt => 1, default => sub { 4 }); # optional parameter 'count' with default value 4
975  
976 sub fix {
977 my ($self,$data) = @_;
978 $data->{meow} = $self->msg x $self->count;
979 $data;
980 }
981  
982 1;
983  
984 Using this code the fix statement can be used like:
985  
986 # Will add 'meow' = 'purrpurrpurrpurr'
987 meow('purr', -count => 4)
988  
989 =head2 Advanced
990  
991 The advanced method is required when one needs to read or write values from/to deeply nested JSON paths.
992 One could parse JSON paths using the quick and easy Perl class above, but this would require a
993 lot of inefficient for-while loops. The advanced method emits Perl code that gets compiled.
994 This compiled code is evaled against all Perl hashes in the unput.The best
995 way to learn this method is by inspecting some example Fix commands.
996  
997 To ease the implementation of Fixed that emit Perl code some helper methods are created. Many Fix functions
998 require a transformation of one or more values on a JSON Path. The L<Catmandu::Fix::SimpleGetValue>
999 provides an easy way to create such as script. In the example below we'll set the value at a JSON Path
1000 to 'purrrrr':
1001  
1002 package Catmandu::Fix::purrrrr;
1003  
1004 use Catmandu::Sane;
1005 use Moo;
1006 use Catmandu::Fix::Has;
1007  
1008 has path => (fix_arg => 1);
1009  
1010 with 'Catmandu::Fix::SimpleGetValue';
1011  
1012 sub emit_value {
1013 my ($self, $var, $fixer) = @_;
1014 "${var} = 'purrrrr';";
1015 }
1016  
1017 1;
1018  
1019 Run this command as:
1020  
1021 # Set the value(s) of an existing path to 'purrr'
1022 purrrrr(my.deep.nested.path)
1023 purrrrr(all.my.values.*)
1024  
1025 Notice how the C<emit_value> of the Catmandu::Fix::purrrrr package returns Perl code and doesn't
1026 operate directy on the Perl data. The parameter C<$var> contains only the name of a temporary variable
1027 that will hold the value of the JSON path after compiling the code into Perl.
1028  
1029 Use L<Catmandu::Fix::Has> to add more arguments to this fix:
1030  
1031 package Catmandu::Fix::purrrrr;
1032  
1033 use Catmandu::Sane;
1034 use Moo;
1035 use Catmandu::Fix::Has;
1036  
1037 has path => (fix_arg => 1);
1038 has msg => (fix_opt => 1 , default => sub { 'purrrrr' });
1039  
1040 with 'Catmandu::Fix::SimpleGetValue';
1041  
1042 sub emit_value {
1043 my ($self, $var, $fixer) = @_;
1044 my $msg = $fixer->emit_string($self->msg);
1045 "${var} = ${msg};";
1046 }
1047  
1048 1;
1049  
1050 Run this command as:
1051  
1052 # Set the value(s) of an existing path to 'okido'
1053 purrrrr(my.deep.nested.path, -msg => 'okido')
1054 purrrrr(all.my.values.*, -msg => 'okido')
1055  
1056 Notice how the C<emit_value> needs to quote the C<msg> option using the emit_string function.
1057  
1058 =head1 INTERNAL METHODS
1059  
1060 This module provides several methods for writing fix packages. Usage can best
1061 be understood by reading the code of existing fix packages.
1062  
1063 =over
1064  
1065 =item capture
1066  
1067 =item emit_block
1068  
1069 =item emit_clone
1070  
1071 =item emit_clear_hash_ref
1072  
1073 =item emit_create_path
1074  
1075 =item emit_declare_vars
1076  
1077 =item emit_delete_key
1078  
1079 =item emit_fix
1080  
1081 =item emit_fixes
1082  
1083 =item emit_foreach
1084  
1085 =item emit_foreach_key
1086  
1087 =item emit_get_key
1088  
1089 =item emit_reject
1090  
1091 =item emit_retain_key
1092  
1093 this method is DEPRECATED.
1094  
1095 =item emit_set_key
1096  
1097 =item emit_string
1098  
1099 =item emit_value
1100  
1101 =item emit_walk_path
1102  
1103 =item generate_var
1104  
1105 =item split_path
1106  
1107 =back
1108  
1109 =head1 SEE ALSO
1110  
1111 L<Catmandu::Fixable>,
1112 L<Catmandu::Importer>,
1113 L<Catmandu::Exporter>,
1114 L<Catmandu::Store>,
1115 L<Catmandu::Bag>
1116  
1117 =cut
« blib/lib/Catmandu/Paged.pm ↑ Summary blib/lib/Catmandu/Cmd/run.pm »