blib/lib/PDL/Doc/Perldl.pm

filter: Statementstmt 23.6% 60 / 254 Branchbran 5.1% 6 / 116 Conditioncond 2.7% 1 / 37 MC/DCmcdc 0.0% 0 / 22 Subroutinesub 34.7% 8 / 23 Podpod 50.0% 8 / 16 totaltotal 17.7% 83 / 468 CC 84 SCAR 50.9
CC
84
Cov
16%
finddoc
462.0
whatis_r
306.0
find_autodoc
110.0
CRAP 162.9
« blib/lib/PDL/IO/FlexRaw.pm ↑ Summary lib/PDL/MatrixOps.pd »
1 =head1 NAME
2  
3 PDL::Doc::Perldl - commands for accessing PDL doc database from 'perldl' shell
4  
5 =head1 DESCRIPTION
6  
7 This module provides a set of functions to
8 access the PDL documentation database, for use
9 from the I<perldl> shell as well as the
10 I<pdldoc> command-line program.
11  
12 Autoload files are also matched, via a search of the PDLLIB autoloader
13 tree. That behavior can be switched off with the variable
14 C<$PERLDL::STRICT_DOCS> (true: don't search autoload tree; false: search
15 the autoload tree.)
16  
17 In the interest of brevity, functions that print module names (at the moment
18 just L</apropos> and L</usage>) use some shorthand notation for module names.
19 Currently-implemented shorthands are
20  
21 =over 3
22  
23 =item * P:: (short for PDL::)
24  
25 =item * P::G:: (short for PDL::Graphics::)
26  
27 =back
28  
29 To turn this feature off, set the variable $PERLDL::long_mod_names to a true value.
30 The feature is assumed to be on for the purposes of this documentation.
31  
32 =head1 SYNOPSIS
33  
34 use PDL::Doc::Perldl; # Load all documentation functions
35  
36 =head1 FUNCTIONS
37  
38 =cut
39  
40 package PDL::Doc::Perldl;
41  
42 1 ▶use Exporter;
Subroutine BEGIN: called CC=1 SCAR=0.0
43 1 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
44 1 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
45  
46 1 our @ISA = qw(Exporter);
47 1 our @EXPORT = qw( apropos aproposover usage help sig badinfo whatis );
48  
49 1 ▶use PDL::Doc;
Subroutine BEGIN: called CC=1 SCAR=0.0
50 1 ▶use Pod::Text;
Subroutine BEGIN: called CC=1 SCAR=0.0
51 1 ▶use Cwd; # to help Debian packaging
Subroutine BEGIN: called CC=1 SCAR=0.0
52  
53 # Find std file
54  
55 0 ▶sub FindStdFile {
Subroutine FindStdFile: not called CC=3 SCAR=24.8
Pod undocumented
56 0 my @found = PDL::Doc::find_dbs();
57 0 ▶ warn("Unable to find *.db in ".join(":",@INC)."\n"), return if !@found;
Branch: 1 branch
BranchTrueFalseTotal
unless @found 0 0 0
58 0 ▶ if ($PDL::verbose) {
Branch: 1 branch
BranchTrueFalseTotal
if ($PDL::verbose) 0 0 0
59 0 print join '', map "$_\n", "Found docs databases:", map " $_", @found;
60 }
61 0 @found;
62 }
63  
64 # used to find out how wide the screen should be
65 # for format_ref - really should check for a sensible lower limit
66 sub screen_width {
67 local $@;
68 eval {
69 require Term::ReadKey;
70 ( Term::ReadKey::GetTerminalSize(\*STDOUT) )[0];
71 } // 72;
72 }
73  
74 0 ▶sub printmatch {
Subroutine printmatch: not called CC=3 SCAR=24.8
Pod undocumented
75 0 ▶ return print "no match\n" if !@_;
Branch: 1 branch
BranchTrueFalseTotal
unless @_ 0 0 0
76 0 print for format_ref(@_);
77 }
78  
79 # given a long module name, return the (perhaps shortened) module name.
80  
81 2 ▶sub shortmod {
Subroutine shortmod: called CC=3 SCAR=11.6
Pod undocumented
82 2 my $module = shift;
83 2 $module =~ s/::$//;
84 2 ▶ unless ($PERLDL::long_mod_names && $PERLDL::long_mod_names){ # silence warn
Branch: 1 branch
BranchTrueFalseTotal
unless ($PERLDL::long_mod_names and $PERLDL::long_mod_names) 2 0 2
Condition33%1/3
$PERLDL::long_mod_names and $PERLDL::long_mod_names
!ll&&!rl&&r
200
MC/DC0%0/2
$PERLDL::long_mod_names and $PERLDL::long_mod_names
$PERLDL::long_mod_names $PERLDL::long_mod_names
Truth table33%1/3
A and B
A= $PERLDL::long_mod_namesB= $PERLDL::long_mod_names
ABresult
0X0
100
111
85 2 $module =~ s/^PDL::/P::/;
86 2 $module =~ s/^P::Graphics::/P::G::/;
87 #additional abbreviation substitutions go here
88 }
89 2 return $module;
90 }
91  
92 # return a string containing a formated version of the Ref string
93 # for the given matches
94 1 my $LONG_FMT = "%s ...\n " . ' 'x15 . "%-*s %s\n";
95 1 my $NORMAL_FMT = "%-15s %-*s %s\n";
96 1 ▶sub format_ref {
Subroutine format_ref: called CC=8 SCAR=22.0
Pod undocumented
97 1 my @match = @_;
98 1 my @text = ();
99 #finding the max width before doing the printing means looping through @match an extra time; so be it.
100 1 my @module_shorthands = map { shortmod($_->[1]) } @match;
101 1 my $max_mod_length = -1;
102 1 ▶ map {$max_mod_length = length if (length>$max_mod_length) } @module_shorthands;
Branch: 1 branch
BranchTrueFalseTotal
if length $_ > $max_mod_length 1 0 1
103 1 my $width = screen_width()-17-1-$max_mod_length;
104 1 my @parser_args = (width => $width, indent => 0, sentence => 0);
105 1 my %seen;
106 1 for my $m (@match) {
107 1 my $name = $m->[0];
108 1 my $module = shortmod($m->[1]);
109 1 my $ref = $m->[2]{Ref};
110 1 ▶ if (!$ref) {
Branch: 2 branches
BranchTrueFalseTotal
if (not $ref) { } 0 1 1
elsif ($seen{$ref}) { } 0 1 1
111 $ref = defined $m->[2]{CustomFile}
112 0 ▶ ? "[No ref avail. for `".$m->[2]{CustomFile}."']"
Branch: 1 branch
BranchTrueFalseTotal
defined $m->[2]{'CustomFile'} ? : 0 0 0
113 : "[No reference available]";
114 } elsif ($seen{$ref}) {
115 0 $ref = "[As $seen{$ref}]";
116 } else {
117 1 $seen{$ref} = $name;
118 1 my $parser = Pod::Text->new(@parser_args);
119 1 $parser->output_string(\my $out_text);
120 1 $parser->parse_string_document("=encoding utf8\n\n$ref");
121 1 $ref = $out_text;
122 1 $ref =~ s/\n*$//; # remove last newlines so no append spaces at end
123 0 $ref =~ s/\n/"\n".' 'x($max_mod_length+18)/eg;
124 1 $ref =~ s/^\s*//;
125 }
126 1 ▶ push @text, sprintf length($name) > 15 ? $LONG_FMT : $NORMAL_FMT, $name, $max_mod_length, $module, $ref;
Branch: 1 branch
BranchTrueFalseTotal
length $name > 15 ? : 0 1 1
127 }
128 1 ▶ wantarray ? @text : $text[0];
Branch: 1 branch
BranchTrueFalseTotal
wantarray ? : 0 1 1
129 }
130  
131 =head2 apropos
132  
133 =for ref
134  
135 Regex search PDL documentation database
136  
137 =for usage
138  
139 apropos 'text'
140  
141 =for example
142  
143 pdl> apropos 'pic'
144 PDL::IO::Pic P::IO::Pic Module: image I/O for PDL
145 grabpic3d P::G::TriD Grab a 3D image from the screen.
146 rim P::IO::Pic Read images in most formats, with improved RGB handling.
147 rpic P::IO::Pic Read images in many formats with automatic format detection.
148 rpiccan P::IO::Pic Test which image formats can be read/written
149 wim P::IO::Pic Write a pdl to an image file with selected type (or using filename extensions)
150 wmpeg P::IO::Pic Write an image sequence (a (3,x,y,n) byte pdl) as an animation.
151 wpic P::IO::Pic Write images in many formats with automatic format selection.
152 wpiccan P::IO::Pic Test which image formats can be read/written
153  
154 To find all the manuals that come with PDL, try
155  
156 apropos 'manual:'
157  
158 and to get quick info about PDL modules say
159  
160 apropos 'module:'
161  
162 You get more detailed info about a PDL function/module/manual
163 with the C<help> function
164  
165 =cut
166  
167 0 ▶sub aproposover {
Subroutine aproposover: not called CC=2 SCAR=17.9
Pod undocumented
168 0 ▶ die "Usage: aproposover \$funcname\n" if !@_;
Branch: 1 branch
BranchTrueFalseTotal
unless @_ 0 0 0
169 0 my $func = shift;
170 0 $func =~ s:\/:\\\/:g;
171 0 search_docs("m/$func/",['Name','Ref','Module'],1);
172 }
173  
174 0 ▶sub apropos {
Subroutine apropos: not called CC=2 SCAR=17.9
Pod documented
175 0 ▶ die "Usage: apropos \$funcname\n" unless $#_>-1;
Branch: 1 branch
BranchTrueFalseTotal
unless $#_ > -1 0 0 0
176 0 my $func = shift;
177 0 printmatch aproposover $func;
178 0 '';
179 }
180  
181 =head2 PDL::Doc::Perldl::search_docs
182  
183 =for ref
184  
185 Internal routine to search docs database and autoload files
186  
187 =cut
188  
189 0 ▶sub search_docs {
Subroutine search_docs: not called CC=2 SCAR=17.9
Pod documented
190 0 my ($func,$types,$sortflag,$exact) = @_;
191 0 my @match;
192  
193 0 ▶ $PDL::onlinedoc //= PDL::Doc->new(FindStdFile());
Condition0%0/3
$PDL::onlinedoc //= "PDL::Doc"->new(FindStdFile())
l!l&&r!l&&!r
000
MC/DC0%0/2
$PDL::onlinedoc //= "PDL::Doc"->new(FindStdFile())
$PDL::onlinedoc "PDL::Doc"->new(FindStdFile())
Truth table0%0/3
A //= B
A= $PDL::onlinedocB= "PDL::Doc"->new(FindStdFile())
ABresult
1X1
011
000
194 0 @match = $PDL::onlinedoc->search($func,$types,$sortflag);
195 0 push(@match,find_autodoc( $func, $exact ) );
196  
197 0 @match;
198 }
199  
200  
201  
202 =head2 PDL::Doc::Perldl::finddoc
203  
204 =for ref
205  
206 Internal interface to the PDL documentation searcher
207  
208 =cut
209  
210 0 ▶sub finddoc {
Subroutine finddoc: not called CC=21 SCAR=61.4
Pod documented
211 0 ▶ local $SIG{PIPE}= sub {}; # Prevent crashing if user exits the pager
Subroutine __ANON__: not called CC=1 SCAR=6.9
212  
213 0 ▶ die 'Usage: doc $topic' unless $#_>-1;
Branch: 1 branch
BranchTrueFalseTotal
unless $#_ > -1 0 0 0
214 0 my $topic = shift;
215  
216 # See if it matches a PDL function name
217  
218 0 ▶ my $subfield = $1
Branch: 1 branch
BranchTrueFalseTotal
if $topic =~ s/\[(\d*)\]$// 0 0 0
219 if( $topic =~ s/\[(\d*)\]$// ); #does it end with a number in square brackets?
220  
221 0 (my $t2 = $topic) =~ s/([^a-zA-Z0-9_])/\\$1/g; #$t2 is a copy of $topic with escaped non-word characters
222  
223 0 my @match = search_docs("m/^(PDL::)?".$t2."\$/",['Name'],0) ; #matches: ^PDL::topic$ or ^topic$
224  
225 0 ▶ unless(@match) {
Branch: 1 branch
BranchTrueFalseTotal
unless (@match) 0 0 0
226 0 print "No PDL docs for '$topic'. Using 'whatis'. (Try 'apropos $topic'?)\n\n";
227 0 whatis($topic);
228 0 return;
229 }
230  
231 # print out the matches
232 0 open my $out, "| pod2text | $PDL::Doc::pager";
233 0 binmode $out, ':encoding(UTF-8)';
234  
235 0 ▶ if($subfield) {
Branch: 1 branch
BranchTrueFalseTotal
if ($subfield) 0 0 0
236 0 ▶ if($subfield <= @match) {
Branch: 1 branch
BranchTrueFalseTotal
if ($subfield <= @match) { } 0 0 0
237 0 @match = ($match[$subfield-1]);
238 0 $subfield = 0;
239 } else {
240 0 print $out "\n\n=head1 PDL HELP: Ignoring out-of-range selector $subfield\n\n=head1\n\n=head1 --------------------------------\n\n";
241 0 $subfield = undef;
242 }
243 }
244  
245 0 my $num_pdl_pod_matches = scalar @match;
246 0 my $pdl_pod_matchnum = 0;
247  
248 0 ▶ while (@match) {
Branch: 1 branch
BranchTrueFalseTotal
if (@match) 0 0 0
249 0 $pdl_pod_matchnum++;
250  
251 0 ▶ if ( @match > 1 and !$subfield and $pdl_pod_matchnum==1 ) {
Branch: 1 branch
BranchTrueFalseTotal
if (@match > 1 and not $subfield and $pdl_pod_matchnum == 1) 0 0 0
Condition0%0/6
@match > 1 and not $subfield and $pdl_pod_matchnum == 1
!ll&&!rl&&r
000
@match > 1 and not $subfield
!ll&&!rl&&r
000
MC/DC0%0/3
@match > 1 and not $subfield and $pdl_pod_matchnum == 1
@match > 1 not $subfield $pdl_pod_matchnum == 1
Truth table0%0/4
A and not(B) and C
A= @match > 1B= not $subfieldC= $pdl_pod_matchnum == 1
ABCresult
0XX0
10X0
1100
1111
252 0 print $out "\n\n=head1 MULTIPLE MATCHES FOR HELP TOPIC '$topic':\n\n=head1\n\n=over 3\n\n";
253 0 my $i=0;
254 0 for my $m ( @match ) {
255 0 ▶ printf $out "\n=item [%d]\t%-30s %s%s\n\n", ++$i, $m->[0], $m->[2]{Module} && "in ", $m->[2]{CustomFile} || $m->[2]{Module};
Condition0%0/5
$m->[2]{'Module'} && 'in '
!ll
00
$m->[2]{'CustomFile'} || $m->[2]{'Module'}
l!l&&r!l&&!r
000
MC/DC0%0/1
$m->[2]{'Module'} && 'in '
$m->[2]{'Module'}
MC/DC0%0/2
$m->[2]{'CustomFile'} || $m->[2]{'Module'}
$m->[2]{'CustomFile'} $m->[2]{'Module'}
Truth table0%0/2
A
A= $m->[2]{'Module'}
Aresult
00
11
Truth table0%0/3
A || B
A= $m->[2]{'CustomFile'}B= $m->[2]{'Module'}
ABresult
1X1
011
000
256 }
257 0 print $out "\n=back\n\n=head1\n\n To see item number \$n, use 'help ${topic}\[\$n\]'. \n\n=cut\n\n";
258 }
259  
260 0 ▶ if (@match > 0 and $num_pdl_pod_matches > 1) {
Branch: 1 branch
BranchTrueFalseTotal
if (@match > 0 and $num_pdl_pod_matches > 1) 0 0 0
Condition0%0/3
@match > 0 and $num_pdl_pod_matches > 1
!ll&&!rl&&r
000
MC/DC0%0/2
@match > 0 and $num_pdl_pod_matches > 1
@match > 0 $num_pdl_pod_matches > 1
Truth table0%0/3
A and B
A= @match > 0B= $num_pdl_pod_matches > 1
ABresult
0X0
100
111
261 0 print $out "\n=head1 Displaying item $pdl_pod_matchnum:\n\n=head1 --------------------------------------\n\n=cut\n\n";
262 }
263  
264 0 my $m = shift @match;
265  
266 0 my $Ref = $m->[2]{Ref};
267 0 ▶ if ( $Ref && $Ref =~ /^(Module|Manual|Script): / ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($Ref and $Ref =~ /^(Module|Manual|Script): /) { } 0 0 0
Condition0%0/3
$Ref and $Ref =~ /^(Module|Manual|Script): /
!ll&&!rl&&r
000
MC/DC0%0/2
$Ref and $Ref =~ /^(Module|Manual|Script): /
$Ref $Ref =~ /^(Module|Manual|Script): /
Truth table0%0/3
A and B
A= $RefB= $Ref =~ /^(Module|Manual|Script): /
ABresult
0X0
100
111
268 # We've got a file name and we have to open it. With the relocatable db, we have to reconstitute the absolute pathname.
269 0 my $relfile = $m->[2]{File};
270 0 my $absfile = undef;
271 0 my @scnd = @{$PDL::onlinedoc->{Scanned}};
272 0 for my $dbf (@scnd) {
273 0 $dbf = Cwd::abs_path($dbf); # help Debian packaging
274 0 $dbf =~ s:\/[^\/]*$::; # Trim file name off the end of the database file to get just the directory
275 0 $dbf .= "/$relfile";
276 0 ▶ $absfile = $dbf if( -e $dbf );
Branch: 1 branch
BranchTrueFalseTotal
if -e $dbf 0 0 0
277 }
278 0 ▶ unless ($absfile) {
Branch: 1 branch
BranchTrueFalseTotal
unless ($absfile) 0 0 0
279 0 die "Documentation error: couldn't find absolute path to $relfile\n";
280 }
281 0 open my $in, "<", $absfile;
282 0 print $out join("",<$in>);
283 } else {
284 0 ▶ if(defined $m->[2]{CustomFile}) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined $m->[2]{'CustomFile'}) { } 0 0 0
285  
286 0 require Pod::Text;
287 0 my $parser = Pod::Text->new;
288 0 print $out "=head1 Autoload file \"".$m->[2]{CustomFile}."\"\n\n";
289 0 $parser->parse_from_file($m->[2]{CustomFile},$out);
290 0 print $out "\n\n=head2 Docs from\n\n".$m->[2]{CustomFile}."\n\n";
291  
292 } else {
293  
294 0 print $out "=encoding utf8\n\n=head1 Module ",$m->[2]{Module}, "\n\n";
295 0 $PDL::onlinedoc->funcdocs(@$m[0,1],$out);
296  
297 }
298  
299 }
300 }
301 }
302  
303  
304 =head2 find_autodoc
305  
306 =for ref
307  
308 Internal routine that finds and returns documentation in the
309 PDL::AutoLoader path, if it exists.
310  
311 You feed in a topic and it searches for the file "${topic}.pdl". If
312 that exists, then the filename gets returned in a match structure
313 appropriate for the rest of finddoc.
314  
315 =cut
316  
317 # Yuck. Sorry. At least it works. -CED
318  
319 0 ▶sub find_autodoc {
Subroutine find_autodoc: not called CC=10 SCAR=47.0
Pod documented
320 0 my $topic = shift;
321 0 my $exact = shift;
322 0 my $matcher;
323 # Fix up regexps and exact matches for the special case of
324 # searching the autoload dirs...
325 0 ▶ if($exact) {
Branch: 1 branch
BranchTrueFalseTotal
if ($exact) { } 0 0 0
326 0 $topic =~ s/\(\)$//; # "func()" -> "func"
327 0 ▶ $topic .= ".pdl" unless $topic =~ m/\.pdl$/;
Branch: 1 branch
BranchTrueFalseTotal
unless $topic =~ /\.pdl$/ 0 0 0
328 } else {
329  
330 0 $topic =~ s:([^\$])(.)$:$1\.\*\$$2:; # Include explicit ".*$" at end of
331 # vague matches -- so that we can
332 # make it a ".*\.pdl$" below.
333  
334 0 $topic =~ s:\$(.)$:\.pdl\$$1:; # Force ".pdl" at end of file match
335  
336 0 $matcher = eval "sub { ${topic}i && \$\_ };"; # Avoid multiple compiles
337 }
338  
339 0 my @out;
340  
341 0 ▶ return unless(@main::PDLLIB);
Branch: 1 branch
BranchTrueFalseTotal
unless @main::PDLLIB 0 0 0
342 0 ▶ @main::PDLLIB_EXPANDED = PDL::AutoLoader::expand_path(@main::PDLLIB)
Branch: 1 branch
BranchTrueFalseTotal
unless @main::PDLLIB_EXPANDED 0 0 0
343 unless(@main::PDLLIB_EXPANDED);
344  
345 0 for my $dir(@main::PDLLIB_EXPANDED) {
346 0 ▶ if($exact) {
Branch: 1 branch
BranchTrueFalseTotal
if ($exact) { } 0 0 0
347 0 my $file = $dir . "/" . "$topic";
348 0 ▶ push(@out,
Branch: 1 branch
BranchTrueFalseTotal
if -e $file 0 0 0
349 [$file, undef, {CustomFile => "$file", Module => "file '$file'"}]
350 )
351 if(-e $file);
352 } else {
353 0 ▶ opendir(FOO,$dir) || next;
Branch: 1 branch
BranchTrueFalseTotal
opendir FOO, $dir or next 0 0 0
354 0 my @dir = readdir(FOO);
355 0 closedir(FOO);
356 0 for my $file( grep( &$matcher, @dir ) ) {
357 0 push(@out,
358 [$file, undef, {CustomFile => "$dir/$file", Module => "file '$dir/$file'"}]
359 );
360 }
361  
362 }
363 }
364 0 @out;
365 }
366  
367  
368 =head2 usage, badinfo
369  
370 =for ref
371  
372 Prints usage information for a PDL function
373  
374 =for usage
375  
376 Usage: usage func
377  
378 =for example
379  
380 pdl> usage inner
381 inner P::Primitive Inner product over one dimension
382 Signature:
383 (a(n); b(n); [o]c())
384 Types: (sbyte byte short ushort long ulong indx ulonglong longlong
385 float double ldouble cfloat cdouble cldouble)
386 Usage:
387 $c = inner($a, $b);
388 inner($a, $b, $c); # all arguments given
389 $c = $a->inner($b); # method call
390 $a->inner($b, $c);
391 Bad value support:
392 If "a() * b()" contains only bad data,
393 c() is set bad. Otherwise c() will have its bad flag cleared,
394 as it will not contain any bad values.
395  
396 =cut
397  
398 0 ▶sub usage {
Subroutine usage: not called CC=2 SCAR=17.9
Pod documented
399 0 ▶ die 'Usage: usage $funcname' unless $#_>-1;
Branch: 1 branch
BranchTrueFalseTotal
unless $#_ > -1 0 0 0
400 0 print usage_string(@_);
401 0 ''
402 }
403 1 *badinfo = \&usage;
404 0 ▶sub usage_string {
Subroutine usage_string: not called CC=6 SCAR=37.4
Pod undocumented
405 0 my $func = shift;
406 0 my $str = "";
407 0 ▶ return "no match\n" unless
Branch: 1 branch
BranchTrueFalseTotal
unless my(@match) = search_docs("m/^(PDL::)?$func\$|::$func\$/", ["Name"]) 0 0 0
408 my @match = search_docs("m/^(PDL::)?$func\$|\:\:$func\$/",['Name']);
409 0 my $count = @match;
410 #this sorts by namespace depth by counting colons in the name.
411 #PDL::Ufunc::max comes before PDL::GSL::RNG::max, for example.
412 0 foreach my $m (sort { scalar(()=$a->[1]=~/\:/g) <=> scalar(()=$b->[1]=~/\:/g) } @match) {
413 0 $str .= "\n" . format_ref( $m );
414 0 my ($name,$module,$hash) = @$m;
415 0 ▶ die "No usage info found for $func\n" if !grep defined, @$hash{qw(Example Sig Usage)};
Branch: 1 branch
BranchTrueFalseTotal
unless grep defined($_), @$hash{"Example", "Sig", "Usage"} 0 0 0
416 0 for (grep $hash->{$_->[0]},
417 ['Sig','Signature'],['Usage','Usage'],['Opt','Options'],
418 ['Example','Example'],['Bad','Bad value support'],
419 ) {
420 0 $str .= " $_->[1]:\n".allindent($hash->{$_->[0]},4)."\n";
421 }
422 0 ▶ $str .= '='x20 unless 1==$count--;
Branch: 1 branch
BranchTrueFalseTotal
unless 1 == $count-- 0 0 0
423 }
424 0 $str;
425 }
426  
427 =head2 sig
428  
429 =for ref
430  
431 prints signature of PDL function
432  
433 =for usage
434  
435 sig 'func'
436  
437 The signature is the normal dimensionality of the
438 function's arguments. Calling with different dimensions
439 doesn't break -- it causes broadcasting. See L<PDL::PP> and L<PDL::Broadcasting> for details.
440  
441 =for example
442  
443 pdl> sig 'outer'
444 Signature: outer(a(n); b(m); [o]c(n,m))
445  
446 =cut
447  
448 0 ▶sub sig {
Subroutine sig: not called CC=7 SCAR=40.3
Pod documented
449 0 ▶ die "Usage: sig \$funcname\n" unless $#_>-1;
Branch: 1 branch
BranchTrueFalseTotal
unless $#_ > -1 0 0 0
450 0 my $func = shift;
451 0 my @match = search_docs("m/^(PDL::)?$func\$|\:\:$func\$/",['Name']);
452 0 my $count = @match;
453 0 ▶ unless (@match) { print "\n no match\n" } else {
Branch: 1 branch
BranchTrueFalseTotal
if (@match) { } 0 0 0
454 0 foreach my $m(sort { scalar(()=$a->[1]=~/\:/g) <=> scalar(()=$b->[1]=~/\:/g) } @match){
455 0 my ($name,$module,$hash) = @{$m};
456 0 ▶ die "No signature info found for $func\n" if !defined $hash->{Sig};
Branch: 1 branch
BranchTrueFalseTotal
unless defined $hash->{"Sig"} 0 0 0
457 0 ▶ print " Signature: $name($hash->{Sig})\n" if defined $hash->{Sig};
Branch: 1 branch
BranchTrueFalseTotal
if defined $hash->{"Sig"} 0 0 0
458 0 ▶ print '='x20 unless 1==$count--;
Branch: 1 branch
BranchTrueFalseTotal
unless 1 == $count-- 0 0 0
459 }
460 }
461 }
462  
463 0 ▶sub allindent {
Subroutine allindent: not called CC=5 SCAR=34.0
Pod undocumented
464 0 my ($txt,$n) = @_;
465 0 my ($ntxt,$tspc) = ($txt,' 'x8);
466 0 $ntxt =~ s/^\s*$//mg;
467 0 $ntxt =~ s/\t/$tspc/g;
468 0 my $minspc = length $txt;
469 0 ▶ for (split '\n', $txt) { if (/^(\s*)/)
Branch: 1 branch
BranchTrueFalseTotal
if (/^(\s*)/) 0 0 0
470 0 ▶ { $minspc = length $1 if length $1 < $minspc } }
Branch: 1 branch
BranchTrueFalseTotal
if length $1 < $minspc 0 0 0
471 0 $n -= $minspc;
472 0 $tspc = ' 'x abs($n);
473 0 ▶ $ntxt =~ s/^/$tspc/mg if $n > 0;
Branch: 1 branch
BranchTrueFalseTotal
if $n > 0 0 0 0
474 0 $ntxt;
475 }
476  
477  
478 =head2 whatis
479  
480 =for ref
481  
482 Describe a perl and/or PDL variable or expression. Useful for
483 determining the type of an expression, identifying the keys in a hash
484 or a data structure, or examining WTF an unknown object is.
485  
486 =for usage
487  
488 Usage: whatis $var
489 whatis <expression>
490  
491 =cut
492  
493 0 ▶sub whatis {
Subroutine whatis: not called CC=2 SCAR=17.9
Pod documented
494 0 my $topic;
495  
496 0 ▶ if(@_ > 1) {
Branch: 1 branch
BranchTrueFalseTotal
if (@_ > 1) { } 0 0 0
497 0 whatis_r('',0,[@_]);
498 } else {
499 0 whatis_r('',0,shift);
500 }
501 }
502  
503 1 $PDL::Doc::Perldl::max_strlen = 55;
504 1 $PDL::Doc::Perldl::max_arraylen = 1;
505 1 $PDL::Doc::Perldl::max_keylen = 8;
506 1 $PDL::Doc::Perldl::array_indent=5;
507 1 $PDL::Doc::Perldl::hash_indent=3;
508  
509 0 ▶sub whatis_r {
Subroutine whatis_r: not called CC=17 SCAR=57.2
Pod undocumented
510 0 my $prefix = shift;
511 0 my $indent = shift;
512 0 my $x = shift;
513  
514 0 ▶ unless(defined $x) {
Branch: 1 branch
BranchTrueFalseTotal
unless (defined $x) 0 0 0
515 0 print $prefix,"<undef>\n";
516 0 return;
517 }
518  
519 0 ▶ unless(ref $x) {
Branch: 1 branch
BranchTrueFalseTotal
unless (ref $x) 0 0 0
520 0 ▶ print "${prefix}'".
Condition0%0/2
length $x > $PDL::Doc::Perldl::max_strlen && '...'
!ll
00
MC/DC0%0/1
length $x > $PDL::Doc::Perldl::max_strlen && '...'
length $x > $PDL::Doc::Perldl::max_strlen
Truth table0%0/2
A
A= length $x > $PDL::Doc::Perldl::max_strlen
Aresult
00
11
521 substr($x,0,$PDL::Doc::Perldl::max_strlen).
522 "'".((length $x > $PDL::Doc::Perldl::max_strlen) && '...').
523 "\n";
524 0 return;
525 }
526  
527 0 ▶ if(ref $x eq 'ARRAY') {
Branch: 1 branch
BranchTrueFalseTotal
if (ref $x eq "ARRAY") 0 0 0
528 0 print "${prefix}Array (".scalar(@$x)." elements):\n";
529  
530 0 my($el);
531 0 for $el(0..$#$x) {
532 0 my $pre = sprintf("%s %2d: "," "x$indent,$el);
533 0 whatis_r($pre,$indent + $PDL::Doc::Perldl::array_indent, $x->[$el]);
534 0 ▶ last if($el == $PDL::Doc::Perldl::max_arraylen);
Branch: 1 branch
BranchTrueFalseTotal
if $el == $PDL::Doc::Perldl::max_arraylen 0 0 0
535 }
536 0 ▶ printf "%s ... \n"," " x $indent
Branch: 1 branch
BranchTrueFalseTotal
if $x->$#* > $PDL::Doc::Perldl::max_arraylen 0 0 0
537 if($#$x > $PDL::Doc::Perldl::max_arraylen);
538  
539 0 return;
540 }
541  
542 0 ▶ if(ref $x eq 'HASH') {
Branch: 1 branch
BranchTrueFalseTotal
if (ref $x eq "HASH") 0 0 0
543 0 print "${prefix}Hash (".scalar(keys %$x)." elements)\n";
544 0 my $key;
545 0 for $key(sort keys %$x) {
546 0 my $pre = " " x $indent .
547 " $key: " .
548 (" "x($PDL::Doc::Perldl::max_keylen - length($key))) ;
549  
550 0 whatis_r($pre,$indent + $PDL::Doc::Perldl::hash_indent, $x->{$key});
551 }
552 0 return;
553 }
554  
555 0 ▶ if(ref $x eq 'CODE') {
Branch: 1 branch
BranchTrueFalseTotal
if (ref $x eq "CODE") 0 0 0
556 0 print "${prefix}Perl CODE ref\n";
557 0 return;
558 }
559  
560 0 ▶ if(ref $x eq 'SCALAR' || ref $x eq 'REF') {
Branch: 1 branch
BranchTrueFalseTotal
if (ref $x eq "SCALAR" or ref $x eq "REF") 0 0 0
Condition0%0/3
ref $x eq "SCALAR" or ref $x eq "REF"
l!l&&r!l&&!r
000
MC/DC0%0/2
ref $x eq "SCALAR" or ref $x eq "REF"
ref $x eq "SCALAR" ref $x eq "REF"
Truth table0%0/3
A or B
A= ref $x eq "SCALAR"B= ref $x eq "REF"
ABresult
1X1
011
000
561 0 whatis_r($prefix." Ref -> ",$indent+8,$$x);
562 0 return;
563 }
564  
565 0 ▶ if(UNIVERSAL::can($x,'px')) {
Branch: 1 branch
BranchTrueFalseTotal
if (UNIVERSAL::can($x, 'px')) { } 0 0 0
566 0 my $y;
567 0 local $PDL::debug = 1;
568  
569 0 ▶ $y = ( (UNIVERSAL::isa($x,'PDL') && $x->nelem < 5 && $x->ndims < 2)
Branch: 1 branch
BranchTrueFalseTotal
UNIVERSAL::isa($x, 'PDL') && $x->nelem < 5 && $x->ndims < 2 ? : 0 0 0
Condition0%0/6
UNIVERSAL::isa($x, "PDL") and $x->nelem < 5 and $x->ndims < 2
!ll&&!rl&&r
000
UNIVERSAL::isa($x, "PDL") and $x->nelem < 5
!ll&&!rl&&r
000
MC/DC0%0/3
UNIVERSAL::isa($x, "PDL") and $x->nelem < 5 and $x->ndims < 2
UNIVERSAL::isa($x, "PDL") $x->nelem < 5 $x->ndims < 2
Truth table0%0/4
A and B and C
A= UNIVERSAL::isa($x, "PDL")B= $x->nelem < 5C= $x->ndims < 2
ABCresult
0XX0
10X0
1100
1111
570 ?
571 ": $x" :
572 ": *****"
573 );
574  
575 0 $x->px($prefix.(ref $x)." %7T (%D) ".$y);
576  
577 } else {
578  
579 0 print "${prefix}Object: ".ref($x)."\n";
580  
581 }
582 }
583  
584 =head2 help
585  
586 =for ref
587  
588 print documentation about a PDL function or module or show a PDL manual
589  
590 In the case of multiple matches, the first command found is printed out,
591 and the remaining commands listed, along with the names of their modules.
592  
593  
594 =for usage
595  
596 Usage: help 'func'
597  
598 =for example
599  
600 pdl> help 'PDL::Tutorials' # show the guide to PDL tutorials
601 pdl> help 'PDL::Slices' # show the docs in the PDL::Slices module
602 pdl> help 'slice' # show docs on the 'slice' function
603  
604 =cut
605  
606 0 ▶sub help {
Subroutine help: not called CC=6 SCAR=37.4
Pod documented
607 0 ▶ if (@_) {
Branch: 1 branch
BranchTrueFalseTotal
if (@_) { } 0 0 0
608 0 require PDL::Dbg;
609 0 my $topic = shift;
610 0 ▶ if (PDL::Core::blessed($topic) && $topic->can('px')) {
Branch: 1 branch
BranchTrueFalseTotal
if (PDL::Core::blessed($topic) and $topic->can('px')) { } 0 0 0
Condition0%0/3
PDL::Core::blessed($topic) and $topic->can("px")
!ll&&!rl&&r
000
MC/DC0%0/2
PDL::Core::blessed($topic) and $topic->can("px")
PDL::Core::blessed($topic) $topic->can("px")
Truth table0%0/3
A and B
A= PDL::Core::blessed($topic)B= $topic->can("px")
ABresult
0X0
100
111
611 0 local $PDL::debug = 1;
612 0 $topic->px('This variable is');
613 } else {
614 0 ▶ $topic = 'PDL::Doc::Perldl' if $topic =~ /^\s*help\s*$/i;
Branch: 1 branch
BranchTrueFalseTotal
if $topic =~ /^\s*help\s*$/i 0 0 0
615 0 ▶ if ($topic =~ /^\s*vars\s*$/i) {
Branch: 1 branch
BranchTrueFalseTotal
if ($topic =~ /^\s*vars\s*$/i) { } 0 0 0
616 0 PDL->px((caller)[0]);
617 } else {
618 0 finddoc($topic);
619 }
620 }
621 } else {
622 0 print <<'EOH';
623  
624 The following commands support online help in the perldl shell:
625  
626 help 'thing' -- print docs on 'thing' (func, module, manual, autoload-file)
627 help vars -- print information about all current ndarrays
628  
629 whatis <expr> -- Describe the type and structure of an expression or ndarray.
630 apropos 'word' -- search for keywords/function names
631 usage -- print usage information for a given PDL function
632 including support for bad values
633 sig -- print signature of PDL function
634  
635 ('?' is an alias for 'help'; '??' is an alias for 'apropos'.)
636  
637 Quick start:
638 apropos 'manual:' -- Find all the manual documents
639 apropos 'module:' -- Quick summary of all PDL modules
640 help 'help' -- details about PDL help system
641 help 'perldl' -- help about this shell
642  
643 EOH
644 }
645 0 ''
646 }
647  
648 1 1; # OK
« blib/lib/PDL/IO/FlexRaw.pm ↑ Summary lib/PDL/MatrixOps.pd »