first_and_only 1.0.0 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 2b4c91e830188491065f0ce936d55c0cfee7757e
-  data.tar.gz: 9d85444ffd3680109fb97e7ebfa49289681cbabc
+  metadata.gz: 9f854f3edf7c69ae6b88c87c29678b91678ed91c
+  data.tar.gz: c2d49e72515a4d1bac8367c76ecfaa473efed78c
 SHA512:
-  metadata.gz: 7c00ff20741d3eac47a38b9815a87a3fd2e270dcf194f6155e9e702466909c7d2c877eb53d2e598940790aaa0743eede95650eb01fc57ac81c486bb10ed4a383
-  data.tar.gz: 0ebc077a6d80d5e47de14de7d5c1e3d17c71e07be4ec4a7972958815c3a57a07a03435733b88f17045d2aeee4b8d3e992aed643922bff4a95444fa4009db83b0
+  metadata.gz: a477760c26ecaabfc516a8968ccab37467bcba33ee5197d15eae078f56f235a71acb02868c0932bc0203cef3bf99a44f3d17c71b0e72e349aaf4c50b5de921c2
+  data.tar.gz: cd2cd50bbed8f4f40ed478f5d20ade952272a5047cc7f6144c17657374e177a13df713f918bb8687947bab43ea946e03e14b107839e29e582d508fa800056eab

data/.travis.yml

@@ -0,0 +1,7 @@
+language: ruby
+rvm:
+ - "1.9.3"
+ - "2.0.0"
+ - "2.1.0"
+ - "2.2.3"
+script: bundle exec rspec

data/README.md

@@ -1,24 +1,52 @@
 # FirstAndOnly
 
