/ 
DateTimeX-Easy-0.060
River stage two • 12 direct dependents • 59 total dependents
/ DateTimeX::Easy

NAME

DateTimeX::Easy - Use DT::F::Flexible and DT::F::Natural for quick and easy DateTime creation

VERSION

Version 0.060

SYNOPSIS

# Make DateTimeX object for "now":
my $dt = DateTimeX::Easy->new("today");

# Same thing:
my $dt = DateTimeX::Easy->new("now");

# Uses ::F::Natural's coolness (similar in capability to Date::Manip)
my $dt = DateTimeX::Easy->new("last monday");

# ... but in 1969:
my $dt = DateTimeX::Easy->new("last monday", year => 1969);

# ... at the 100th nanosecond:
my $dt = DateTimeX::Easy->new("last monday", year => 1969, nanosecond => 100);

# ... in US/Eastern: (This will NOT do a timezone conversion)
my $dt = DateTimeX::Easy->new("last monday", year => 1969, nanosecond => 100, timezone => "US/Eastern");

# This WILL do a proper timezone conversion:
my $dt = DateTimeX::Easy->new("last monday", year => 1969, nanosecond => 100, timezone => "US/Pacific");
$dt->set_time_zone("US/Eastern");

DESCRIPTION

DateTimeX::Easy makes DateTime object creation quick and easy. It uses DateTime::Format::Flexible and DateTime::Format::Natural to do the bulk of the parsing, with some custom tweaks to smooth out the rough edges (mainly concerning timezone detection).

METHODS

DateTimeX::Easy->new( ... )

DateTimeX::Easy->parse( ... )

DateTimeX::Easy->parse_date( ... )

DateTimeX::Easy->parse_datetime( ... )

DateTimeX::Easy->date( ... )

DateTimeX::Easy->datetime( ... )

DateTimeX::Easy->new_date( ... )

DateTimeX::Easy->new_datetime( ... )

Parse the given date/time specification using ::F::Flexible or ::F::Natural and use the result to create a DateTime object. Returns a DateTime object.

You can pass the following in:

parse       # The string or DateTime object to parse.
year        # A year to override the result of parsing
month       # A month to override the result of parsing
day         # A day to override the result of parsing
hour        # A hour to override the result of parsing
minute      # A minute to override the result of parsing
second      # A second to override the result of parsing
truncate    # A truncation parameter (e.g. year, day, month, week, etc.)

time_zone   # - Can be:
            # * A timezone (e.g. US/Pacific, UTC, etc.)
            # * A DateTime special timezone (e.g. floating, local)
            # * A question mark ('?'), which means to use the timezone parsed from the end of the string, e.g. "... GMT" or "... US/Eastern"
            #
            # - If neither "timezone" nor "time_zone" is set, then we'll default to using "?", and then "floating"
            # - If a DateTime object was passed in, then the object's timezone will be used unless overridden.
            # - Either "time_zone" or "timezone" will work, but "time_zone" has precedence
            # - WARNING: No timezone conversion takes place (unless "convert => 1" is set), the timezone is essentially appended to the datetime given.
            # - See below for examples!

convert     # Set this flag to 1 if you want to actually perform the conversion be between the parsed timezone and the given timezone
            # Optionally, set it to the timezone you want to convert to. In this case, "time_zone" is the original "old" timezone
            # and "convert" is the "new" timezone. Furthermore, in this case, "time_zone" will become "local" if it's "floating".

... and anything else that you want to pass to the DateTime->new constructor

If truncate is specificied, then DateTime->truncate will be run after object creation.

Furthermore, you can simply pass the value for "parse" as the first positional argument of the DateTimeX::Easy call, e.g.:

# This:
DateTimeX::Easy->new("today", year => 2008, truncate => "hour");

# ... is the same as this:
DateTimeX::Easy->new(parse => "today", year => 2008, truncate => "hour");

Timezone processing can be a little complicated. Here are some examples:

DateTimeX::Easy->parse("today"); # Will use a floating timezone

DateTimeX::Easy->parse("2007-07-01 10:32:10"); # Will ALSO use a floating timezone

DateTimeX::Easy->parse("2007-07-01 10:32:10 US/Eastern"); # Will use US/Eastern as a timezone

DateTimeX::Easy->parse("2007-07-01 10:32:10 US/Eastern", time_zone => "?"); # Will again use US/Eastern as the timezone

DateTimeX::Easy->parse("2007-07-01 10:32:10", time_zone => "?"); # Will use the floating timezone

DateTimeX::Easy->parse("2007-07-01 10:32:10 UTC", convert => "US/Pacific"); # Will convert from UTC to US/Pacific

DateTimeX::Easy->parse("2007-07-01 10:32:10", convert => "US/Pacific"); # Will convert from the local timezone to US/Pacific

my $dt = DateTime->now->set_time_zone("US/Eastern");
DateTimeX::Easy->parse($dt); # Will use US/Eastern as the timezone

DateTimeX::Easy->parse($dt, time_zone => "floating"); # Will use a floating timezone

DateTimeX::Easy->parse($dt, time_zone => "US/Pacific"); # Will use US/Pacific as the timezone with NO conversion
                                                        # For example, "22:00 US/Eastern" will become "22:00 PST8PDT" 

DateTimeX::Easy->parse($dt)->set_time_zone("US/Pacific"); # Will use US/Pacific as the timezone WITH conversion
                                                          # For example, "22:00 US/Eastern" will become "19:00 PST8PDT" 

DateTimeX::Easy->parse($dt, time_zone => "US/Pacific", convert => 1); # Will ALSO use US/Pacific as the timezone WITH conversion

DateTimeX::Easy->parse($dt, time_zone => "US/Pacific", convert => "UTC"); # Will convert FROM US/Pacific TO UTC

EXPORT

parse( ... )

parse_date( ... )

parse_datetime( ... )

date( ... )

datetime( ... )

new_date( ... )

new_datetime( ... )

Same syntax as above. See above for more information.

MOTIVATION

Although I really like using DateTimeX for date/time handling, I was often frustrated by its inability to parse even the simplest of date/time strings. There does exist a wide variety of DateTimeX::Format::* modules, but they all have different interfaces and different capabilities. Coming from a Date::Manip background, I wanted something that gave me the power of ParseDate while still returning a DateTimeX object. Most importantly, I wanted explicit control of the timezone setting at every step of the way. DateTimeX::Easy is the result.

SEE ALSO

DateTime, DateTime::Format::Natural, DateTime::Format::Flexible, Date::Manip

AUTHOR

Robert Krimen, <rkrimen at cpan.org>

BUGS

Please report any bugs or feature requests to bug-datetime-easy at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=DateTimeX-Easy. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc DateTimeX::Easy

You can also look for information at:

ACKNOWLEDGEMENTS

COPYRIGHT & LICENSE

Copyright 2007 Robert Krimen, all rights reserved.

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