NAME

Pod::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

DESCRIPTION

Pod::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 - 2011, chromatic. Some rights reserved. You may use, modify, and distribute this module under the same terms as Perl 5.12, in the hope that it is useful but certainly under no guarantee.