`Web::DateTime::Parser`

Date and time parser for Web

SYNOPSIS

  use Web::DateTime::Parser;
  $parser = Web::DateTime::Parser->new;
  $dt = $parser->parse_global_date_and_time_string ($value);

DESCRIPTION

The Web::DateTime::Parser module is a collection of parsing methods for various date and time formats used in Web.

METHODS

Following methods are available:

$parser = Web::DateTime::Parser->new

Create a new instance of the parser.

$parser->onerror ($code)

$code = $parser->onerror

Get or set the error handler for parser methods. Any parse error, as well as warning and additional processing information, is reported to the handler. See <https://github.com/manakai/data-errors/blob/master/doc/onerror.txt> for details of error handling.

The value should not be set while the parser is running. If the value is changed, the result is undefined.

$dt = $parser->parse_html_datetime_value ($string)

Parse the argument as an HTML time element datetime value [HTML] and return a Web::DateTime, Web::DateTime::TimeZone, or Web::DateTime::Duration object (or undef if failed). Any error is reported through the onerror handler.

This method is suitable for values from HTML time element's datetime attribute or element content.

$dt = $parser->parse_global_date_and_time_string ($string)

Parse the argument as an HTML global date and time string [HTML] and return a Web::DateTime (or undef if failed). Any error is reported through the onerror handler.

This method is suitable for values from HTML <input type=datetime>.

$dt = $parser->parse_xs_date_time_stamp_string ($string)

Parse the argument as an XML Schema xs:dateTimeStamp string [XSDT] and return a Web::DateTime (or undef if failed). Any error is reported through the onerror handler.

$dt = $parser->parse_local_date_and_time_string ($string)

Parse the argument as an HTML local date and time string [HTML] and return a Web::DateTime (or undef if failed). Any error is reported through the onerror handler.

This method is suitable for values from HTML <input type=datetime-local>.

$dt = $parser->parse_xs_date_time_string ($string)

Parse the argument as an XML Schema xs:dateTime string [XSDT] and return a Web::DateTime (or undef if failed). Any error is reported through the onerror handler.

$dt = $parser->parse_schema_org_date_time_string ($string)

Parse the argument as an http://schema.org/DateTime string [SCHEMAORG] and return a Web::DateTime (or undef if failed). Any error is reported through the onerror handler.

The format might support leap seconds, but the Web::DateTime module does not support leap seconds. If a leap second is specified, a Web::DateTime object representing the second just before the leap second is returned.

$dt = $parser->parse_ogp_date_time_string ($string)

Parse the argument as an OGP DateTime string [OGP] and return a Web::DateTime (or undef if failed). Any error is reported through the onerror handler.

$dt = $parser->parse_rfc3339_date_time_string ($string)

Parse the argument as an RFC 3339 date-time string [RFC3339] and return a Web::DateTime (or undef if failed). Any error is reported through the onerror handler.

The RFC 3339 format does support leap seconds, but the Web::DateTime module does not support leap seconds. If a leap second is specified, a Web::DateTime object representing the second just before the leap second is returned.

$dt = $parser->parse_rfc3339_xs_date_time_string ($string)

Parse the argument as an RFC 3339 date-time string [RFC3339], applying constraints of XML Schema xs:dateTime datatype [XSDT], and return a Web::DateTime (or undef if failed). Any error is reported through the onerror handler.

This method is suitable for values in Atom 1.0 Date construct.

$dt = $parser->parse_pkix_generalized_time_string ($string)

Parse the argument as a PKIX GeneralizedTime string [PKIX]. Any error is reported through the onerror handler.

This method is suitable for various timestamp fields in Certificates, CRLs, and OCSP objects, used with TLS.

$dt = $parser->parse_pkix_utc_time_string ($string)

Parse the argument as a PKIX UTCTime string [PKIX]. Any error is reported through the onerror handler.

This method is suitable for various timestamp fields in Certificates used with TLS.

$dt = $parser->parse_http_date_string ($string)

Parse the argument as an HTTP-date string [HTTP], using the parsing rules in RFC 6265 [COOKIES], and return a Web::DateTime (or undef if failed). Any error is reported through the onerror handler.

Leap seconds are treated as invalid second values, which is a willful violation to RFC 7231.

This method is suitable for values in HTTP Expires, Last-Modified, and Date headers, as well as in Expires attribute in Cookies.

$dt = $parser->parse_rss2_date_time_string ($string)

Parse the argument as an RFC 822 date-time string used in RSS 2.0 document [RFC822] [RSS2] [RSS2BP], and return a Web::DateTime (or undef if failed). Any error is reported through the onerror handler.

This method is suitable for values in RSS 2.0 elements. This method is NOT suitable for dates in e-mail, netnews, or HTTP headers.

$dt = $parser->parse_date_string ($string)

