File Coverage

blib/lib/Date/CommonFormats.pm
Criterion Covered Total %
statement 24 76 31.5
branch 0 12 0.0
condition 0 2 0.0
subroutine 8 14 57.1
pod 6 6 100.0
total 38 110 34.5


line stmt bran cond sub pod time code
1             package Date::CommonFormats;
2              
3 1     1   31992 use strict;
  1         3  
  1         46  
4 1     1   7 use warnings;
  1         2  
  1         38  
5             require Exporter;
6 1     1   1088 use Date::Format;
  1         17162  
  1         112  
7 1     1   1310 use Date::Parse;
  1         3663  
  1         174  
8 1     1   1609 use Date::Calc qw (Month_to_Text English_Ordinal Day_of_Week Day_of_Week_to_Text);
  1         58285  
  1         143  
9 1     1   1242 use DateTime::Format::MySQL;
  1         381499  
  1         42  
10 1     1   13 use Carp;
  1         3  
  1         119  
11              
12             =head1 NAME
13              
14             Date::CommonFormats - Common date formats made simple.
15              
16             =head1 VERSION
17              
18             Version 0.05
19              
20             =cut
21              
22             our $VERSION = '0.05';
23              
24             =head1 SYNOPSIS
25              
26             Date::CommonFormats provides a super simple interface for formatting
27             very common types of dates used on web pages and in RSS feeds.
28              
29             use Date::CommonFormats qw(:all);
30              
31             print format_date_w3c($timestamp);
32             print format_date_rss($datetime);
33             print format_date_usenglish_long_ampm($datetime);
34              
35             Most of these functions expect as input a datetime value in
36             the standard mysql format such as 2011-02-02 01:02:03.
37             format_date_integer and format_date_usenglish can
38             accept date or datetime
39              
40             =head1 EXPORT
41              
42             You can import all functions, however none are imported by default.
43             use Date::CommonFormats qw(:all);
44             Importing all functions should be safe as the names are quite unique.
45              
46             =cut
47              
48 1     1   7 use vars qw(@ISA @EXPORT @EXPORT_OK %EXPORT_TAGS);
  1         2  
  1         1142  
