time_will_tell 0.0.3 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 9df2e1dbc70a4b7a75f46a82274345c31e28503b
-  data.tar.gz: 6301da2b44cfdf952d658caad8b21d74ae18e051
+  metadata.gz: c5a680687c83bfbc5595591eed660e67f9bf6af1
+  data.tar.gz: ebbe5e4ffb9981daa57889fbc6bc5c94f290af56
 SHA512:
-  metadata.gz: 416388541bc70c215cb26bede5c8f1bd06b35df69b3c08803eadea363ed1fa137561f3b68aabe7da06427614e191fce7e0494c6f85a0f19aa4553aaf51a70def
-  data.tar.gz: 1adda75db830cf80c1af65ed034b7d721db63c7150a629e26084a8a18750426ffc1fdeed4f660d000f6fa1f26afc7b91fa2bf22d75551fec17ecf0ccf474ff35
+  metadata.gz: 4083a53a1234ac98932b8d8b58289dee948369873b1e3e179447c611990514acd8e992d670b93247888ce94f588b4a1d9fb4dd6f230fa2f912c8fefa2947f027
+  data.tar.gz: 2697182c903ade85536a061facb3b542d648ff2013a8b76a53b58b979812155ea00ed0799bf11d0b3d1ac90c62255d975d79840947a1eeb4c596926641a515d1

data/README.md

@@ -4,21 +4,104 @@ Specialized conversions of dates and times to strings.
 
 ## Installation
 
-Add this line to your application's Gemfile:
+Add `time_will_tell` to your Gemfile:
 
     gem 'time_will_tell'
 
-And then execute:
+### Install the default locale file
 
-    $ bundle
+Run the generator to add the default locale file `time_will_tell.en.yml` to your `config/locales` directory:
 
-Or install it yourself as:
-
-    $ gem install time_will_tell
+    $ rails generate time_will_tell:install
 
 ## Usage
 
