[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