Templat...n::Date(3)

💖 NAME 💖

okay bestie 💅 this is Templat...n::Date(3) from the User Contributed Perl Documentation, and it's literally the page for Template::Plugin::Date — the plugin to generate formatted date strings. That's the whole job: formatted date strings, no cap. ✨

---

✨ SYNOPSIS ✨

Here's the exact code energy, bestie. Copy these literally:

[% USE date %]

# use current time and default format
[% date.format %]

# specify time as seconds since epoch
# or as a 'h:m:s d-m-y' or 'y-m-d h:m:s' string
[% date.format(960973980) %]
[% date.format('4:20:36 21/12/2000') %]
[% date.format('2000/12/21 4:20:36') %]

# specify format
[% date.format(mytime, '%H:%M:%S') %]

# specify locale
[% date.format(date.now, '%a %d %b %y', 'en_GB') %]

# named parameters
[% date.format(mytime, format = '%H:%M:%S') %]
[% date.format(locale = 'en_GB') %]
[% date.format(time       = date.now,
               format     = '%H:%M:%S',
               locale     = 'en_GB'
               use_offset = 1) %]

# specify default format to plugin
[% USE date(format = '%H:%M:%S', locale = 'de_DE') %]

[% date.format %]
...

---

🌸 DESCRIPTION 🌸

The Date plugin is your easy-peasy way to generate formatted time and date strings, and it does it by delegating to the POSIX strftime() routine. Iconic delegation behavior. 💅

🎀 Loading and default names 🎀

You load it with the familiar USE directive:

[% USE date %]

That creates a plugin object with the default name of "date". You can give it an alternate name like this:

[% USE myname = date %]

💫 The format() method 💫

The plugin provides the format() method, which accepts a time value, a format string and a locale name. All of these parameters are optional. If they're undefined, you get the current system time, the default format ("%H:%M:%S %d-%b-%Y") and the current locale respectively. You can also set default values for the time, format and/or locale as named parameters in the USE directive.

[% USE date(format = '%a %d-%b-%Y', locale = 'fr_FR') %]

When you call format() without any parameters, it returns a string representing the current system time, formatted by strftime() according to the default format and for the default locale (which may not be the current one if locale is set in the USE directive).

[% date.format %]

You can pass a time/date as seconds since the epoch, as returned by time():

File last modified: [% date.format(filemod_time) %]

You can also pass a time/date as a string of the form "h:m:s d/m/y" or "y/m/d h:m:s". Any of the characters :, /, - or a space may be used to delimit fields.

[% USE day = date(format => '%A', locale => 'en_GB') %]
[% day.format('4:20:00 9-13-2000') %]

Output:

Tuesday

A format string can also be passed to the format() method, and a locale specification may follow that.

[% date.format(filemod, '%d-%b-%Y') %]
[% date.format(filemod, '%d-%b-%Y', 'en_GB') %]

A fourth parameter lets you force output in GMT, in the case of seconds-since-the-epoch input:

[% date.format(filemod, '%d-%b-%Y', 'en_GB', 1) %]

Note: in this case, if the local time is not GMT, then also specifying %Z (time zone) in the format parameter will lead to an extremely misleading result. Like, don't do that to yourself. 😭

To maintain backwards compatibility, using the %z placeholder in the format string (to output the UTC offset) currently requires the use_offset parameter to be set to a true value. This can also be passed as the fifth parameter to format (but the former will probably be clearer).

Any or all of these parameters may be named. Positional parameters should always be in the order ($time, $format, $locale).

[% date.format(format => '%H:%M:%S') %]
[% date.format(time => filemod, format => '%H:%M:%S') %]
[% date.format(mytime, format => '%H:%M:%S') %]
[% date.format(mytime, format => '%H:%M:%S', locale => 'fr_FR') %]
[% date.format(mytime, format => '%H:%M:%S', gmt => 1) %]
...etc...

🕰️ now() 🕰️

The now() method returns the current system time in seconds since the epoch.

[% date.format(date.now, '%A') %]

🧮 calc() 🧮

The calc() method can be used to create an interface to the Date::Calc module (if installed on your system).

[% calc = date.calc %]
[% calc.Monday_of_Week(22, 2001).join('/') %]

🪄 manip() 🪄

The manip() method can be used to create an interface to the Date::Manip module (if installed on your system).

[% manip = date.manip %]
[% manip.UnixDate("Noon Yesterday","%Y %b %d %H:%M") %]

---

🫶 AUTHORS 🫶

Thierry-Michel Barral wrote the original plugin. Andy Wardley provided some minor fixups/enhancements, a test script and documentation. Mark D. Mills cloned Date::Manip from the Date::Calc sub-plugin. A whole collaborative slay. 👑

---

👑 COPYRIGHT 👑

Copyright (C) 2000-2022 Thierry-Michel Barral, Andy Wardley.

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

---

🦋 SEE ALSO 🦋

Go peek at Template::Plugin and POSIX, bestie. They're right there in the references. 🌈

okay bye bestie 🫶 this page is from perl v5.42.0, dated 2024-06-23, and it's Templat...n::Date(3) — mwah. 💋