subclass_must_implement 0.0.1 → 0.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: be7eacd344df936c6557036eed810d353b476445
-  data.tar.gz: f7c20318294fc06bb3ff92a2776d81f7cc8fb5d6
+  metadata.gz: b9eaa616a9b8edf88f77acd435aae5663f5f7263
+  data.tar.gz: 459bd4737551b160317f6cec391be93c23a73666
 SHA512:
-  metadata.gz: 5de082a47ac63d76765acfa7bbb2777c7a067ba91861903862dd4b2430b380fd0addbe3d79bdf809780861b124cbbc8f9d3043dce4b8cc3814cd23925a91ebeb
-  data.tar.gz: 3aec63e7c84a7983315504ff8e0fefd81ade0bc02bf4555f2f81891e5b4ee4e97dda9a2a2157b71a36f571c2580b778aa56b80cca191c2e2a1a9ec13567e2af2
+  metadata.gz: d211c4b1ded0fce194fcf8c745cc79e4029d4d50cb37b4cb9a1258b00e7d4900cbe9337805eb4dddbf62c27982a918d59592dbfc6ffb032021ec7c8008dfadbc
+  data.tar.gz: c16e69619f667b52bccd90c8a160cd71bb6e40d4332546a63153d805b147a0bed880d41a8e2a8ba908f7f193eeffad8e16b768153218421b90d9c39c61748efb

data/.gitignore

@@ -21,4 +21,3 @@ tmp
 *.a
 mkmf.log
 .ruby-version
-

data/.simplecov

