NAME

       Time::Fake - Simulate different times without changing your system clock

SYNOPSIS

       Pretend we are running 1 day in the future:

         use Time::Fake '+1d';

       Pretend we are running 1 year in the past:

         use Time::Fake '-1y';

       Pretend the script started at epoch time 1234567:

         use Time::Fake 1234567;

       See what an existing script would do if run 20 years in the future:

         % perl -MTime::Fake="+20y" test.pl

       Run a section of code in a time warp:

         use Time::Fake;

         # do some setup

         Time::Fake->offset("+1y");
         run_tests(); # thinks it's a year ahead

         Time::Fake->reset; # back to the present

DESCRIPTION

       Use this module to achieve the effect of changing your system clock, but without actually
       changing your system clock. It overrides the Perl builtin subs "time", "localtime", and
       "gmtime", causing them to return a "faked" time of your choice. From the script's point of
       view, time still flows at the normal rate, but it is just offset as if it were executing
       in the past or present.

       You may find this module useful in writing test scripts for code that has time-sensitive
       logic.

USAGE

   Using and importing:
         use Time::Fake $t;

       Is equivalent to:

         use Time::Fake;
         Time::Fake->offset($t);

       See below for arguments to "offset". This usage makes it easy to fake the time for
       existing scripts, as in:

         % perl -MTime::Fake=+1y script.pl

   offset
         Time::Fake->offset( [$t] );

       $t is either an epoch time, or a relative offset of the following form:

         +3    # 3 seconds in the future
         -3s   # 3 seconds in the past
         +1h   # 1 hour in the future
         etc..

       Relative offsets must begin with a plus or minus symbol. The supported units are:

         s second
         m minute
         h hour
         d day (24 hours)
         M month (30 days)
         y year (365 days)

       If $t is an epoch time, then "time", "localtime", and "gmtime" will act as though the the
       current time (when "offset" was called) was actually at $t epoch seconds.  Otherwise, the
       offset $t will be added to the times returned by these builtin subs.

       When $t is false, "time", "localtime", "gmtime" remain overridden, but their behavior
       resets to reflect the actual system time.

       When $t is omitted, nothing is changed, but "offset" returns the current additive offset
       (in seconds). Otherwise, its return value is the previous offset.

       "offset" may be called several times. However, The effect of multiple calls is NOT
       CUMULATIVE. That is:

         Time::Fake->offset("+1h");
         Time::Fake->offset("+1h");

         ## same as
         # Time::Fake->offset("+1h");

         ## NOT the same as
         # Time::Fake->offset("+2h");

       Each call to "offset" completely cancels out the effect of any previous calls. To make the
       effect cumulative, use the return value of calling "offset" with no arguments:

         Time::Fake->offset("+1h");
         ...
         Time::Fake->offset( Time::Fake->offset + 3600 ); # add another hour

   reset
         Time::Fake->reset;

       Is the same as:

         Time::Fake->offset(0);

       That is, it returns all the affected builtin subs to their default behavior -- reporing
       the actual system time.

KNOWN CAVEATS

       Time::Fake must be loaded at "BEGIN"-time (e.g., with a standard "use" statement). It must
       be loaded before perl compiles any code that uses "time", "localtime", or "gmtime". Due to
       inherent limitations in overriding builtin subs, any code that was compiled before loading
       Time::Fake will not be affected.

       Because the system clock is not being changed, only Perl code that uses "time",
       "localtime", or "gmtime" will be fooled about the date.  In particular, the operating
       system is not fooled, nor are other programs. If your Perl code modifies a file for
       example, the file's modification time will reflect the actual (not faked) time.  Along the
       same lines, if your Perl script obtains the time from somewhere other than the affected
       builtins subs (e.g., "qx/date/"), the actual (not faked) time will be reflected.

       Time::Fake doesn't affect -M, -A, -C filetest operators in the way you'd probably want.
       These still report the actual (not faked) script start time minus file access time.

       Time::Fake has not been tested with other modules that override the time builtins, e.g.,
       Time::HiRes.

SEE ALSO

       Time::Warp, which uses XS to fool more of Perl.

AUTHOR

       Time::Fake is written by Mike Rosulek <mike@mikero.com>. Feel free to contact me with
       comments, questions, patches, or whatever.

COPYRIGHT

       Copyright (c) 2008 Mike Rosulek. All rights reserved. This module is free software; you
       can redistribute it and/or modify it under the same terms as Perl itself.