NaturalTime

A small and dirty Elixir library that attempts to parse date and time from natural english.

It is capable of parsing at least the following formats:

• tomorrow 1pm
• 1 p.m. tomorrow
• on next monday 2 in the morning
• 10pm
• next fri at 5:10pm
• next fri 5:10pm

I wrote this library mainly for my own use only. Therefore, some of the expected features may be missing, which includes:

• non-weekday dates (e.g. 2021-01-01 13:00)
• seconds (e.g. 12:59:59)
• dates without a time (e.g. next monday)
• time-of-day description without a specific time (e.g. morning, midnight)
• “next” with times (next 2pm)

That being said, these formats should be relatively simple to add and I will welcome your pull requests :)

Installation

Find the latest version on hex and include it in your mix.exs as such.

def deps do
  [
    {:natural_time, "~> 0.1.0"}
  ]
end

Usage

The library exports a single module with a single function NaturalTime.parse/2.

@doc """
Specify a string and a DateTime object indicating the reference time.

The timezone information in the reference time will be used for
inference. For example, if the reference time has timezone of
"UTC+1", then "2pm" will parse to 2pm in UTC+1 timezone.

Example usage:

    iex> now = Timex.parse!("2019-06-02T01:04:21+08:00", "{ISO:Extended}")
    iex> parse("10pm", now) == Timex.parse!("2019-06-02T22:00:00+08:00", "{ISO:Extended}")
    true
"""
@spec parse(String.t(), DateTime.t()) :: nil | DateTime.t()
def parse(str, rel \\ Timex.now())

It spits out nil if the string cannot be parsed. Otherwise a DateTime object will be returned. Check out the tests for extra examples.