duck_puncher 2.9.3 → 2.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: b2ebd6df2befa524cfa62d7e94bd86c95b6e05f4
-  data.tar.gz: efc4ed3226ffb5ed36fafd67735d294a48f0f8e2
+  metadata.gz: e0a5aa2de7709f8b53e6ab183581335b3493eb5e
+  data.tar.gz: 9838712103fbf49a3614ee930b53c6c7171457b8
 SHA512:
-  metadata.gz: e13d18b83abee84c985762eb05639c63a8a9e32f2a936d709c4a26b100cb5e95008ee561640d16f2ccf5fca4aedf6745347cf2d26e2026637ddae5dc2ed9d693
-  data.tar.gz: 4d777965f7a99d0cec674d290d9290b512394068e9cca996b59565e27e640a29bb3308d0079aa0132a672cc73a6223fc2421acb8de064ed52e1f6ea1310c598b
+  metadata.gz: d3d4032fcfd695eaec9baeaaa6d4c4c6f9d6e8144cbfaa5cd01edda887320818fac8d55b5b49391f1edc129db8d703ad275449b191850236606bcfe16530a122
+  data.tar.gz: f3d6bb17dd490336d578d7e13747393b14233fc1c1da36857fc1966ea8384ae8a20ca2a716004391192662681e25674f9ef841b1fd70b12e4c079c0de518bfc0

data/README.md

@@ -1,26 +1,26 @@
-# DuckPuncher
+# DuckPuncher [![Gem Version](https://badge.fury.io/rb/duck_puncher.svg)](http://badge.fury.io/rb/duck_puncher)  [![Build Status](https://travis-ci.org/ridiculous/duck_puncher.svg)](https://travis-ci.org/ridiculous/duck_puncher) [![Code Climate](https://codeclimate.com/github/ridiculous/duck_puncher/badges/gpa.svg)](https://codeclimate.com/github/ridiculous/duck_puncher)
 
 Since Ruby objects walk and talk like ducks, they must therefore _be_ ducks. But ducks don't always behave, and some times they need
-tough love. You know, lil love punches! :punch: :heart:
+tough love! :punch: :heart:
 
 These are the ducks I love the most:
 
 ```ruby
-Array#m             => `[].m(:to_s)` => `[].map(&:to_s)` 
-Array#mm            => `[].mm(:sub, /[aeiou]/, '*')` => `[].map { |x| x.sub(/[aeiou]/, '*') }` 
-Array#get           => `[].methods.get('ty?')` => [:empty?] 
-Hash#dig            => `{a: 1, b: {c: 2}}.dig(:b, :c)` => 2 (Part of standard lib in Ruby >= 2.3)
-Numeric#to_currency => `25.245.to_currency` => 25.25 
-Numeric#to_duration => `10_000.to_duration` => '2 h 46 min'
-Numeric#to_time_ago => `10_000.to_time_ago` => '2 hours ago'
-Numeric#to_rad      => `10.15.to_rad` => 0.17715091907742445
-String#pluralize    => `'hour'.pluralize(2)` => "hours"
-String#underscore   => `'DuckPuncher::JSONStorage'.underscore` => 'duck_puncher/json_storage'
-Object#clone!       => `Object.new.clone!` => a deep clone of the object (using Marshal.dump)
-Object#punch        => `'duck'.punch` => a copy of 'duck' with the mixed String punches
-Object#track        => `'duck'.punch.track` => downloads the [ObjectTracker](https://github.com/ridiculous/object_tracker) gem if it's not available and starts tracking this object
-Method#to_instruct  => `Benchmark.method(:measure).to_instruct` returns the Ruby VM instruction sequence for the method
-Method#to_source    => `Benchmark.method(:measure).to_source` returns the method definition as a string
+Array   #m            => `[].m(:to_s)` => `[].map(&:to_s)` 
+        #mm           => `[].mm(:sub, /[aeiou]/, '*')` => `[].map { |x| x.sub(/[aeiou]/, '*') }` 
+        #get          => `[].methods.get('ty?')` => [:empty?] 
+Hash    #dig          => `{a: 1, b: {c: 2}}.dig(:b, :c)` => 2 (Part of standard lib in Ruby >= 2.3)
+Numeric #to_currency  => `25.245.to_currency` => 25.25 
+        #to_duration  => `10_000.to_duration` => '2 h 46 min'
+        #to_time_ago  => `10_000.to_time_ago` => '2 hours ago'
+        #to_rad       => `10.15.to_rad` => 0.17715091907742445
+String  #pluralize    => `'hour'.pluralize(2)` => "hours"
+        #underscore   => `'DuckPuncher::JSONStorage'.underscore` => 'duck_puncher/json_storage'
+Object  #clone!       => `Object.new.clone!` => a deep clone of the object (using Marshal.dump)
+        #punch        => `'duck'.punch` => a copy of 'duck' with the mixed String punches
+        #track        => `'duck'.punch.track` => downloads the [ObjectTracker](https://github.com/ridiculous/object_tracker) gem if it's not available and starts tracking this object
+Method  #to_instruct  => `Benchmark.method(:measure).to_instruct` returns the Ruby VM instruction sequence for the method
+        #to_source    => `Benchmark.method(:measure).to_source` returns the method definition as a string
 ```
 
 ## Tactical punches
