chrono_english/

lib.rs

//! ## Parsing English Dates
//!
//! I've always admired the ability of the GNU `date` command to
//! convert "English" expressions to dates and times with `date -d expr`.
//! `chrono-english` does similar expressions, although with extensions, so
//! that for instance you can specify both the day and the time "next friday 8pm".
//! No attempt at full natural language parsing is made - only a limited set of
//! patterns is supported.
//!
//! ## Supported Formats
//!
//! `chrono-english` does _absolute_ dates:  ISO-like dates "2018-04-01" and the month name forms
//! "1 April 2018" and "April 1, 2018". (There's no ambiguity so both of these forms are fine)
//!
//! The informal "01/04/18" or American form "04/01/18" is supported.
//! There is a `Dialect` enum to specify what kind of date English you would like to speak.
//! Both short and long years are accepted in this form; short dates pivot between 1940 and 2040.
//!
//! Then there are are _relative_ dates like 'April 1' and '9/11' (this
//! if using `Dialect::Us`). The current year is assumed, but this can be modified by 'next'
//! and 'last'. For instance, it is now the 13th of March, 2018: 'April 1' and 'next April 1'
//! are in 2018; 'last April 1' is in 2017.
//!
//! Another relative form is simply a month name
//! like 'apr' or 'April' (case-insensitive, only first three letters significant) where the
//! day is assumed to be the 1st.
//!
//! A week-day works in the same way: 'friday' means this
//! coming Friday, relative to today. 'last Friday' is unambiguous,
//! but 'next Friday' has different meanings; in the US it means the same as 'Friday'
//! but otherwise it means the Friday of next week (plus 7 days)
//!
//! Date and time can be specified also by a number of time units. So "2 days", "3 hours".
//! Again, first three letters, but 'd','m' and 'y' are understood (so "3h"). We make
//! a distinction between _second_ intervals (seconds,minutes,hours,days,weeks) and _month_
//! intervals (months,years).  Month intervals always give us the same date, if possible
//! But adding a month to "30 Jan" will give "28 Feb" or "29 Feb" depending if a leap year.
//!
//! Finally, dates may be followed by time. Either 'formal' like 18:03, with optional
//! second (like 18:03:40) or 'informal' like 6.03pm. So one gets "next friday 8pm' and so
//! forth.
//!
//! ## API
//!
//! There are two entry points: `parse_date_string` and `parse_duration`. The
//! first is given the date string, a `DateTime` from which relative dates and
//! times operate, and a dialect (either `Dialect::Uk` or `Dialect::Us`
//! currently.) The base time also specifies the desired timezone.
//!
//! ```ignore
//! extern crate chrono_english;
//! extern crate chrono;
//! use chrono_english::{parse_date_string,Dialect};
//!
//! use chrono::prelude::*;
//!
//! let date_time = parse_date_string("next friday 8pm", Local::now(), Dialect::Uk)?;
//! println!("{}",date_time.format("%c"));
//! ```
//!
//! There is a little command-line program `parse-date` in the `examples` folder which can be used to play
//! with these expressions.
//!
//! The other function, `parse_duration`, lets you access just the relative part
//! of a string like 'two days ago' or '12 hours'. If successful, returns an
//! `Interval`, which is a number of seconds, days, or months.
//!
//! ```
//! use chrono_english::{parse_duration,Interval};
//!
//! assert_eq!(parse_duration("15m ago").unwrap(), Interval::Seconds(-15 * 60));
//! ```
//!

extern crate chrono;
extern crate scanlex;
use chrono::prelude::*;

mod errors;
mod parser;
mod types;
use errors::*;
use types::*;

pub use errors::{DateError, DateResult};
pub use types::Interval;

#[derive(Clone, Copy, Debug)]
pub enum Dialect {
    Uk,
    Us,
}

pub fn parse_date_string<Tz: TimeZone>(
    s: &str,
    now: DateTime<Tz>,
    dialect: Dialect,
) -> DateResult<DateTime<Tz>>
where
    Tz::Offset: Copy,
{
    let mut dp = parser::DateParser::new(s);
    if let Dialect::Us = dialect {
        dp = dp.american_date();
    }
    let d = dp.parse()?;

    // we may have explicit hour:minute:sec
    let tspec = match d.time {
        Some(tspec) => tspec,
        None => TimeSpec::new_empty(),
    };
    if tspec.offset.is_some() {
        //   return DateTime::fix()::parse_from_rfc3339(s);
    }
    let date_time = if let Some(dspec) = d.date {
        dspec
            .to_date_time(now, tspec, dp.american)
            .or_err("bad date")?
    } else {
        // no date, time set for today's date
        tspec.to_date_time(now.date()).or_err("bad time")?
    };
    Ok(date_time)
}

