[Bps-public-commit] r9688 - in Date-Extract: lib/Date
sartak at bestpractical.com
sartak at bestpractical.com
Thu Nov 15 21:59:31 EST 2007
Author: sartak
Date: Thu Nov 15 21:59:30 2007
New Revision: 9688
Modified:
Date-Extract/ (props changed)
Date-Extract/README
Date-Extract/lib/Date/Extract.pm
Log:
r45250 at onn: sartak | 2007-11-15 21:58:52 -0500
Doc fixes
Modified: Date-Extract/README
==============================================================================
--- Date-Extract/README (original)
+++ Date-Extract/README Thu Nov 15 21:59:30 2007
@@ -1,30 +1,144 @@
-Date::Extract - simple date extraction
+NAME
+ Date::Extract - extract probable dates from strings
-There are already a few modules for getting a date out of a string.
-DateTime::Format::Natural should be your first choice. There's also
-Time::ParseDate which fits some very specific formats. Finally, you can
-coerce Date::Manip to do your bidding.
+VERSION
+ Version 0.00 released ???
-But I needed something that will take an arbitrary block of text, search it
-for something that looks like a date string, and build a DateTime object
-out of 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.
+SYNOPSIS
+ my $parser = Date::Extract->new();
+ my $dt = $parser->extract($arbitrary_text)
+ or die "No date found.";
+ return $dt->ymd;
-INSTALLATION
+MOTIVATION
+ There are already a few modules for getting a date out of a string.
+ DateTime::Format::Natural should be your first choice. There's also
+ Time::ParseDate which fits some very specific formats. Finally, you can
+ coerce Date::Manip to do your bidding.
- perl Makefile.PL
- make
- make test
- make install
+ But I needed something that will take an arbitrary block of text, search
+ it for something that looks like a date string, and build a DateTime
+ object out of 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 DateTime object with the year
+ set to 2019.
-MAJOR CHANGES
+METHODS
+ new PARAMHASH => "Date::Extract"
+ arguments
+ time_zone
+ Forces a particular time zone to be set (this actually matters, as
+ "Tuesday" on Monday at 11 PM means something different than
+ "Tuesday" on Tuesday at 1 AM).
-0.00: none yet!
+ By default it will use the "floating" time zone. See the
+ documentation for DateTime.
-COPYRIGHT AND LICENCE
+ This controls both the input time zone and output time zone.
-Copyright (C) 2007 Best Practical Solutions
+ 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:
+
+ nearest
+ Prefer the nearest date. This is the default.
+
+ future
+ Prefer the closest future date.
+
+ past
+ Prefer the closest past date.
+
+ returns
+ If the text has multiple possible dates, then this argument
+ determines which date will be returned. By default it's 'first'.
+
+ first
+ Returns the first date found in the string.
+
+ last
+ Returns the final date found in the string.
+
+ earliest
+ Returns the date found in the string that chronologically
+ precedes any other date in the string.
+
+ latest
+ Returns the date found in the string that chronologically
+ follows any other date in the string.
+
+ all Returns all dates found in the string, in the order they were
+ found in the strong.
+
+ all_cron
+ Returns all dates found in the string, in chronological order.
+
+ This method will combine the arguments of parser->new and extract.
+ Modify the "to" hash directly.
+
+ extract text => "DateTime", ARGS
+ Takes an arbitrary amount of text and extracts one or more dates
+ from it. The return value will be zero or more "DateTime" objects.
+ If called in scalar context, the first will be returned, even if the
+ "returns" argument specifies multiple possible return values.
+
+ See the documentation of "new" for the configuration of this method.
+ Any arguments passed into this method will trump those from the
+ parser.
+
+ You may reuse a parser for multiple calls to "extract".
+
+ You do not need to have an instantiated "Date::Extract" object to
+ call this method. Just "Date::Extract->extract($foo)" will work.
+
+CAVEATS
+ This module is *intentionally* very simple. Surprises are *not*
+ welcome here.
+
+SEE ALSO
+ DateTime::Format::Natural, Time::ParseDate, Date::Manip
+
+AUTHOR
+ Shawn M Moore, "<sartak at gmail.com>"
+
+BUGS
+ No known bugs at this point.
+
+ Please report any bugs or feature requests to "bug-date-extract at
+ rt.cpan.org", or through the web interface at
+ <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Date-Extract>. I
+ will be notified, and then you'll automatically be notified of
+ progress on your bug as I make changes.
+
+SUPPORT
+ You can find documentation for this module with the perldoc command.
+
+ perldoc Date::Extract
+
+ You can also look for information at:
+
+ * AnnoCPAN: Annotated CPAN documentation
+ <http://annocpan.org/dist/Date-Extract>
+
+ * CPAN Ratings
+ <http://cpanratings.perl.org/d/Date-Extract>
+
+ * RT: CPAN's request tracker
+ <http://rt.cpan.org/NoAuth/Bugs.html?Dist=Date-Extract>
+
+ * Search CPAN
+ <http://search.cpan.org/dist/Date-Extract>
+
+ACKNOWLEDGEMENTS
+ Thanks to Steven Schubiger for writing the fine
+ DateTime::Format::Natural. We still use it, but it doesn't quite
+ fill all the particular needs we have.
+
+COPYRIGHT & LICENSE
+ Copyright 2007 Best Practical Solutions.
+
+ This program is free software; you can redistribute it and/or modify
+ it under the same terms as Perl itself.
-This program is free software; you can redistribute it and/or modify it
-under the same terms as Perl itself.
Modified: Date-Extract/lib/Date/Extract.pm
==============================================================================
--- Date-Extract/lib/Date/Extract.pm (original)
+++ Date-Extract/lib/Date/Extract.pm Thu Nov 15 21:59:30 2007
@@ -14,7 +14,7 @@
=head1 NAME
-Date::Extract - simple date extraction
+Date::Extract - extract probable dates from strings
=head1 VERSION
@@ -42,7 +42,8 @@
for something that looks like a date string, and build a L<DateTime> object
out of 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.
+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.
=head1 METHODS
@@ -138,13 +139,13 @@
&& $args{returns} ne 'latest'
&& $args{returns} ne 'all'
&& $args{returns} ne 'all_cron') {
- _croak "Invalid `returns` passed to constructor: expected 'first', 'last', earliest', 'latest', 'all', or 'all_cron'.";
+ _croak "Invalid `returns` passed to constructor: expected `first', `last', `earliest', `latest', `all', or `all_cron'.";
}
if ($args{prefers} ne 'nearest'
&& $args{prefers} ne 'past'
&& $args{prefers} ne 'future') {
- _croak "Invalid `prefers` passed to constructor: expected 'first', 'last', earliest', 'latest', 'all', or 'all_cron'.";
+ _croak "Invalid `prefers` passed to constructor: expected `nearest', `past', or `future'.";
}
my $self = bless \%args, ref($class) || $class;
More information about the Bps-public-commit
mailing list