blib/lib/PDL/Util.pm

filter: Statementstmt 95.1% 79 / 83 Branchbran 85.2% 29 / 34 Conditioncond 54.5% 6 / 11 MC/DCmcdc 28.5% 2 / 7 Subroutinesub 100% 12 / 12 Podpod 100% 3 / 3 totaltotal 87.3% 131 / 150 CC 23 SCAR 17.3
CC
23
Cov
89%
export2d
8.2
add_pdl_method
8.2
import
6.0
CRAP 5.7
↑ Summary
1 package PDL::Util;
2 {
3 6 $PDL::Util::VERSION = '0.010';
4 }
5  
6 6 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
7 6 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
8  
9 =head1 NAME
10  
11 PDL::Util
12  
13 =head1 SYNOPSIS
14  
15 use PDL;
16 use PDL::Util 'export2d';
17  
18 my $pdl = rvals(6,4);
19  
20 open my $fh, '>', 'file.dat';
21 export2d($pdl, $fh);
22  
23 =head1 DESCRIPTION
24  
25 Convenient utility functions/methods for use with PDL.
26  
27 =cut
28  
29 6 ▶use PDL;
Subroutine BEGIN: called CC=1 SCAR=0.0
30 6 ▶use Scalar::Util qw/openhandle blessed/;
Subroutine BEGIN: called CC=1 SCAR=0.0
31  
32 6 ▶use Carp;
Subroutine BEGIN: called CC=1 SCAR=0.0
33  
34 6 ▶use parent 'Exporter';
Subroutine BEGIN: called CC=1 SCAR=0.0
35 6 our %EXPORT_TAGS = (
36 functions => [qw/add_pdl_method/],
37 methods => [qw/unroll export2d/],
38 );
39  
40 6 our @EXPORT_OK;
41 6 push @EXPORT_OK, @$_ for values %EXPORT_TAGS;
42  
43 6 $EXPORT_TAGS{'all'} = \@EXPORT_OK;
44  
45 =head1 IMPORT
46  
47 use PDL:Util 'export2d', ['unroll']
48 # imports 'export2d', adds 'unroll' as a PDL method
49  
50 L<PDL::Util> does not export anything by default. A list of symbols may be imported as usual. The exportable symbols come in two types, functions (tag C<:function>) and methods (tag C<:methods>). The word I<methods> here is a strange word. When importing symbols one does not import methods. In this context a 'method' is a function which expects a piddle as its first argument. However, there is a reason ...
51  
52 If an array reference or hash reference is passed as the last item in the import list, the reference will be passed to the L<add_pdl_method> function below, in which case these functions are imported into the C<PDL> namespace and may be used as method calls. Note, when doing this for symbols from the L<PDL::Util> module, only those listed in the C<:methods> tag may be added as a method (this is the origin of the confusing terminology). Read about the L<add_pdl_method> function carefully before using this functionality.
53  
54 =cut
55  
56 6 ▶sub import {
Subroutine import: called CC=6 SCAR=17.9
57 6 my $package = shift;
58 6 ▶ return 1 unless @_;
Branch: 1 branch
BranchTrueFalseTotal
unless @_ 1 5 6
59  
60 5 ▶ my $ref_last = ref $_[-1] || '';
Condition100%2/2
ref $_[-1] || ''
l!l
32
MC/DC100%1/1
ref $_[-1] || ''
ref $_[-1]
Truth table100%2/2
A
A= ref $_[-1]
Aresult
11
00
61 5 ▶ my $method_spec = ( grep {$ref_last eq $_} qw/HASH ARRAY/ ) ? pop : 0;
Branch: 1 branch
BranchTrueFalseTotal
grep({$ref_last eq $_;} 'HASH', 'ARRAY') ? : 3 2 5
62  
63 5 ▶ add_pdl_method($method_spec) if ($method_spec);
Branch: 1 branch
BranchTrueFalseTotal
if $method_spec 3 2 5
64  
65 5 ▶ __PACKAGE__->export_to_level(1, $package, @_) if @_;
Branch: 1 branch
BranchTrueFalseTotal
if @_ 2 3 5
66 }
67  
68 =head1 TAG :functions
69  
70 =head2 add_pdl_method
71  
72 add_pdl_method({'my_method' => sub { my $self = shift; ... });
73 $pdl->my_method # calls the anonymous sub on $pdl
74  
75 add_pdl_method(['export2d']);
76 $pdl->export2d() # calls 'export2d' on $pdl
77  
78 add_pdl_method({'my_unroll' => 'unroll'});
79 $pdl->my_unroll() # calls 'unroll' method on $pdl
80  
81 C<add_pdl_method> pushes subroutines into the PDL namespace. It takes a single argument, a reference either an array or hash. The keys of the hash reference are the method name that will be used in the call (e.g. C<< $pdl->method_name >>, the values are either a reference to a subroutine or a string containing the name of a method provided by L<PDL::Util>. The array reference form can only take names of C<PDL::Util> methods.
82  
83 When adding your own subroutine as a L<PDL> method, be aware that the first argument passed will be a self (i.e. C<$self>) reference, in the normal Perl OO manner.
84  
85 =cut
86  
87 6 ▶sub add_pdl_method {
Subroutine add_pdl_method: called CC=8 SCAR=21.0
Pod documented
88 6 my $spec = shift;
89 croak 'make_pdl_method expects a hash or array reference as its argument'
90 6 ▶ unless grep {ref $spec eq $_} qw/HASH ARRAY/;
Branch: 1 branch
BranchTrueFalseTotal
unless grep {ref $spec eq $_;} "HASH", "ARRAY" 0 6 6
91  
92 6 ▶ if (ref $spec eq 'ARRAY') {
Branch: 1 branch
BranchTrueFalseTotal
if (ref $spec eq "ARRAY") 2 4 6
93 2 $spec = { map { $_ => $_ } @$spec };
94 }
95  
96 6 foreach my $method (keys %$spec) {
97 8 my $function = $spec->{$method};
98  
99 # Check to see if PDL already has a method by the same name
100 8 ▶ carp <<MESSAGE if PDL->can($method);
Branch: 1 branch
BranchTrueFalseTotal
if "PDL"->can($method) 0 8 8
101 PDL already provides a method named '$method', read the PDL::Util documentation to learn to avoid this conflict.
102 MESSAGE
103  
104 8 ▶ unless (ref $function && ref $function eq 'CODE') {
Branch: 1 branch
BranchTrueFalseTotal
unless (ref $function and ref $function eq "CODE") 7 1 8
Condition66%2/3
ref $function and ref $function eq "CODE"
!ll&&!rl&&r
701
MC/DC50%1/2
ref $function and ref $function eq "CODE"
ref $function ref $function eq "CODE"
Truth table66%2/3
A and B
A= ref $functionB= ref $function eq "CODE"
ABresult
0X0
100
111
105 7 ▶ if ( 1 == grep { $_ eq $function } @{ $EXPORT_TAGS{'methods'} } ) {
Branch: 1 branch
BranchTrueFalseTotal
if (1 == grep({$_ eq $function;} @{$PDL::Util::EXPORT_TAGS{'methods'};})) { } 7 0 7
106 6 ▶ no strict 'refs';
Subroutine BEGIN: called CC=1 SCAR=0.0
107 7 $function = \&{ 'PDL::Util::' . $function };
108 } else {
109 0 croak "value for $method must be either a code reference or the name of one of PDL::Util's exportable functions";
110 }
111 }
112
113 6 ▶ no strict 'refs';
Subroutine BEGIN: called CC=1 SCAR=0.0
114 8 *{'PDL::'.$method} = $function;
115 }
116 }
117  
118 =head1 TAG :methods
119  
120 Again, the I<functions> provided in the method tag are not automatically methods. They simply are function which are called with a PDL object (piddle) as their first argument. This function ARE available to be imported into the PDL namespace using the L<add_pdl_method> function describe above.
121  
122 =head2 unroll
123  
124 $AoA = unroll($pdl);
125 -- or --
126 $AoA = $pdl->unroll();
127  
128 L<PDL> provides a function for constructing a PDL object (piddle) from a Perl nested array, however it does not provide a tool to convert a piddle to a nested array structure. The closest function is the C<list> function, which returns the elements of the piddle as a list, i.e. a 1D flattened array. C<unroll> converts piddles to a native Perl data structure; it can be thought of as the logical inverse of the C<pdl> function in that C<pdl(unroll($pdl))> should return the original data structure, although bad values and data types may be changed.
129  
130 When called as a function C<unroll> takes a single argument (the piddle to unroll). When used as a method it takes no arguments. It returns a reference to an array containing the Perl equivalent data structure.
131  
132 =cut
133  
134 10 ▶sub unroll {
Subroutine unroll: called CC=4 SCAR=14.8
Pod documented
135 10 my $pdl = shift;
136  
137 10 ▶ if ( blessed($pdl) and $pdl->isa('PDL') ) {
Branch: 1 branch
BranchTrueFalseTotal
if (builtin::blessed($pdl) and $pdl->isa('PDL')) { } 10 0 10
Condition33%1/3
builtin::blessed($pdl) and $pdl->isa("PDL")
!ll&&!rl&&r
0010
MC/DC0%0/2
builtin::blessed($pdl) and $pdl->isa("PDL")
builtin::blessed($pdl) $pdl->isa("PDL")
Truth table33%1/3
A and B
A= builtin::blessed($pdl)B= $pdl->isa("PDL")
ABresult
0X0
100
111
138 10 ▶ if ($pdl->ndims > 1) {
Branch: 1 branch
BranchTrueFalseTotal
if ($pdl->ndims > 1) { } 4 6 10
139 4 return [ map {unroll($_)} dog $pdl ];
140 } else {
141 6 return [list $pdl];
142 }
143 } else {
144 0 croak "Attempted to unroll a non-PDL object";
145 #return $pdl;
146 }
147  
148 }
149  
150 =head2 export2d
151  
152 export2d($pdl, $fh, ',');
153 -- or --
154 $pdl->export2d($fh, ',');
155  
156 C<export2d> may take up to 2 optional arguments (neglecting the object reference), a lexical filehandle (or globref, e.g. C<\*FILE>) to write to, and a string containing a column separator. The defaults, if arguments are not given are to print to STDOUT and use a single space as the column separator. The order does not matter, the method will determine whether an argument refers to a file or not. This is done so that one may call either
157  
158 $pdl->export2d($fh);
159 $pdl->export2d(',');
160  
161 and it will do what you mean. Unfortunately this means that unlike C<wcols> one cannot use a filename rather than a filehandle; C<export2d> would interpret the string as the column separator!
162  
163 The method returns the number of columns that were written.
164  
165 =cut
166  
167 9 ▶sub export2d {
Subroutine export2d: called CC=8 SCAR=21.0
Pod documented
168 9 my ($pdl, $fh, $sep);
169 9 $pdl = shift;
170 9 ▶ unless ( blessed($pdl) and $pdl->isa('PDL') ) {
Branch: 1 branch
BranchTrueFalseTotal
unless (builtin::blessed($pdl) and $pdl->isa("PDL")) 0 9 9
Condition33%1/3
builtin::blessed($pdl) and $pdl->isa("PDL")
!ll&&!rl&&r
009
MC/DC0%0/2
builtin::blessed($pdl) and $pdl->isa("PDL")
builtin::blessed($pdl) $pdl->isa("PDL")
Truth table33%1/3
A and B
A= builtin::blessed($pdl)B= $pdl->isa("PDL")
ABresult
0X0
100
111
171 0 carp "cannot call export2d without a piddle input";
172 0 return 0;
173 }
174 9 ▶ unless ($pdl->ndims == 2) {
Branch: 1 branch
BranchTrueFalseTotal
unless ($pdl->ndims == 2) 2 7 9
175 2 carp "export2d may only be called on a 2D piddle";
176 2 return 0;
177 }
178  
179 # Parse additional input parameters
180 7 ▶ while (@_) {
Branch: 1 branch
BranchTrueFalseTotal
if (@_) 9 7 16
181 9 my $param = shift;
182 9 ▶ if (openhandle($param)) {
Branch: 1 branch
BranchTrueFalseTotal
if (&openhandle($param)) { } 5 4 9
183 5 $fh = $param;
184 } else {
185 4 $sep = $param;
186 }
187 }
188  
189 # Extract columns from piddle
190 7 my @params = map {$pdl->slice("($_),")} (0..$pdl->dim(0)-1);
191 7 my $num_cols = @params;
192  
193 # Push additional parameters for wcols
194 7 ▶ push @params, $fh if (defined $fh);
Branch: 1 branch
BranchTrueFalseTotal
if defined $fh 5 2 7
195 7 ▶ push @params, {Colsep => $sep} if (defined $sep);
Branch: 1 branch
BranchTrueFalseTotal
if defined $sep 4 3 7
196  
197 # Write columns
198 7 wcols @params;
199  
200 7 return $num_cols;
201 }
202  
203 6 1;
204  
205 =head1 SEE ALSO
206  
207 L<PDL>
208 L<Website|http://pdl.perl.org>
209  
210 =head1 SOURCE REPOSITORY
211  
212 L<http://github.com/jberger/PDL-Util>
213  
214 =head1 AUTHOR
215  
216 Joel Berger, E<lt>joel.a.berger@gmail.comE<gt>
217  
218 =head1 COPYRIGHT AND LICENSE
219  
220 Copyright (C) 2011 by Joel Berger
221  
222 This library is free software; you can redistribute it and/or modify
223 it under the same terms as Perl itself.
224  
↑ Summary