Debian Codegraph @

bench/perl/Template/Plugin/Date.pm

raw
1 #============================================================= -*-Perl-*-
2 #
3 # Template::Plugin::Date
4 #
5 # DESCRIPTION
6 #
7 # Plugin to generate formatted date strings.
8 #
9 # AUTHORS
10 # Thierry-Michel Barral <[email protected]>
11 # Andy Wardley <[email protected]>
12 #
13 # COPYRIGHT
14 # Copyright (C) 2000-2007 Thierry-Michel Barral, Andy Wardley.
15 #
16 # This module is free software; you can redistribute it and/or
17 # modify it under the same terms as Perl itself.
18 #
19 #============================================================================
20
21 package Template::Plugin::Date;
22
23 use strict;
24 use warnings;
25 use base 'Template::Plugin';
26
27 use POSIX ();
28
29 our $VERSION = 2.78;
30 our $FORMAT = '%H:%M:%S %d-%b-%Y'; # default strftime() format
31 our @LOCALE_SUFFIX = qw( .ISO8859-1 .ISO_8859-15 .US-ASCII .UTF-8 );
32
33
34 #------------------------------------------------------------------------
35 # new(\%options)
36 #------------------------------------------------------------------------
37
38 sub new {
39 my ($class, $context, $params) = @_;
40 bless {
41 $params ? %$params : ()
42 }, $class;
43 }
44
45
46 #------------------------------------------------------------------------
47 # now()
48 #
49 # Call time() to return the current system time in seconds since the epoch.
50 #------------------------------------------------------------------------
51
52 sub now {
53 return time();
54 }
55
56
57 #------------------------------------------------------------------------
58 # format()
59 # format($time)
60 # format($time, $format)
61 # format($time, $format, $locale)
62 # format($time, $format, $locale, $gmt_flag)
63 # format(\%named_params);
64 #
65 # Returns a formatted time/date string for the specified time, $time,
66 # (or the current system time if unspecified) using the $format, $locale,
67 # and $gmt values specified as arguments or internal values set defined
68 # at construction time). Specifying a Perl-true value for $gmt will
69 # override the local time zone and force the output to be for GMT.
70 # Any or all of the arguments may be specified as named parameters which
71 # get passed as a hash array reference as the final argument.
72 # ------------------------------------------------------------------------
73
74 sub format {
75 my $self = shift;
76 my $params = ref($_[$#_]) eq 'HASH' ? pop(@_) : { };
77 my $time = shift(@_) || $params->{ time } || $self->{ time }
78 || $self->now();
79 my $format = @_ ? shift(@_)
80 : ($params->{ format } || $self->{ format } || $FORMAT);
81 my $locale = @_ ? shift(@_)
82 : ($params->{ locale } || $self->{ locale });
83 my $gmt = @_ ? shift(@_)
84 : ($params->{ gmt } || $self->{ gmt });
85 my (@date, $datestr);
86
87 if ($time =~ /^\d+$/) {
88 # $time is now in seconds since epoch
89 if ($gmt) {
90 @date = (gmtime($time))[0..6];
91 }
92 else {
93 @date = (localtime($time))[0..6];
94 }
95 }
96 else {
97 # if $time is numeric, then we assume it's seconds since the epoch
98 # otherwise, we try to parse it as either a 'Y:M:D H:M:S' or a
99 # 'H:M:S D:M:Y' string
100
101 my @parts = (split(/(?:\/| |:|-)/, $time));
102
103 if (@parts >= 6) {
104 if (length($parts[0]) == 4) {
105 # year is first; assume 'Y:M:D H:M:S'
106 @date = @parts[reverse 0..5];
107 }
108 else {
109 # year is last; assume 'H:M:S D:M:Y'
110 @date = @parts[2,1,0,3..5];
111 }
112 }
113
114 if (!@date) {
115 return (undef, Template::Exception->new('date',
116 "bad time/date string: " .
117 "expects 'h:m:s d:m:y' got: '$time'"));
118 }
119 $date[4] -= 1; # correct month number 1-12 to range 0-11
120 $date[5] -= 1900; # convert absolute year to years since 1900
121 $time = &POSIX::mktime(@date);
122 }
123
124 if ($locale) {
125 # format the date in a specific locale, saving and subsequently
126 # restoring the current locale.
127 my $old_locale = &POSIX::setlocale(&POSIX::LC_ALL);
128
129 # some systems expect locales to have a particular suffix
130 for my $suffix ('', @LOCALE_SUFFIX) {
131 my $try_locale = $locale.$suffix;
132 my $setlocale = &POSIX::setlocale(&POSIX::LC_ALL, $try_locale);
133 if (defined $setlocale && $try_locale eq $setlocale) {
134 $locale = $try_locale;
135 last;
136 }
137 }
138 $datestr = &POSIX::strftime($format, @date);
139 &POSIX::setlocale(&POSIX::LC_ALL, $old_locale);
140 }
141 else {
142 $datestr = &POSIX::strftime($format, @date);
143 }
144
145 return $datestr;
146 }
147
148 sub calc {
149 my $self = shift;
150 eval { require "Date/Calc.pm" };
151 $self->throw("failed to load Date::Calc: $@") if $@;
152 return Template::Plugin::Date::Calc->new('no context');
153 }
154
155 sub manip {
156 my $self = shift;
157 eval { require "Date/Manip.pm" };
158 $self->throw("failed to load Date::Manip: $@") if $@;
159 return Template::Plugin::Date::Manip->new('no context');
160 }
161
162
163 sub throw {
164 my $self = shift;
165 die (Template::Exception->new('date', join(', ', @_)));
166 }
167
168
169 package Template::Plugin::Date::Calc;
170 use base qw( Template::Plugin );
171 use vars qw( $AUTOLOAD );
172 *throw = \&Template::Plugin::Date::throw;
173
174 sub AUTOLOAD {
175 my $self = shift;
176 my $method = $AUTOLOAD;
177
178 $method =~ s/.*:://;
179 return if $method eq 'DESTROY';
180
181 my $sub = \&{"Date::Calc::$method"};
182 $self->throw("no such Date::Calc method: $method")
183 unless $sub;
184
185 &$sub(@_);
186 }
187
188 package Template::Plugin::Date::Manip;
189 use base qw( Template::Plugin );
190 use vars qw( $AUTOLOAD );
191 *throw = \&Template::Plugin::Date::throw;
192
193 sub AUTOLOAD {
194 my $self = shift;
195 my $method = $AUTOLOAD;
196
197 $method =~ s/.*:://;
198 return if $method eq 'DESTROY';
199
200 my $sub = \&{"Date::Manip::$method"};
201 $self->throw("no such Date::Manip method: $method")
202 unless $sub;
203
204 &$sub(@_);
205 }
206
207
208 1;
209
210 __END__
211
212 =head1 NAME
213
214 Template::Plugin::Date - Plugin to generate formatted date strings
215
216 =head1 SYNOPSIS
217
218 [% USE date %]
219
220 # use current time and default format
221 [% date.format %]
222
223 # specify time as seconds since epoch
224 # or as a 'h:m:s d-m-y' or 'y-m-d h:m:s' string
225 [% date.format(960973980) %]
226 [% date.format('4:20:36 21/12/2000') %]
227 [% date.format('2000/12/21 4:20:36') %]
228
229 # specify format
230 [% date.format(mytime, '%H:%M:%S') %]
231
232 # specify locale
233 [% date.format(date.now, '%a %d %b %y', 'en_GB') %]
234
235 # named parameters
236 [% date.format(mytime, format = '%H:%M:%S') %]
237 [% date.format(locale = 'en_GB') %]
238 [% date.format(time = date.now,
239 format = '%H:%M:%S',
240 locale = 'en_GB) %]
241
242 # specify default format to plugin
243 [% USE date(format = '%H:%M:%S', locale = 'de_DE') %]
244
245 [% date.format %]
246 ...
247
248 =head1 DESCRIPTION
249
250 The C<Date> plugin provides an easy way to generate formatted time and date
251 strings by delegating to the C<POSIX> C<strftime()> routine.
252
253 The plugin can be loaded via the familiar USE directive.
254
255 [% USE date %]
256
257 This creates a plugin object with the default name of 'C<date>'. An alternate
258 name can be specified as such:
259
260 [% USE myname = date %]
261
262 The plugin provides the C<format()> method which accepts a time value, a
263 format string and a locale name. All of these parameters are optional
264 with the current system time, default format ('C<%H:%M:%S %d-%b-%Y>') and
265 current locale being used respectively, if undefined. Default values
266 for the time, format and/or locale may be specified as named parameters
267 in the C<USE> directive.
268
269 [% USE date(format = '%a %d-%b-%Y', locale = 'fr_FR') %]
270
271 When called without any parameters, the C<format()> method returns a string
272 representing the current system time, formatted by C<strftime()> according
273 to the default format and for the default locale (which may not be the
274 current one, if locale is set in the C<USE> directive).
275
276 [% date.format %]
277
278 The plugin allows a time/date to be specified as seconds since the epoch,
279 as is returned by C<time()>.
280
281 File last modified: [% date.format(filemod_time) %]
282
283 The time/date can also be specified as a string of the form C<h:m:s d/m/y>
284 or C<y/m/d h:m:s>. Any of the characters : / - or space may be used to
285 delimit fields.
286
287 [% USE day = date(format => '%A', locale => 'en_GB') %]
288 [% day.format('4:20:00 9-13-2000') %]
289
290 Output:
291
292 Tuesday
293
294 A format string can also be passed to the C<format()> method, and a locale
295 specification may follow that.
296
297 [% date.format(filemod, '%d-%b-%Y') %]
298 [% date.format(filemod, '%d-%b-%Y', 'en_GB') %]
299
300 A fourth parameter allows you to force output in GMT, in the case of
301 seconds-since-the-epoch input:
302
303 [% date.format(filemod, '%d-%b-%Y', 'en_GB', 1) %]
304
305 Note that in this case, if the local time is not GMT, then also specifying
306 'C<%Z>' (time zone) in the format parameter will lead to an extremely
307 misleading result.
308
309 Any or all of these parameters may be named. Positional parameters
310 should always be in the order C<($time, $format, $locale)>.
311
312 [% date.format(format => '%H:%M:%S') %]
313 [% date.format(time => filemod, format => '%H:%M:%S') %]
314 [% date.format(mytime, format => '%H:%M:%S') %]
315 [% date.format(mytime, format => '%H:%M:%S', locale => 'fr_FR') %]
316 [% date.format(mytime, format => '%H:%M:%S', gmt => 1) %]
317 ...etc...
318
319 The C<now()> method returns the current system time in seconds since the
320 epoch.
321
322 [% date.format(date.now, '%A') %]
323
324 The C<calc()> method can be used to create an interface to the C<Date::Calc>
325 module (if installed on your system).
326
327 [% calc = date.calc %]
328 [% calc.Monday_of_Week(22, 2001).join('/') %]
329
330 The C<manip()> method can be used to create an interface to the C<Date::Manip>
331 module (if installed on your system).
332
333 [% manip = date.manip %]
334 [% manip.UnixDate("Noon Yesterday","%Y %b %d %H:%M") %]
335
336 =head1 AUTHORS
337
338 Thierry-Michel Barral wrote the original plugin.
339
340 Andy Wardley provided some minor
341 fixups/enhancements, a test script and documentation.
342
343 Mark D. Mills cloned C<Date::Manip> from the C<Date::Calc> sub-plugin.
344
345 =head1 COPYRIGHT
346
347 Copyright (C) 2000-2007 Thierry-Michel Barral, Andy Wardley.
348
349 This module is free software; you can redistribute it and/or
350 modify it under the same terms as Perl itself.
351
352 =head1 SEE ALSO
353
354 L<Template::Plugin>, L<POSIX>
355