NAME

Template::Plugin::TimeDate - Template::Toolkit plugin to parse/format dates using TimeDate

SYNOPSIS

[% USE TimeDate %]

# get current time, as "seconds since the epoch"
[% TimeDate.now %]

# parse date string and show in default format (ISO8601)
[% TimeDate.parse('2007-09-02 12:34:56 PDT') %]

# parse date string with explicit time zone
[% TimeDate.parse('2007-09-02 12:34:56', 'EDT') %]

# get current time, with custom format
[% TimeDate.format('%b %e %Y @ %l:%M %p') %]

# parse/display
[% USE mydate = TimeDate('2007-09-02 12:34:56 PDT') %]
[% mydate.format('%b %e %Y @ %l:%M %p') %]

# method chaining
[% USE mydate = TimeDate %]
[% mydate.parse('2007-09-02 12:34:56 PDT').format('%Y-%m-%d %H:%M:%S %z') %]

DESCRIPTION

Template::Plugin::TimeDate is a Template::Toolkit plug-in that makes of the Date::Parse and Date::Format modules from the TimeDate distribution, to help deal with parsing/formatting dates.

Why another date/time plug-in? Template::Plugin::Date doesn't handle output in different timezones, and Template::Plugin::DateTime didn't give me a means of easily parsing dates before turning them into DateTime objects. I'd been using the Date::Parse module elsewhere to parse dates, and so this plug-in was built to help capture the parse/format cycle that I wanted to use in my templates.

The plug-in should be loaded via the USE directive:

[% USE TimeDate %]

This creates a plug-in object with the default name of 'TimeDate'. An alternate name can be specified such as:

[% USE mydate = TimeDate %]

METHODS

new(string)

Creates a new TimeDate plug-in object, returning it to the caller. An optional date/time string may be passed in, which is parsed automatically.

now

Sets the current time to "now", and returns it as "the number of seconds since the epoch".

epoch

Returns the currently set time as "the number of seconds since the epoch". If a date/time hasn't explicitly been parsed, we default to the current time.

parse(string, zone)

Parses the given date/time string and sets that as the current time value for further operations. An optional time zone is used if there is no time zone information present in the provided date string.

str2time(string, zone)

An alternate name for the parse method above.

format(format, zone)

Formats the current time value using the given strftime format, optionally converting it into the given time zone. If a date/time hasn't explicitly been parsed, we default to the current time.

You may also refer to this method as time2str; its original name from the Date::Format module.

time2str(format, zone)

An alternate name for the format method above.

stringify

Stringifies the object, in ISO8601 format (%Y-%m-%d %H:%M:%S).

This method is overloaded, so that simply turning the TimeDate object into a string will output it in ISO8601 format.

AUTHOR

Graham TerMarsch (cpan@howlingfrog.com)

COPYRIGHT

Copyright (C) 2007, Graham TerMarsch. All Rights Reserved.

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

SEE ALSO

Date::Parse, Date::Format, Template.