@@ -8,6 +8,7 @@ SimpleCov.formatter = SimpleCov::Formatter::MultiFormatter.new([
 
 SimpleCov.start do
   add_filter "/spec/"
+  add_filter "/lib/subclass_must_implement/rspec_matchers"
 
   # Fail the build when coverage is < 100%:
   at_exit do

data/README.md

@@ -1,7 +1,10 @@
 # SubclassMustImplement
 
-There are circumstances when it is desirable to specify certain methods as abstract, i.e. it is the responsibility of any subclass to implement them.
-Getting a `MethodMIssing` is not helpful; an error that explicitly explains that the missing method is required by contract will save much time.
+There are circumstances when it is desirable to specify certain methods as abstract,
+i.e. it is the responsibility of any subclass to implement them.
+Getting a `MethodMIssing` is not helpful; an error that explicitly explains that the
+missing method is required by contract to fully implement the interface will save much
+time and frustration.
 
 ## Installation
 
@@ -65,6 +68,36 @@ b.bar # return :bar
 b.foo # raises a NotImplementedError with the specified error message "Version expected!!!"
 ```
 
+## Using With RSpec
+
+There is a custom [RSpec](http://rspec.info/) matcher included to simplify testing.
+
+Example:
+
+```ruby
+# NOTE: depending on gem load order, you may need to manually load the matcher.
+# If so, add the following line to your `spec_helper.rb`
+require "subclass_must_implement/rspec_matcher/require_subclass_to_implement_matcher"
+
+# Given the following class:
+class BaseBar
+  extend SubclassMustImplement
+
+  subclass_must_implement :foo, :bar, err_message: "Version expected!!!"
+end
+
+# Test to ensure required functionality is specified:
+
+# Custom error messages can be specified
+it { expect(BaseBar).to require_subclass_to_implement(:version).with_error_message("Version expected!!!")}
+
+# Either the class or the instance can be passed to the matcher
+it { expect(BaseBar.new).to require_subclass_to_implement(:sub_version) }
+
+# Sometimes it makes sense to specify certain methods as not required
+it { expect(BaseBar).to_not require_subclass_to_implement(:foo) }
+```
+
 ## Contributing
 
 1. Fork it ( https://github.com/[my-github-username]/subclass_must_implement/fork )

data/lib/subclass_must_implement.rb

@@ -42,29 +42,39 @@
 #
 module SubclassMustImplement
 
-  # Injects the `subclass_must_implement` macro
+  # Inject the `subclass_must_implement` macro.
   def self.included(base)
     base.extend ClassMethods
   end
 
-  # Injects the `subclass_must_implement` macro
+  # Inject the `subclass_must_implement` macro.
   def self.extended(base)
     base.extend ClassMethods
   end
 
-  # Returns the Gem version as a string
+  # Return the Gem version as a string.
+  # @return [String]
   def self.version
-    "0.0.1"
+    "0.0.2"
+  end
+
+  # Create the default error message for the given method name.
+  # @param method_name [String|Symbol]
+  # @return [String]
+  def self.default_error_message(method_name)
+    "`#{method_name}` must be implemented in a subclass."
   end
 
   # The class level macros are defined here.
   module ClassMethods
 
-    # Defines a method for each method name that raises a NotImplementedError when called.
+    # Define a method for each method name that raises a NotImplementedError when called.
     # Pass in a custom error message if desired using the err_message named argument.
+    # @param method_names [Enumerable<Symbol>]
+    # @param err_message [String]
     def subclass_must_implement(*method_names, err_message: nil)
       method_names.each do |method_name|
-        err = err_message.nil? ? "`#{method_name}` must be implemented in a subclass." : "#{err_message}"
+        err = err_message.nil? ? ::SubclassMustImplement.default_error_message(method_name) : "#{err_message}"
         define_method method_name do |*_|
           raise NotImplementedError, err
         end
@@ -72,3 +82,7 @@ module SubclassMustImplement
     end
   end
 end
+
+if defined? RSpec
+  require "subclass_must_implement/rspec_matchers/require_subclass_to_implement_matcher"
+end

data/lib/subclass_must_implement/rspec_matchers/require_subclass_to_implement_matcher.rb

@@ -0,0 +1,42 @@
+require "rspec/expectations"
+
+RSpec::Matchers.define :require_subclass_to_implement do |method_name|
+
+  chain :with_error_message do |err_message|
+    @err_message = err_message
+  end
+
+  match do |klass|
+    item = if klass.is_a?(Class)
+             klass.new
+           else
+             klass
+           end
+
+    if item.respond_to?(method_name)
+      begin
+        item.__send__ method_name
+        false
+      rescue NotImplementedError => err
+        @err_message ||= ::SubclassMustImplement.default_error_message(method_name)
+        err.message == @err_message
+      end
+    else
+      false
+    end
+
+  end # match do
+
+  failure_message do
+    "should require subclasses to implement method `#{method_name}`, " \
+    "otherwise raise a NotImplementedError with message '#{@err_message}'"
+  end
+
+  failure_message_when_negated do
+    "should not require method `#{method_name}` to be implemented by subclasses"
+  end
+
+  description do
+    "method `#{method_name}` must be implemented by subclasses"
+  end
+end

data/spec/spec_helper.rb

@@ -1,6 +1,8 @@
 require 'simplecov'
 SimpleCov.start
 
+load "subclass_must_implement.rb"
+
 # See http://rubydoc.info/gems/rspec-core/RSpec/Core/Configuration
 RSpec.configure do |config|
   # rspec-expectations config goes here. You can use an alternate

data/spec/subclass_must_implement_spec.rb

@@ -30,7 +30,7 @@ RSpec.describe SubclassMustImplement do
   let(:bar) { Bar.new }
 
   context "module included" do
-    it "will raise a not implemented error if any required method is not implemented in the subclass" do
+    it "will raise a NotImplementedError if any required method is not implemented in the subclass" do
       expect { foo.bar }.to raise_error(NotImplementedError, "`bar` must be implemented in a subclass.")
       expect { foo.baz }.to raise_error(NotImplementedError, "`baz` must be implemented in a subclass.")
     end
@@ -41,7 +41,7 @@ RSpec.describe SubclassMustImplement do
   end
 
   context "module extended" do
-    it "will raise a not implemented error if any required method is not implemented in the subclass" do
+    it "will raise a NotImplementedError if any required method is not implemented in the subclass" do
       expect { bar.sub_version }.to raise_error(NotImplementedError, "Version expected!!!")
     end
 
@@ -49,4 +49,14 @@ RSpec.describe SubclassMustImplement do
       expect(bar.version).to eq(described_class.version)
     end
   end
+
+  context "matcher" do
+    it { expect(BaseFoo    ).to require_subclass_to_implement(:foo) }
+    it { expect(BaseFoo.new).to require_subclass_to_implement(:bar) }
+    it { expect(BaseFoo).not_to require_subclass_to_implement(:qux) }
+
+    it do
+      expect(BaseBar).to require_subclass_to_implement(:version).with_error_message("Version expected!!!")
+    end
+  end
 end

data/subclass_must_implement.gemspec

@@ -24,4 +24,5 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency "simplecov"
   spec.add_development_dependency "simplecov-rcov-text"
   spec.add_development_dependency "colorize"
+  spec.add_development_dependency "yard"
 end

data/tags

@@ -0,0 +1,40 @@
+!_TAG_FILE_FORMAT	2	/extended format; --format=1 will not append ;" to lines/
+!_TAG_FILE_SORTED	1	/0=unsorted, 1=sorted, 2=foldcase/
+!_TAG_PROGRAM_AUTHOR	Darren Hiebert	/dhiebert@users.sourceforge.net/
+!_TAG_PROGRAM_NAME	Exuberant Ctags	//
+!_TAG_PROGRAM_URL	http://ctags.sourceforge.net	/official site/
+!_TAG_PROGRAM_VERSION	5.8	//
+AllFiles	coverage/index.html	32;"	a	line:32
+Bar	spec/subclass_must_implement_spec.rb	23;"	c	line:23
+BaseBar	spec/subclass_must_implement_spec.rb	17;"	c	line:17
+BaseFoo	spec/subclass_must_implement_spec.rb	5;"	c	line:5
+ClassMethods	lib/subclass_must_implement.rb	61;"	m	line:61	class:SubclassMustImplement
+Foo	spec/subclass_must_implement_spec.rb	11;"	c	line:11
+K.D	coverage/assets/0.10.2/application.js	17;"	f	line:17
+K.E	coverage/assets/0.10.2/application.js	17;"	f	line:17
+K.l	coverage/assets/0.10.2/application.js	17;"	f	line:17
+K.m	coverage/assets/0.10.2/application.js	17;"	f	line:17
+SubclassMustImplement	lib/subclass_must_implement.rb	43;"	m	line:43
+V.N	coverage/assets/0.10.2/application.js	17;"	f	line:17
+b$.bA	coverage/assets/0.10.2/application.js	17;"	f	line:17
+b$.bW	coverage/assets/0.10.2/application.js	17;"	f	line:17
+b$.bX	coverage/assets/0.10.2/application.js	17;"	f	line:17
+b$.bY	coverage/assets/0.10.2/application.js	17;"	f	line:17
+b$.bZ	coverage/assets/0.10.2/application.js	17;"	f	line:17
+b$.bi	coverage/assets/0.10.2/application.js	17;"	f	line:17
+b$.bj	coverage/assets/0.10.2/application.js	17;"	f	line:17
+b$.bk	coverage/assets/0.10.2/application.js	17;"	f	line:17
+b$.bl	coverage/assets/0.10.2/application.js	17;"	f	line:17
+b$.bm	coverage/assets/0.10.2/application.js	17;"	f	line:17
+bh.bg	coverage/assets/0.10.2/application.js	17;"	f	line:17
+cp.ce	coverage/assets/0.10.2/application.js	17;"	f	line:17
+cp.cf	coverage/assets/0.10.2/application.js	17;"	f	line:17
+extended	lib/subclass_must_implement.rb	51;"	F	line:51	class:SubclassMustImplement
+foo	spec/subclass_must_implement_spec.rb	12;"	f	line:12	class:Foo
+function.cr	coverage/assets/0.10.2/application.js	17;"	f	line:17
+included	lib/subclass_must_implement.rb	46;"	F	line:46	class:SubclassMustImplement
+k.function.J	coverage/assets/0.10.2/application.js	17;"	f	line:17
+k.var.e	coverage/assets/0.10.2/application.js	17;"	f	line:17
+subclass_must_implement	lib/subclass_must_implement.rb	65;"	f	line:65	class:SubclassMustImplement.ClassMethods
+version	lib/subclass_must_implement.rb	56;"	F	line:56	class:SubclassMustImplement
+version	spec/subclass_must_implement_spec.rb	24;"	f	line:24	class:Bar

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: subclass_must_implement
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.2
 platform: ruby
 authors:
 - Arthur Shagall
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-04-08 00:00:00.000000000 Z
+date: 2018-04-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -94,6 +94,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: yard
+  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'
 description: Auto-generate abstract method stubs to mark them as required to be implemented
   in subclasses.
 email:
@@ -111,9 +125,11 @@ files:
 - README.md
 - Rakefile
 - lib/subclass_must_implement.rb
+- lib/subclass_must_implement/rspec_matchers/require_subclass_to_implement_matcher.rb
 - spec/spec_helper.rb
 - spec/subclass_must_implement_spec.rb
 - subclass_must_implement.gemspec
+- tags
 homepage: ''
 licenses:
 - MIT