Parse the argument as an HTML date string [HTML] and return a Web::DateTime (or undef if failed). Any error is reported through the onerror handler.

This method is suitable for values from HTML <input type=date>.

$dt = $parser->parse_xs_date_string ($string)

Parse the argument as an XML Schema xs:date string [XSDT] and return a Web::DateTime (or undef if failed). Any error is reported through the onerror handler.

$dt = $parser->parse_iso8601_date_string ($string)

Parse the argument as an ISO 8601:2004 date representation [ISO8601] and return a Web::DateTime (or undef if failed). Any error is reported through the onerror handler.

This method is suitable for microdata http://schema.org/Date item values and date item values in data-vocabulary.org microdata vocabulary.

$dt = $parser->parse_ymd_string ($string)

Parse the argument as an YMD string in the Gregorian calendar [DATETIME] and return a Web::DateTime (or undef if failed). Any error is reported through the onerror handler.

$dt = $parser->parse_julian_ymd_string ($string)

Parse the argument as an YMD string in the Julian calendar [DATETIME] and return a Web::DateTime (or undef if failed). Any error is reported through the onerror handler.

$dt = $parser->parse_date_string_with_optional_time ($string)

Parse the argument as an HTML date string with optional time [HTML] and return a Web::DateTime (or undef if failed). Any error is reported through the onerror handler.

This method is suitable for values in HTML <ins datetime=""> and <del datetime="" attributes.

$dt = $parser->parse_js_date_time_string ($string)

Parse the argument as a date and time string in the way similar to the Date() constructor and Date.parse() method of JavaScript (ECMAScript) [JS]. Please note that this method is not compatible with JavaScript enough yet as those JavaScript methods are largely undocumented.

$dt = $parser->parse_w3c_dtf_string ($string)

Parse the argument as a so-called W3C-DTF string [W3CDTF] and return a Web::DateTime (or undef if failed). Any error is reported through the onerror handler.

This method is suitable for values in Atom 0.3 Date construct and RSS 1.0 dc:date elements.

$dt = $parser->parse_year_string ($string)

Parse the argument as a year string in HTML and return a Web::DateTime (or undef if failed). Any error is reported through the onerror handler.

$dt = $parser->parse_xs_g_year_string ($string)

Parse the argument as an XML Schema xs:gYear string [XSDT] and return a Web::DateTime (or undef if failed). Any error is reported through the onerror handler.

$dt = $parser->parse_manakai_year_string ($string)

Parse the argument as a year string in manakai Date and Time specification [DATETIME] and return a Web::DateTime (or undef if failed). Any error is reported through the onerror handler.

$dt = $parser->parse_month_string ($string)

Parse the argument as an HTML month string [HTML] and return a Web::DateTime (or undef if failed). Any error is reported through the onerror handler.

This method is suitable for values from HTML <input type=month>.

$dt = $parser->parse_xs_g_year_month_string ($string)

Parse the argument as an XML Schema xs:gYearMonth string [XSDT] and return a Web::DateTime (or undef if failed). Any error is reported through the onerror handler.

$dt = $parser->parse_yearless_date_string ($string)

Parse the argument as an HTML yearless date string [HTML] and return a Web::DateTime (or undef if failed). Year of the returned object is set to 2000. Any error is reported through the onerror handler.

$dt = $parser->parse_xs_g_month_day_string ($string)

Parse the argument as an XML Schema xs:gMonthDay string [XSDT] and return a Web::DateTime (or undef if failed). Year of the returned object is set to 2000. Any error is reported through the onerror handler.

$dt = $parser->parse_xs_g_month_string ($string)

Parse the argument as an XML Schema xs:gMonth string [XSDT] and return a Web::DateTime (or undef if failed). Year of the returned object is set to 2000. Any error is reported through the onerror handler.

$dt = $parser->parse_xs_g_day_string ($string)

Parse the argument as an XML Schema xs:gDay string [XSDT] and return a Web::DateTime (or undef if failed). Year and month of the returned object is set to 2000 and 1, respectively. Any error is reported through the onerror handler.

$dt = $parser->parse_week_string ($string)

Parse the argument as an HTML week string [HTML] and return a Web::DateTime (or undef if failed). Any error is reported through the onerror handler.

This method is suitable for values from HTML <input type=week>.

$dt = $parser->parse_time_string ($string)

Parse the argument as an HTML time string [HTML] and return a Web::DateTime (or undef if failed). Any error is reported through the onerror handler.

This method is suitable for values from HTML <input type=time>.

$dt = $parser->parse_xs_time_string ($string)

Parse the argument as an XML Schema xs:time string [XSDT] and return a Web::DateTime (or undef if failed). Any error is reported through the onerror handler.

This method is suitable for microdata http://schema.org/Time item value.

$tz = $parser->parse_time_zone_offset_string ($string)

Parse the argument as an HTML time-zone offset string [HTML] and return a Web::DateTime::TimeZone (or undef if failed). Any error is reported through the onerror handler.

