series_joiner 1.2.2 → 1.2.3

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2011 Cerebris Corporation
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,91 @@
+# SeriesJoiner [![Build Status](https://secure.travis-ci.org/cerebris/series_joiner.png)](http://travis-ci.org/cerebris/series_joiner)
+
+A gem for joining items in arrays together into grammatically correct series, such as "a, b and c". 
+
+SeriesJoiner extends the `Array` class with a `join_as_series()` method which is similar to the built-in `join()` method. However, `join_as_series()` allows for custom delimiters and conjunctions. 
+
+## Installation
+
+Run the following (perhaps as sudo):
+
+```
+gem install series_joiner
+```
+
+## Bundler Configuration
+
+Add the following to your Gemfile:
+
+```
+gem 'series_joiner'
+```
+
+## Usage
+
+`join_as_series()` 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 => '')
+:conjunction     # inserted between the final two items (default => ' and ')
+```
+
+By default, items are joined as follows:
+
+```
+['a'].join_as_series #=> 'a'
+
+['a', 'b'].join_as_series #=> 'a and b'
+
+['a', 'b', 'c'].join_as_series #=> 'a, b and c'
+
+['a', 'b', 'c', 'd'].join_as_series #=> 'a, b, c and d'
+```
+
+Here are some examples using custom delimiters and/or conjunctions:
+
+```
+['a', 'b', 'c'].join_as_series(:delimiter => '; ') #=> 'a; b and c'
+
+['a', 'b', 'c'].join_as_series(:conjunction => ' or ') #=> 'a, b or c'
+
+['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 circles (http://en.wikipedia.org/wiki/Serial_comma). And who doesn't enjoy a rousing debate about grammar? Don't answer that. Anyway, SeriesJoiner does not use the serial comma by default. If you prefer to use it, just set the `:final_delimiter` option to `','`:
+
+```
+['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, include the following translations for your locales:
+
+```
+  en:
+    series_joiner:
+      default_delimiter: ', '
+      default_final_delimiter: ''
+      default_conjunction: ' and '
+```
+
+## Tests
+
+This gem uses rspec for testing. To test:
+
+```
+rake spec
+```
+
+## Notes
+
+This gem's `join_as_series()` method may be compared with the similar `to_sentence()` method implemented in ActiveSupport  (https://github.com/rails/rails/blob/master/activesupport/lib/active_support/core_ext/array/conversions.rb). There are several differences:
+
+ * `to_sentence()` is part of ActiveSupport, while `join_as_series` is independent;
+ * `to_sentence()` implements the serial comma (see definition above) by default, while `join_as_series()` does not; and,
+ * `to_sentence()` requires two options (`:two_words_connector` and `:last_word_connector`) to override a conjunction, instead of the one (`:conjunction`) required by `join_as_series()`.
+
+## License
+
+Copyright (c) 2011 Cerebris Corporation. This is free software released under the MIT License (see MIT-LICENSE for details).

data/Rakefile

@@ -0,0 +1,6 @@
+require "bundler/gem_tasks"
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/lib/series_joiner/version.rb

@@ -1,3 +1,3 @@
 module SeriesJoiner
-  VERSION = "1.2.2"
+  VERSION = "1.2.3"
 end

data/spec/series_joiner_spec.rb

@@ -0,0 +1,89 @@
+require 'spec_helper'
+
+describe SeriesJoiner do
+  describe "using default options" do
+    it "should join an empty array as nil" do
+      [].join_as_series.should eq nil
+    end
+    it "should join an array of one item" do
+      ['a'].join_as_series.should eq 'a'
+    end
+    it "should join an array of two items" do
+      ['a', 'b'].join_as_series.should eq 'a and b'
+    end
+    it "should join an array of three items" do
+      ['a', 'b', 'c'].join_as_series.should eq 'a, b and c'
+    end
+    it "should join an array of four items" do
+      ['a', 'b', 'c', 'd'].join_as_series.should eq 'a, b, c and d'
+    end
+  end
+  
+  describe "using an 'or' conjunction" do
+    let(:options) { {:conjunction => ' or '} }
+    
+    it "should join an array of one item" do
+      ['a'].join_as_series(options).should eq 'a'
+    end
+    it "should join an array of two items" do
+      ['a', 'b'].join_as_series(options).should eq 'a or b'
+    end
+    it "should join an array of three items" do
+      ['a', 'b', 'c'].join_as_series(options).should eq 'a, b or c'
+    end
+    it "should join an array of four items" do
+      ['a', 'b', 'c', 'd'].join_as_series(options).should eq 'a, b, c or d'
+    end
+  end
+
+  describe "using a ';' delimiter" do
+    let(:options) { {:delimiter => '; '} }
+    
+    it "should join an array of one item" do
+      ['a'].join_as_series(options).should eq 'a'
+    end
+    it "should join an array of two items" do
+      ['a', 'b'].join_as_series(options).should eq 'a and b'
+    end
+    it "should join an array of three items" do
+      ['a', 'b', 'c'].join_as_series(options).should eq 'a; b and c'
+    end
+    it "should join an array of four items" do
+      ['a', 'b', 'c', 'd'].join_as_series(options).should eq 'a; b; c and d'
+    end
+  end
+
+  describe "using a ';' delimiter properly" do
+    let(:options) { {:delimiter => '; ', :conjunction => '; or, '} }
+    
+    it "should join an array of one item" do
+      ['a'].join_as_series(options).should eq 'a'
+    end
+    it "should join an array of two items" do
+      ['a', 'b'].join_as_series(options).should eq 'a; or, b'
+    end
+    it "should join an array of three items" do
+      ['a', 'b', 'c'].join_as_series(options).should eq 'a; b; or, c'
+    end
+    it "should join an array of four items" do
+      ['a', 'b', 'c', 'd'].join_as_series(options).should eq 'a; b; c; or, d'
+    end
+  end
+
+  describe "using a ',' final delimiter" do
+    let(:options) { {:final_delimiter => ','} }
+
+    it "should join an array of one item" do
+      ['a'].join_as_series(options).should eq 'a'
+    end
+    it "should join an array of two items" do
+      ['a', 'b'].join_as_series(options).should eq 'a and b'
+    end
+    it "should join an array of three items" do
+      ['a', 'b', 'c'].join_as_series(options).should eq 'a, b, and c'
+    end
+    it "should join an array of four items" do
+      ['a', 'b', 'c', 'd'].join_as_series(options).should eq 'a, b, c, and d'
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1 @@
+require 'series_joiner'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: series_joiner
 version: !ruby/object:Gem::Version
-  version: 1.2.2
+  version: 1.2.3
   prerelease: 
 platform: ruby
 authors:
@@ -9,11 +9,11 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-02-10 00:00:00.000000000 Z
+date: 2012-02-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec
-  requirement: &70182283182780 !ruby/object:Gem::Requirement
+  requirement: &70142208065620 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -21,7 +21,7 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70182283182780
+  version_requirements: *70142208065620
 description: Extends Array with a join_as_series() method for joining arrays of items
   together into grammatically correct series. Useful for joining series like 'a, b
   and c'. Custom delimiters and conjunctions can be specified.
@@ -30,9 +30,14 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- lib/series_joiner.rb
 - lib/series_joiner/array_additions.rb
 - lib/series_joiner/version.rb
+- lib/series_joiner.rb
+- MIT-LICENSE
+- Rakefile
+- README.md
+- spec/series_joiner_spec.rb
+- spec/spec_helper.rb
 homepage: https://github.com/cerebris/series_joiner
 licenses: []
 post_install_message: 
@@ -57,5 +62,7 @@ rubygems_version: 1.8.10
 signing_key: 
 specification_version: 3
 summary: Join items in arrays together into grammatically correct series.
-test_files: []
+test_files:
+- spec/series_joiner_spec.rb
+- spec/spec_helper.rb
 has_rdoc: