PDL::Demos - PDL demo infrastructure
# in a demo, if text-orientated package PDL::Demos::Blah; sub info { ('blah', 'Longer description of demo') } sub init { 'use PDL::Graphics::PGPLOT;' } my @demo = ( [comment => "Welcome to the Blah demo"], [act => <<'EOF'], output "PDL can make n-dimensional sequences:\n"; output $x = sequence(2,3); EOF ); sub demo { @demo } sub done { "# return things to previous state\n" } # a GUI-orientated one package PDL::Demos::GUIBlah; use GUIBlah; # so demo won't show up in list if GUIBlah not installed sub info { ('blahgui', 'GUIBlah demo') } sub demo {[actnw => q| # starting up the GUI demo app |.__PACKAGE__.q|::run(); |]} sub run { # this is just a convention, but a good one # ... } # iterate a demo of your own module - call it PDL::Demos::(something) make && perl -Mblib -S perldl # run "demo" and it will see your demo # in a CLI or REPL use PDL::Demos; sub demo { if (!$_[0]) { require List::Util; my @kw = sort grep $_ ne 'pdl', PDL::Demos->keywords; my $maxlen = List::Util::max(map length, @kw); print "Use:\n"; printf " demo %-${maxlen}s # %s\n", @$_[0,1] for map [PDL::Demos->info($_)], 'pdl', @kw; return; } no strict; PDL::Demos->init($_[0]); $_->[0]->($_->[1]) for PDL::Demos->demo($_[0]); PDL::Demos->done($_[0]); }
Provides utilities to make demos for PDL modules.
PDL demos should be in the PDL::Demos::* namespace so that they can be auto-discovered.
PDL::Demos::*
Please ensure that your demo module is included in a CPAN distribution and add it to the appropriate metadata (e.g. Makefile.PL and MANIFEST).
Makefile.PL
MANIFEST
Class method; goes through @INC finding all modules starting with PDL::Demos:: (with up to two ::-separated words). Cached after first run. Does not distinguish demo modules that did not load.
@INC
PDL::Demos::
::
Returns the list of keywords (first element of info return-list) of all found modules that loaded successfully and implement an info method. Caches results.
info
Given a keyword, returns the result of calling info on the relevant module plus the module name (three elements) or throws exception if unknown keyword.
Given a keyword, evals the result of calling init on the relevant module if it has one, or throws exception if unknown keyword.
eval
init
Given a keyword, returns the result of calling demo on the relevant module or throws exception if unknown keyword.
demo
Given a keyword, evals the result of calling done on the relevant module if it has one, or throws exception if unknown keyword.
done
Each demo module must provide these class methods:
Return a two-element list of strings: a single keyword (probably lower-case), and a short description of the demo. Both will be displayed when a user enters demo without giving a name.
Returns a list of array-refs of two elements: a function provided by this module, and an argument for it.
Return a string of Perl code which will be evaluated in the package running the demo. Use this e.g. for use statements that import functions needed in your demo.
use
These are all exported.
Prints its argument, prompts user to press enter before returning.
Prints its argument (best for use in actnw etc).
actnw
The argument must be a string containing valid Perl code. The string is printed with a separator, then evaluated as Perl code in the package running the demo, with PDL loaded. Doesn't prompt, so use this for e.g. GUI demos that return when the user tells them to.
PDL
Multiline code string should start with a newline.
As above, but prompts before returning.
Check the prerequisites (e.g. optional Perl modules) for your demo in your demo module and not only in the code string you pass to the init routine. If the code in your demo module dies, then the demo will not be offered in the demo overview. Fatal errors in the init routine will be printed and mess up the output layout. Also, error messages might be difficult to understand if users just want to run the demo.
If you want to show the demo in the overview though it can't run in the current situation, then make sure that your demo method informs the user what is missing, and where they can obtain it.
Copyright (C) 1998 Tuomas J. Lukka. Tweaks by Ed J for PDL 2.077, 2022.
To install PDL, copy and paste the appropriate command in to your terminal.
cpanm
cpanm PDL
CPAN shell
perl -MCPAN -e shell install PDL
For more information on module installation, please visit the detailed CPAN module installation guide.