blib/lib/PDL/Demos.pm

filter: Statementstmt 58.0% 47 / 81 Branchbran 41.6% 10 / 24 Conditioncond 27.2% 3 / 11 MC/DCmcdc 14.2% 1 / 7 Subroutinesub 56.2% 9 / 16 Podpod 100% 9 / 9 totaltotal 53.3% 79 / 148 CC 21 SCAR 25.0
CC
21
Cov
52%
list
26.3
actnw
12.0
comment
6.0
CRAP 12.1
« blib/lib/PDL/AutoLoader.pm ↑ Summary blib/lib/PDL/IO/STL.pm »
1 package PDL::Demos;
2  
3 1 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
4 1 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
5 1 ▶use Carp;
Subroutine BEGIN: called CC=1 SCAR=0.0
6 1 ▶use Exporter;
Subroutine BEGIN: called CC=1 SCAR=0.0
7 1 require File::Spec;
8  
9 1 our @ISA="Exporter";
10 1 our @EXPORT = qw/comment act actnw/;
11  
12 0 ▶sub comment($) {
Subroutine comment: not called CC=2 SCAR=17.9
Pod documented
13 0 local $SIG{__DIE__} = \&Carp::confess;
14 0 print "----\n";
15 0 print $_[0];
16 0 my $prompt = "---- (press enter)";
17 0 ▶ defined($PERLDL::TERM) ? $PERLDL::TERM->readline($prompt) : ( print $prompt, <> );
Branch: 1 branch
BranchTrueFalseTotal
defined $PERLDL::TERM ? : 0 0 0
18 }
19  
20 0 ▶sub act($) {
Subroutine act: not called CC=2 SCAR=17.9
Pod documented
21 0 local $SIG{__DIE__} = \&Carp::confess;
22 0 actnw($_[0], (caller)[0]);
23 0 my $prompt = "---- (press enter)";
24 0 ▶ defined($PERLDL::TERM) ? $PERLDL::TERM->readline($prompt) : ( print $prompt, <> );
Branch: 1 branch
BranchTrueFalseTotal
defined $PERLDL::TERM ? : 0 0 0
25 }
26  
27 0 ▶sub _eval_pkg {
Subroutine _eval_pkg: not called CC=1 SCAR=6.9
28 0 my ($txt, $pack) = @_;
29 0 eval "package $pack; no strict; use PDL; $txt";
30 }
31 0 ▶sub actnw($) {
Subroutine actnw: not called CC=3 SCAR=24.8
Pod documented
32 0 local $SIG{__DIE__} = \&Carp::confess;
33 0 my ($script, $pack) = @_;
34 0 print "---- Code:";
35 0 print $script;
36 0 print "---- Output:\n";
37 0 ▶ _eval_pkg($script, $pack // (caller)[0]);
Condition0%0/3
$pack // (caller)[0]
l!l&&r!l&&!r
000
MC/DC0%0/2
$pack // (caller)[0]
$pack (caller)[0]
Truth table0%0/3
A // B
A= $packB= (caller)[0]
ABresult
1X1
011
000
38 0 print "----\n";
39 0 ▶ print "----\nOOPS!!! Something went wrong, please make a bug report!: $@\n----\n" if $@;
Branch: 1 branch
BranchTrueFalseTotal
if $@ 0 0 0
40 }
41  
42 1 my ($searched, @found);
43 1 my @d = qw(PDL Demos);
44 2 ▶sub list {
Subroutine list: called CC=13 SCAR=32.7
Pod documented
45 2 ▶ return @found if $searched;
Branch: 1 branch
BranchTrueFalseTotal
if $searched 1 1 2
46 1 $searched = 1;
47 1 my %found_already;
48 1 foreach my $path ( @INC ) {
49 8 ▶ next if !-d (my $dir = File::Spec->catdir( $path, @d ));
Branch: 1 branch
BranchTrueFalseTotal
unless -d (my $dir = "File::Spec"->catdir($path, @d)) 5 3 8
50 3 ▶ my @c = do { opendir my $dirfh, $dir or die "$dir: $!"; grep !/^\./, readdir $dirfh };
Branch: 1 branch
BranchTrueFalseTotal
opendir my $dirfh, $dir or die "${dir}: $!" 3 0 3
51 3 ▶ for my $f (grep /\.pm$/ && -f File::Spec->catfile( $dir, $_ ), @c) {
Condition66%2/3
/\.pm$/ && -f 'File::Spec'->catfile($dir, $_)
!ll&&!rl&&r
3018
MC/DC50%1/2
/\.pm$/ && -f 'File::Spec'->catfile($dir, $_)
/\.pm$/ -f 'File::Spec'->catfile($dir, $_)
Truth table66%2/3
A && B
A= /\.pm$/B= -f 'File::Spec'->catfile($dir, $_)
ABresult
0X0
100
111
52 18 $f =~ s/\.pm//;
53 18 my $found_mod = join "::", @d, $f;
54 18 ▶ next if $found_already{$found_mod}++;
Branch: 1 branch
BranchTrueFalseTotal
if $found_already{$found_mod}++ 12 6 18
55 6 push @found, $found_mod;
56 }
57 3 for my $t (grep -d $_->[1], map [$_, File::Spec->catdir( $dir, $_ )], @c) {
58 0 my ($subname, $subd) = @$t;
59 # one extra level
60 0 ▶ my @c = do { opendir my $dirfh, $subd or die "$subd: $!"; grep !/^\./, readdir $dirfh };
Branch: 1 branch
BranchTrueFalseTotal
opendir my $dirfh, $subd or die "${subd}: $!" 0 0 0
61 0 ▶ for my $f (grep /\.pm$/ && -f File::Spec->catfile( $subd, $_ ), @c) {
Condition0%0/3
/\.pm$/ && -f 'File::Spec'->catfile($subd, $_)
!ll&&!rl&&r
000
MC/DC0%0/2
/\.pm$/ && -f 'File::Spec'->catfile($subd, $_)
/\.pm$/ -f 'File::Spec'->catfile($subd, $_)
Truth table0%0/3
A && B
A= /\.pm$/B= -f 'File::Spec'->catfile($subd, $_)
ABresult
0X0
100
111
62 0 $f =~ s/\.pm//;
63 0 my $found_mod = join "::", @d, $subname, $f;
64 0 ▶ next if $found_already{$found_mod}++;
Branch: 1 branch
BranchTrueFalseTotal
if $found_already{$found_mod}++ 0 0 0
65 0 push @found, $found_mod;
66 }
67 }
68 }
69 1 @found;
70 }
71  
72 1 my ($kw_loaded, %kw2info); # info = [kw, description, module]
73 3 ▶sub _load_keywords {
Subroutine _load_keywords: called CC=2 SCAR=6.9
74 3 ▶ return if $kw_loaded;
Branch: 1 branch
BranchTrueFalseTotal
if $kw_loaded 2 1 3
75 1 $kw_loaded = 1;
76 1 my @modules = grep eval "require $_; 1", __PACKAGE__->list;
77 1 my %mod2i = map +($_ => [$_->info]), grep $_->can('info'), @modules;
78 1 %kw2info = map +($mod2i{$_}[0] => [@{$mod2i{$_}}, $_]), keys %mod2i;
79 }
80 1 ▶sub keywords { _load_keywords(); keys %kw2info; }
Subroutine keywords: called CC=1 SCAR=0.0
Pod documented
81 2 ▶sub info {
Subroutine info: called CC=2 SCAR=7.1
Pod documented
82 2 _load_keywords();
83 2 ▶ my $info = $kw2info{$_[1]} || die "unknown demo $_[1]\n";
Condition50%1/2
$kw2info{$_[1]} || die("unknown demo $_[1]\n")
l!l
20
MC/DC0%0/1
$kw2info{$_[1]} || die("unknown demo $_[1]\n")
$kw2info{$_[1]}
Truth table50%1/2
A
A= $kw2info{$_[1]}
Aresult
11
00
84 2 @$info;
85 }
86 1 ▶sub demo {
Subroutine demo: called CC=2 SCAR=7.2
Pod documented
87 1 my $pkg = ($_[0]->info($_[1]))[2];
88 1 ▶ $pkg->can('demo') ? $pkg->demo : [comment=>"No demo data found for $_[1]\n"];
Branch: 1 branch
BranchTrueFalseTotal
$pkg->can('demo') ? : 1 0 1
89 }
90 0 ▶sub _proxy {
Subroutine _proxy: not called CC=2 SCAR=17.9
91 0 my $method = shift;
92 0 my $pkg = ($_[0]->info($_[1]))[2];
93 0 ▶ return if !$pkg->can($method);
Branch: 1 branch
BranchTrueFalseTotal
unless $pkg->can($method) 0 0 0
94 0 _eval_pkg($pkg->$method, (caller 1)[0]);
95 }
96 0 ▶sub init { _proxy('init', @_) }
Subroutine init: not called CC=1 SCAR=6.9
Pod documented
97 0 ▶sub done { _proxy('done', @_) }
Subroutine done: not called CC=1 SCAR=6.9
Pod documented
98  
99 =head1 NAME
100  
101 PDL::Demos - PDL demo infrastructure
102  
103 =head1 SYNOPSIS
104  
105 # in a demo, if text-orientated
106 package PDL::Demos::Blah;
107 sub info { ('blah', 'Longer description of demo') }
108 sub init { 'use PDL::Graphics::Simple;' }
109 my @demo = (
110 [comment => "Welcome to the Blah demo"],
111 [act => <<'EOF'],
112 print "PDL can make n-dimensional sequences:\n";
113 print $x = sequence(2,3);
114 EOF
115 );
116 sub demo { @demo }
117 sub done { "# return things to previous state\n" }
118  
119 # a GUI-orientated one
120 package PDL::Demos::GUIBlah;
121 use GUIBlah; # so demo won't show up in list if GUIBlah not installed
122 sub info { ('blahgui', 'GUIBlah demo') }
123 sub demo {[actnw => q|
124 # starting up the GUI demo app
125 |.__PACKAGE__.q|::run();
126 |]}
127 sub run { # this is just a convention, but a good one
128 # ...
129 }
130  
131 # iterate a demo of your own module - call it PDL::Demos::(something)
132 make && perl -Mblib -S perldl # run "demo" and it will see your demo
133  
134 # in a CLI or REPL
135 use PDL::Demos;
136 sub demo {
137 if (!$_[0]) {
138 require List::Util;
139 my @kw = sort grep $_ ne 'pdl', PDL::Demos->keywords;
140 my $maxlen = List::Util::max(map length, @kw);
141 print "Use:\n";
142 printf " demo %-${maxlen}s # %s\n", @$_[0,1] for map [PDL::Demos->info($_)], 'pdl', @kw;
143 return;
144 }
145 no strict;
146 PDL::Demos->init($_[0]);
147 $_->[0]->($_->[1]) for PDL::Demos->demo($_[0]);
148 PDL::Demos->done($_[0]);
149 }
150  
151 =head1 DESCRIPTION
152  
153 Provides utilities to make demos for PDL modules.
154  
155 PDL demos should be in the C<PDL::Demos::*> namespace so that they can
156 be auto-discovered.
157  
158 Please ensure that your demo module is included in a CPAN distribution
159 and add it to the appropriate metadata (e.g. C<Makefile.PL> and
160 C<MANIFEST>).
161  
162 =head1 METHODS
163  
164 =head2 list
165  
166 Class method; goes through C<@INC> finding all modules starting with
167 C<PDL::Demos::> (with up to two C<::>-separated words). Cached after
168 first run. Does not distinguish demo modules that did not load.
169  
170 =head2 keywords
171  
172 Returns the list of keywords (first element of C<info> return-list)
173 of all found modules that loaded successfully and implement an C<info>
174 method. Caches results.
175  
176 =head2 info
177  
178 Given a keyword, returns the result of calling C<info> on the relevant
179 module plus the module name (three elements) or throws exception if
180 unknown keyword.
181  
182 =head2 init
183  
184 Given a keyword, C<eval>s the result of calling C<init> on the relevant
185 module if it has one, or throws exception if unknown keyword.
186  
187 =head2 demo
188  
189 Given a keyword, returns the result of calling C<demo> on the relevant
190 module or throws exception if unknown keyword.
191  
192 =head2 done
193  
194 Given a keyword, C<eval>s the result of calling C<done> on the relevant
195 module if it has one, or throws exception if unknown keyword.
196  
197 =head1 DEMO MODULE METHODS
198  
199 Each demo module must provide these class methods:
200  
201 =over
202  
203 =item info
204  
205 Return a two-element list of strings: a single keyword (probably
206 lower-case), and a short description of the demo. Both will be displayed
207 when a user enters C<demo> without giving a name.
208  
209 =item demo
210  
211 Returns a list of array-refs of two elements: a L<function|/FUNCTIONS>
212 provided by this module, and an argument for it.
213  
214 =item init
215  
216 Return a string of Perl code which will be evaluated in the package
217 running the demo. Use this e.g. for C<use> statements that import
218 functions needed in your demo.
219  
220 =back
221  
222 =head1 FUNCTIONS
223  
224 These are all exported.
225  
226 =head2 comment
227  
228 Prints its argument, prompts user to press enter before returning.
229  
230 =head2 actnw
231  
232 The argument must be a string containing valid Perl code. The string
233 is printed with a separator, then evaluated as Perl code in the
234 package running the demo, with C<PDL> loaded. Doesn't prompt, so use
235 this for e.g. GUI demos that return when the user tells them to.
236  
237 Multiline code string should start with a newline.
238  
239 =head2 act
240  
241 As above, but prompts before returning.
242  
243 =head1 ERROR HANDLING
244  
245 Check the prerequisites (e.g. optional Perl modules) for your demo in
246 your demo module and not only in the code string you pass to the
247 C<init> routine. If the code in your demo module dies, then the demo
248 will not be offered in the demo overview. Fatal errors in the init
249 routine will be printed and mess up the output layout. Also, error
250 messages might be difficult to understand if users just want to run
251 the demo.
252  
253 If you want to show the demo in the overview though it can't run in
254 the current situation, then make sure that your C<demo> method informs
255 the user what is missing, and where they can obtain it.
256  
257 =head1 AUTHOR
258  
259 Copyright (C) 1998 Tuomas J. Lukka.
260 Tweaks by Ed J for PDL 2.077, 2022.
261  
262 =cut
263  
264 1 1;
« blib/lib/PDL/AutoLoader.pm ↑ Summary blib/lib/PDL/IO/STL.pm »