@@ -29,7 +29,7 @@ Sometimes you don't want to punch all the ducks. That's why you can punch only c
 
 ```ruby
 >> DuckPuncher.punch! :Numeric, only: [:to_currency, :to_duration]
-INFO: Already punched Numeric
+WARN: Punching [:to_currency, :to_duration] onto Numeric
 => nil
 >> 100.to_currency '$'
 => "$100.00"
@@ -39,29 +39,6 @@ INFO: Already punched Numeric
 NoMethodError: undefined method `to_time_ago' for 100:Fixnum
 ```
 
-There is also an experimental punch that tries to download the required gem if it doesn't exist on your computer. The
-method is called `require!` and works like this:
-
-Downloads and activates a gem for the current and subsequent consoles. For example:
-
-```bash
->> `require 'pry'` 
-LoadError: cannot load such file -- pry
- from (irb):1:in `require'
- from (irb):1
- from bin/console:10:in `<main>'
->> require! 'pry'
-Fetching: method_source-0.8.2.gem (100%)
-Fetching: slop-3.6.0.gem (100%)
-Fetching: coderay-1.1.0.gem (100%)
-Fetching: pry-0.10.3.gem (100%)
-=> true
->> Pry.start
-[1] pry(main)>
-```
-
-Pretty cool, right? Although, it doesn't work well with bigger gems or those with native extensions.
-
 ## Install
 
     gem 'duck_puncher'
@@ -72,29 +49,92 @@ Ducks need to be _loaded_ before they can be punched! Maybe put this in an initi
 
 ```ruby
 # config/initializers/duck_puncher.rb
-DuckPuncher.punch_all!                   #=> punches all the ducks forever
-DuckPuncher.punch! :Hash, :Object        #=> only punches the Hash and Object ducks
-DuckPuncher.punch! :Object, only: :punch #=> only opens a can of whoop ass! Define one method to rule them all
+DuckPuncher.punch_all!                   # => punches all the ducks forever
+DuckPuncher.punch! :Hash, :Object        # => only punches the Hash and Object ducks
+DuckPuncher.punch! :Object, only: :punch # => only opens a can of whoop ass! Define one method to rule them all
 ```
 
-Create a new class of your favorite duck pre-punched:
+The `.punch` method creates and caches a new punched class that inherits from the original. This avoids altering built-in
+classes. For example:
 
 ```ruby
-DuckPuncher.punch :String               #=> returns an anonymous punched duck that inherits from String
-DuckString = DuckPuncher.punch :String  #=> give the anonymous duck a name, so that you can use it!
-DuckString.new.respond_to? :underscore  #=> true
+>> DuckPuncher.punch :String
+=> DuckPuncher::StringDuck
+>> DuckPuncher::StringDuck.new('Yes').to_boolean
+=> true
+>> String.new('Yes').respond_to? :to_boolean
+=> false
 ```
 
 If you punch `Object` then you can use `punch` on any object to get a new decorated copy of the class with the desired
 functionality mixed in:
 
 ```ruby
