NAME
DateTime::Format::Alami - Parse human date/time expression (base class)
VERSION
This document describes version 0.07 of DateTime::Format::Alami (from Perl distribution DateTime-Format-Alami), released on 2016-04-13.
SYNOPSIS
Use English:
use DateTime::Format::Alami::EN;
my $parser = DateTime::Format::Alami::EN->new();
my $dt;
$dt = $parser->parse_datetime("2 hours 13 minutes from now");
$dt = $parser->parse_datetime("yesterday");
use Indonesian:
use DateTime::Format::Alami::ID;
my $parser = DateTime::Format::Alami::ID->new();
my $dt;
$dt = $parser->parse_datetime("5 jam lagi");
$dt = $parser->parse_datetime("hari ini");
DESCRIPTION
EARLY RELEASE: PROOF OF CONCEPT ONLY AND VERY VERY INCOMPLETE.
This class parses human/natural date/time string and returns DateTime object. Currently it supports English and Indonesian. The goal of this module is to make it easier to add support for other human languages.
It works by matching date string with a bunch of regex patterns (assembled from p_*
methods, e.g. p_today
, p_dur_ago
, p_dur_later
, and so on). If a pattern is found, the corresponding a_*
method is called to compute the DateTime object (e.g. if p_today
pattern matches, a_today
is called).
To actually use this class, you must use one of its subclasses for each human language that you want to parse.
There are already some other DateTime human language parsers on CPAN and elsewhere, see "SEE ALSO".
ADDING A NEW HUMAN LANGUAGE
TBD
METHODS
new => obj
Constructor. You actually must instantiate subclass instead.
parse_datetime($str[ , \%opts ]) => obj
Parse/extract date/time expression in $str
. Return undef if expression cannot be parsed. Otherwise return DateTime object (or string/number if format
option is verbatim
/epoch
, or hash if format
option is combined
) or array of objects/strings/numbers (if returns
option is all
/all_cron
).
Known options:
time_zone => str
Will be passed to DateTime constructor.
format => str (DateTime|verbatim|epoch|combined)
The default is
DateTime
, which will return DateTime object. Other choices includeverbatim
(returns the original text),epoch
(returns Unix timestamp),combined
(returns a hash containing keys likeDateTime
,verbatim
,epoch
, and other extra information:pos
[position of pattern in the string],pattern
[pattern name],m
[raw named capture groups],uses_time
[whether the date involves time of day]).You might think that choosing
epoch
could avoid the overhead of DateTime, but actually you can't since DateTime is used as the primary format during parsing. The epoch is retrieved from the DateTime object using theepoch
method.But if you choose
verbatim
, you can avoid the overhead of DateTime (as long as you setreturns
tofirst
,last
, orall
).prefers => str (nearest|future|past)
NOT YET IMPLEMENTED.
This option decides what happens when an ambiguous date appears in the input. For example, "Friday" may refer to any number of Fridays. Possible choices are:
nearest
(prefer the nearest date, the default),future
(prefer the closest future date),past
(prefer the closest past date).returns => str (first|last|earliest|latest|all|all_cron)
If the text has multiple possible dates, then this argument determines which date will be returned. Possible choices are:
first
(return the first date found in the string, the default),last
(return the final date found in the string),earliest
(return the date found in the string that chronologically precedes any other date in the string),latest
(return the date found in the string that chronologically follows any other date in the string),all
(return all dates found in the string, in the order they were found in the string),all_cron
(return all dates found in the string, in chronological order).When
all
orall_cron
is chosen, function will return array(ref) of results instead of a single result, even if there is only a single actual result.
FAQ
What does "alami" mean?
It is an Indonesian word, meaning "natural".
HOMEPAGE
Please visit the project's homepage at https://metacpan.org/release/DateTime-Format-Alami.
SOURCE
Source repository is at https://github.com/perlancar/perl-DateTime-Format-Alami.
BUGS
Please report any bugs or feature requests on the bugtracker website https://rt.cpan.org/Public/Dist/Display.html?Name=DateTime-Format-Alami
When submitting a bug or request, please include a test-file or a patch to an existing test-file that illustrates the bug or desired feature.
SEE ALSO
Similar modules on CPAN
Date::Extract. DateTime::Format::Alami has some features of Date::Extract so it can be used to replace Date::Extract.
For Indonesian: DateTime::Format::Indonesian, Date::Extract::ID (currently this module uses DateTime::Format::Alami as its backend).
For English: DateTime::Format::Natural. You probably want to use this instead, unless you want something other than English. I did try to create an Indonesian translation for this module a few years ago, but gave up. Perhaps I should make another attempt.
Other modules on CPAN
DateTime::Format::Human deals with formatting and not parsing.
Similar non-Perl libraries
Natt Java library, which the last time I tried sometimes gives weird answer, e.g. "32 Oct" becomes 1 Oct in the far future. http://natty.joestelmach.com/
Duckling Clojure library, which can parse date/time as well as numbers with some other units like temperature. https://github.com/wit-ai/duckling
AUTHOR
perlancar <perlancar@cpan.org>
COPYRIGHT AND LICENSE
This software is copyright (c) 2016 by perlancar@cpan.org.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.