DOKK / manpages / debian 12 / pdl / PDL::Demos.3pm.en
Demos(3pm) User Contributed Perl Documentation Demos(3pm)

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.

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.

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.

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, "eval"s the result of calling "init" on the relevant module if it has one, or throws exception if unknown keyword.

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

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

Each demo module must provide these class methods:

Return a two-element list: a single keyword (probably lower-case), and a short description of the demo.
Returns a list of array-refs of two elements: a function provided by this module, and an argument for it.
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.

These are all exported.

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

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

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.

As above, but prompts before returning.

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

2023-04-27 perl v5.36.0