.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Demos 3pm"
.TH Demos 3pm "2023-04-27" "perl v5.36.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
PDL::Demos \- PDL demo infrastructure
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 10
\&  # in a demo, if text\-orientated
\&  package PDL::Demos::Blah;
\&  sub info { (\*(Aqblah\*(Aq, \*(AqLonger description of demo\*(Aq) }
\&  sub init { \*(Aquse PDL::Graphics::PGPLOT;\*(Aq }
\&  my @demo = (
\&    [comment => "Welcome to the Blah demo"],
\&    [act => <<\*(AqEOF\*(Aq],
\&  output "PDL can make n\-dimensional sequences:\en";
\&  output $x = sequence(2,3);
\&  EOF
\&  );
\&  sub demo { @demo }
\&  sub done { "# return things to previous state\en" }
\&
\&  # a GUI\-orientated one
\&  package PDL::Demos::GUIBlah;
\&  use GUIBlah; # so demo won\*(Aqt show up in list if GUIBlah not installed
\&  sub info { (\*(Aqblahgui\*(Aq, \*(AqGUIBlah demo\*(Aq) }
\&  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 \*(Aqpdl\*(Aq, PDL::Demos\->keywords;
\&      my $maxlen = List::Util::max(map length, @kw);
\&      print "Use:\en";
\&      printf "   demo %\-${maxlen}s # %s\en", @$_[0,1] for map [PDL::Demos\->info($_)], \*(Aqpdl\*(Aq, @kw;
\&      return;
\&    }
\&    no strict;
\&    PDL::Demos\->init($_[0]);
\&    $_\->[0]\->($_\->[1]) for PDL::Demos\->demo($_[0]);
\&    PDL::Demos\->done($_[0]);
\&  }
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Provides utilities to make demos for \s-1PDL\s0 modules.
.SH "METHODS"
.IX Header "METHODS"
.SS "list"
.IX Subsection "list"
Class method; goes through \f(CW@INC\fR finding all modules starting with
\&\f(CW\*(C`PDL::Demos::\*(C'\fR (with up to two \f(CW\*(C`::\*(C'\fR\-separated words). Cached after
first run. Does not distinguish demo modules that did not load.
.SS "keywords"
.IX Subsection "keywords"
Returns the list of keywords (first element of \f(CW\*(C`info\*(C'\fR return-list)
of all found modules that loaded successfully and implement an \f(CW\*(C`info\*(C'\fR
method. Caches results.
.SS "info"
.IX Subsection "info"
Given a keyword, returns the result of calling \f(CW\*(C`info\*(C'\fR on the relevant
module plus the module name (three elements) or throws exception if
unknown keyword.
.SS "init"
.IX Subsection "init"
Given a keyword, \f(CW\*(C`eval\*(C'\fRs the result of calling \f(CW\*(C`init\*(C'\fR on the relevant
module if it has one, or throws exception if unknown keyword.
.SS "demo"
.IX Subsection "demo"
Given a keyword, returns the result of calling \f(CW\*(C`demo\*(C'\fR on the relevant
module or throws exception if unknown keyword.
.SS "done"
.IX Subsection "done"
Given a keyword, \f(CW\*(C`eval\*(C'\fRs the result of calling \f(CW\*(C`done\*(C'\fR on the relevant
module if it has one, or throws exception if unknown keyword.
.SH "DEMO MODULE METHODS"
.IX Header "DEMO MODULE METHODS"
Each demo module must provide these class methods:
.IP "info" 4
.IX Item "info"
Return a two-element list: a single keyword (probably lower-case),
and a short description of the demo.
.IP "demo" 4
.IX Item "demo"
Returns a list of array-refs of two elements: a function provided by this
module, and an argument for it.
.IP "init" 4
.IX Item "init"
Return a string which will be evaluated in the package running the
demo. Use this for \f(CW\*(C`use\*(C'\fR statements that import functions needed in
your demo.
.SH "FUNCTIONS"
.IX Header "FUNCTIONS"
These are all exported.
.SS "comment"
.IX Subsection "comment"
Prints its argument, prompts user to press enter before returning.
.SS "output"
.IX Subsection "output"
Prints its argument (best for use in \f(CW\*(C`actnw\*(C'\fR etc).
.SS "actnw"
.IX Subsection "actnw"
Prints its argument with a separator, then evaluates it as Perl code
with \f(CW\*(C`PDL\*(C'\fR loaded. Doesn't prompt, so use this for e.g. \s-1GUI\s0 demos that
return when the user tells them to.
.SS "act"
.IX Subsection "act"
As above, but prompts before returning.
.SH "AUTHOR"
.IX Header "AUTHOR"
Copyright (C) 1998 Tuomas J. Lukka.
Tweaks by Ed J for \s-1PDL 2.077, 2022.\s0