series_joiner 1.1.1 → 1.2.0

data/README.rdoc

@@ -1,6 +1,6 @@
 = SeriesJoiner
 
-A gem for joining items in arrays together into grammatically correct series. 
+A gem for joining items in arrays together into grammatically correct series, such as "a, b and c". 
 
 SeriesJoiner extends the <tt>Array</tt> class with a <tt>join_as_series()</tt> method which is similar to the built-in <tt>join()</tt> method. However, <tt>join_as_series()</tt> allows for custom delimiters and conjunctions. 
 
@@ -18,7 +18,7 @@ Add the following to your Gemfile:
 
 == Usage
 
-join_as_series() accepts the following options:
+<tt>join_as_series()</tt> accepts the following options:
 
   :delimiter       # inserted between items, except for the final two (default => ', ')
   :final_delimiter # inserted between the final two items (if > 2), but before the conjunction (default => '')
@@ -42,10 +42,22 @@ Here are some examples using custom delimiters and/or conjunctions:
 
   ['a', 'b', 'c'].join_as_series(:delimiter => '; ', :conjunction => '; or, ') #=> 'a; b; or, c'
 
-The use of the serial comma (i.e. the final comma sometimes used before the conjunction) is much debated in grammar (http://en.wikipedia.org/wiki/Serial_comma). By default, SeriesJoiner does not use the serial comma. However, the <tt>:final_delimiter</tt> option can be set to <tt>','</tt> to include it:
+The use of the serial comma (i.e. the final comma sometimes used before the conjunction) is much debated in grammar circles (http://en.wikipedia.org/wiki/Serial_comma). And who doesn't enjoy a rousing debate about grammar? (Don't answer that)
+
+By default, SeriesJoiner sides with The New York Times stylebook and does not use the serial comma. However, so as not to offend adherents to The Chicago Manual of Style, the <tt>:final_delimiter</tt> option can be set to <tt>','</tt> to include it. For example:
 
   ['a', 'b', 'c'].join_as_series(:final_delimiter => ',') #=> 'a, b, and c'
 
+== I18n Support
+
+If you're using SeriesJoiner in a project with I18n support, such as Rails, include the following translations for your locales:
+
+  en:
+    series_joiner:
+      default_delimiter: ', '
+      default_final_delimiter: ''
+      default_conjunction: ' and '
+
 == Implementation
 
 This gem is generated with jeweler and uses shoulda for testing. To run tests:
@@ -54,11 +66,10 @@ This gem is generated with jeweler and uses shoulda for testing. To run tests:
 
 == Notes
 
-This gem may be compared with the Rails ActiveSupport extension to Array <tt>to_sentence()</tt> (https://github.com/rails/rails/blob/master/activesupport/lib/active_support/core_ext/array/conversions.rb). Here are a couple differences:
+This gem's <tt>join_as_series()</tt> method may be compared with the similar <tt>to_sentence()</tt> method implemented in ActiveSupport  (https://github.com/rails/rails/blob/master/activesupport/lib/active_support/core_ext/array/conversions.rb). There are several differences:
 * <tt>to_sentence()</tt> requires ActiveSupport, while <tt>join_as_series</tt> has no dependencies;
-* <tt>to_sentence()</tt> has I18n support baken in; and,
-* <tt>to_sentence()</tt> implements the serial comma (see definition above) by default, while <tt>join_as_series</tt> does not; and,
-* <tt>to_sentence()</tt> requires two options (<tt>:two_words_connector</tt> and <tt>:last_word_connector</tt>) to override a conjunction, instead of the one (<tt>:conjunction</tt>) required by <tt>join_as_series</tt>.
+* <tt>to_sentence()</tt> implements the serial comma (see definition above) by default, while <tt>join_as_series()</tt> does not; and,
+* <tt>to_sentence()</tt> requires two options (<tt>:two_words_connector</tt> and <tt>:last_word_connector</tt>) to override a conjunction, instead of the one (<tt>:conjunction</tt>) required by <tt>join_as_series()</tt>.
 
 == License
 

data/VERSION

@@ -1 +1 @@
-1.1.1
+1.2.0

data/lib/series_joiner.rb

@@ -1,15 +1,24 @@
 module SeriesJoiner
-  # join_as_series - join items in an array together in a grammatically correct manner
-  #
-  # options:
-  #   :delimiter       => inserted between items, except for the final two (default => ',')
-  #   :final_delimiter => inserted between the final two items (if > 2), but before the conjunction (default => '')
-  #   :conjunction     => inserted between the final two items (default => 'and')
+  # Joins items in an array together in a grammatically correct manner.
   #
+  # Options:
+  # * <tt>delimiter</tt> - inserted between items, except for the final two (default: ', ')
+  # * <tt>final_delimiter</tt> - inserted between the final two items (if > 2), but before the conjunction (default: '')
+  # * <tt>conjunction</tt> - inserted between the final two items (default: ' and ')
   def join_as_series(options = {})
-    delimiter = options[:delimiter] || ', '
-    final_delimiter = options[:final_delimiter] || ''
-    conjunction = options[:conjunction] || ' and '
+    if defined?(I18n)
+      default_delimiter       = I18n.translate(:'series_joiner.default_delimiter',       :locale => options[:locale])
+      default_final_delimiter = I18n.translate(:'series_joiner.default_final_delimiter', :locale => options[:locale])
+      default_conjunction     = I18n.translate(:'series_joiner.default_conjunction',     :locale => options[:locale])
+    else
+      default_delimiter       = ', '
+      default_final_delimiter = ''
+      default_conjunction     = ' and '
+    end
+    
+    delimiter = options[:delimiter] || default_delimiter
+    final_delimiter = options[:final_delimiter] || default_final_delimiter
+    conjunction = options[:conjunction] || default_conjunction
 
     sz = self.size
     if sz > 0

data/series_joiner.gemspec

@@ -5,7 +5,7 @@
 
 Gem::Specification.new do |s|
   s.name = %q{series_joiner}
-  s.version = "1.1.1"
+  s.version = "1.2.0"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Dan Gebhardt"]

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: series_joiner
 version: !ruby/object:Gem::Version 
-  hash: 17
+  hash: 31
   prerelease: 
   segments: 
   - 1
-  - 1
-  - 1
-  version: 1.1.1
+  - 2
+  - 0
+  version: 1.2.0
 platform: ruby
 authors: 
 - Dan Gebhardt