NAME

       PDL::Demos - PDL demo infrastructure

SYNOPSIS

         # 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]);
         }

DESCRIPTION

       Provides utilities to make demos for PDL modules.

METHODS

   list
       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.

   keywords
       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.

   init
       Given a keyword, "eval"s the result of calling "init" on the relevant module if it has
       one, or throws exception if unknown keyword.

   demo
       Given a keyword, returns the result of calling "demo" on the relevant module or throws
       exception if unknown keyword.

   done
       Given a keyword, "eval"s the result of calling "done" on the relevant module if it has
       one, or throws exception if unknown keyword.

DEMO MODULE METHODS

       Each demo module must provide these class methods:

       info
           Return a two-element list: a single keyword (probably lower-case), and a short
           description of the demo.

       demo
           Returns a list of array-refs of two elements: a function provided by this module, and
           an argument for it.

       init
           Return a string which will be evaluated in the package running the demo. Use this for
           "use" statements that import functions needed in your demo.

FUNCTIONS

       These are all exported.

   comment
       Prints its argument, prompts user to press enter before returning.

   output
       Prints its argument (best for use in "actnw" etc).

   actnw
       Prints its argument with a separator, then evaluates it as Perl code with "PDL" loaded.
       Doesn't prompt, so use this for e.g. GUI demos that return when the user tells them to.

   act
       As above, but prompts before returning.

AUTHOR

       Copyright (C) 1998 Tuomas J. Lukka.  Tweaks by Ed J for PDL 2.077, 2022.