File Coverage

blib/lib/Template/Plugin/TimeDate.pm
Criterion Covered Total %
statement 39 41 95.1
branch 4 4 100.0
condition n/a
subroutine 12 13 92.3
pod 6 6 100.0
total 61 64 95.3


line stmt bran cond sub pod time code
1             package Template::Plugin::TimeDate;
2              
3             ###############################################################################
4             # Required inclusions.
5             ###############################################################################
6 1     1   118491 use strict;
  1         13  
  1         35  
7 1     1   5 use warnings;
  1         2  
  1         29  
8 1     1   495 use Date::Parse qw();
  1         8266  
  1         35  
9 1     1   545 use Date::Format qw();
  1         3242  
  1         39  
10 1     1   9 use overload '""' => \&stringify;
  1         2  
  1         13  
11              
12             ###############################################################################
13             # Version number.
14             ###############################################################################
15             our $VERSION = '1.04';
16              
17             ###############################################################################
18             # Derive ourselves from our base class.
19             ###############################################################################
20 1     1   604 use Template::Plugin;
  1         589  
  1         31  
21 1     1   7 use base qw( Template::Plugin );
  1         3  
  1         387  
22              
23             ###############################################################################
24             # Subroutine: new(string)
25             ###############################################################################
26             # Creates a new TimeDate plug-in object, returning it to the caller. An
27             # optional date/time string may be passed in, which is parsed automatically.
28             ###############################################################################
29             sub new {
30 11     11 1 118768 my ($class, $context, $string) = @_;
31 11         27 my $self = {};
32 11         25 bless $self, $class;
33 11 100       35 if ($string) {
34 1         4 $self->parse( $string );
35             }
36 11         32 return $self;
37             }
38              
39             ###############################################################################
40             # Subroutine: now
41             ###############################################################################
42             # Sets the current time to "now", and returns it as "the number of seconds
43             # since the epoch".
44             ###############################################################################
45             sub now {
46 2     2 1 47 my $self = shift;
47 2         7 $self->{'epoch'} = time();
48 2         56 return $self->{'epoch'};
49             }
50              
51             ###############################################################################
52             # Subroutine: epoch
53             ###############################################################################
54             # Returns the currently set time as "the number of seconds since the epoch".
55             # If a date/time hasn't explicitly been parsed, we default to the current time.
56             ###############################################################################
57             sub epoch {
58 9     9 1 89 my $self = shift;
59 9 100       31 unless ($self->{'epoch'}) {
60 1         3 $self->now();
61             }
62 9         38 return $self->{'epoch'};
63             }
64              
65             ###############################################################################
66             # Subroutine: parse(string, zone)
67             ###############################################################################
68             # Parses the given date/time 'string' and sets that as the current time value
69             # for further operations. An optional time 'zone' is used if there is no time
70             # zone information present in the provided date string.
71             ###############################################################################
72             sub parse {
73 8     8 1 356 my ($self, $string, $zone) = @_;
74 8         36 $self->{'epoch'} = Date::Parse::str2time( $string, $zone );
75 8         2870 return $self;
76             }
77              
78             ###############################################################################
79             # Subroutine: str2time(string, zone)
80             ###############################################################################
81             # An alternate name for the 'parse' method above.
82             ###############################################################################
83             *str2time = \&parse;
84              
85             ###############################################################################
86             # Subroutine: format(format, zone)
87             ###############################################################################
88             # Formats the current time value using the given strftime 'format', optionally
89             # converting it into the given time 'zone'. If a date/time hasn't explicitly
90             # been parsed, we default to the current time.
91             #
92             # You may also refer to this method as 'time2str'; its original name from the
93             # 'Date::Format' module.
94             ###############################################################################
95             sub format {
96 5     5 1 16 my ($self, $format, $zone) = @_;
97 5         18 return Date::Format::time2str( $format, $self->epoch(), $zone );
98             }
99              
100             ###############################################################################
101             # Subroutine: time2str(format, zone)
102             ###############################################################################
103             # An alternate name for the 'format' method above.
104             ###############################################################################
105             *time2str = \&format;
106              
107             ###############################################################################
108             # Subroutine: stringify
109             ###############################################################################
110             # Stringifies the object, in ISO8601 format (%Y-%m-%d %H:%M:%S).
111             #
112             # This method is overloaded, so that simply turning the TimeDate object into a
113             # string will output it in ISO8601 format.
114             ###############################################################################
115             sub stringify {
116 0     0 1   my $self = shift;
117 0           return $self->format( '%Y-%m-%d %H:%M:%S' );
118             }
119              
120             1;
121              
122             =for stopwords ISO8601
123              
124             =head1 NAME
125              
126             Template::Plugin::TimeDate - Template::Toolkit plugin to parse/format dates using TimeDate
127              
128             =head1 SYNOPSIS
129              
130             [% USE TimeDate %]
131              
132             # get current time, as "seconds since the epoch"
133             [% TimeDate.now %]
134              
135             # parse date string and show in default format (ISO8601)
136             [% TimeDate.parse('2007-09-02 12:34:56 PDT') %]
137              
138             # parse date string with explicit time zone
139             [% TimeDate.parse('2007-09-02 12:34:56', 'EDT') %]
140              
141             # get current time, with custom format
142             [% TimeDate.format('%b %e %Y @ %l:%M %p') %]
143              
144             # parse/display
145             [% USE mydate = TimeDate('2007-09-02 12:34:56 PDT') %]
146             [% mydate.format('%b %e %Y @ %l:%M %p') %]
147              
148             # method chaining
149             [% USE mydate = TimeDate %]
150             [% mydate.parse('2007-09-02 12:34:56 PDT').format('%Y-%m-%d %H:%M:%S %z') %]
151              
152             =head1 DESCRIPTION
153              
154             C is a C plug-in that makes of
155             the C and C modules from the C
156             distribution, to help deal with parsing/formatting dates.
157              
158             Why another date/time plug-in? C doesn't handle output
159             in different timezones, and C didn't give me a means
160             of easily parsing dates before turning them into C objects. I'd been
161             using the C module elsewhere to parse dates, and so this plug-in
162             was built to help capture the parse/format cycle that I wanted to use in my
163             templates.
164              
165             The plug-in should be loaded via the USE directive:
166              
167             [% USE TimeDate %]
168              
169             This creates a plug-in object with the default name of 'TimeDate'. An
170             alternate name can be specified such as:
171              
172             [% USE mydate = TimeDate %]
173              
174             =head1 METHODS
175              
176             =over
177              
178             =item new(string)
179              
180             Creates a new TimeDate plug-in object, returning it to the caller. An
181             optional date/time string may be passed in, which is parsed automatically.
182              
183             =item now
184              
185             Sets the current time to "now", and returns it as "the number of seconds
186             since the epoch".
187              
188             =item epoch
189              
190             Returns the currently set time as "the number of seconds since the epoch".
191             If a date/time hasn't explicitly been parsed, we default to the current
192             time.
193              
194             =item parse(string, zone)
195              
196             Parses the given date/time C and sets that as the current time
197             value for further operations. An optional time C is used if there is
198             no time zone information present in the provided date string.
199              
200             =item str2time(string, zone)
201              
202             An alternate name for the C method above.
203              
204             =item format(format, zone)
205              
206             Formats the current time value using the given strftime C,
207             optionally converting it into the given time C. If a date/time hasn't
208             explicitly been parsed, we default to the current time.
209              
210             You may also refer to this method as C; its original name from
211             the C module.
212              
213             =item time2str(format, zone)
214              
215             An alternate name for the C method above.
216              
217             =item stringify
218              
219             Stringifies the object, in ISO8601 format (%Y-%m-%d %H:%M:%S).
220              
221             This method is overloaded, so that simply turning the TimeDate object into
222             a string will output it in ISO8601 format.
223              
224             =back
225              
226             =head1 AUTHOR
227              
228             Graham TerMarsch (cpan@howlingfrog.com)
229              
230             =head1 COPYRIGHT
231              
232             Copyright (C) 2007, Graham TerMarsch. All Rights Reserved.
233              
234             This is free software; you can redistribute it and/or modify it under the same
235             terms as Perl itself.
236              
237             =head1 SEE ALSO
238              
239             L,
240             L,
241             L