Pod::ToDemo(3) User Contributed Perl Documentation Pod::ToDemo(3)NAMEPod::ToDemo - writes a demo program from a tutorial POD
SYNOPSIS
use Pod::ToDemo <<'END_HERE';
print "Hi, here is my demo program!\n";
END_HERE
DESCRIPTIONPod::ToDemo allows you to write POD-only modules that serve as
tutorials which can write out demo programs if you invoke them
directly. That is, while SDL::Tutorial is a tutorial on writing
beginner SDL applications with Perl, you can invoke it as:
$ perl -MSDL::Tutorial=sdl_demo.pl -e 1
and it will write a bare-bones demo program called "sdl_demo.pl" based
on the tutorial.
USAGE
You can do things the easy way or the hard way. I recommend the easy
way, but the hard way has advantages.
The Easy Way
The easy way is to do exactly as the synopsis suggests. Pass a string
containing your code as the only argument to the "use Pod::ToDemo"
line. The module will write the demo file, when appropriate, and
refuse to do anything, when appropriate.
The Hard Way
The hard way exists so that you can customize exactly what you write.
This is useful, for example, if you want to steal the demo file
entirely out of your POD already -- so grab the module's file handle,
rewind it as appropriate, and search through it for your verbatim code.
Call "Pod::ToDemo::write_demo()" with two arguments. $filename is the
name of the file to write. If there's no name, this function will
"die()" with an error message. If a file already exists with this
name, this function will also "die()" with another error message. The
second argument, $demo, is the text of the demo program to write.
If you're using this in tutorial modules, as you should be, you will
probably want to protect programs that inadvertently use the tutorial
from attempting to write demo files. Pod::ToDemo does this
automatically for you by checking that you haven't invoked the tutorial
module from the command line.
To prevent "perl" from interpreting the name of the file to write as
the name of a file to invoke (a file which does not yet exist), you
must pass the name of the file on the command line as an argument to
the tutorial module's "import()" method. If this doesn't make sense to
you, just remember to tell people to write:
$ perl -MTutorial::Module=I<file_to_write.pl> -e 1
FUNCTIONS and METHODS
import_default( $program_text )
This is a class method.
Given the test of the demo program to write, returns a subroutine
suitable for writing a demo file. The subroutine returned takes
the current package and the name of the file to write and writes
the file to the filesystem.
The program text does not need to include the "#!" line, or the use
of the strict and warnings pragmas.
write_demo( $filename, $demo_text )
Given the name of a file to write and the test of the demo program,
attempts to write the file. This will throw an exception that
there is no filename if there is no filename and will throw an
exception if you attempt to overwrite an existing file. Finally,
it will also throw an exception if it cannot write the file.
AUTHOR
chromatic, "chromatic at wgz dot org".
BUGS
No known bugs, now. Thanks to Greg Lapore for helping me track down a
bug in 0.10 and to Robert Rothenberg for Windows test tweaks.
COPYRIGHT
Copyright (c) 2003 - 2005, chromatic. All rights reserved. You may
use, modify, and distribute this module under the same terms as Perl
5.8.x, in the hope that it is useful but certainly under no guarantee.
perl v5.10.1 2005-11-19 Pod::ToDemo(3)