pub fn parse_duration(s: &str) -> DateResult<Interval> {
    let mut dp = parser::DateParser::new(s);
    let d = dp.parse()?;

    if d.time.is_some() {
        return date_result("unexpected time component");
    }

    // shouldn't happen, but.
    if d.date.is_none() {
        return date_result("could not parse date");
    }

    match d.date.unwrap() {
        DateSpec::Absolute(_) => date_result("unexpected absolute date"),
        DateSpec::FromName(_) => date_result("unexpected date component"),
        DateSpec::Relative(skip) => Ok(skip.to_interval()),
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    const FMT_ISO: &str = "%+";

    fn display(t: DateResult<DateTime<Utc>>) -> String {
        t.unwrap().format(FMT_ISO).to_string()
    }

    #[test]
    fn basics() {
        let base = parse_date_string("2018-03-21 11:00", Utc::now(), Dialect::Uk).unwrap();

        // Day of week - relative to today. May have a time part
        assert_eq!(
            display(parse_date_string("friday", base, Dialect::Uk)),
            "2018-03-23T00:00:00+00:00"
        );
        assert_eq!(
            display(parse_date_string("friday 10:30", base, Dialect::Uk)),
            "2018-03-23T10:30:00+00:00"
        );
        assert_eq!(
            display(parse_date_string("friday 8pm", base, Dialect::Uk)),
            "2018-03-23T20:00:00+00:00"
        );

        // The day of week is the _next_ day after today, so "Tuesday" is the next Tuesday after Wednesday
        assert_eq!(
            display(parse_date_string("tues", base, Dialect::Uk)),
            "2018-03-27T00:00:00+00:00"
        );

        // The expression 'next Monday' is ambiguous; in the US it means the day following (same as 'Monday')
        // (This is how the `date` command interprets it)
        assert_eq!(
            display(parse_date_string("next mon", base, Dialect::Us)),
            "2018-03-26T00:00:00+00:00"
        );
        // but otherwise it means the day in the next week..
        assert_eq!(
            display(parse_date_string("next mon", base, Dialect::Uk)),
            "2018-04-02T00:00:00+00:00"
        );

        assert_eq!(
            display(parse_date_string("last fri 9.30", base, Dialect::Uk)),
            "2018-03-16T09:30:00+00:00"
        );

        // date expressed as month, day - relative to today. May have a time part
        assert_eq!(
            display(parse_date_string("9/11", base, Dialect::Us)),
            "2018-09-11T00:00:00+00:00"
        );
        assert_eq!(
            display(parse_date_string("last 9/11", base, Dialect::Us)),
            "2017-09-11T00:00:00+00:00"
        );
        assert_eq!(
            display(parse_date_string("last 9/11 9am", base, Dialect::Us)),
            "2017-09-11T09:00:00+00:00"
        );
        assert_eq!(
            display(parse_date_string("April 1 8.30pm", base, Dialect::Uk)),
            "2018-04-01T20:30:00+00:00"
        );

        // advance by time unit from today
        // without explicit time, use base time - otherwise override
        assert_eq!(
            display(parse_date_string("2d", base, Dialect::Uk)),
            "2018-03-23T11:00:00+00:00"
        );
        assert_eq!(
            display(parse_date_string("2d 03:00", base, Dialect::Uk)),
            "2018-03-23T03:00:00+00:00"
        );
        assert_eq!(
            display(parse_date_string("3 weeks", base, Dialect::Uk)),
            "2018-04-11T11:00:00+00:00"
        );
        assert_eq!(
            display(parse_date_string("3h", base, Dialect::Uk)),
            "2018-03-21T14:00:00+00:00"
        );
        assert_eq!(
            display(parse_date_string("6 months", base, Dialect::Uk)),
            "2018-09-21T00:00:00+00:00"
        );
        assert_eq!(
            display(parse_date_string("6 months ago", base, Dialect::Uk)),
            "2017-09-21T00:00:00+00:00"
        );
        assert_eq!(
            display(parse_date_string("3 hours ago", base, Dialect::Uk)),
            "2018-03-21T08:00:00+00:00"
        );
        assert_eq!(
            display(parse_date_string(" -3h", base, Dialect::Uk)),
            "2018-03-21T08:00:00+00:00"
        );
        assert_eq!(
            display(parse_date_string(" -3 month", base, Dialect::Uk)),
            "2017-12-21T00:00:00+00:00"
        );

        // absolute date with year, month, day - formal ISO and informal UK or US
        assert_eq!(
            display(parse_date_string("2017-06-30", base, Dialect::Uk)),
            "2017-06-30T00:00:00+00:00"
        );
        assert_eq!(
            display(parse_date_string("30/06/17", base, Dialect::Uk)),
            "2017-06-30T00:00:00+00:00"
        );
        assert_eq!(
            display(parse_date_string("06/30/17", base, Dialect::Us)),
            "2017-06-30T00:00:00+00:00"
        );

        // may be followed by time part, formal and informal
        assert_eq!(
            display(parse_date_string("2017-06-30 08:20:30", base, Dialect::Uk)),
            "2017-06-30T08:20:30+00:00"
        );
        assert_eq!(
            display(parse_date_string(
                "2017-06-30 08:20:30 +02:00",
                base,
                Dialect::Uk
            )),
            "2017-06-30T06:20:30+00:00"
        );
        assert_eq!(
            display(parse_date_string(
                "2017-06-30 08:20:30 +0200",
                base,
                Dialect::Uk
            )),
            "2017-06-30T06:20:30+00:00"
        );
        assert_eq!(
            display(parse_date_string("2017-06-30T08:20:30Z", base, Dialect::Uk)),
            "2017-06-30T08:20:30+00:00"
        );
        assert_eq!(
            display(parse_date_string("2017-06-30T08:20:30", base, Dialect::Uk)),
            "2017-06-30T08:20:30+00:00"
        );
        assert_eq!(
            display(parse_date_string("2017-06-30 8.20", base, Dialect::Uk)),
            "2017-06-30T08:20:00+00:00"
        );
        assert_eq!(
            display(parse_date_string("2017-06-30 8.30pm", base, Dialect::Uk)),
            "2017-06-30T20:30:00+00:00"
        );
        assert_eq!(
            display(parse_date_string("2017-06-30 8:30pm", base, Dialect::Uk)),
            "2017-06-30T20:30:00+00:00"
        );
        assert_eq!(
            display(parse_date_string("2017-06-30 2am", base, Dialect::Uk)),
            "2017-06-30T02:00:00+00:00"
        );
        assert_eq!(
            display(parse_date_string("30 June 2018", base, Dialect::Uk)),
            "2018-06-30T00:00:00+00:00"
        );
        assert_eq!(
            display(parse_date_string("June 30, 2018", base, Dialect::Uk)),
            "2018-06-30T00:00:00+00:00"
        );
        assert_eq!(
            display(parse_date_string("June   30,    2018", base, Dialect::Uk)),
            "2018-06-30T00:00:00+00:00"
        );
    }

    fn get_err(r: DateResult<Interval>) -> String {
        r.err().unwrap().to_string()
    }

    #[test]
    fn durations() {
        assert_eq!(parse_duration("6h").unwrap(), Interval::Seconds(6 * 3600));
        assert_eq!(
            parse_duration("4 hours ago").unwrap(),
            Interval::Seconds(-4 * 3600)
        );
        assert_eq!(parse_duration("5 min").unwrap(), Interval::Seconds(5 * 60));
        assert_eq!(parse_duration("10m").unwrap(), Interval::Seconds(10 * 60));
        assert_eq!(
            parse_duration("15m ago").unwrap(),
            Interval::Seconds(-15 * 60)
        );

        assert_eq!(parse_duration("1 day").unwrap(), Interval::Days(1));
        assert_eq!(parse_duration("2 days ago").unwrap(), Interval::Days(-2));
        assert_eq!(parse_duration("3 weeks").unwrap(), Interval::Days(21));
        assert_eq!(parse_duration("2 weeks ago").unwrap(), Interval::Days(-14));

        assert_eq!(parse_duration("1 month").unwrap(), Interval::Months(1));
        assert_eq!(parse_duration("6 months").unwrap(), Interval::Months(6));
        assert_eq!(parse_duration("8 years").unwrap(), Interval::Months(12 * 8));

        // errors
        assert_eq!(
            get_err(parse_duration("2020-01-01")),
            "unexpected absolute date"
        );
        assert_eq!(
            get_err(parse_duration("2 days 15:00")),
            "unexpected time component"
        );
        assert_eq!(
            get_err(parse_duration("tuesday")),
            "unexpected date component"
        );
        assert_eq!(
            get_err(parse_duration("bananas")),
            "expected week day or month name"
        );
    }
}