blib/lib/Catmandu/Fix/Bind.pm

filter: Statementstmt 97.8% 46 / 47 Branchbran 83.3% 5 / 6 Conditioncond n/a MC/DCmcdc n/a Subroutinesub 100% 9 / 9 Podpod 66.6% 2 / 3 totaltotal 95.3% 62 / 65 CC 5 SCAR 7.3
CC
5
Cov
96%
emit
4.0
__ANON__
2.0
BEGIN
1.0
CRAP 2.1
« blib/lib/Catmandu/Fix/move_field.pm ↑ Summary blib/lib/Catmandu.pm »
1 package Catmandu::Fix::Bind;
2  
3 10 ▶use Catmandu::Sane;
Subroutine BEGIN: called CC=1 SCAR=0.0
4  
5 10 our $VERSION = '1.0201_02';
6  
7 10 ▶use Moo::Role;
Subroutine BEGIN: called CC=1 SCAR=0.0
8 10 ▶use namespace::clean;
Subroutine BEGIN: called CC=1 SCAR=0.0
9  
10 10 with 'Catmandu::Logger';
11  
12 10 requires 'unit';
13 10 requires 'bind';
14  
15 97 ▶has return => (is => 'rw', default => sub {[0]});
Subroutine __ANON__: called CC=1 SCAR=0.0
16 97 ▶has fixes => (is => 'rw', default => sub {[]});
Subroutine __ANON__: called CC=1 SCAR=0.0
17  
18 around bind => sub {
19 133 ▶ my ($orig, $self, $prev, @args) = @_;
Subroutine __ANON__: called CC=2 SCAR=6.9
20 133 my $next = $orig->($self, $prev, @args);
21  
22 128 ▶ if ($self->can('plus')) {
Branch: 1 branch
BranchTrueFalseTotal
if ($self->can('plus')) { } 11 117 128
23 11 return $self->plus($prev, $next);
24 }
25 else {
26 117 return $next;
27 }
28 10 };
29  
30 sub unit {
31 58 ▶ my ($self, $data) = @_;
Subroutine unit: called CC=1 SCAR=0.0
Pod documented
32 58 return $data;
33 }
34  
35 sub bind {
36 33 ▶ my ($self, $data, $code, $name, $fixes) = @_;
Subroutine bind: called CC=1 SCAR=0.0
Pod documented
37 33 return $code->($data);
38 }
39  
40 sub emit {
41 104 ▶ my ($self, $fixer, $label) = @_;
Subroutine emit: called CC=4 SCAR=13.9
Pod undocumented
42 104 my $perl = "";
43  
44 104 my $var = $fixer->var;
45 104 my $bind_var = $fixer->capture($self);
46 104 my $unit = $fixer->generate_var;
47 104 my $sub_fixer = Catmandu::Fix->new(fixes => $self->fixes);
48 104 my $sub_fixer_var = $fixer->capture($sub_fixer);
49  
50 104 $perl .= "my ${unit} = ${bind_var}->unit(${var});";
51  
52 104 for my $fix (@{$self->fixes}) {
53 106 my $name = ref($fix);
54 106 my $original_code = $fixer->emit_fix($fix);
55 106 my $generated_code
56 = "sub { my ${var} = shift; $original_code ; ${var} }";
57  
58 106 $perl
59 .= "${unit} = ${bind_var}->bind(${unit}, $generated_code,'$name',${sub_fixer_var});";
60 }
61  
62 104 ▶ if ($self->can('result')) {
Branch: 1 branch
BranchTrueFalseTotal
if ($self->can("result")) 57 47 104
63 57 $perl .= "${unit} = ${bind_var}->result(${unit});";
64 }
65  
66 104 ▶ if ($self->return) {
Branch: 1 branch
BranchTrueFalseTotal
if ($self->return) 0 104 104
67 0 $perl .= "${var} = ${unit};";
68 }
69  
70 104 $perl;
71 }
72  
73 10 1;
74  
75 __END__
76  
77 =pod
78  
79 =head1 NAME
80  
81 Catmandu::Fix::Bind - a wrapper for Catmandu::Fix-es
82  
83 =head1 SYNOPSIS
84  
85 package Catmandu::Fix::Bind::demo;
86 use Moo;
87 with 'Catmandu::Fix::Bind';
88  
89 sub bind {
90 my ($self,$data,$code,$name) = @_;
91 warn "executing $name";
92 $code->($data);
93 }
94  
95 # in your fix script you can now write
96 do
97 demo()
98  
99 fix1()
100 fix2()
101 fix3()
102 end
103  
104 # this will execute all the fixes as expected, and print to STDERR the following messages
105  
106 executing fix1
107 executing fix2
108 executing fix3
109
110 =head1 DESCRIPTION
111  
112 Bind is a package that wraps Catmandu::Fix-es and other Catmandu::Bind-s together. This gives
113 the programmer further control on the excution of fixes. With Catmandu::Fix::Bind you can simulate
114 the 'before', 'after' and 'around' modifiers as found in Moo or Dancer.
115  
116 To wrap Fix functions, the Fix language has a 'do' statement:
117  
118 do BIND
119 FIX1
120 FIX2
121 FIX3
122 end
123  
124 where BIND is a implementation of Catmandu::Fix::Bind and FIX1,...,FIXn are Catmandu::Fix functions.
125  
126 In the example above the BIND will wrap FIX1, FIX2 and FIX3. BIND will first wrap the record data
127 using its 'unit' method and send the data sequentially to each FIX which can make inline changes
128 to the record data. In pseudo-code this will look like:
129  
130 $bind_data = $bind->unit($data);
131 $bind_data = $bind->bind($bind_data, $fix1);
132 $bind_data = $bind->bind($bind_data, $fix2);
133 $bind_data = $bind->bind($bind_data, $fix3);
134 return $data;
135  
136 An alternative form exists, 'doset' which will overwrite the record data with results of the last
137 fix.
138  
139 doset BIND
140 FIX1
141 FIX2
142 FIX3
143 end
144  
145 Will result in a pseudo code like:
146  
147 $bind_data = $bind->unit($data);
148 $bind_data = $bind->bind($bind_data, $fix1);
149 $bind_data = $bind->bind($bind_data, $fix2);
150 $bind_data = $bind->bind($bind_data, $fix3);
151 return $bind_data;
152  
153 A Catmandu::Fix::Bind needs to implement two methods: 'unit' and 'bind'.
154  
155 =head1 METHODS
156  
157 =head2 unit($data)
158  
159 The unit method receives a Perl $data HASH and should return it, possibly converted to a new type.
160 The 'unit' method is called before all Fix methods are executed. A trivial, but verbose, implementation
161 of 'unit' is:
162  
163 sub unit {
164 my ($self,$data) = @_;
165 my $wrapped_data = $data;
166 return $wrapped_data;
167 }
168  
169 =head2 bind($wrapped_data,$code,$name,$perl)
170  
171 The bind method is executed for every Catmandu::Fix method in the fix script. It receives the $wrapped_data
172 (wrapped by 'unit'), the fix method as anonymous subroutine and the name of the fix. It should return data
173 with the same type as returned by 'unit'.
174 A trivial, but verbose, implementaion of 'bind' is:
175  
176 sub bind {
177 my ($self,$wrapped_data,$code,$name,$perl) = @_;
178 my $data = $wrapped_data;
179 $data = $code->($data);
180 # we don't need to wrap it again because the $data and $wrapped_data have the same type
181 $data;
182 }
183  
184 =head1 REQUIREMENTS
185  
186 Bind modules are simplified implementations of Monads. They should answer the formal definition of Monads, codified
187 in 3 monadic laws:
188  
189 =head2 left unit: unit acts as a neutral element of bind
190  
191 my $monad = Catmandu::Fix::Bind->demo();
192  
193 # bind(unit(data), coderef) == unit(coderef(data))
194 $monad->bind( $monad->unit({foo=>'bar'}) , $coderef) == $monad->unit($coderef->({foo=>'bar'}));
195  
196 =head2 right unit: unit act as a neutral element of bind
197  
198 # bind(unit(data), unit) == unit(data)
199 $monad->bind( $monad->unit({foo=>'bar'}) , sub { $monad->unit(shift) } ) == $monad->unit({foo=>'bar'});
200  
201 =head2 associative: chaining bind blocks should have the same effect as nesting them
202  
203 # bind(bind(unit(data),f),g) == bind(unit(data), sub { return bind(unit(f(data)),g) } )
204 my $f = sub { my $data = shift; $data->{demo} = 1 ; $data };
205 my $g = sub { my $data = shift; $data->{demo} += 1 ; $data};
206  
207 $monad->bind( $monad->bind( $monad->unit({}) , f ) , g ) ==
208 $monad->bind( $monad->unit({}) , sub { my $data = shift; $monad->bind($monad->unit($f->($data)), $g ); $data; });
209  
210 =head1 SEE ALSO
211  
212 L<Catmandu::Fix::Bind::identity>, L<Catmandu::Fix::Bind::benchmark>
213  
214 =cut
« blib/lib/Catmandu/Fix/move_field.pm ↑ Summary blib/lib/Catmandu.pm »