Time::Fake(3pm)

💖 NAME 💖

okay so hi bestie, welcome to Time::Fake — the Perl module that lets you simulate a totally different time without ever touching your actual system clock 🕰️✨ (manual section 3pm, in case you were wondering, and it lives in the User Contributed Perl Documentation crowd 💅)

---

✨ SYNOPSIS ✨

bestie, watch this. Pretend we're running 1 day in the future:

use Time::Fake '+1d';

Pretend we're running 1 year in the past:

use Time::Fake '-1y';

Pretend the script started at epoch time 1234567:

use Time::Fake 1234567;

Wanna see what an existing script would do if it ran 20 years in the future? No code changes, just vibes:

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

And if you wanna run just a section of code in a time warp, that's giving main character energy fr:

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 get the whole entire effect of changing your system clock — but without actually changing your system clock. Iconic, honestly. It overrides the Perl builtin subs time, localtime, and gmtime, so they return a "faked" time of your choosing 🎀

From the script's point of view, time still flows at the normal rate — it's just offset, as if it were executing in the past or the present. So it's lowkey a lie but a very well-behaved lie 💅

You'll probably find this module useful for writing test scripts for code that has time-sensitive logic. Like if your code does stuff based on the date and you're not about to wait a year to find out if it works. No cap. 🧚

---

🦋 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 super easy to fake the time for existing scripts, like so:

% 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 — that's the vibe check, don't skip it. 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. (So they're still the impostor subs, they're just telling the truth again 🙈)

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. Like, every call is a fresh start, periodt. 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 — reporting the actual system time. Back to reality bestie 🌈

---

💀 KNOWN CAVEATS 💀

okay this part is important, don't skip it, I'm literally begging 🫶

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. So timing is everything — ironic, I know 😭

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. The illusion only goes so far, bestie 💅

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. So close, and yet 😔

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

---

🔥 SEE ALSO 🔥

• Time::Warp, which uses XS to fool more of Perl. (overachiever behavior, honestly 👑)

---

🎀 AUTHOR 🎀

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

---

💜 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.

---

and that's the whole page, bestie!! this little masterpiece is perl v5.36.0, dated 2022-11-20 — now go fake some time, you absolute icon 💖✨🦋🌸💅