=pod
=head1 NAME
DateTime::Format::ISO8601 - Parses ISO8601 formats
=head1 SYNOPSIS
use DateTime::Format::ISO8601;
my $dt = DateTime::Format::ISO8601->parse_datetime( $str );
my $dt = DateTime::Format::ISO8601->parse_time( $str );
or
my $iso8601 = DateTime::Format::ISO8601->new;
my $dt = $iso8601->parse_datetime( $str );
my $dt = $iso8601->parse_time( $str );
=head1 DESCRIPTION
Parses almost all ISO8601 date and time formats.
ISO8601 time-intervals will be supported in a later release.
=head1 USAGE
=head2 Import Parameters
This module accepts no arguments to it's C<import> method.
=head2 Methods
=head3 Constructors
=over 4
=item * new( ... )
Accepts an optional hash.
my $iso8601 = DateTime::Format::ISO8601->new(
base_datetime => $dt,
cut_off_year => 42,
legacy_year => 1,
);
=over 4
=item * base_datetime
A C<DateTime> object that will be used to fill in missing information from
incomplete date/time formats.
This key is optional.
=item * cut_off_year
A integer representing the cut-off point between interpreting 2-digits years
as 19xx or 20xx.
2-digit years < legacy_year will be interpreted as 20xx
2-digit years >= legacy_year will be untreated as 19xx
This key defaults to the value of C<DefaultCutOffYear>.
=item * legacy_year
A boolean value controlling if a 2-digit year is interpreted as being in the
current century (unless a C<base_datetime> is set) or if C<cut_off_year>
should be used to place the year in either 20xx or 19xx.
This key defaults to the value of C<DefaultLegacyYear>.
=back
=item * clone
Returns a replica of the given object.
=back
=head3 Object Methods
=over 4
=item * base_datetime
Returns a C<DateTime> object if a C<base_datetime> has been set.
=item * set_base_datetime( object => $object )
Accepts a C<DateTime> object that will be used to fill in missing information
from incomplete date/time formats.
=item * cut_off_year
Returns a integer representing the cut-off point between interpreting
2-digits years as 19xx or 20xx.
=item * set_cut_off_year( $int )
Accepts a integer representing the cut-off point between interpreting
2-digits years as 19xx or 20xx.
2-digit years < legacy_year will be interpreted as 20xx
2-digit years >= legacy_year will be interpreted as 19xx
=item * legacy_year
Returns a boolean value indicating the 2-digit year handling behavior.
=item * set_legacy_year( $bool )
Accepts a boolean value controlling if a 2-digit year is interpreted as being
in the current century (unless a C<base_datetime> is set) or if
C<cut_off_year> should be used to place the year in either 20xx or 19xx.
=back
=head3 Class Methods
=over 4
=item * DefaultCutOffYear( $int )
Accepts a integer representing the cut-off point for 2-digit years when
calling C<parse_*> as class methods and the default value for C<cut_off_year>
when creating objects. If called with no parameters this method will return
the default value for C<cut_off_year>.
=item * DefaultLegacyYear( $bool )
Accepts a boolean value controlling the legacy year behavior when calling
C<parse_*> as class methods and the default value for C<legacy_year> when
creating objects. If called with no parameters this method will return the
default value for C<legacy_year>.
=back
=head3 Parser(s)
These may be called as either class or object methods.
=over 4
=item * parse_datetime
=item * parse_time
Please see the L</FORMATS> section.
=back
=head1 FORMATS
There are 6 string that can match against date only or time only formats.
The C<parse_datetime> method will attempt to match these ambiguous strings
against date only formats. If you want to match against the time only
formats see the C<parse_time> method.
=head2 Conventions
=over 4
=item * Expanded ISO8601
These formats are supported with exactly 6 digits for the year.
Support for a variable number of digits will be in a later release.
=item * Precision
If a format doesn't include a year all larger time unit up to and including
the year are filled in using the current date/time or [if set] the
C<base_datetime> object.
=item * Fractional time
There is no limit on the expressed precision.
=back
=head2 Supported via parse_datetime
The supported formats are listed by the section of ISO 8601:2000(E) in
which they appear.
=head3 5.2 Dates
=head3 5.2.1.1
YYYYMMDD
YYYY-MM-DD
=head3 5.2.1.2
YYYY-MM
YYYY
YY
=head3 5.2.1.3
YYMMDD
YY-MM-DD
-YYMM
-YY-MM
-YY
--MMDD
--MM-DD
--MM
---DD
=head3 5.2.1.4
+[YY]YYYYMMDD
+[YY]YYYY-MM-DD
+[YY]YYYY-MM
+[YY]YYYY
+[YY]YY
=head3 5.2.2.1
YYYYDDD
YYYY-DDD
=head3 5.2.2.2
YYDDD
YY-DDD
-DDD
=head3 5.2.2.3
+[YY]YYYYDDD
+[YY]YYYY-DDD
=head3 5.3.2.1
YYYYWwwD
YYYY-Www-D
=head3 5.2.3.2
YYYYWww
YYYY-Www
YYWwwD
YY-Www-D
YYWww
YY-Www
-YWwwD
-Y-Www-D
-YWww
-Y-Www
-WwwD
-Www-D
-Www
-W-D
=head3 5.2.3.4
+[YY]YYYYWwwD
+[YY]YYYY-Www-D
+[YY]YYYYWww
+[YY]YYYY-Www
=head3 5.3 Time of Day
=head3 5.3.1.1 - 5.3.1.3
optionally prefixed with 'T'
=head3 5.3.1.1
hh:mm:ss
=head3 5.3.1.2
hh:mm
=head3 5.3.1.3 - 5.3.1.4
fractional (decimal) separator maybe either ',' or '.'
=head3 5.3.1.3
hhmmss,ss
hh:mm:ss,ss
hhmm,mm
hh:mm,mm
hh,hh
=head3 5.3.1.4
-mm:ss
-mmss,s
-mm:ss,s
-mm,m
--ss,s
=head3 5.3.3 - 5.3.4.2
optionally prefixed with 'T'
=head3 5.3.3
hhmmssZ
hh:mm:ssZ
hhmmZ
hh:mmZ
hhZ
hhmmss.ssZ
hh:mm:ss.ssZ
=head3 5.3.4.2
hhmmss[+-]hhmm
hh:mm:ss[+-]hh:mm
hhmmss[+-]hh
hh:mm:ss[+-]hh
hhmmss.ss[+-]hhmm
hh:mm:ss.ss[+-]hh:mm
=head3 5.4 Combinations of date and time of day
=head3 5.4.1
YYYYMMDDThhmmss
YYYY-MM-DDThh:mm:ss
YYYYMMDDThhmmssZ
YYYY-MM-DDThh:mm:ssZ
YYYYMMDDThhmmss[+-]hhmm
YYYY-MM-DDThh:mm:ss[+-]hh:mm
YYYYMMDDThhmmss[+-]hh
YYYY-MM-DDThh:mm:ss[+-]hh
=head3 5.4.2
YYYYMMDDThhmmss.ss
YYYY-MM-DDThh:mm:ss.ss
YYYYMMDDThhmmss.ss[+-]hhmm
YYYY-MM-DDThh:mm:ss.ss[+-]hh:mm
Support for this section is not complete.
YYYYMMDDThhmm
YYYY-MM-DDThh:mm
YYYYDDDThhmmZ
YYYY-DDDThh:mmZ
YYYYWwwDThhmm[+-]hhmm
YYYY-Www-DThh:mm[+-]hh
=head3 5.5 Time-Intervals
Will be supported in a later release.
=head2 Supported via parse_time
=head3 5.3.1.1 - 5.3.1.3
optionally prefixed with 'T'
=head3 5.3.1.1
hhmmss
=head3 5.3.1.2
hhmm
hh
=head3 5.3.1.4
-mmss
-mm
--ss
=head1 STANDARDS DOCUMENT
=head2 Title
ISO8601:2000(E)
Data elements and interchange formats - information exchange -
Representation of dates and times
Second edition 2000-12-15
=head2 Reference Number
ISO/TC 154 N 362
=head1 CREDITS
Iain 'Spoon' Truskett (SPOON) who wrote L<DateTime::Format::Builder>.
That has grown into I<The Vacuum Energy Powered C<Swiss Army> Katana>
of date and time parsing. This module was inspired by and conceived
in honor of Iain's work.
Tom Phoenix (PHOENIX) and PDX.pm for helping me solve the ISO week conversion
bug. Not by fixing the code but motivation me to fix it so I could
participate in a game of C<Zendo>.
Jonathan Leffler (JOHNL) for reporting a test bug.
Kelly McCauley for a patch to add 8 missing formats.
Alasdair Allan (AALLAN) for complaining about excessive test execution time.
Everyone at the DateTime C<Asylum>.
=head1 SUPPORT
Support for this module is provided via the <datetime@perl.org> email list.
See L<http://lists.perl.org/> for more details.
=head1 AUTHOR
Joshua Hoblitt <jhoblitt@cpan.org>
=head1 COPYRIGHT
Copyright (c) 2003-2005 Joshua Hoblitt. All rights reserved. This program is
free software; you can redistribute it and/or modify it under the same terms as
Perl itself.
The full text of the licenses can be found in the I<LICENSE> file included with
this module, or in L<perlartistic> and L<perlgpl> as supplied with Perl 5.8.1
and later.
=head1 SEE ALSO
L<DateTime>, L<DateTime::Format::Builder>, L<http://datetime.perl.org/>
=cut