.\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .if !\nF .nr F 0 .if \nF>0 \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} .\} .\" ======================================================================== .\" .IX Title "DateTimeX::Easy 3pm" .TH DateTimeX::Easy 3pm "2018-02-18" "perl v5.26.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" DateTimeX::Easy \- Parse a date/time string using the best method available .SH "VERSION" .IX Header "VERSION" version 0.089 .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 2 \& # Make DateTimeX object for "now": \& my $dt = DateTimeX::Easy\->new("today"); \& \& # Same thing: \& my $dt = DateTimeX::Easy\->new("now"); \& \& # Uses ::F::Natural\*(Aqs 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"); \& \& # Custom DateTimeX ability: \& my $dt = DateTimeX::Easy\->new("last second of last month"); \& $dt = DateTimeX::Easy\->new("last second of first month of last year"); \& $dt = DateTimeX::Easy\->new("last second of first month of 2000"); .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" DateTimeX::Easy makes DateTime object creation quick and easy. It uses a variety of DateTime::Format packages to do the bulk of the parsing, with some custom tweaks to smooth out the rough edges (mainly concerning timezone detection and selection). .SH "PARSING" .IX Header "PARSING" Currently, DateTimeX::Easy will attempt to parse input in the following order: .IP "DateTime \- Is the input a DateTime object?" 4 .IX Item "DateTime - Is the input a DateTime object?" .PD 0 .IP "ICal \- Was DT::F::ICal able to parse the input?" 4 .IX Item "ICal - Was DT::F::ICal able to parse the input?" .IP "DateParse \- Was DT::F::DateParse able to parse the input?" 4 .IX Item "DateParse - Was DT::F::DateParse able to parse the input?" .PD A caveat, I actually use a modified version of DateParse in order to avoid DateParse's default timezone selection. .IP "Natural \- Was DT::F::Natural able to parse the input?" 4 .IX Item "Natural - Was DT::F::Natural able to parse the input?" Since this module barfs pretty loudly on strange input, we use a silent \f(CW$SIG\fR{_\|_WARN_\|_} to hide errors. .IP "Flexible \- Was DT::F::Flexible able to parse the input?" 4 .IX Item "Flexible - Was DT::F::Flexible able to parse the input?" This step also looks at the string to see if there is any timezone information at the end. .IP "DateManip \- Was DT::F::DateManip able to parse the input?" 4 .IX Item "DateManip - Was DT::F::DateManip able to parse the input?" DateManip isn't very nice with preserving the input timezone, but it's here as a last resort. .ie n .SH """last second of first month of year of 2005""" .el .SH "``last second of first month of year of 2005''" .IX Header "last second of first month of year of 2005" DateTimeX::Easy also provides additional parsing and transformation for input like: .PP .Vb 10 \& "first day of last month" \& "last day of last month" \& "last day of this month" \& "last day of next month" \& "last second of first month of last year" \& "ending day of month of 2007\-10\-02" \& "last second of first month of year of 2005" \& "last second of last month of year of 2005" \& "beginning day of month of 2007\-10\-02" \& "last month of year of 2007" .Ve .PP It will look at each sequence of \*(L" of \*(R" and do \->add, \->subtract, and \->truncate operations on the parsed DateTime object .PP Also, It's best to be as explicit as possible; the following will work: .PP .Vb 3 \& "last month of 2007" \& "last second of last month of 2005" \& "beginning day of 2007\-10\-02" .Ve .PP This won't, though: .PP .Vb 1 \& "last day of 2007" .Ve .PP You'll have to do this instead: .PP .Vb 1 \& "last day of year of 2007" .Ve .PP The reason is that the date portion is opaque to the parser. It doesn't know whether it has \*(L"2007\*(R" or \*(L"2007\-10\*(R" or \*(L"now\*(R" as the last input. To fix this, you can give a hint to the parser, like \*(L" of \*(R" (as in \*(L"year of 2007\*(R" above). .PP \&\s-1WARNING:\s0 This feature is still somewhat new, so there may be bugs lurking about. Please forward failing tests/scenarios. .SH "METHODS" .IX Header "METHODS" .SS "DateTimeX::Easy\->new( ... )" .IX Subsection "DateTimeX::Easy->new( ... )" .SS "DateTimeX::Easy\->parse( ... )" .IX Subsection "DateTimeX::Easy->parse( ... )" .SS "DateTimeX::Easy\->parse_date( ... )" .IX Subsection "DateTimeX::Easy->parse_date( ... )" .SS "DateTimeX::Easy\->parse_datetime( ... )" .IX Subsection "DateTimeX::Easy->parse_datetime( ... )" .SS "DateTimeX::Easy\->date( ... )" .IX Subsection "DateTimeX::Easy->date( ... )" .SS "DateTimeX::Easy\->datetime( ... )" .IX Subsection "DateTimeX::Easy->datetime( ... )" .SS "DateTimeX::Easy\->new_date( ... )" .IX Subsection "DateTimeX::Easy->new_date( ... )" .SS "DateTimeX::Easy\->new_datetime( ... )" .IX Subsection "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. .PP You can pass the following in: .PP .Vb 1 \& 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: \& timezone # * A timezone (e.g. US/Pacific, UTC, etc.) \& tz # * A DateTime special timezone (e.g. floating, local) \& # \& # \- If neither "tz", "timezone", nor "time_zone" is set, then it\*(Aqll use whatever is parsed. \& # \- If no timezone is parsed, then the default is floating. \& # \- If the given timezone is different from the parsed timezone, \& # then a time conversion will take place (unless "soft_time_zone_conversion" is set). \& # \- Either "time_zone", "timezone", "tz" will work (in that order), with "time_zone" having highest precedence \& # \- See below for examples! \& \& soft_time_zone_conversion # Set this flag to 1 if you don\*(Aqt want the time to change when a given timezone is \& # different from a parsed timezone. For example, "10:00 UTC" soft converted to \& # PST8PDT would be "10:00 PST8PDT". \& \& time_zone_if_floating # The value of this option should be a valid timezone. If this option is set, then a DateTime object \& # with a floating timezone has it\*(Aqs timezone set to the value. \& default_time_zone # Same as "time_zone_if_floating" \& \& ambiguous # Set this flag to 0 if you want to disallow ambiguous input like: \& # "last day of 2007" or "first minute of April" \& # This will require you to specify them as "last day of year of 2007" and "first minute of month of April" \& # instead. This flag is 1 (false) by default. \& \& ... and anything else that you want to pass to the DateTime\->new constructor .Ve .PP If \f(CW\*(C`truncate\*(C'\fR is specificied, then DateTime\->truncate will be run after object creation. .PP Furthermore, you can simply pass the value for \*(L"parse\*(R" as the first positional argument of the DateTimeX::Easy call, e.g.: .PP .Vb 2 \& # This: \& DateTimeX::Easy\->new("today", year => 2008, truncate => "hour"); \& \& # ... is the same as this: \& DateTimeX::Easy\->new(parse => "today", year => 2008, truncate => "hour"); .Ve .PP Timezone processing can be a little complicated. Here are some examples: .PP .Vb 1 \& 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"); # Will use the floating timezone \& \& DateTimeX::Easy\->parse("2007\-07\-01 10:32:10", time_zone_if_floating => "local"); # Will use the local timezone \& \& DateTimeX::Easy\->parse("2007\-07\-01 10:32:10 UTC", time_zone => "US/Pacific"); # Will convert from UTC 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", soft_time_zone_conversion => 1); \& # 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"); # Will ALSO use US/Pacific as the timezone WITH conversion .Ve .SH "EXPORT" .IX Header "EXPORT" .SS "parse( ... )" .IX Subsection "parse( ... )" .SS "parse_date( ... )" .IX Subsection "parse_date( ... )" .SS "parse_datetime( ... )" .IX Subsection "parse_datetime( ... )" .SS "date( ... )" .IX Subsection "date( ... )" .SS "datetime( ... )" .IX Subsection "datetime( ... )" .SS "new_date( ... )" .IX Subsection "new_date( ... )" .SS "new_datetime( ... )" .IX Subsection "new_datetime( ... )" Same syntax as above. See above for more information. .SH "MOTIVATION" .IX Header "MOTIVATION" Although I really like using DateTime 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 DateTime::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 DateTime object. Most importantly, I wanted explicit control of the timezone setting at every step of the way. DateTimeX::Easy is the result. .SH "THANKS" .IX Header "THANKS" Dave Rolsky and crew for writing DateTime .SH "SEE ALSO" .IX Header "SEE ALSO" DateTime .PP DateTime::Format::Natural .PP DateTime::Format::Flexible .PP DateTime::Format::ICal .PP DateTime::Format::DateManip .PP DateTime::Format::ParseDate .PP Date::Manip .SH "SOURCE" .IX Header "SOURCE" You can contribute or fork this project via GitHub: .PP .PP .Vb 1 \& git clone git://github.com/robertkrimen/datetimex\-easy.git DateTimeX\-Easy .Ve .SH "ACKNOWLEDGEMENTS" .IX Header "ACKNOWLEDGEMENTS" .SH "COPYRIGHT & LICENSE" .IX Header "COPYRIGHT & LICENSE" Copyright 2007 Robert Krimen, all rights reserved. .PP This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. .SH "AUTHOR" .IX Header "AUTHOR" .Vb 1 \& Robert Krimen .Ve .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" This software is copyright (c) 2010 by Robert Krimen. .PP This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.