Chronic

Like Chronic, but for Elixir.

Usage

Add it as a dependency to your project:

defp deps do
  [
    {:chronic, "~> 3.1"},
  ]
end

Then you can use it wherever you wish:

{ :ok, time, offset } = Chronic.parse("tuesday 9am")

The time returned is a NaiveDateTime from Elixir and the offset returned is a time zone offset.

Chronic uses universal time by default

Chronic works based off the current UTC time by default. This is important to know because of how Chronic behaves. If you're in UTC +10 (Melbourne), like I am, and it's currently Tuesday, 25th September 2018 at 1pm in Melbourne, Chronic will think it is "currently" 3am -- because it is in UTC time.

So if you ask Chronic what "Tuesday at 12pm" looks like, it will tell give you a time for today:

{:ok, time, offset} = Chronic.parse("Tuesday 12pm")
{:ok, ~N[2018-09-25 12:00:00.000000], 0}

This is probably not what you want because it's a date in Melbourne's past but UTC's future. To fix this, you can use the currently option and pass it your local time:

{:ok, time, offset} = Chronic.parse("tuesday at 12pm", currently: :calendar.local_time)
{:ok, ~N[2018-10-02 12:00:00.000000], 0}

This is a better time because it's in the future; probbaly what you want.

However, it's important to note here that the offset value will be 0 rather than the correct timezone, so it's better ignored in this case.

Bad / Unknown Formats

If Chronic encounters a format it doesn't recognise, it will return an error tuple:

{ :error, :unknown_format } = Chronic.parse("definitely not a known format, no siree")

If NaiveDateTime doesn't know what you mean (i.e. if you ask for a date such as "January 32nd"), then you'll see this error instead:

{:error, :invalid_datetime} = Chronic.parse("January 32nd")

If you're not sure what you're going to get back, use a case:

input = "some user input goes here"
case Chronic.parse(input) do
  { :ok, time, offset } ->
    # do something with time + offset
  { :error, _ } ->
    # present a good error message to the user
end