NAME
    Util::SelfDestruct - Conditionally prevent execution of a script

SYNOPSIS
     # Immediately prevent execution of script by dying on invocation
     # if it has already been executed once before. (The default behavior
     # is to self destruct by dying, unless instructed otherwise).
     use Util::SelfDestruct;
      
 # Delete the script after it is executed
     use Util::SelfDestruct('unlink');
      
 # Prevent execution of the script by dying if it
     # is executed after Dec 17th 2005 at 6pm
     use Util::SelfDestruct(after => '2005-12-17 18h00m00s');
      
 # Delete the script after execution, if it is executed
     # between 1st Dec 2005 and 17th Dec 2005 at 4:05pm
     use Util::SelfDestruct('unlink', 
                            after => '2005-12-01',
                            before => '2005-12-17 16:05:00',
                       );

DESCRIPTION
    This module will prevent execution of your script by either dying or
    deleting (unlinking) the script from disk after it is executed. This can
    be useful if you have written a script for somebody that must never be
    executed more than once. A database upgrade script for example.

    The 'self destruct' mechanism can be achieved through deleting the
    script so that it cannot be executed again, or by dying (terminating the
    scripts execution).

  Die Method (default)
    This is the default, and safest behaviour. This allows the script to be
    executed once. If it is executed again, it will immediately die during
    the initial compilation phase, preventing the script from fully
    executing.

    To do this, the Util::SelfDestruct needs to know if the calling script
    has ever been executed before. It does this by writing a memo to a file
    called ".selfdestruct" in the user's home directory whenever the script
    is executed. It can therefore find out if the script has been run before
    during subsequent invocations.

  Unlink Method
    This method should be used with caution. To specify the unlink method,
    add the "unlink" boolean flag as an import paramter (see examples in the
    synopsis above). Aliases for the "unlink" flag are "erase" and "delete".

    This method will allow the script to execute, but then delete the file
    during the cleanup phase after execution. (Specifically during the
    execution of the END{} in the Util::SelfDestruct module).

  Before & After Qualifiers
    The default behavior of Util::SelfDestruct is to only allow a script to
    execute once, through either deletion of the script itself, or by dying
    on all subsqeuent invocations after it's first execution.

    Instead of this default behaviour, the "before" and "after" options
    allow conditional timing of when the script will self destruct.
    Specifying "before" will cause the script to self destruct if executed
    before the specified date and time. Likewise, the "after" option will
    cause the script to self destruct if executed after the specified date.
    They can also be used in conjunction with eachother to specify a finite
    time frame.

    Examples of valid date time formats are as follows:

     YYYYMMDDHHMMSS
     YYYYMMDD
     
 YYYY-MM-DD HH:MM:SS
     YYYY-MM-DD

    Any non-numeric characters will be removed from the date time string
    before it is parsed. This allows more pleasing formatting to be used.

    If only a date is specified and not a time, 00:00:00 is assumed in the
    case of the "before" option, and 23:59:59 is assumes in the case of the
    "after" option.

VERSION
    $Id: SelfDestruct.pm,v 1.20 2006/01/12 22:45:11 nicolaw Exp $

AUTHOR
    Nicola Worthington <nicolaw@cpan.org>

    <http://perlgirl.org.uk>

COPYRIGHT
    Copyright 2005,2006 Nicola Worthington.

    This software is licensed under The Apache Software License, Version
    2.0.

    <http://www.apache.org/licenses/LICENSE-2.0>