Debian Codegraph @

README

raw
1 NAME
2 DateTimeX::Auto - use DateTime without needing to call constructors
3
4 SYNOPSIS
5 use DateTimeX::Auto -auto;
6
7 my $ga_start = '2000-04-06' + 'P10Y';
8 printf("%s %s\n", $ga_start, ref $ga_start); # 2010-04-06 DateTime
9
10 {
11 no DateTimeX::Auto;
12 my $string = '2000-04-06';
13 printf( "%s\n", ref($string) ? 'Ref' : 'NoRef' ); # NoRef
14 }
15
16 DESCRIPTION
17 DateTime is awesome, but constructing `DateTime` objects can be annoying.
18 You often need to use one of the formatter modules, or call
19 `DateTime->new()` with a bunch of values. If you've got a bunch of
20 constant dates in your code, then `DateTimeX::Auto` makes all this a bit
21 simpler.
22
23 It uses overload to overload the `q()` operator, automatically turning all
24 string constants that match particular regular expressions into `DateTime`
25 objects. It also overloads stringification to make sure that `DateTime`
26 objects get stringified back to exactly the format they were given in.
27
28 The date formats supported are:
29
30 yyyy-mm-dd
31 yyyy-mm-ddZ
32 yyyy-mm-ddThh:mm:ss
33 yyyy-mm-ddThh:mm:ssZ
34
35 The optional trailing 'Z' puts the datetime into the UTC timezone.
36 Otherwise the datetime will be in DateTime's default (floating) timezone.
37
38 Fractional seconds are also supported, to an arbitrary number of decimal
39 places. However, as `DateTime` only supports nanosecond precision, any
40 digits after the ninth will be zeroed out.
41
42 my $dt ='1234-12-12T12:34:56.123456789123456789';
43 print "$dt\n"; # 1234-12-12T12:34:56.123456789000000000
44
45 Objects are blessed into the `DateTimeX::Auto::DateTime` class which
46 inherits from `DateTime`. They use UNIVERSAL::ref (if installed) to
47 masquerade as plain `DateTime` objects.
48
49 print ref('2000-01-01')."\n"; # DateTime
50
51 Additionally, ISO 8601 durations are supported:
52
53 my $dt = '2000-01-01';
54 say( $dt + 'P4Y2M12D' ); # 2004-03-13
55
56 Durations are possibly not quite as clever at preserving the incoming
57 string formatting.
58
59 The `d` and `dt` Functions
60 As an alternative `DateTimeX::Auto` can export a function called `d`. This
61 might be useful if you'd prefer not to have every string constant in your
62 code turned into a `DateTime`.
63
64 use DateTimeX::Auto 'd';
65 my $dt = d('2000-01-01');
66
67 If `d` is called with a string that is in an unrecognised format, it
68 croaks. If called with no arguments, returns a `DateTime` representing the
69 current time.
70
71 An alias `dt` is also available. They're exactly the same.
72
73 The `dur` Function
74 Called with an ISO 8601 duration string, returns a
75 DateTimeX::Auto::Duration object.
76
77 Object-Oriented Interface
78 This somewhat negates the purpose of the module, but it's also possible to
79 use it without exporting anything, in the usual normal Perl
80 object-oriented fashion:
81
82 use DateTimeX::Auto;
83
84 my $dt1 = DateTimeX::Auto::DateTime->new('2000-01-01T12:00:00.1234');
85
86 # Traditional DateTime style
87 my $dt2 = DateTimeX::Auto::DateTime->new(
88 year => 2000,
89 month => 2,
90 day => 3,
91 );
92
93 Called in the traditional DateTime style, throws an exception if the date
94 isn't valid. Called in the DateTimeX::Auto::DateTime stringy style,
95 returns undef if the date isn't in a recognised format, but throws if it's
96 otherwise invalid (e.g. 30th of February).
97
98 There is similarly a DateTimeX::Auto::Duration class which is a similar
99 thin wrapper around DateTime::Duration.
100
101 EXAMPLES
102 use DateTimeX::Auto ':auto';
103
104 my $date = '2000-01-01';
105 while ($date < '2000-02-01')
106 {
107 print "$date\n";
108 $date += 'P1D'; # add one day
109 }
110
111 use DateTimeX::Auto 'd';
112
113 my $date = d('2000-01-01');
114 while ($date < d('2000-02-01'))
115 {
116 print "$date\n";
117 $date += dur('P1D'); # add one day
118 }
119
120 SEE ALSO
121 DateTime, DateTime::Duration, DateTimeX::Easy.
122
123 AUTHOR
124 Toby Inkster <[email protected]>.
125
126 COPYRIGHT
127 Copyright 2011-2012, 2014 Toby Inkster
128
129 This library is free software; you can redistribute it and/or modify it
130 under the same terms as Perl itself.
131
132 DISCLAIMER OF WARRANTIES
133 THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED
134 WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
135 MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.
136