.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43) .\" .\" 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 .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "DateTime::Format::Natural 3pm" .TH DateTime::Format::Natural 3pm "2023-10-26" "perl v5.36.0" "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" DateTime::Format::Natural \- Parse informal natural language date/time strings .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& use DateTime::Format::Natural; \& \& $parser = DateTime::Format::Natural\->new; \& \& $dt = $parser\->parse_datetime($date_string); \& @dt = $parser\->parse_datetime_duration($date_string); \& \& $date_string = $parser\->extract_datetime($extract_string); \& @date_strings = $parser\->extract_datetime($extract_string); \& \& if ($parser\->success) { \& # operate on $dt/@dt, for example: \& print $dt\->strftime(\*(Aq%d.%m.%Y %H:%M:%S\*(Aq), "\en"; \& } else { \& warn $parser\->error; \& } \& \& @traces = $parser\->trace; \& \& # examples \& \& 12:14 PM \& next tuesday at 2am \& tomorrow morning \& 4pm yesterday \& 10 weeks ago \& \& 1st tuesday last november \& 2nd friday in august \& final thursday in april \& \& for 3 hours \& monday to friday \& 1 April 10 am to 1 May 8am \& \& jan 24, 2011 12:00 .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" \&\f(CW\*(C`DateTime::Format::Natural\*(C'\fR parses informal natural language date/time strings. In addition, parsable date/time substrings may be extracted from ordinary strings. .SH "CONSTRUCTOR" .IX Header "CONSTRUCTOR" .SS "new" .IX Subsection "new" Creates a new \f(CW\*(C`DateTime::Format::Natural\*(C'\fR object. Arguments to \f(CW\*(C`new()\*(C'\fR are options and not necessarily required. .PP .Vb 12 \& $parser = DateTime::Format::Natural\->new( \& datetime => DateTime\->new(...), \& lang => \*(Aqen\*(Aq, \& format => \*(Aqmm/dd/yy\*(Aq, \& prefer_future => [0|1], \& demand_future => [0|1], \& time_zone => \*(Aqfloating\*(Aq, \& daytime => { morning => 06, \& afternoon => 13, \& evening => 20, \& }, \& ); .Ve .IP "\(bu" 4 \&\f(CW\*(C`datetime\*(C'\fR .Sp Overrides the present now with a DateTime object provided. .IP "\(bu" 4 \&\f(CW\*(C`lang\*(C'\fR .Sp Contains the language selected, currently limited to \f(CW\*(C`en\*(C'\fR (english). Defaults to '\f(CW\*(C`en\*(C'\fR'. .IP "\(bu" 4 \&\f(CW\*(C`format\*(C'\fR .Sp Specifies the format of numeric dates. .Sp The format is used to influence how numeric dates are parsed. Given two numbers separated by a slash, the month/day order expected comes from this option. If there is a third number, this option describes where to expect the year. When this format can't be used to interpret the date, some unambiguous dates may be parsed, but there is no form guarantee. .Sp Current supported \*(L"month/day\*(R" formats: \f(CW\*(C`dd/mm\*(C'\fR, \f(CW\*(C`mm/dd\*(C'\fR. .Sp Current supported \*(L"year/month/day\*(R" formats (with slashes): \f(CW\*(C`dd/mm/yy\*(C'\fR, \&\f(CW\*(C`dd/mm/yyyy\*(C'\fR, \f(CW\*(C`mm/dd/yyyy\*(C'\fR, \f(CW\*(C`yyyy/mm/dd\*(C'\fR. .Sp Note that all of the above formats with three units do also parse with dots or dashes as format separators. .Sp Furthermore, formats can be abbreviated as long as they remain unambiguous. .Sp Defaults to '\f(CW\*(C`d/m/y\*(C'\fR'. .IP "\(bu" 4 \&\f(CW\*(C`prefer_future\*(C'\fR .Sp Prefers future time and dates. Accepts a boolean, defaults to false. .IP "\(bu" 4 \&\f(CW\*(C`demand_future\*(C'\fR .Sp Demands future time and dates. Similar to \f(CW\*(C`prefer_future\*(C'\fR, but stronger. Accepts a boolean, defaults to false. .IP "\(bu" 4 \&\f(CW\*(C`time_zone\*(C'\fR .Sp The time zone to use when parsing and for output. Accepts any time zone recognized by DateTime. Defaults to 'floating'. .IP "\(bu" 4 \&\f(CW\*(C`daytime\*(C'\fR .Sp A hash reference consisting of customized daytime hours, which may be selectively changed. .SH "METHODS" .IX Header "METHODS" .SS "parse_datetime" .IX Subsection "parse_datetime" Returns a DateTime object constructed from a natural language date/time string. .PP .Vb 2 \& $dt = $parser\->parse_datetime($date_string); \& $dt = $parser\->parse_datetime(string => $date_string); .Ve .IP "\(bu" 4 \&\f(CW\*(C`string\*(C'\fR .Sp The date string. .SS "parse_datetime_duration" .IX Subsection "parse_datetime_duration" Returns one or two DateTime objects constructed from a natural language date/time string which may contain timespans/durations. \fISame\fR interface and options as \f(CW\*(C`parse_datetime()\*(C'\fR, but should be explicitly called in list context. .PP .Vb 2 \& @dt = $parser\->parse_datetime_duration($date_string); \& @dt = $parser\->parse_datetime_duration(string => $date_string); .Ve .SS "extract_datetime" .IX Subsection "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 \f(CW\*(C`parse_datetime()\*(C'\fR/ \&\f(CW\*(C`parse_datetime_duration()\*(C'\fR methods. .PP .Vb 5 \& $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); .Ve .SS "success" .IX Subsection "success" Returns a boolean indicating success or failure for parsing the date/time string given. .SS "error" .IX Subsection "error" Returns the error message if the parsing did not succeed. .SS "trace" .IX Subsection "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. .SH "GRAMMAR" .IX Header "GRAMMAR" The grammar handling has been rewritten to be easily extendable and hence everybody is encouraged to propose sensible new additions and/or changes. .PP See the class DateTime::Format::Natural::Lang::EN if you're intending to hack a bit on the grammar guts. .SH "EXAMPLES" .IX Header "EXAMPLES" See the class DateTime::Format::Natural::Lang::EN for an overview of currently valid input. .SH "BUGS & CAVEATS" .IX Header "BUGS & CAVEATS" \&\f(CW\*(C`parse_datetime()\*(C'\fR/\f(CW\*(C`parse_datetime_duration()\*(C'\fR 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 \*(L"current\*(R" now) is likely to be returned. It is therefore recommended to use \f(CW\*(C`success()\*(C'\fR to assert that the parse did succeed (at least, for common uses), otherwise the absence of a parse failure cannot be guaranteed. .PP \&\f(CW\*(C`parse_datetime()\*(C'\fR is not capable of handling durations. .SH "CREDITS" .IX Header "CREDITS" Thanks to Tatsuhiko Miyagawa for the initial inspiration. See Miyagawa's journal entry for more information. .PP Furthermore, thanks to (in order of appearance) who have contributed valuable suggestions and patches: .PP .Vb 10 \& Clayton L. Scott \& Dave Rolsky \& CPAN Author \*(AqSEKIMURA\*(Aq \& mike (pulsation) \& Mark Stosberg \& Tuomas Jormola \& Cory Watson \& Urs Stotz \& Shawn M. Moore \& Andreas J. Ko\*:nig \& 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 \& David Steinbrunner \& Debian Perl Group \& Tim Bunce \& Ricardo Signes \& Felix Ostmann \& Jo\*:rn Clausen \& Jim Avera \& Olaf Alders \& Karen Etheridge .Ve .SH "SEE ALSO" .IX Header "SEE ALSO" dateparse, DateTime, Date::Calc, .SH "AUTHOR" .IX Header "AUTHOR" Steven Schubiger .SH "LICENSE" .IX Header "LICENSE" This program is free software; you may redistribute it and/or modify it under the same terms as Perl itself. .PP See