-DuckPuncher.punch! :Object, only: :punch
-%w[yes no 1].punch.m(:punch).punch.m(:to_boolean) #=> [true, false, true]
+>> DuckPuncher.punch! :Object, only: :punch
+>> %w[yes no 1].punch.m(:punch).punch.m(:to_boolean)
+=> [true, false, true]
 ```
 
 Because `DuckPuncher` extends the amazing [Usable](https://github.com/ridiculous/usable) gem, you can configure only the punches you want! 
 
+## Registering custom punches
+
+DuckPuncher allows you to utilize the `punch` interface to decorate any kind of object with your own punches. Simply call 
+`.register` with the name of your module:
+
+```ruby
+module Donald
+  def tap_tap
+    p self
+    self
+  end
+end
+
+DuckPuncher.register :Donald, class: 'Array', if: -> { !defined?(::Rails) || Rails.env.development? } 
+```
+
+The register method takes the same options as [Duck#initialize](https://github.com/ridiculous/duck_puncher/blob/master/lib/duck_puncher/duck.rb#L11)
+and will be used to configure punches.
+
+Activate a custom punch:
+
+```ruby
+DuckPuncher.punch! :Donald
+[].tap_tap
+# or
+DuckPuncher.punch! :Object, only: :punch
+[].punch(:Donald).tap_tap
+```
+
+## Experimental
+
+__Object#require__ will try to require a gem, or, if it's not found, then _download_ it! It will also keep track of any
+downloaded gems and load them for subsequent IRB/rails console sessions. Gems are _not_ 
+saved to the Gemfile.
+
+In the wild:
+
+```bash
+>> `require 'pry'` 
+LoadError: cannot load such file -- pry
+ from (irb):1:in `require'
+ from (irb):1
+ from bin/console:10:in `<main>'
+>> DuckPuncher.punch! :Object, only: :require!
+WARN: Punching require! onto Object
+=> nil
+>> require! 'pry'
+Fetching: method_source-0.8.2.gem (100%)
+Fetching: slop-3.6.0.gem (100%)
+Fetching: coderay-1.1.0.gem (100%)
+Fetching: pry-0.10.3.gem (100%)
+=> true
+>> Pry.start
+[1] pry(main)>
+```
+
+Perfect! Mostly ... although, it doesn't work well with bigger gems or those with native extensions ¯\\\_(ツ)_/¯
+
 ## Contributing
 
 * Fork it

data/Rakefile

@@ -7,7 +7,7 @@ Rake::TestTask.new(:soft_punch_test) do |t|
 end
 
 Rake::TestTask.new(:hard_punch_test) do |t|
-  t.pattern = 'test/duck_puncher/*_test.rb'
+  t.pattern = 'test/lib/**/*_test.rb'
 end
 
 task default: [:soft_punch_test, :hard_punch_test]

data/lib/duck_puncher/duck.rb

@@ -2,15 +2,20 @@ module DuckPuncher
   class Duck
     attr_accessor :name, :options
 
+    # @param [Symbol] name of the duck
+    # @param [Hash] options to modify the duck #punch method behavior
+    # @option options [String] :class (name) to punch
+    # @option options [Proc] :if Stops +punch+ if it returns false
+    # @option options [Proc] :before A hook that is called with the target @klass before +punch+
+    # @option options [Proc] :after A hook that is called with the target @klass after +punch+
     def initialize(name, options = {})
       @name = name
       @options = options
     end
 
-    def load_path
-      "duck_puncher/ducks/#{name.to_s.gsub(/\B([A-Z])/, '_\1').downcase}"
-    end
-
+    # @param [Hash] opts to modify punch
+    # @option options [Class] :target Overrides the @klass to be punched
+    # @option options [Array,Symbol] :only Specifies the methods to extend onto the current object
     def punch(opts = {})
       if options[:if] && !options[:if].call
         DuckPuncher.log.warn %Q(Failed to punch #{name}!)
@@ -28,8 +33,10 @@ module DuckPuncher
       @klass ||= (options[:class] || name).to_s.split('::').inject(Kernel) { |k, part| k.const_get part }
     end
 
-    def delegated
-      DelegateClass(klass).tap { |k| punch target: k }
+    # @param [Class] obj The object being punched
+    def delegated(obj = nil)
+      obj_class = obj ? obj.class : klass
+      DelegateClass(obj_class).tap { |k| punch target: k }
     end
 
     def classify

data/lib/duck_puncher/ducks/object.rb

@@ -11,8 +11,8 @@ module DuckPuncher
         end
       end
 
-      def punch
-        DuckPuncher.delegate_class(self.class.name.to_sym).new(self)
+      def punch(duck_name = self.class.name)
+        DuckPuncher.delegate_class(duck_name.to_sym, self).new(self)
       end
 
       def track

data/lib/duck_puncher/ducks.rb

@@ -17,6 +17,10 @@ module DuckPuncher
         list.find { |duck| duck.name == name.to_sym } ||
           DuckPuncher.log.info(%Q(Couldn't find "#{name}" in my list of Ducks! I know about: #{list.map(&:name).map(&:to_s)}))
       end
+
+      def load_path_for(duck)
+        "duck_puncher/ducks/#{duck.name.to_s.gsub(/\B([A-Z])/, '_\1').downcase}"
+      end
     end
 
     #
@@ -24,7 +28,7 @@ module DuckPuncher
     #
 
     list.each do |duck|
-      autoload duck.name, duck.load_path
+      autoload duck.name, load_path_for(duck)
     end
   end
 end

data/lib/duck_puncher/version.rb

@@ -1,3 +1,3 @@
 module DuckPuncher
-  VERSION = '2.9.3'.freeze
+  VERSION = '2.10.0'.freeze
 end

data/lib/duck_puncher.rb

@@ -14,17 +14,33 @@ module DuckPuncher
   class << self
     attr_accessor :log
 
-    def delegate_class(name)
+    def delegations
       @delegations ||= {}
-      @delegations[name] ||= Ducks[name].dup.delegated
+    end
+
+    def classes
+      @classes ||= {}
+    end
+
+    # @param [Symbol] duck_name
+    # @param [Class] obj The object being punched
+    def delegate_class(duck_name, obj = nil)
+      delegations[duck_name] ||= const_set "#{duck_name}DuckDelegated", Ducks[duck_name].dup.delegated(obj)
+    end
+
+    def duck_class(name)
+      classes[name] ||= const_set "#{name}Duck", Ducks[name].dup.classify
     end
 
     # @description Extends functionality to a copy of the specified class
     def punch(*names)
       singular = names.size == 1
-      punched_ducks = names.map { |name| Ducks[name].dup.classify }.compact
-      punched_ducks = punched_ducks.first if singular
-      punched_ducks
+      punched_ducks = names.map(&method(:duck_class)).compact
+      if singular
+        punched_ducks.first
+      else
+        punched_ducks
+      end
     end
 
     def punch!(*names)
@@ -43,6 +59,10 @@ module DuckPuncher
       log.warn 'Punching all ducks! Watch out!'
       Ducks.list.each &:punch
     end
+
+    def register(*args)
+      Ducks.list << Duck.new(*args)
+    end
   end
 
   # @description Default logger

data/test/{duck_puncher → lib/duck_puncher}/array_test.rb

@@ -1,4 +1,5 @@
-require_relative '../test_helper'
+require_relative '../../test_helper'
+
 DuckPuncher.punch! :Object
 
 class ArrayTest < MiniTest::Test

data/test/{duck_puncher → lib/duck_puncher}/hash_test.rb

@@ -1,4 +1,4 @@
-require_relative '../test_helper'
+require_relative '../../test_helper'
 DuckPuncher.punch! :Object
 
 class HashTest < MiniTest::Test

data/test/{duck_puncher → lib/duck_puncher}/method_test.rb

@@ -1,5 +1,5 @@
-require_relative '../test_helper'
-require_relative '../fixtures/wut'
+require_relative '../../test_helper'
+require_relative '../../fixtures/wut'
 DuckPuncher.punch! :Method
 
 class MethodTest < MiniTest::Test

data/test/{duck_puncher → lib/duck_puncher}/numeric_test.rb

@@ -1,4 +1,4 @@
-require_relative '../test_helper'
+require_relative '../../test_helper'
 DuckPuncher.punch! :Numeric
 
 class NumericTest < MiniTest::Test

data/test/{duck_puncher → lib/duck_puncher}/object_test.rb

@@ -1,4 +1,4 @@
-require_relative '../test_helper'
+require_relative '../../test_helper'
 DuckPuncher.punch! :Object
 
 class ObjectTest < MiniTest::Test

data/test/{duck_puncher → lib/duck_puncher}/string_test.rb

@@ -1,4 +1,4 @@
-require_relative '../test_helper'
+require_relative '../../test_helper'
 
 DuckPuncher.punch! :String
 

data/test/lib/duck_puncher_test.rb

@@ -0,0 +1,23 @@
+require_relative '../test_helper'
+
+module CustomPunch
+  def tap_tap
+    p self
+    self
+  end
+end
+
+class DuckPuncherTest < MiniTest::Test
+  def teardown
+    Object.send :remove_const, :CustomPunch
+  end
+
+  def test_register
+    refute_respond_to [], :tap_tap
+    DuckPuncher.register :CustomPunch, class: 'Array'
+    DuckPuncher.punch! :CustomPunch
+    assert_respond_to [], :tap_tap
+    DuckPuncher.punch! :Object, only: :punch
+    assert_respond_to [].punch(:CustomPunch), :tap_tap
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: duck_puncher
 version: !ruby/object:Gem::Version
-  version: 2.9.3
+  version: 2.10.0
 platform: ruby
 authors:
 - Ryan Buckley
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-02-06 00:00:00.000000000 Z
+date: 2016-02-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: usable
@@ -117,13 +117,14 @@ files:
 - lib/duck_puncher/gem_installer.rb
 - lib/duck_puncher/json_storage.rb
 - lib/duck_puncher/version.rb
-- test/duck_puncher/array_test.rb
-- test/duck_puncher/hash_test.rb
-- test/duck_puncher/method_test.rb
-- test/duck_puncher/numeric_test.rb
-- test/duck_puncher/object_test.rb
-- test/duck_puncher/string_test.rb
 - test/fixtures/wut.rb
+- test/lib/duck_puncher/array_test.rb
+- test/lib/duck_puncher/hash_test.rb
+- test/lib/duck_puncher/method_test.rb
+- test/lib/duck_puncher/numeric_test.rb
+- test/lib/duck_puncher/object_test.rb
+- test/lib/duck_puncher/string_test.rb
+- test/lib/duck_puncher_test.rb
 - test/soft_punch/duck_puncher_test.rb
 - test/test_helper.rb
 homepage: https://github.com/ridiculous/duck_puncher
@@ -151,12 +152,13 @@ signing_key:
 specification_version: 4
 summary: Administer precision punches to your favorite Ruby classes
 test_files:
-- test/duck_puncher/array_test.rb
-- test/duck_puncher/hash_test.rb
-- test/duck_puncher/method_test.rb
-- test/duck_puncher/numeric_test.rb
-- test/duck_puncher/object_test.rb
-- test/duck_puncher/string_test.rb
 - test/fixtures/wut.rb
+- test/lib/duck_puncher/array_test.rb
+- test/lib/duck_puncher/hash_test.rb
+- test/lib/duck_puncher/method_test.rb
+- test/lib/duck_puncher/numeric_test.rb
+- test/lib/duck_puncher/object_test.rb
+- test/lib/duck_puncher/string_test.rb
+- test/lib/duck_puncher_test.rb
 - test/soft_punch/duck_puncher_test.rb
 - test/test_helper.rb