The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
Date-Parse-Lite-0.03
River stage zero No dependents
++
/ Date::Parse::Lite

NAME

Date::Parse::Lite - Light weight parsing of human-entered date strings

VERSION

Version 0.03

SYNOPSIS

Parse human-entered strings that are intended to contain dates and attempt to extract machine-readable date information from them while being as generous as possible with format interpretation.

    use Date::Parse::Lite;

    my $parser = Date::Parse::Lite->new();
    $parser->parse('June 1st 17');

    if($parser->parsed()) {
        my $day = $parser->day();

    ...

DESCRIPTION

This simple module attempts to parse a day, a month and a year from a string on the assumption that the string is intended to represent a date. Note that it does not validate the date except to the extent that doing so informs the parsing, e.g. numbers in the range 13 to 31 will be parsed as days rather than months but 31 will still be parsed as a day even when the month is 2. The responsibility for validating the results and/or representing them in a more useful form remains with the caller, if it is interested in doing so.

The parser will extract dates from a wide range of inputs, including a lot which would not look like dates to a human reader. The intention is to maximise the likelihood that a date entered by a human being will be accepted as such without the need to place difficult restrictions on what may be entered. To add to the flexibility there are some configuration options. These are described with their corresponding methods, below.

The API is entirely object oriented - you must instantiate an object, which will encapsulate the configuration and the strings to be parsed, and then query that object to get the results.

DATE FORMATS

The parser is very forgiving about date formats - anything that's not a string of digits or letters is essentially treated as a separator and then the remaining numbers and words are understood as a day, month and year with words describing months taken as priority over numbers. Any trailing text is ignored and any amount of non-alphanumeric text may surround and separate the recognised parts. While this means that a wide range of formats are accepted it does also mean that the fact that this parser was able to extract date information from a string does not guarantee that the string would have looked like a date to a human observer. The parser is founded on the assumption that the string to be parsed is intended to be a date.

There is a single special case: a string of 8 digits, with or without leading and/or trailing whitespace, is treated as YYYYMMDD.

METHODS

new([param => $value [, ...]])

Create a new parser object. You may pass in a hash to initialise the object with the following keys:

prefer_month_first_order
literal_years_below_100
month_names

Initialise the configuration set by the methods of the same names - see below.

date

A string to be parsed - this will be passed to the parse method. Note that this is optional; you can just call parse later (and repeatedly) if you wish.

day()

Returns the day parsed from the date string, if any. This will be a number in the range 1 to 31 if the parse was succesful.

month()

Returns the month parsed from the date string, if any. This will be a number in the range 1 to 12 if the parse was succesful.

year()

Returns the year parsed from the date string, if any. This will be a number if the parse was succesful.

parsed()

Reaturns a flag indicating whether a date has been successfully parsed from a string.

prefer_month_first_order([$flag])

Returns a flag indicating how day-month order ambiguity will be resolved, e.g. in a date like 1/2/2015. Defaults to true so that American dates are parsed as expected. You may optionally pass a value to set the flag.

literal_years_below_100([$flag])

Returns a flag indicating whether years below 100 will be interpreted literally (i.e. as being in the first century). If this is not set then such years will be intepreted as being the one nearest the system date that suits, e.g. in 2015 the year 15 is interpreted as 2015, 50 as 2050 and 90 as 1990. Defaults to false. You may optionally pass a value to set the flag.

parse($string)

Parse a string and attempt to extract a date. Returns a success flag (see the parsed method). You can call this as many times as you like if you need to parse multiple strings. The results available from the methods described above will always be for the most recently parsed date string.

month_names($name => $number [, ...])

Add new names to be recognised as months, typically for internationalisation. You may pass an array with an even number of elements or a reference to the same. Month names are matched by comparing the number of characters found in the parsed string with the same number of characters at the start of the names provided through this method. Thus abreviations are understood as long as they are intial sections of the provided names. Other abbreviations must be specified separately - you may pass as many names with the same month number as you wish. Comparisons are case-insensitive.

Multiple calls to this method will add to the list of names - to reset the list you must create a new object but note that all objects include the twelve common English month names. This means that you won't have much luck with languages that have the same names, or abbreviations of them, for different months. I don't know of any such though.

AUTHOR

Merlyn Kline, <pause.perl.org at binary.co.uk>

BUGS

Please report any bugs or feature requests to bug-date-parse-lite at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Date-Parse-Lite. 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::Parse::Lite

You can also look for information at:

LICENSE AND COPYRIGHT

Copyright 2015 Merlyn Kline.

This program is free software; you can redistribute it and/or modify it under the terms of the the Artistic License (2.0). You may obtain a copy of the full license at:

http://www.perlfoundation.org/artistic_license_2_0

Any use, modification, and distribution of the Standard or Modified Versions is governed by this Artistic License. By using, modifying or distributing the Package, you accept this license. Do not use, modify, or distribute the Package, if you do not accept this license.

If your Modified Version has been derived from a Modified Version made by someone other than you, you are nevertheless required to ensure that your Modified Version complies with the requirements of this license.

This license does not grant you the right to use any trademark, service mark, tradename, or logo of the Copyright Holder.

This license includes the non-exclusive, worldwide, free-of-charge patent license to make, have made, use, offer to sell, sell, import and otherwise transfer the Package with respect to any patent claims licensable by the Copyright Holder that are necessarily infringed by the Package. If you institute patent litigation (including a cross-claim or counterclaim) against any party alleging that the Package constitutes direct or contributory patent infringement, then this Artistic License to you shall terminate on the date that such litigation is filed.

Disclaimer of Warranty: THE PACKAGE IS PROVIDED BY THE COPYRIGHT HOLDER AND CONTRIBUTORS "AS IS' AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES. THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT ARE DISCLAIMED TO THE EXTENT PERMITTED BY YOUR LOCAL LAW. UNLESS REQUIRED BY LAW, NO COPYRIGHT HOLDER OR CONTRIBUTOR WILL BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING IN ANY WAY OUT OF THE USE OF THE PACKAGE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.