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.