49             @ISA = qw(Exporter);
50             @EXPORT = qw();
51             @EXPORT_OK = qw
52             (
53             format_date_integer
54             format_date_rss
55             format_date_usenglish
56             format_date_usenglish_long_ampm
57             format_date_cms_publishdate
58             format_date_w3c
59             );
60             %EXPORT_TAGS = ('all' => [@EXPORT_OK]);
61              
62             =head1 SUBROUTINES
63              
64             =head2 format_date_integer
65              
66             Use this function for reducing a date or datetime to an integer useful
67             in comparisons.
68              
69             if (format_date_integer($date1) > format_date_integer($date2)) {
70             if (format_date_integer($datetime1) > format_date_integer($datetime2)) {
71              
72             ...
73             }
74              
75             =cut
76              
77             #"%Y%m%d%H%M%S"
78             ### this one shouldn't require any external module, mysql dates should convert happily to comparable number
79             sub format_date_integer {
80 0     0 1   my $datetime = shift;
81              
82             ### $dt isn't really used we just use DateTime::Format::MySQL to validate the date format
83 0 0         if (length($datetime) == 10) {
84 0           my $dt = DateTime::Format::MySQL->parse_date( $datetime );
85             } else {
86 0           my $dt = DateTime::Format::MySQL->parse_datetime( $datetime );
87             }
88              
89 0           my ($date, $time) = split(" ", $datetime);
90 0           my @datevals = split("-", $date);
91 0   0       $time ||= "00:00:00";
92 0           my @timevals = split(":", $time);
93 0           my $retval = join("", @datevals) . join("", @timevals);
94              
95 0           return $retval;
96             }
97              
98             =head2 format_date_rss
99              
100             Use this for formatting dates in the proper format for an RSS feed. In other words: RFC-822.
101              
102             my $rss_formatted_date = format_date_rss($datetime);
103              
104             =cut
105              
106             #"%a, %e %B %Y %T %Z"
107             #Tue, 03 Jun 2003 09:39:21 GMT
108             sub format_date_rss {
109 0     0 1   my $datetime = shift;
110              
111 0           my $dt = DateTime::Format::MySQL->parse_datetime( $datetime );
112              
113 0           my $timezone = time2str("%Z", str2time($datetime));
114              
115 0           my @datevals = (Day_of_Week_to_Text(Day_of_Week($dt->year,$dt->month,$dt->day)), $dt->day, Month_to_Text($dt->month), $dt->year,$dt->hour,$dt->minute,$dt->second, $timezone);
116 0           my $retval = sprintf("%.3s, %02d %.3s %d %02d:%02d:%02d %s", @datevals);
117 0           return $retval;
118             }
119              
120             =head2 format_date_usenglish
121              
122             Use this for formatting dates in US English similar to what you would
123             see in a US newspaper or blog entry.
124              
125             my $formatted_date = format_date_usenglish($date);
126             my $formatted_date = format_date_usenglish($datetime);
127              
128             =cut
129              
130             #Dec 22nd, 1956
131             ## this one can accept mysql date or mysql datetime or mysql timestamp
132             sub format_date_usenglish {
133 0     0 1   my $datetime = shift;
134              
135 0           my $dt;
136 0 0         if (length($datetime) == 10) {
137 0           $dt = DateTime::Format::MySQL->parse_date( $datetime );
138             } else {
139 0           $dt = DateTime::Format::MySQL->parse_datetime( $datetime );
140             }
141              
142 0           my $retval = sprintf("%.3s %s, %d",
143             Month_to_Text($dt->month),
144             English_Ordinal($dt->day),
145             $dt->year
146             );
147 0           return $retval;
148             }
149              
150             =head2 format_date_usenglish_long_ampm
151              
152             Use this for formatting dates in US English similar to what you would
153             see in a US newspaper or blog entry. This is the same as usenglish
154             except it includes the time in AM/PM format.
155              
156             my $formatted_date = format_date_usenglish_long_ampm($datetime);
157              
158             =cut
159              
160             #Dec 22nd, 1956 09:23 PM
161             sub format_date_usenglish_long_ampm {
162 0     0 1   my $datetime = shift;
163              
164 0           my $dt = DateTime::Format::MySQL->parse_datetime( $datetime );
165              
166 0           my $ampm = 'AM';
167 0           my $hour = $dt->hour;
168 0 0         if ($hour >= 12) {
169 0           $hour -= 12;
170 0           $ampm = 'PM';
171             }
172 0 0         $hour = 12 unless $hour;
173 0           my $retval = sprintf("%.3s %s, %d %02d:%02d %s",
174             Month_to_Text($dt->month),
175             English_Ordinal($dt->day),
176             $dt->year,
177             $hour, $dt->minute,
178             $ampm
179             );
180 0           return $retval;
181             }
182              
183             =head2 format_date_cms_publishdate
184              
185             Use this for formatting dates in short 24 hour format which is
186             useful in a CRUD list screen where you need to see and sort by
187             datetime but need to conserve space on the page by keeping your
188             columns narrow.
189              
190             my $formatted_date = format_date_cms_publishdate($datetime);
191              
192             =cut
193              
194             #Dec 22nd, 1956 09:23 PM
195             sub format_date_cms_publishdate {
196 0     0 1   my $datetime = shift;
197              
198 0           my $dt = DateTime::Format::MySQL->parse_datetime( $datetime );
199              
200 0           my $ampm = 'AM';
201 0           my $hour = $dt->hour;
202 0 0         if ($hour >= 12) {
203 0           $hour -= 12;
204 0           $ampm = 'PM';
205             }
206 0 0         $hour = 12 unless $hour;
207 0           my $retval = sprintf("%02d-%02d-%d %02d:%02d %s",
208             $dt->month,
209             $dt->day,
210             $dt->year,
211             $hour, $dt->minute,
212             $ampm
213             );
214 0           return $retval;
215             }
216              
217             =head2 format_date_w3c
218              
219             Use this for formatting dates in the W3C accepted format as
220             described by ISO 8601. This can be useful for certain XML
221             applications.
222              
223             my $formatted_date = format_date_w3c($datetime);
224              
225             =cut
226              
227             ## ISO 8601
228             ## $date = sprintf("%d-%02d-%02d %02d:%02d:%02d", @date);
229              
230             sub format_date_w3c {
231 0     0 1   my $datetime = shift;
232              
233 0           my $dt = DateTime::Format::MySQL->parse_datetime( $datetime );
234              
235 0           my $timezone = time2str("%z", str2time($datetime));
236 0           my $tz_firstpart = substr $timezone,0,3;
237 0           my $tz_secondpart = substr $timezone,3,2;
238 0           my $tz_finalstring = $tz_firstpart . ":" . $tz_secondpart;
239              
240 0           my @datevals = ($dt->year,$dt->month,$dt->day,"T",$dt->hour,$dt->minute,$dt->second, $tz_finalstring);
241 0           my $retval = sprintf("%04d-%02d-%02d%s%02d:%02d:%02d%s", @datevals);
242 0           return $retval;
243             }
244              
245              
246             =head1 AUTHOR
247              
248             Chris Fulton, C<< >>
249              
250             =head1 BUGS
251              
252             Please report any bugs or feature requests to C, or through
253             the web interface at L. I will be notified, and then you'll
254             automatically be notified of progress on your bug as I make changes.
255              
256             =head1 SUPPORT
257              
258             You can find documentation for this module with the perldoc command.
259              
260             perldoc Date::CommonFormats
261              
262              
263             You can also look for information at:
264              
265             =over 4
266              
267             =item * GITHUB
268              
269             L
270              
271             =item * RT: CPAN's request tracker
272              
273             L
274              
275             =item * AnnoCPAN: Annotated CPAN documentation
276              
277             L
278              
279             =item * CPAN Ratings
280              
281             L
282              
283             =item * Search CPAN
284              
285             L
286              
287             =back
288              
289              
290             =head1 ACKNOWLEDGEMENTS
291              
292              
293             =head1 LICENSE AND COPYRIGHT
294              
295             Copyright 2011 Chris Fulton.
296              
297             This program is free software; you can redistribute it and/or modify it
298             under the terms of either: the GNU General Public License as published
299             by the Free Software Foundation; or the Artistic License.
300              
301             See http://dev.perl.org/licenses/ for more information.
302              
303              
304             =cut
305              
306             1; # End of Date::CommonFormats