DateTime::Format::Natural(3pm)				User Contributed Perl Documentation			    DateTime::Format::Natural(3pm)

NAME

       DateTime::Format::Natural - Create machine readable date/time with natural parsing logic

SYNOPSIS

	use DateTime::Format::Natural;

	$parser = DateTime::Format::Natural->new;

	$date_string  = $parser->extract_datetime($extract_string);
	@date_strings = $parser->extract_datetime($extract_string);

	$dt = $parser->parse_datetime($date_string);
	@dt = $parser->parse_datetime_duration($date_string);

	if ($parser->success) {
	    # operate on $dt/@dt, for example:
	    printf("%02d.%02d.%4d %02d:%02d:%02d
", $dt->day,
						     $dt->month,
						     $dt->year,
						     $dt->hour,
						     $dt->min,
						     $dt->sec);
	} else {
	    warn $parser->error;
	}

	@traces = $parser->trace;

DESCRIPTION

       "DateTime::Format::Natural" takes a string with a human readable date/time and creates a machine readable one by applying natural parsing
       logic.

CONSTRUCTOR

   new
       Creates a new "DateTime::Format::Natural" object. Arguments to "new()" are options and not necessarily required.

	$parser = DateTime::Format::Natural->new(
		  datetime	=> DateTime->new(...),
		  lang		=> 'en',
		  format	=> 'mm/dd/yy',
		  prefer_future => '[0|1]',
		  time_zone	=> 'floating',
		  daytime	=> { morning   => 06,
				     afternoon => 13,
				     evening   => 20,
				   },
	);

       o   "datetime"

	   Overrides the present now with a DateTime object provided.

       o   "lang"

	   Contains the language selected, currently limited to "en" (english).  Defaults to '"en"'.

       o   "format"

	   Specifies the format of numeric dates, defaults to '"d/m/y"'.

       o   "prefer_future"

	   Turns ambiguous weekdays/months to their future relatives. Accepts a boolean, defaults to false.

       o   "time_zone"

	   The time zone to use when parsing and for output. Accepts any time zone recognized by DateTime. Defaults to 'floating'.

       o   "daytime"

	   An anonymous hash reference consisting of customized daytime hours, which may be selectively changed.

METHODS

   parse_datetime
       Returns a DateTime object constructed from a human readable date/time string.

	$dt = $parser->parse_datetime($date_string);
	$dt = $parser->parse_datetime(string => $date_string);

       o   "string"

	   The date string.

   parse_datetime_duration
       Returns one or two DateTime objects constructed from a human readable date/time string which may contain timespans/durations. Same
       interface and options as "parse_datetime()", but should be explicitly called in list context.

	@dt = $parser->parse_datetime_duration($date_string);
	@dt = $parser->parse_datetime_duration(string => $date_string);

   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 "parse_datetime()"/ "parse_datetime_duration()" methods.

	$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);

   success
       Returns a boolean indicating success or failure for parsing the date/time string given.

   error
       Returns the error message if the parsing did not succeed.

   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.

GRAMMAR

       The grammar handling has been rewritten to be easily extendable and hence everybody is encouraged to propose sensible new additions and/or
       changes.

       See the classes "DateTime::Format::Natural::Lang::[language_code]" if you're intending to hack a bit on the grammar guts.

EXAMPLES

       See the classes "DateTime::Format::Natural::Lang::[language_code]" for an overview of currently valid input.

BUGS &; CAVEATS
       "parse_datetime()"/"parse_datetime_duration()" 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
       "current" now) is likely to be returned. It is therefore recommended to use "success()" to assert that the parse did succeed (at least, for
       common uses), otherwise the absence of a parse failure cannot be guaranteed.

       "parse_datetime()" is not capable of handling durations.

CREDITS

       Thanks to Tatsuhiko Miyagawa for the initial inspiration. See Miyagawa's journal entry <http://use.perl.org/~miyagawa/journal/31378> for
       more information.

       Furthermore, thanks to (in order of appearance) who have contributed valuable suggestions and patches:

	Clayton L. Scott
	Dave Rolsky
	CPAN Author 'SEKIMURA'
	mike (pulsation)
	Mark Stosberg
	Tuomas Jormola
	Cory Watson
	Urs Stotz
	Shawn M. Moore
	Andreas J. Koenig
	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

SEE ALSO

       dateparse, DateTime, Date::Calc, <http://datetime.perl.org>

AUTHOR

       Steven Schubiger <schubiger@cpan.org>

LICENSE

       This program is free software; you may redistribute it and/or modify it under the same terms as Perl itself.

       See <http://dev.perl.org/licenses/>

perl v5.14.2							    2012-05-31					    DateTime::Format::Natural(3pm)