TimeWillTell

Specialized conversions of dates and times to strings.

Installation

Add time_will_tell to your Gemfile:

gem 'time_will_tell'

Install the default locale file

Run the generator to add the default locale file time_will_tell.en.yml to your config/locales directory:

$ rails generate time_will_tell:install

Usage

time_will_tell offers 2 view helpers for dealing with dates.

exact_distance_of_time_in_words

The similarity with distance_of_time_in_words is not a coincidence. Both methods share the a similar signature:

exact_distance_of_time_in_words(from_time, to_time, options = {})

# => '2 hours 33 minutes'
# => '1 hour and a half'
# => '3 years 11 months and 21 seconds'
# => '1 month 15 days and 1 minute'
# => '1 day 2 hours and a half and 5 seconds'
# => 'half an hour'

Options

Displaying the seconds is optional and off by default. Use include_seconds: true to include them.

You can also supply your own locale by specifying a locale scope. The default is time_will_tell.distance_in_words.

Locales

You can either replace the default locale strings or copy the structure under a different scope to be able to toggle between a default version and an alternate one.

For example, the following scope would output

compact_distance_in_words:
  template: "%{count}%{unit}"
  template_long: "%{rest} %{last}"

  units:
    second: s
    minute: m
    hour: h
    day: d
    month: M
    year: Y

  special:
    half_an_hour: 30m
    and_a_half: 30m

exact_distance_of_time_in_words(from_time, to_time, scope: 'compact_distance_in_words')
# => '1d 2h 30m 5s'

date_range

date_range simplifies displaying a date range in a brief format.

# Oct 3 - 8, 2012
# Jan 30 - Feb 5, 2013
# Dec 26, 2012 - Jan 3, 2013

The output depends on whether the dates are on the same day, month and year.

Options

format

You can choose to display the full month names by specifying format: :long.

date_range(from_date, to_date, format: :long)
# January 30 - February 5, 2013

separator

You can choose a different separator if you don't like this guy -.

date_range(from_date, to_date, separator: 'to')
# Oct 3 to 8, 2012

show_year

Sometimes you don't want the year to show up in the date range.

date_range(from_date, to_date, show_year: false)
# Jan 30 - Feb 5

By default the year will always be shown. Also, if the dates are in different years, the years will be shown even if show_year is false.

Locales

Just as with exact_distance_of_time_in_words you can specify your own locale scope.

Contributing

1. Fork it ( http://github.com//time_will_tell/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 new Pull Request