view release on metacpan or  search on metacpan

lib/Date/Extract.pm  view on Meta::CPAN

    } elsif ($fmt eq 'combined') {
        return @combined;
    } else {
        return map {$_->{DateTime}} @combined;
    }
}

1;

__END__

=pod

=encoding UTF-8

=head1 NAME

Date::Extract

=head1 VERSION

version 0.05.01

=head1 SYNOPSIS

    my $parser = Date::Extract->new();
    my $dt = $parser->extract($arbitrary_text)
        or die "No date found.";
    return $dt->ymd;

=head1 NAME

Date::Extract - extract probable dates from strings

=head1 MOTIVATION

There are already a few modules for getting a date out of a string.
L<DateTime::Format::Natural> should be your first choice. There's also
L<Time::ParseDate> which fits many formats. Finally, you can coerce
L<Date::Manip> to do your bidding.

But I needed something that will take an arbitrary block of text, search it for
something that looks like a date string, and extract it. This module fills this
niche. By design it will produce few false positives. This means it will not
catch nearly everything that looks like a date string. So if you have the string
"do homework for class 2019" it won't return a L<DateTime> object with the year
set to 2019. This is what your users would probably expect.

=head1 METHODS

=head2 new PARAMHASH => C<Date::Extract>

=head3 arguments

=over 4

=item format

Choose what format the extracted date(s) will be. The default is "DateTime",
which will return L<DateTime> object(s). Other option include "verbatim" (return
the original text), "epoch" (return Unix timestamp), or "combined" (return
hashref containing these keys "verbatim", "DateTime", "pos" [position of date
string in the text]).

=item time_zone

Only relevant when C,format> is set to "DateTime".

Forces a particular time zone to be set (this actually matters, as "tomorrow"
on Monday at 11 PM means something different than "tomorrow" on Tuesday at 1
AM).

By default it will use the "floating" time zone. See the documentation for
L<DateTime>.

This controls both the input time zone and output time zone.

=item prefers

This argument decides what happens when an ambiguous date appears in the
input. For example, "Friday" may refer to any number of Fridays. The valid
options for this argument are:

=over 4

=item nearest

Prefer the nearest date. This is the default.

=item future

Prefer the closest future date.

=item past

Prefer the closest past date. B<NOT YET SUPPORTED>.

=back

=item returns

If the text has multiple possible dates, then this argument determines which
date will be returned. By default it's 'first'.

=over 4

=item first

Returns the first date found in the string.

=item last

Returns the final date found in the string.

=item earliest

Returns the date found in the string that chronologically precedes any other
date in the string.

=item latest