-TODO: Write usage instructions here
+`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`](http://api.rubyonrails.org/classes/ActionView/Helpers/DateHelper.html#method-i-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
 

data/lib/generators/time_will_tell/install/install_generator.rb

@@ -1,3 +1,4 @@
+# encoding: UTF-8
 module TimeWillTell
   module Generators
     class InstallGenerator < Rails::Generators::Base

data/lib/generators/time_will_tell/install/templates/config/locales/time_will_tell.en.yml

@@ -1,10 +1,11 @@
 en:
   time_will_tell:
     date_range:
-      different_months_same_year: "%{from_month} %{from_day} %{sep} %{to_month} %{to_day}, %{year}"
+      different_months_same_year: "%{from_month} %{from_day} %{sep} %{to_month} %{to_day}"
       different_years: "%{from_month} %{from_day}, %{from_year} %{sep} %{to_month} %{to_day}, %{to_year}"
-      same_month: "%{month} %{from_day} %{sep} %{to_day}, %{year}"
-      same_date: "%{month} %{from_day}, %{year}"
+      same_month: "%{month} %{from_day} %{sep} %{to_day}"
+      same_date: "%{month} %{from_day}"
+      with_year: "%{date_range}, %{year}"
 
     distance_in_words:
       template: "%{count} %{unit}"

data/lib/time_will_tell/helpers/date_range_helper.rb

@@ -6,6 +6,7 @@ module TimeWillTell
         format    = options.fetch(:format, :short)
         scope     = options.fetch(:scope, 'time_will_tell.date_range')
         separator = options.fetch(:separator, '—')
+        show_year = options.fetch(:show_year, true)
 
         month_names = format.to_sym == :short ? I18n.t("date.abbr_month_names") : I18n.t("date.month_names")
 
@@ -39,7 +40,13 @@ module TimeWillTell
           end
         end
 
-        I18n.t("#{scope}.#{template}", dates)
+        without_year = I18n.t("#{scope}.#{template}", dates)
+
+        if show_year && from_date.year == to_date.year
+          I18n.t("#{scope}.with_year", date_range: without_year, year: from_year, default: without_year)
+        else
+          without_year
+        end
       end
 
     end

data/lib/time_will_tell/version.rb

@@ -1,3 +1,3 @@
 module TimeWillTell
-  VERSION = '0.0.3'.freeze
+  VERSION = '0.1.0'.freeze
 end

data/spec/fixtures/locales/time_will_tell.fr.yml

@@ -31,10 +31,11 @@ fr:
 
   time_will_tell:
     date_range:
-      different_months_same_year: "%{from_day} %{from_month} %{sep} %{to_day} %{to_month} %{year}"
+      different_months_same_year: "%{from_day} %{from_month} %{sep} %{to_day} %{to_month}"
       different_years: "%{from_day} %{from_month} %{from_year} %{sep} %{to_day} %{to_month} %{to_year}"
-      same_month: "%{from_day} %{sep} %{to_day} %{month} %{year}"
-      same_date: "%{from_day} %{month} %{year}"
+      same_month: "%{from_day} %{sep} %{to_day} %{month}"
+      same_date: "%{from_day} %{month}"
+      with_year: "%{date_range} %{year}"
 
     distance_in_words:
       template: "%{count} %{unit}"

data/spec/helpers/date_range_helper_spec.rb

@@ -11,18 +11,18 @@ describe TimeWillTell::Helpers::DateRangeHelper do
   describe '#date_range' do
     {
       # short form
-      [Date.new(2012, 10, 3), Date.new(2012, 10, 8)] => 'Oct 3 — 8, 2012',
-      [Date.new(2013, 1, 30), Date.new(2013, 2, 5)] => 'Jan 30 — Feb 5, 2013',
-      [Date.new(2012, 12, 26), Date.new(2013, 1, 3)] => 'Dec 26, 2012 — Jan 3, 2013',
-      [Date.new(2013, 8, 24), Date.new(2013, 8, 24)] => 'Aug 24, 2013',
-      [Date.new(2014, 2, 10), Date.new(2015, 2, 10)] => 'Feb 10, 2014 — Feb 10, 2015',
+      [Date.new(2012, 10, 3),  Date.new(2012, 10, 8)] => 'Oct 3 — 8, 2012',
+      [Date.new(2013, 1, 30),  Date.new(2013, 2, 5)]  => 'Jan 30 — Feb 5, 2013',
+      [Date.new(2012, 12, 26), Date.new(2013, 1, 3)]  => 'Dec 26, 2012 — Jan 3, 2013',
+      [Date.new(2013, 8, 24),  Date.new(2013, 8, 24)] => 'Aug 24, 2013',
+      [Date.new(2014, 2, 10),  Date.new(2015, 2, 10)] => 'Feb 10, 2014 — Feb 10, 2015',
 
       # long form
-      [Date.new(2012, 10, 3), Date.new(2012, 10, 8), format: :long] => 'October 3 — 8, 2012',
-      [Date.new(2013, 1, 30), Date.new(2013, 2, 5), format: :long] => 'January 30 — February 5, 2013',
-      [Date.new(2012, 12, 26), Date.new(2013, 1, 3), format: :long] => 'December 26, 2012 — January 3, 2013',
-      [Date.new(2013, 8, 24), Date.new(2013, 8, 24), format: :long] => 'August 24, 2013',
-      [Date.new(2014, 2, 10), Date.new(2015, 2, 10), format: :long] => 'February 10, 2014 — February 10, 2015',
+      [Date.new(2012, 10, 3),  Date.new(2012, 10, 8), format: :long] => 'October 3 — 8, 2012',
+      [Date.new(2013, 1, 30),  Date.new(2013, 2, 5),  format: :long] => 'January 30 — February 5, 2013',
+      [Date.new(2012, 12, 26), Date.new(2013, 1, 3),  format: :long] => 'December 26, 2012 — January 3, 2013',
+      [Date.new(2013, 8, 24),  Date.new(2013, 8, 24), format: :long] => 'August 24, 2013',
+      [Date.new(2014, 2, 10),  Date.new(2015, 2, 10), format: :long] => 'February 10, 2014 — February 10, 2015',
     }.each do |args, expected|
       it "outputs '#{expected}" do
         from_date = args[0]
@@ -53,6 +53,27 @@ describe TimeWillTell::Helpers::DateRangeHelper do
       ).to eq 'Oct 31 ~ Dec 25, 2013'
     end
 
+    context 'when show_year option is false' do
+      let(:options) { { show_year: false } }
+
+      subject { helper.date_range(from_date, to_date, options) }
+
+      {
+        [Date.new(2012, 10, 3),  Date.new(2012, 10, 8)] => 'Oct 3 — 8',
+        [Date.new(2013, 1, 30),  Date.new(2013, 2, 5)]  => 'Jan 30 — Feb 5',
+        [Date.new(2012, 12, 26), Date.new(2013, 1, 3)]  => 'Dec 26, 2012 — Jan 3, 2013',
+        [Date.new(2013, 8, 24),  Date.new(2013, 8, 24)] => 'Aug 24',
+        [Date.new(2014, 2, 10),  Date.new(2015, 2, 10)] => 'Feb 10, 2014 — Feb 10, 2015',
+      }.each do |args, expected|
+        context "from #{args[0]} to #{args[1]}" do
+          let(:from_date) { args[0] }
+          let(:to_date)   { args[1] }
+
+          it { should eq expected }
+        end
+      end
+    end # when show_year option is false
+
     context 'with a custom locale' do
       let(:locale) { :fr }
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: time_will_tell
 version: !ruby/object:Gem::Version
-  version: 0.0.3
+  version: 0.1.0
 platform: ruby
 authors:
 - Michel Billard
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-03-18 00:00:00.000000000 Z
+date: 2014-08-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: railties
@@ -112,7 +112,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.0.3
+rubygems_version: 2.3.0
 signing_key: 
 specification_version: 4
 summary: Specialized conversions of dates and times to strings.