File Coverage

blib/lib/Ftree/Date/Tiny.pm
Criterion Covered Total %
statement 30 55 54.5
branch 0 2 0.0
condition 0 3 0.0
subroutine 11 23 47.8
pod 8 10 80.0
total 49 93 52.6


line stmt bran cond sub pod time code
1             package Ftree::Date::Tiny;
2 1     1   6 use strict;
  1         2  
  1         25  
3 1     1   4 use warnings;
  1         2  
  1         22  
4 1     1   5 use version; our $VERSION = qv('2.3.31');
  1         1  
  1         5  
5             =pod
6              
7             =head1 NAME
8              
9             Ftree::Date::Tiny - A date object, with as little code as possible
10              
11             =head1 SYNOPSIS
12              
13             # Create a date manually
14             $christmas = Ftree::Date::Tiny->new(
15             year => 2006,
16             month => 12,
17             day => 25,
18             );
19            
20             # Show the current date
21             $today = Ftree::Date::Tiny->now;
22             print "Year : " . $today->year . "\n";
23             print "Month: " . $today->month . "\n";
24             print "Day : " . $today->day . "\n";
25              
26             =head1 DESCRIPTION
27              
28             B<Ftree::Date::Tiny> is a member of the L<DateTime::Tiny> suite of time modules.
29              
30             It implements an extremely lightweight object that represents a date,
31             without any time data.
32              
33             =head2 The Tiny Mandate
34              
35             Many CPAN modules which provide the best implementation of a concept
36             can be very large. For some reason, this generally seems to be about
37             3 megabyte of ram usage to load the module.
38              
39             For a lot of the situations in which these large and comprehensive
40             implementations exist, some people will only need a small fraction of the
41             functionality, or only need this functionality in an ancillary role.
42              
43             The aim of the Tiny modules is to implement an alternative to the large
44             module that implements a subset of the functionality, using as little
45             code as possible.
46              
47             Typically, this means a module that implements between 50% and 80% of
48             the features of the larger module, but using only 100 kilobytes of code,
49             which is about 1/30th of the larger module.
50              
51             =head2 The Concept of Tiny Date and Time
52              
53             Due to the inherent complexity, Date and Time is intrinsically very
54             difficult to implement properly.
55              
56             The arguably B<only> module to implement it completely correct is
57             L<DateTime>. However, to implement it properly L<DateTime> is quite slow
58             and requires 3-4 megabytes of memory to load.
59              
60             The challenge in implementing a Tiny equivalent to DateTime is to do so
61             without making the functionality critically flawed, and to carefully
62             select the subset of functionality to implement.
63              
64             If you look at where the main complexity and cost exists, you will find
65             that it is relatively cheap to represent a date or time as an object,
66             but much much more expensive to modify or convert the object.
67              
68             As a result, B<Ftree::Date::Tiny> provides the functionality required to
69             represent a date as an object, to stringify the date and to parse it
70             back in, but does B<not> allow you to modify the dates.
71              
72             The purpose of this is to allow for date object representations in
73             situations like log parsing and fast real-time work.
74              
75             The problem with this is that having no ability to modify date limits
76             the usefulness greatly.
77              
78             To make up for this, B<if> you have L<DateTime> installed, any
79             B<Ftree::Date::Tiny> module can be inflated into the equivalent L<DateTime>
80             as needing, loading L<DateTime> on the fly if necesary.
81              
82             For the purposes of date/time logic, all B<Ftree::Date::Tiny> objects exist
83             in the "C" locale, and the "floating" time zone (although obviously in a
84             pure date context, the time zone largely doesn't matter).
85              
86             When converting up to full L<DateTime> objects, these local and time
87             zone settings will be applied (although an ability is provided to
88             override this).
89              
90             In addition, the implementation is strictly correct and is intended to
91             be very easily to sub-class for specific purposes of your own.
92              
93             =head1 METHODS
94              
95             In general, the intent is that the API be as close as possible to the
96             API for L<DateTime>. Except, of course, that this module implements
97             less of it.
98              
99             =cut
100              
101 1     1   110 use 5.005;
  1         4  
102 1     1   5 use strict;
  1         2  
  1         46  
103 1     1   5 use overload 'bool' => sub () { 1 };
  1         2  
  1         7  
104 1     1   63 use overload '""' => 'as_string';
  1         2  
  1         4  
105 1     1   97 use overload 'eq' => sub { "$_[0]" eq "$_[1]" };
  1     0   2  
  1         6  
  0         0  
106 1     1   99 use overload 'ne' => sub { "$_[0]" ne "$_[1]" };
  1     0   2  
  1         6  
  0         0  
107              
108 1     1   59 use vars qw{$VERSION};
  1         8  
  1         53  
109             BEGIN {
110 1     1   504 $VERSION = '0.01';
111             }
112              
113              
114              
115              
116              
117             #####################################################################
118             # Constructor and Accessors
119              
120             =pod
121              
122             =head2 new
123              
124             my $date = Ftree::Date::Tiny->new(
125             year => 2006,
126             month => 12,
127             day => 31,
128             );
129              
130             The C<new> constructor creates a new B<Ftree::Date::Tiny> object.
131              
132             It takes three named params. C<day> should be the day of the month (1-31),
133             C<month> should be the month of the year (1-12), C<year> as a 4 digit year.
134              
135             These are the only params accepted.
136              
137             Returns a new B<Ftree::Date::Tiny> object.
138              
139             =cut
140             my $format_string = "%d/%m/%Y";
141              
142             sub new {
143 0     0 1   my $class = shift;
144 0           bless { @_ }, $class;
145             }
146              
147             =pod
148              
149             =head2 now
150              
151             my $current_date = Ftree::Date::Tiny->now;
152              
153             The C<now> method creates a new date object for the current date.
154              
155             The date created will be based on localtime, despite the fact that
156             the date is created in the floating time zone.
157              
158             Returns a new B<Ftree::Date::Tiny> object.
159              
160             =cut
161              
162             sub now {
163 0     0 1   my $class = shift;
164 0           my @t = localtime time;
165 0           $class->new(
166             year => $t[5] + 1900,
167             month => $t[4] + 1,
168             day => $t[3],
169             );
170             }
171              
172             =pod
173              
174             =head2 year
175              
176             The C<year> accessor returns the 4-digit year for the date.
177              
178             =cut
179              
180             sub year {
181 0     0 1   $_[0]->{year};
182             }
183              
184             =pod
185              
186             =head2 month
187              
188             The C<month> accessor returns the 1-12 month of the year for the date.
189              
190             =cut
191              
192             sub month {
193 0     0 1   $_[0]->{month};
194             }
195              
196             =pod
197              
198             =head2 day
199              
200             The C<day> accessor returns the 1-31 day of the month for the date.
201              
202             =cut
203              
204             sub day {
205 0     0 1   $_[0]->{day};
206             }
207              
208             =pod
209              
210             =head2 ymd
211              
212             The C<ymd> method returns the most common and accurate stringified date
213             format, which returns in the form "2006-04-12".
214              
215             =cut
216              
217             sub ymd {
218 0     0 1   sprintf( "%04u-%02u-%02u", $_[0]->year, $_[0]->month, $_[0]->day );
219             }
220              
221             sub set_format {
222 0     0 0   $format_string = $_[1];
223             }
224              
225             sub format {
226 0 0 0 0 0   return $_[0]->year
227             if(!defined $_[0]->day && !defined $_[0]->month);
228 0           my $res = $format_string;
229 0           my $day = $_[0]->day;
230 0           my $month = $_[0]->month;
231 0           my $year = $_[0]->year;
232 0           $res =~ s/%d/$day/;
233 0           $res =~ s/%m/$month/;
234 0           $res =~ s/%Y/$year/;
235 0           return $res;
236             }
237              
238              
239             #####################################################################
240             # Type Conversion
241              
242             =pod
243              
244             =head2 as_string
245              
246             The C<as_string> method converts the date to the default string, which
247             at present is the same as that returned by the C<ymd> method above.
248              
249             =cut
250              
251             sub as_string {
252 0     0 1   $_[0]->ymd;
253             }
254              
255             =pod
256              
257             =head2 DateTime
258              
259             The C<DateTime> method is used to inflate the B<Date::Time> object into a
260             full L<DateTime> object.
261              
262             =cut
263              
264             # Convert to "real" DateTime object
265             sub DateTime {
266 0     0 1   require DateTime;
267 0           my $self = shift;
268 0           DateTime->new(
269             day => $self->day,
270             month => $self->month,
271             year => $self->year,
272             locale => 'C',
273             time_zone => 'floating',
274             @_,
275             );
276             }
277              
278             1;
279              
280             =pod
281              
282             =head1 SUPPORT
283              
284             Bugs should be reported via the CPAN bug tracker at
285              
286             L<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Date-Tiny>
287              
288             For other issues, or commercial enhancement or support, contact the author.
289              
290             =head1 AUTHOR
291              
292             Adam Kennedy E<lt>cpan@ali.asE<gt>
293              
294             =head1 SEE ALSO
295              
296             L<DateTime>, L<DateTime::Tiny>, L<Time::Tiny>, L<Config::Tiny>, L<ali.as>
297              
298             =head1 COPYRIGHT
299              
300             Copyright 2006 Adam Kennedy.
301              
302             This program is free software; you can redistribute
303             it and/or modify it under the same terms as Perl itself.
304              
305             The full text of the license can be found in the
306             LICENSE file included with this module.
307              
308             =cut