NAME

DateTimeX::Web - DateTime factory for web apps

SYNOPSIS

  use DateTimeX::Web

  # create a factory.
  my $dtx = DateTimeX::Web->new(time_zone => 'Asia/Tokyo');

  # then, grab a DateTime object from there.
  my $obj = $dtx->now;

  # with arguments for a DateTime constructor.
  my $obj = $dtx->from(year => 2008, month => 2, day => 9);

  # or with epoch (you don't need 'epoch =>' as it's obvious).
  my $obj = $dtx->from_epoch(time);

  # or with a WWWC datetime format string.
  my $obj = $dtx->from_rss('2008-02-09T01:00:02');

  # actually you can use any Format plugins.
  my $obj = $dtx->parse_as(MySQL => '2008-02-09 01:00:02');

  # of course you may need to parse with strptime.
  my $obj = $dtx->parse('%Y-%m-%d', $string);

  # you may want to create a datetime string for HTTP headers.
  my $str = $dtx->for_http;

  # or for emails (you can pass an arbitrary DateTime object).
  my $str = $dtx->for_mail($dt);

  # or for database (with arguments for a DateTime constructor).
  my $str = $dtx->for_mysql(year => 2007, month => 3, day => 3);

  # actually you can use any Format plugins.
  my $str = $dtx->render_as(MySQL => $dt);

  # you want finer control?
  my $str = $dtx->format('mysql')->format_date($dt);

DESCRIPTION

The DateTime framework is quite useful and complete. However, sometimes it's a bit too strict and cumbersome. Also, we usually need to load too many common DateTime components when we build a web application. That's not DRY.

So, here's a factory to make it sweet. If you want more chocolate or cream, help yourself. The DateTime framework boasts a variety of flavors.

METHODS

new

creates a factory object. If you pass a hash, or a hash reference, it will be passed to a DateTime constructor. You usually want to provide a sane "time_zone" option.

Optionally, you can pass an "on_error" option ("ignore"/"croak"/some code reference) to the constructor. DateTimeX::Web croaks by default when DateTime spits an error. If "ignore" is set, DateTimeX::Web would ignore the error and return undef. If you want finer control, provide a code reference.

format

takes a formatter's base name and returns the corresponding DateTime::Format:: object. You can pass an optional formatter package name/object to replace the previous formatter (or to add a new one).

time_zone, locale

returns the current time zone/locale object of the factory, which would be passed to every DateTime object it creates. You can pass an optional time zone/locale string/object to replace.

METHODS TO GET A DATETIME OBJECT

now, today, from_epoch, from_object, from_day_of_year, last_day_of_month

returns a DateTime object as you expect.

from

takes arguments for a DateTime constructor and returns a DateTime object. Also, You can pass (epoch => time) pair for convenience.

from_rss, from_wwwc

takes a W3CDTF (ISO 8601) datetime string used by RSS 1.0 etc, and returns a DateTime object.

from_mail, from_rss20

takes a RFC2822 compliant datetime string used by email, and returns a DateTime object.

from_mysql

takes a MySQL datetime string, and returns a DateTime object.

from_http

takes a HTTP datetime string, and returns a DateTime object.

parse_as

takes a name of DateTime::Format plugin and some arguments for it, and returns a DateTime object.

parse, strptime

takes a strptime format string and a datetime string, and returns a DateTime object.

METHODS TO GET A DATETIME STRING

for_rss, for_wwwc

may or may not take a DateTime object (or arguments for a DateTime constructor), and returns a W3CDTF datetime string.

for_mail, for_rss20

the same as above but returns a RFC2822 datetime string.

for_mysql

the same as above but returns a MySQL datetime string.

for_http

the same as above but returns a HTTP datetime string.

render_as

takes a name of DateTime::Format plugin and the same thing(s) as above, and returns a formatted string.

SEE ALSO

DateTime, DateTime::Format::Mail, DateTime::Format::MySQL, DateTime::Format::W3CDFT, DateTime::Format::HTTP, DateTime::Format::Strptime, DateTime::TimeZone, DateTime::Locale

AUTHOR

Kenichi Ishigaki, <ishigaki@cpan.org>

COPYRIGHT AND LICENSE

Copyright (C) 2008 by Kenichi Ishigaki.

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

cpanm DateTimeX::Web

perl -MCPAN -e shell
install DateTimeX::Web