$tz = $parser->parse_vcard_time_zone_offset_string ($string)

Parse the argument as a time-zone offset string used in vCard tz item value [HTML] and return a Web::DateTime::TimeZone (or undef if failed). Any error is reported through the onerror handler.

$duration = $parser->parse_duration_string ($string)

Parse the argument as an HTML duration string [HTML] and return a Web::DateTime::Duration (or undef if failed). Any error is reported through the onerror handler.

$duration = $parser->parse_vevent_duration_string ($string)

Parse the argument as an HTML vevent duration string [HTML] and return a Web::DateTime::Duration (or undef if failed). Any error is reported through the onerror handler.

$duration = $parser->parse_xs_duration_string ($string)

Parse the argument as an XML Schema xs:duration string [XSDT] and return a Web::DateTime::Duration (or undef if failed). Any error is reported through the onerror handler.

$duration = $parser->parse_xs_day_time_duration_string ($string)

Parse the argument as an XML Schema xs:dayTimeDuration string [XSDT] and return a Web::DateTime::Duration (or undef if failed). Any error is reported through the onerror handler.

$duration = $parser->parse_xs_year_month_duration_string ($string)

Parse the argument as an XML Schema xs:yearMonthDuration string [XSDT] and return a Web::DateTime::Duration (or undef if failed). Any error is reported through the onerror handler.

$duration = $parser->parse_iso8601_duration_string ($string)

Parse the argument as an ISO 8601:2004 duration string [ISO8601] and return a Web::DateTime::Duration (or undef if failed). Any error is reported through the onerror handler.

Strictly speaking, ISO 8601 has different semantics for durations from those of Web::DateTime::Duration. The method returns a duration object which consist of numbers of months and seconds by assuming that P1Y is equal to P12M; P1W is equal to P7D, P1D is equal to PT24H, PT1H is equal to PT60M, and PT1M is equal to PT60S; and a duration in alternative format equals to number of seconds represented by it.

This method is suitable for microdata http://schema.org/Duration item values and date item values in data-vocabulary.org microdata vocabulary.

$obj = $parser->parse_date_string_with_optional_time_and_duration ($string)

Parse the argument as either a valid date string, a valid global date and time string, a pair of two valid global date and time strings, or a pair of a valid global date and time string and a valid vevent duration string, and return a Web::DateTime or Web::DateTime::Interval (or undef if failed). Any error is reported through the onerror handler. This method can be used to parse the value of the vEvent microdata's rdate item value [HTML].

$wr = $parser->parse_weekly_time_range_string ($string)

Parse the argument as a weekly time range string [SCHEMAORG] and return a Web::DateTime::WeeklyTimeRange (or undef if failed). Any error is reported through the onerror handler.

DEPENDENCY

The module requires Perl 5.8 or later.

SPECIFICATIONS

HTML

HTML Standard <https://www.whatwg.org/specs/web-apps/current-work/>.

XSDT

W3C XML Schema Definition Language (XSD) 1.1 Part 2: Datatypes <https://www.w3.org/TR/xmlschema11-2/>.

RFC3339

Date and Time on the Internet: Timestamps <https://tools.ietf.org/html/rfc3339>.

SCHEMAORG

Schema.org <http://schema.org/>.

OGP

The Open Graph protocol <http://ogp.me/>.

ISO8601

ISO 8601:2004, Data elements and interchange formats -- Information interchange -- Representation of dates and times.

HTTP

RFC 1945, Hypertext Transfer Protocol -- HTTP/1.0 <https://tools.ietf.org/html/rfc1945>.

RFC 7231, Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content <https://tools.ietf.org/html/rfc7231>.

COOKIES

RFC 6265, HTTP State Management Mechanism <https://tools.ietf.org/html/rfc6265>.

W3CDTF

Date and Time Formats <https://www.w3.org/TR/1998/NOTE-datetime-19980827>.

RFC822

RFC 822, STANDARD FOR THE FORMAT OF ARPA INTERNET TEXT MESSAGES <https://tools.ietf.org/html/rfc822>.

RSS2

RSS 2.0 Specification <http://www.rssboard.org/rss-specification>.

RSS2BP

Really Simple Syndication Best Practices Profile <http://www.rssboard.org/rss-profile>.

JS

ECMA-262 6th Edition Draft ECMAScript Language Specification <https://people.mozilla.org/~jorendorff/es6-draft.html>.

JavaScript and Dates, What a Mess! <http://blog.dygraphs.com/2012/03/javascript-and-dates-what-mess.html>, <http://dygraphs.com/date-formats.html>.

DATETIME

Dates and times <https://manakai.github.io/spec-datetime/>.

AUTHOR

Wakaba <wakaba@suikawiki.org>.

LICENSE

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

The manakai project

Web::DateTime::Parser