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-PeriodParser-0.03
River stage zero No dependents
/ Date::PeriodParser

NAME

Date::PeriodParser - Turns English descriptions into time periods

SYNOPSIS

  use Date::PeriodParser;
  my ($midnight, $midday) = parse_period("this morning");
  my ($monday_am, $sunday_pm) = parse_period("this week");
  ... parse_period("sometime this afternoon");
  ... parse_period("around two weeks ago");

DESCRIPTION

The subroutine parse_period attempts to turn the English description of a time period into a pair of Unix epoch times. As a famous man once said, "Of course, this is a heuristic, which is a fancy way of saying that it doesn't work".

WHAT'S CURRENTLY SUPPORTED

  • sometime

    Returns full range of dates from the epoch to the latest-possible date (currently "Mon Jan 18 19:14:07 2038").

  • now

    Returns the current date and time.

  • today, tomorrow, yesterday

    Supported, with "the day before" and "the day after" accepted as modifiers. This means you can say relatively meaningless things like "the day after yesterday" and "the day before tomorrow", but they work.

  • day, morning, lunchtime, afternoon, evening, night

    These are all supported with "this" and "in the" as modifiers; relative times specified with "in the" (for morning, afternoon, and evening) disambiguate relative to the current time. For instance, if it's afternoon and "in the morning" is specified, this implies "tomorrow morning".

  • "ago" and "from now"

    Offsets in days and "a week" are accepted; you cannot cross a month boundary in this release.

  • "in xxx day(s)" and "in xxx days time"

    Offsets in days are supported; again, crossing month boundaries does not yet work.

If you enter something it can't parse, it'll return an error code and an explanation instead of two epoch time values. Error code -1 means "You entered gibberish", error code -2 means "you entered something ambiguous", and the explanation will tell you how to disambiguate it.

BUGS

Parsing is limited. Some relatively complicated things work fine, but some simple things do not.

  • Supports only a number of days "ago" or "from now". Should be expanded to handle weeks, months, and years as well.

  • The time-of-day words ("morning", "afternoon", "evening", "night", and "lunchtime") should accept relative modifiers (e.g., "lunchtime tomorrow", "yesterday evening"), but don't.

  • Day offsets carrying the day of the month over a valid limit cause an internal error in localtime(). This is the biggest bug at present and will be addressed in the next release.

AUTHOR

Simon Cozens, simon@cpan.org Joe McMahon, mcmahon@cpan.org

LEGAL

Copyright (C) 2002 by Simon Cozens; Copyright (c) 2005 by Joe McMahon

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.5 or, at your option, any later version of Perl 5 you may have available.