1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197
|
NAME
DateTime::Format::Natural - Create machine readable date/time with
natural parsing logic
SYNOPSIS
use DateTime::Format::Natural;
$parser = DateTime::Format::Natural->new;
$date_string = $parser->extract_datetime($extract_string);
@date_strings = $parser->extract_datetime($extract_string);
$dt = $parser->parse_datetime($date_string);
@dt = $parser->parse_datetime_duration($date_string);
if ($parser->success) {
# operate on $dt/@dt, for example:
printf("%02d.%02d.%4d %02d:%02d:%02d\n", $dt->day,
$dt->month,
$dt->year,
$dt->hour,
$dt->min,
$dt->sec);
} else {
warn $parser->error;
}
@traces = $parser->trace;
DESCRIPTION
`DateTime::Format::Natural' takes a string with a human readable
date/time and creates a machine readable one by applying natural parsing
logic.
CONSTRUCTOR
new
Creates a new `DateTime::Format::Natural' object. Arguments to `new()'
are options and not necessarily required.
$parser = DateTime::Format::Natural->new(
datetime => DateTime->new(...),
lang => 'en',
format => 'mm/dd/yy',
prefer_future => '[0|1]',
time_zone => 'floating',
daytime => { morning => 06,
afternoon => 13,
evening => 20,
},
);
* `datetime'
Overrides the present now with a DateTime object provided.
* `lang'
Contains the language selected, currently limited to `en' (english).
Defaults to '`en''.
* `format'
Specifies the format of numeric dates, defaults to '`d/m/y''.
* `prefer_future'
Turns ambiguous weekdays/months to their future relatives. Accepts a
boolean, defaults to false.
* `time_zone'
The time zone to use when parsing and for output. Accepts any time
zone recognized by DateTime. Defaults to 'floating'.
* `daytime'
An anonymous hash reference consisting of customized daytime hours,
which may be selectively changed.
METHODS
parse_datetime
Returns a DateTime object constructed from a human readable date/time
string.
$dt = $parser->parse_datetime($date_string);
$dt = $parser->parse_datetime(string => $date_string);
* `string'
The date string.
parse_datetime_duration
Returns one or two DateTime objects constructed from a human readable
date/time string which may contain timespans/durations. *Same* interface
and options as `parse_datetime()', but should be explicitly called in
list context.
@dt = $parser->parse_datetime_duration($date_string);
@dt = $parser->parse_datetime_duration(string => $date_string);
extract_datetime
Returns parsable date/time substrings (also known as expressions)
extracted from the string provided; in scalar context only the first
parsable substring is returned, whereas in list context all parsable
substrings are returned. Each extracted substring can then be passed to
the `parse_datetime()'/ `parse_datetime_duration()' methods.
$date_string = $parser->extract_datetime($extract_string);
@date_strings = $parser->extract_datetime($extract_string);
# or
$date_string = $parser->extract_datetime(string => $extract_string);
@date_strings = $parser->extract_datetime(string => $extract_string);
success
Returns a boolean indicating success or failure for parsing the
date/time string given.
error
Returns the error message if the parsing did not succeed.
trace
Returns one or two strings with the grammar keyword for the valid
expression parsed, traces of methods which were called within the Calc
class and a summary how often certain units have been modified. More
than one string is commonly returned for durations. Useful as a
debugging aid.
GRAMMAR
The grammar handling has been rewritten to be easily extendable and
hence everybody is encouraged to propose sensible new additions and/or
changes.
See the classes `DateTime::Format::Natural::Lang::[language_code]' if
you're intending to hack a bit on the grammar guts.
EXAMPLES
See the classes `DateTime::Format::Natural::Lang::[language_code]' for
an overview of currently valid input.
BUGS & CAVEATS
`parse_datetime()'/`parse_datetime_duration()' always return one or two
DateTime objects regardless whether the parse was successful or not. In
case no valid expression was found or a failure occurred, an unaltered
DateTime object with its initial values (most often the "current" now)
is likely to be returned. It is therefore recommended to use `success()'
to assert that the parse did succeed (at least, for common uses),
otherwise the absence of a parse failure cannot be guaranteed.
`parse_datetime()' is not capable of handling durations.
CREDITS
Thanks to Tatsuhiko Miyagawa for the initial inspiration. See Miyagawa's
journal entry http://use.perl.org/~miyagawa/journal/31378 for more
information.
Furthermore, thanks to (in order of appearance) who have contributed
valuable suggestions and patches:
Clayton L. Scott
Dave Rolsky
CPAN Author 'SEKIMURA'
mike (pulsation)
Mark Stosberg
Tuomas Jormola
Cory Watson
Urs Stotz
Shawn M. Moore
Andreas J. Knig
Chia-liang Kao
Jonny Schulz
Jesse Vincent
Jason May
Pat Kale
Ankur Gupta
Alex Bowley
Elliot Shank
Anirvan Chatterjee
Michael Reddick
Christian Brink
Giovanni Pensa
Andrew Sterling Hanenkamp
Eric Wilhelm
Kevin Field
Wes Morgan
Vladimir Marek
Rod Taylor
Tim Esselens
Colm Dougan
Chifung Fan
Xiao Yafeng
Roman Filippov
SEE ALSO
dateparse, DateTime, Date::Calc, http://datetime.perl.org
AUTHOR
Steven Schubiger <schubiger@cpan.org>
LICENSE
This program is free software; you may redistribute it and/or modify it
under the same terms as Perl itself.
See http://dev.perl.org/licenses/
|