-TODO: Write a gem description
+Get the first element from an enumerable, and assert that there is only one element to take.
+
+```
+[:just_one].first_and_only!  # => :just_one
+```
+
+```
+[].first_and_only!  # =>  0 (Enumerable::FirstAndOnly::CountNotOne)
+```
+
+```
+[:one, :and_two].first_and_only!  # => 2 (Enumerable::FirstAndOnly::CountNotOne)
+```
+
+## Why?
+
+Sometimes in a spec you have a collection object that you know only has one element.  You set it up this way.  Later spec refactors may accidentally introduce a second element.  To prevent accidental false positives, and to make fixing failures introduced by this easier, you can use `#first_and_only!` to codify the "there is only one" assumption.
+
+Another common use case for `#first_and_only` is `id` assertions on HTML documents.  A valid HTML document can only have one occurrence of each `id` attribute, but authoring tools and browsers don't typically enforce this.  If you hang your JavaScript of the "only one" assumption of `id` attributes, you should enforce this with a specification.
+
+This gem follows the same line of thinking as the [fetching gem](https://github.com/covermymeds/fetching-gem)
 
 ## Installation
 
 Add this line to your application's Gemfile:
 
-    gem 'first_and_only'
+```
+gem 'first_and_only'
+```
 
 And then execute:
 
-    $ bundle
+```
+$ bundle
+```
 
 Or install it yourself as:
 
-    $ gem install first_and_only
+```
+$ gem install first_and_only
+```
 
-## Usage
+## Running specs
 
-TODO: Write usage instructions here
+```
+bundle exec rspec
+```
 
 ## Contributing
 

data/first_and_only.gemspec

@@ -17,11 +17,11 @@ Get the first element from an enumerable, and assert that there is only one elem
 ```
 
 ```
-[].first_and_only!  # =>  0 (Enumerable::FirstAndOnly::LengthNotOne)
+[].first_and_only!  # =>  0 (Enumerable::FirstAndOnly::CountNotOne)
 ```
 
 ```
-[:one, :and_two].first_and_only!  # => 2 (Enumerable::FirstAndOnly::LengthNotOne)
+[:one, :and_two].first_and_only!  # => 2 (Enumerable::FirstAndOnly::CountNotOne)
 ```
   SUMMARY
   spec.homepage      = "https://github.com/dapplebeforedawn/first-and-only-gem"
@@ -34,4 +34,5 @@ Get the first element from an enumerable, and assert that there is only one elem
 
   spec.add_development_dependency "bundler", "~> 1.3"
   spec.add_development_dependency "rake"
+  spec.add_development_dependency "rspec", "~> 2.14.1"
 end

data/lib/first_and_only.rb

@@ -2,11 +2,15 @@ require "first_and_only/version"
 
 module Enumerable
   def first_and_only!
-    fail(FirstAndOnly::LengthNotOne, count) if first(2).count != 1
+    fail(FirstAndOnly::CountNotOne.new count) if first(2).count != 1
     first
   end
 
   module FirstAndOnly
-    LengthNotOne = Class.new(StandardError)
+    class CountNotOne < StandardError
+      def initialize(count)
+        super("Expected the count to be 1, but it was #{count}.")
+      end
+    end
   end
 end

data/lib/first_and_only/version.rb

@@ -1,3 +1,3 @@
 module FirstAndOnly
-  VERSION = "1.0.0"
+  VERSION = "2.0.0"
 end

data/spec/first_and_only_spec.rb

@@ -0,0 +1,79 @@
+require "spec_helper"
+
+describe "Enumerable#first_and_only!" do
+
+  shared_examples_for "it_has_one_element" do
+    specify { expect(subject.first_and_only!).to eq(:element) }
+  end
+
+  shared_examples_for "it_is_empty" do
+    specify do
+      expect { subject.first_and_only! }.to raise_error(
+        Enumerable::FirstAndOnly::CountNotOne,
+        "Expected the count to be 1, but it was 0."
+      )
+    end
+  end
+
+  shared_examples_for "it_has_more_than_one_element" do
+    specify do
+      fail "bad example" if subject.count < 2
+
+      expect { subject.first_and_only! }.to raise_error(
+        Enumerable::FirstAndOnly::CountNotOne,
+        "Expected the count to be 1, but it was #{subject.count}."
+      )
+    end
+  end
+
+  describe "an array" do
+
+    context "with one element" do
+      subject { [:element] }
+      it_behaves_like "it_has_one_element"
+    end
+
+    context "that is empty" do
+      subject { [] }
+      it_behaves_like "it_is_empty"
+    end
+
+    context "with two elements" do
+      subject { [:element, :element] }
+      it_behaves_like "it_has_more_than_one_element"
+    end
+  end
+
+  describe "any enumerable" do
+    let(:my_enumerable) do
+      Class.new do
+        include Enumerable
+
+        def initialize *args
+          @args = args
+        end
+
+        def each
+          @args.each { |arg| yield(arg) }
+        end
+      end
+    end
+
+    context "with one element" do
+      subject { my_enumerable.new(:element) }
+      it_behaves_like "it_has_one_element"
+    end
+
+    context "empty" do
+      subject { my_enumerable.new() }
+      it_behaves_like "it_is_empty"
+    end
+
+    context "with more than on element" do
+      subject { my_enumerable.new(:element, :element) }
+      it_behaves_like "it_has_more_than_one_element"
+    end
+
+  end
+
+end

data/spec/spec_helper.rb

@@ -0,0 +1,13 @@
+require "first_and_only"
+require "rspec/autorun"
+require "pathname"
+
+Pathname(__FILE__).dirname.join("support").each_child { |f| require f }
+
+RSpec.configure do |config|
+  # Run specs in random order to surface order dependencies. If you find an
+  # order dependency and want to debug it, you can fix the order by providing
+  # the seed, which is printed after each run.
+  #     --seed 1234
+  config.order = "random"
+end

data/spec/support/vim_formatter.rb

@@ -0,0 +1,35 @@
+# Adapted from https://github.com/bronson/vim-runtest/blob/master/rspec_formatter.rb.
+require "rspec/core/formatters/base_text_formatter"
+
+class VimFormatter < RSpec::Core::Formatters::BaseTextFormatter
+
+  def example_failed example
+    exception = example.execution_result[:exception]
+    path = Regexp.last_match[1] if exception.backtrace.find do |frame|
+      frame =~ %r{\b(spec/.*_spec\.rb:\d+)(?::|\z)}
+    end
+    message = format_message exception.message
+    path    = format_caller(path || " ")
+    output.puts "#{path}: #{example.example_group.description.strip} " \
+      "#{example.description.strip}: #{message.strip}" if path
+  end
+
+  def example_pending *_args; end
+
+  def dump_failures   *_args; end
+
+  def dump_pending    *_args; end
+
+  def message          _msg;  end
+
+  def dump_summary    *_args; end
+
+  def seed            *_args; end
+
+  private
+
+  def format_message msg
+    msg.gsub("\n", " ")[0, 80]
+  end
+
+end

metadata

@@ -1,43 +1,57 @@
 --- !ruby/object:Gem::Specification
 name: first_and_only
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 2.0.0
 platform: ruby
 authors:
 - Mark Lorenz
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-07-05 00:00:00.000000000 Z
+date: 2015-10-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ~>
+    - - "~>"
       - !ruby/object:Gem::Version
         version: '1.3'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ~>
+    - - "~>"
       - !ruby/object:Gem::Version
         version: '1.3'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 2.14.1
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 2.14.1
 description: |
   Get the first element from an enumerable, and assert that there is only one element to take.
 email:
@@ -46,7 +60,8 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- .gitignore
+- ".gitignore"
+- ".travis.yml"
 - Gemfile
 - LICENSE.txt
 - README.md
@@ -54,6 +69,9 @@ files:
 - first_and_only.gemspec
 - lib/first_and_only.rb
 - lib/first_and_only/version.rb
+- spec/first_and_only_spec.rb
+- spec/spec_helper.rb
+- spec/support/vim_formatter.rb
 homepage: https://github.com/dapplebeforedawn/first-and-only-gem
 licenses:
 - MIT
@@ -64,20 +82,23 @@ require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
-  - - '>='
+  - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - '>='
+  - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.2.2
+rubygems_version: 2.4.8
 signing_key: 
 specification_version: 4
-summary: '``` [:just_one].first_and_only!  # => :just_one ```  ``` [].first_and_only!  #
-  =>  0 (Enumerable::FirstAndOnly::LengthNotOne) ```  ``` [:one, :and_two].first_and_only!  #
-  => 2 (Enumerable::FirstAndOnly::LengthNotOne) ```'
-test_files: []
+summary: "``` [:just_one].first_and_only!  # => :just_one ```  ``` [].first_and_only!
+  \ # =>  0 (Enumerable::FirstAndOnly::CountNotOne) ```  ``` [:one, :and_two].first_and_only!
+  \ # => 2 (Enumerable::FirstAndOnly::CountNotOne) ```"
+test_files:
+- spec/first_and_only_spec.rb
+- spec/spec_helper.rb
+- spec/support/vim_formatter.rb