PDL::Demos(3pm)

✨ NAME ✨

PDL::Demos — it's the whole demo infrastructure for PDL, bestie. like, the scaffolding that lets a demo actually demo. and yes, you're reading PDL::Demos(3pm), the manual page, she's iconic. 💖

---

🌸 SYNOPSIS 🌸

# in a demo, if text-orientated
package PDL::Demos::Blah;
sub info { ('blah', 'Longer description of demo') }
sub init { 'use PDL::Graphics::Simple;' }
my @demo = (
  [comment => "Welcome to the Blah demo"],
  [act => <<'EOF'],
print "PDL can make n-dimensional sequences:\n";
print $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 🦋

okay so lowkey this module is the plug: it gives you the utilities you need to make demos for PDL modules. periodt. 🫶

your demo modules HAVE to live in the PDL::Demos::* namespace, because that's how they get auto-discovered — the module literally goes looking for them. iykyk.

and pls pls pls make sure your demo module ships inside a CPAN distribution and that you add it to the right metadata (like Makefile.PL and MANIFEST). don't be the person whose demo exists in the group chat but never in the repo. 💀

---

👑 METHODS 👑

🎀 list

class method, main character energy. it walks through @INC finding all modules starting with PDL::Demos:: — and that's modules with up to two ::-separated words after it. it caches the result after the first run, so it's not out here doing the same work twice ✨. heads up tho: it does not distinguish demo modules that did not load. the no-loads are just… silently there. 🙈

💜 keywords

returns the list of keywords — that's the first element of what info returns — for all found modules that loaded successfully and implement an info method. and yes, it caches results too. efficient queen. 💅

🍓 info

hand it a keyword and it hands you back the result of calling info on the matching module, plus the module name — three elements total. if the keyword is unknown? it throws an exception. no soft-launching a fake keyword, sorry bestie. 😭

🧚 init

hand it a keyword and it evals whatever init returns on the relevant module — if that module has one. unknown keyword? again: exception thrown. it's giving strict. 💅

🌈 demo

hand it a keyword, get back the result of calling demo on the relevant module. unknown keyword? you already know — exception. 🌈

⭐ done

hand it a keyword and it evals the result of calling done on the relevant module, if it has one. unknown keyword? bestie. exception. every single time. it's consistent and we love that for her. ⭐

---

🌸 DEMO MODULE METHODS 🌸

if you're writing a demo module, these class methods are mandatory. no skipping, this is the assignment. 📝

💖 info

return a two-element list of strings: a single keyword (probably lower-case, keep it cute), and a short description of the demo. both of these get displayed when a user types demo without giving a name. so this is literally your module's whole first impression. slay it. 💖

💖 demo

returns a list of array-refs, each with two elements: a function provided by this module, and an argument for it. simple. iconic.

💖 init

return a string of Perl code. that string gets evaluated in the package that's running the demo. use this for stuff like use statements that import the functions your demo needs — so everything's loaded before the show starts. 🎬

---

🌈 FUNCTIONS 🌈

these are all exported. all of them. help yourself. 🫶

💅 comment

prints its argument, then prompts the user to press enter before it returns. it's a lil "okay we good? continue?" moment. ⏸️

💅 actnw

the argument must be a string containing valid Perl code. the string gets printed with a separator, then evaluated as Perl code in the package running the demo, with PDL loaded. it doesn't prompt, so this is the one for things like GUI demos that return when the user tells them to. and important: a multiline code string should start with a newline. 📝

💅 act

as above, but it prompts before returning. same energy, just with the lil pause. ⏸️

---

😭 ERROR HANDLING 😭

this is the part where we're real with each other, bestie.

check the prerequisites for your demo (like optional Perl modules) in your demo module, not only in the code string you pass to the init routine. why? because if the code in your demo module dies, then the demo will not be offered in the demo overview. just gone. not invited.

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 — they didn't sign up for a stack trace, they signed up for a demo.

so: if you want the demo to still show up in the overview even though it can't run in the current situation, make sure your demo method informs the user what is missing, and where they can obtain it. that's the kind, iconic, main-character move. 👑

---

💜 AUTHOR 💜

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

---

and that's the whole page, babe — this one came to you from perl v5.42.3, dated 2026-08-20, and it's PDL::Demos(3pm) the whole way through. go build something slay. 💅✨