TimeByExample

Provides a Crystal implementation of Go-style time formatting by example.

Installation

1. Add the dependency to your shard.yml:

   dependencies:
     time_by_example:
       github: mamantoha/time_by_example

2. Run shards install

Usage

require "time_by_example"

This shard adds a by_example method to Time.

The argument to this method is the formatted version of a reference date.

For example:

time = Time.local(2022, 12, 20, 17, 15, 30, location: Time::Location.load("Asia/Taipei"))

time.by_example("Jan 02 2006 @ 03:04 pm") => "Dec 20 2022 @ 05:15 pm"
time.by_example("Jan 02 2006 @ 15:04")    => "Dec 20 2022 @ 17:15"
time.by_example("Mon 02 Jan 15:04")       => "Tue 20 Dec 17:15"
time.by_example("01/02/06")               => "12/20/22"
time.by_example("02.01.2006")             => "20.12.2022"
time.by_example("15:04 MST")              => "17:15 Asia/Taipei"

The reference time is Jan 2, 2006 at 3:04:05 PM MST, which can be remembered as 1 2 3 4 5 6 -7.

Supported formats

Period	Constants
Year	2006 and 06
Month	January, JANUARY, Jan, JAN, 1, 01, and _1 for space padding
Day of the week	Mon, MON, Monday, MONDAY
Day of month	2, 02, and _2 for space padding
Day of year	002
Hour	15, 3, 03, pm, PM, am, AM
Minute	04, but not 4
Second	05, 05.000 for milliseconds and 05.000000 and 05.000000000, but not 5
Time Zone	-7000, -07:00, -07:00:00, MST

Alternate usage

If you want to reuse a format multiple times, you can do so by creating and reusing an TimeByExample::ExampleFormat

ef = TimeByExample::ExampleFormat.new("03:04 pm")

ef.format(Time.local(2022, 12, 20, 17, 15, 30)) # => "05:15 pm"
ef.format(Time.local(2022, 12, 20, 5, 15, 30))  # => "05:15 am"

Contributing

1. Fork it (https://github.com/mamantoha/time_by_example/fork)
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create a new Pull Request

Contributors

• Anton Maminov - creator and maintainer