Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
DateTime::Format::NatuUser3Contributed Perl DocumeDateTime::Format::Natural(3)

NAME
       DateTime::Format::Natural - Parse informal natural language date/time
       strings

SYNOPSIS
	use DateTime::Format::Natural;

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

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

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

	if ($parser->success) {
	    # operate on $dt/@dt, for example:
	    print $dt->strftime('%d.%m.%Y %H:%M:%S'), "\n";
	} else {
	    warn $parser->error;
	}

	@traces	= $parser->trace;

	# examples

	12:14 PM
	next tuesday at	2am
	tomorrow morning
	4pm yesterday
	10 weeks ago

	1st tuesday last november
	2nd friday in august
	final thursday in april

	for 3 hours
	monday to friday
	1 April	10 am to 1 May 8am

	jan 24,	2011 12:00

DESCRIPTION
       "DateTime::Format::Natural" parses informal natural language date/time
       strings.	 In addition, parsable date/time substrings may	be extracted
       from ordinary strings.

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],
		  demand_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"

	   Prefers future time and dates. Accepts a boolean, defaults to
	   false.

       o   "demand_future"

	   Demands future time and dates. Similar to "prefer_future", but
	   stronger.  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 natural language 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 natural language
       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 class DateTime::Format::Natural::Lang::EN if you're intending
       to hack a bit on	the grammar guts.

EXAMPLES
       See the class DateTime::Format::Natural::Lang::EN 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
	David Steinbrunner
	Debian Perl Group
	Tim Bunce
	Ricardo	Signes
	Felix Ostmann

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.32.0			  2020-08-08	  DateTime::Format::Natural(3)

NAME | SYNOPSIS | DESCRIPTION | CONSTRUCTOR | METHODS | GRAMMAR | EXAMPLES | BUGS & CAVEATS | CREDITS | SEE ALSO | AUTHOR | LICENSE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=DateTime::Format::Natural&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help