| 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
| |||||||||||||||||||||
| 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
| |||||||||||||||||||||
| 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]
MC/DC0%0/2
$pack // (caller)[0]
$pack
(caller)[0]
Truth table0%0/3
A // B
A= $packB= (caller)[0]
| |||||||||||||||||||||
| 38 | 0 | print "----\n"; | |||||||||||||||||||
| 39 | 0 | ▶ | print "----\nOOPS!!! Something went wrong, please make a bug report!: $@\n----\n" if $@; | ||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||
| 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
| |||||||||||||||||||||
| 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
| |||||||||||||||||||||
| 50 | 3 | ▶ | my @c = do { opendir my $dirfh, $dir or die "$dir: $!"; grep !/^\./, readdir $dirfh }; | ||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||
| 51 | 3 | ▶ | for my $f (grep /\.pm$/ && -f File::Spec->catfile( $dir, $_ ), @c) { | ||||||||||||||||||
|
Condition66%2/3
/\.pm$/ && -f 'File::Spec'->catfile($dir, $_)
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, $_)
| |||||||||||||||||||||
| 52 | 18 | $f =~ s/\.pm//; | |||||||||||||||||||
| 53 | 18 | my $found_mod = join "::", @d, $f; | |||||||||||||||||||
| 54 | 18 | ▶ | next if $found_already{$found_mod}++; | ||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||
| 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
| |||||||||||||||||||||
| 61 | 0 | ▶ | for my $f (grep /\.pm$/ && -f File::Spec->catfile( $subd, $_ ), @c) { | ||||||||||||||||||
|
Condition0%0/3
/\.pm$/ && -f 'File::Spec'->catfile($subd, $_)
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, $_)
| |||||||||||||||||||||
| 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
| |||||||||||||||||||||
| 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
| |||||||||||||||||||||
| 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")
MC/DC0%0/1
$kw2info{$_[1]} || die("unknown demo $_[1]\n")
$kw2info{$_[1]}
Truth table50%1/2
A
A= $kw2info{$_[1]}
| |||||||||||||||||||||
| 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
| |||||||||||||||||||||
| 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
| |||||||||||||||||||||
| 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; | |||||||||||||||||||