| 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
| |||||||||||
| 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
| |||||||||||
| 63 | 57 | $perl .= "${unit} = ${bind_var}->result(${unit});"; | |||||||||
| 64 | } | ||||||||||
| 65 | |||||||||||
| 66 | 104 | ▶ | if ($self->return) { | ||||||||
|
Branch: 1 branch
| |||||||||||
| 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 | ||||||||||