File Coverage

blib/lib/App/Sqitch/DateTime.pm
Criterion Covered Total %
statement 17 17 100.0
branch n/a
condition n/a
subroutine 6 6 100.0
pod n/a
total 23 23 100.0


line stmt bran cond sub pod time code
1             package App::Sqitch::DateTime;
2              
3 39     39   94646 use 5.010;
  39         261  
4 39     39   281 use strict;
  39         140  
  39         1100  
5 39     39   260 use warnings;
  39         278  
  39         1440  
6 39     39   256 use utf8;
  39         94  
  39         516  
7 39     39   1665 use parent 'DateTime';
  39         126  
  39         535  
8 38     38   20222925 use DateTime 1.04;
  38         1204  
  37         1250  
9             use Locale::TextDomain qw(App-Sqitch);
10             use App::Sqitch::X qw(hurl);
11             use List::Util qw(first);
12             use constant ISWIN => $^O eq 'MSWin32';
13              
14             our $VERSION = 'v1.4.0'; # VERSION
15              
16             sub as_string_formats {
17             return qw(
18             raw
19             iso
20             iso8601
21             rfc
22             rfc2822
23             full
24             long
25             medium
26             short
27             );
28             }
29              
30             sub validate_as_string_format {
31             my ( $self, $format ) = @_;
32             hurl datetime => __x(
33             'Unknown date format "{format}"',
34             format => $format
35             ) unless (first { $format eq $_ } $self->as_string_formats)
36             || $format =~ /^(?:cldr|strftime):/;
37             return $self;
38             }
39              
40             sub as_string {
41             my ( $self, %opts ) = @_;
42             my $format = $opts{format} || 'raw';
43             my $dt = $self->clone;
44              
45             if ($format eq 'raw') {
46             $dt->set_time_zone('UTC');
47             return $dt->iso8601 . 'Z';
48             }
49              
50             $dt->set_time_zone('local');
51              
52             if ( first { $format eq $_ } qw(iso iso8601) ) {
53             return join ' ', $dt->ymd('-'), $dt->hms(':'), $dt->strftime('%z');
54             } elsif ( first { $format eq $_ } qw(rfc rfc2822) ) {
55             $dt->set_locale('en_US');
56             ( my $rv = $dt->strftime('%a, %d %b %Y %H:%M:%S %z') ) =~
57             s/\+0000$/-0000/;
58             return $rv;
59             } else {
60             if (ISWIN) {
61             require Win32::Locale;
62             $dt->set_locale( Win32::Locale::get_locale() );
63             } else {
64             require POSIX;
65             $dt->set_locale( POSIX::setlocale( POSIX::LC_TIME() ) );
66             }
67             return $dt->format_cldr($format) if $format =~ s/^cldr://;
68             return $dt->strftime($format) if $format =~ s/^strftime://;
69             my $meth = $dt->locale->can("datetime_format_$format") or hurl(
70             datetime => __x(
71             'Unknown date format "{format}"',
72             format => $format
73             )
74             );
75             return $dt->format_cldr( $dt->locale->$meth );
76             }
77             }
78              
79             1;
80              
81             __END__
82              
83             =head1 Name
84              
85             App::Sqitch::DateTime - Sqitch DateTime object
86              
87             =head1 Synopsis
88              
89             my $dt = App::Sqitch::DateTime->new(%params);
90             say $dt->as_string( format => 'iso' );
91              
92             =head1 Description
93              
94             This subclass of L<DateTime> provides additional interfaces to support named
95             formats. These can be used for L<status|sqitch-status> or L<log|sqitch-log>
96             C<--date-format> options. App::Sqitch::DateTime provides a list of supported
97             formats, validates that a format string, and uses the formats to convert
98             itself into the appropriate string.
99              
100             =head1 Interface
101              
102             =head2 Class Methods
103              
104             =head3 C<as_string_formats>
105              
106             my @formats = App::Sqitch::DateTime->as_string_formats;
107              
108             Returns a list of formats supported by the C<format> parameter to
109             C<as_string>. The list currently includes:
110              
111             =over
112              
113             =item C<iso>
114              
115             =item C<iso8601>
116              
117             ISO-8601 format.
118              
119             =item C<rfc>
120              
121             =item C<rfc2822>
122              
123             RFC-2822 format.
124              
125             =item C<full>
126              
127             =item C<long>
128              
129             =item C<medium>
130              
131             =item C<short>
132              
133             Localized format of the specified length.
134              
135             =item C<raw>
136              
137             Show timestamps in raw format, which is strict ISO-8601 in the UTC time zone.
138              
139             =item C<strftime:$string>
140              
141             Show timestamps using an arbitrary C<strftime> pattern. See
142             L<DateTime/strftime Paterns> for comprehensive documentation of supported
143             patterns.
144              
145             =item C<cldr:$string>
146              
147             Show timestamps using an arbitrary C<cldr> pattern. See L<DateTime/CLDR
148             Paterns> for comprehensive documentation of supported patterns.
149              
150             =back
151              
152             =head3 C<validate_as_string_format>
153              
154             App::Sqitch::DateTime->validate_as_string_format($format);
155              
156             Validates that a format is supported by C<as_string>. Throws an exception if
157             it's not, and returns if it is.
158              
159             =head2 Instance Methods
160              
161             =head3 C<as_string>
162              
163             $dt->as_string;
164             $dt->as_string( format => $format );
165              
166             Returns a string representation using the provided format. The format must be
167             one of those listed by C<as_string_formats> or an exception will be thrown. If
168             no format is passed, the string will be formatted with the C<raw> format.
169              
170             =head1 See Also
171              
172             =over
173              
174             =item L<sqitch-status>
175              
176             Documentation for the C<status> command to the Sqitch command-line client.
177              
178             =item L<sqitch-log>
179              
180             Documentation for the C<log> command to the Sqitch command-line client.
181              
182             =item L<sqitch>
183              
184             The Sqitch command-line client.
185              
186             =back
187              
188             =head1 Author
189              
190             David E. Wheeler <david@justatheory.com>
191              
192             =head1 License
193              
194             Copyright (c) 2012-2023 iovation Inc., David E. Wheeler
195              
196             Permission is hereby granted, free of charge, to any person obtaining a copy
197             of this software and associated documentation files (the "Software"), to deal
198             in the Software without restriction, including without limitation the rights
199             to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
200             copies of the Software, and to permit persons to whom the Software is
201             furnished to do so, subject to the following conditions:
202              
203             The above copyright notice and this permission notice shall be included in all
204             copies or substantial portions of the Software.
205              
206             THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
207             IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
208             FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
209             AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
210             LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
211             OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
212             SOFTWARE.
213              
214             =cut