Hack 35. Write Demos from Tutorials

Give tutorial readers example code to run, tweak, and examine.

Reading code is one thing. Running code is another. Example code is wonderfully useful, but nothing beats playing with itchanging values, moving subroutines around, and seeing what happens if you touch just one more thing.

You'll never escape writing documentation. You can escape having to explain the basics over and over again if that documentation includes working, runnable code that people can customize for their needs. If you've already realized that including pure-POD modules is a great way to document programs, take the next step and make the tutorials themselves write out their examples.

The Hack

Writing a POD-only tutorial is easy. For example, the basic SDL::Tutorial shows how to create a screen using Perl and the SDL bindings:

use SDL::App; # change these values as necessary my  $title                   = 'My SDL App'; my ($width, $height, $depth) = ( 640, 480, 16 ); my $app = SDL::App->new(     -width  => $width,     -height => $height,     -depth  => $depth,     -title  => $title, ); # your code here; remove the next line sleep 2;

Running the Hack

Better yet, if you run the tutorial from the command line, it writes out this program to a file of your choosing:

$ perl -MSDL::Tutorial=sdl_demo.pl -e 1             

Looking at the tutorial itself [Hack #2], it's only a use statement, a heredoc, and the documentation. How does Pod::ToDemo know to write the file and exit? Further, what if someone accidentally uses SDL::Tutorial as a module within a real programwill it write or overwrite a file and throw an error?

Nope; that's part of the magic.

Inside the Hack

Pod::ToDemo has two tricks. The first is writing code that will execute when you run the demo file from the command line only. caller( ) isn't just for checking the calling subroutineit walks the entire call stack. The module's import( ) method has this code:

my @command = caller( 3 ); return if @command and $command[1] ne '-e';

That is, look three levels up the call stack. If the filename of that call frame is not -e (the correct command-line invocation to write a demo file), then someone has accidentally used a demo module in a real program, and the import( ) method returns without doing anything.

Why three levels? The previous level is the implicit BEGIN block surrounding the use call in the demo module [Hack #70]. The next one up is the load of the demo module itself (-M on the command line creates its own block). The top level is the command-line invocation itself.

The rest of the import( ) method itself merely installs another method into the demo module, calling it import( ). By the time the rest of the module finishes compiling, when Perl goes to call that module's import( ), it'll be thereand it can write the file as necessary.

Hacking the Hack

This is the easy way to use Pod::ToDemo. There's also a more difficult way. Consider if you already show the example code within the tutorial, perhaps in one large chunk and perhaps not. Duplicating the code within the string to pass to Pod::ToDemo and the tutorial itself would be a mistake. In that case, generate the code however you like, pulling it out of the POD, and pass a subroutine reference to Pod::ToDemo. The module will call that instead, when appropriate, letting you write the demo file as you like.

This trick would also work to parameterize the demo file based on command-line arguments.