1Demos(3) User Contributed Perl Documentation Demos(3)
2
6 PDL::Demos - PDL demo infrastructure
7
9 # in a demo, if text-orientated
10 package PDL::Demos::Blah;
11 sub info { ('blah', 'Longer description of demo') }
12 sub init { 'use PDL::Graphics::PGPLOT;' }
13 my @demo = (
14 [comment => "Welcome to the Blah demo"],
15 [act => <<'EOF'],
16 output "PDL can make n-dimensional sequences:\n";
17 output $x = sequence(2,3);
18 EOF
19 );
20 sub demo { @demo }
21 sub done { "# return things to previous state\n" }
22 # a GUI-orientated one
24 package PDL::Demos::GUIBlah;
25 use GUIBlah; # so demo won't show up in list if GUIBlah not installed
26 sub info { ('blahgui', 'GUIBlah demo') }
27 sub demo {[actnw => q|
28 # starting up the GUI demo app
29 |.__PACKAGE__.q|::run();
30 |]}
31 sub run { # this is just a convention, but a good one
32 # ...
33 }
34 # iterate a demo of your own module - call it PDL::Demos::(something)
36 make && perl -Mblib -S perldl # run "demo" and it will see your demo
37 # in a CLI or REPL
39 use PDL::Demos;
40 sub demo {
41 if (!$_[0]) {
42 require List::Util;
43 my @kw = sort grep $_ ne 'pdl', PDL::Demos->keywords;
44 my $maxlen = List::Util::max(map length, @kw);
45 print "Use:\n";
46 printf " demo %-${maxlen}s # %s\n", @$_[0,1] for map [PDL::Demos->info($_)], 'pdl', @kw;
47 return;
48 }
49 no strict;
50 PDL::Demos->init($_[0]);
51 $_->[0]->($_->[1]) for PDL::Demos->demo($_[0]);
52 PDL::Demos->done($_[0]);
53 }
54
56 Provides utilities to make demos for PDL modules.
57 PDL demos should be in the "PDL::Demos::*" namespace so that they can
59 be auto-discovered.
60 Please ensure that your demo module is included in a CPAN distribution
62 and add it to the appropriate metadata (e.g. "Makefile.PL" and
63 "MANIFEST").
64
66 list
67 Class method; goes through @INC finding all modules starting with
68 "PDL::Demos::" (with up to two "::"-separated words). Cached after
69 first run. Does not distinguish demo modules that did not load.
70 keywords
72 Returns the list of keywords (first element of "info" return-list) of
73 all found modules that loaded successfully and implement an "info"
74 method. Caches results.
75 info
77 Given a keyword, returns the result of calling "info" on the relevant
78 module plus the module name (three elements) or throws exception if
79 unknown keyword.
80 init
82 Given a keyword, "eval"s the result of calling "init" on the relevant
83 module if it has one, or throws exception if unknown keyword.
84 demo
86 Given a keyword, returns the result of calling "demo" on the relevant
87 module or throws exception if unknown keyword.
88 done
90 Given a keyword, "eval"s the result of calling "done" on the relevant
91 module if it has one, or throws exception if unknown keyword.
92
94 Each demo module must provide these class methods:
95 info
97 Return a two-element list of strings: a single keyword (probably
98 lower-case), and a short description of the demo. Both will be
99 displayed when a user enters "demo" without giving a name.
100 demo
102 Returns a list of array-refs of two elements: a function provided
103 by this module, and an argument for it.
104 init
106 Return a string of Perl code which will be evaluated in the package
107 running the demo. Use this e.g. for "use" statements that import
108 functions needed in your demo.
109
111 These are all exported.
112 comment
114 Prints its argument, prompts user to press enter before returning.
115 output
117 Prints its argument (best for use in "actnw" etc).
118 actnw
120 The argument must be a string containing valid Perl code. The string
121 is printed with a separator, then evaluated as Perl code in the package
122 running the demo, with "PDL" loaded. Doesn't prompt, so use this for
123 e.g. GUI demos that return when the user tells them to.
124 Multiline code string should start with a newline.
126 act
128 As above, but prompts before returning.
129
131 Check the prerequisites (e.g. optional Perl modules) for your demo in
132 your demo module and not only in the code string you pass to the "init"
133 routine. If the code in your demo module dies, then the demo will not
134 be offered in the demo overview. Fatal errors in the init routine will
135 be printed and mess up the output layout. Also, error messages might
136 be difficult to understand if users just want to run the demo.
137 If you want to show the demo in the overview though it can't run in the
139 current situation, then make sure that your "demo" method informs the
140 user what is missing, and where they can obtain it.
141
143 Copyright (C) 1998 Tuomas J. Lukka. Tweaks by Ed J for PDL 2.077,
144 2022.
145perl v5.38.0 2023-07-21 Demos(3)