modifiers 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 1362dad9adfb0a9ac28f10588f0f233f00472038
-  data.tar.gz: 22c39749a7f5ae6c411754899ae57db54fd7e52a
+  metadata.gz: 1c529f23f0c4fe7d0417b298daabad35a18c98ba
+  data.tar.gz: 4e26087e2b3d2a386417c3ae74bef0dfac9ef131
 SHA512:
-  metadata.gz: 3bebfb125f3104c010eb94e4ee1b9de4c40cdeec0f9f542c45d5cb074631a4b3ef93f86ba7b07d6391d16387fb6db8d479144d0ba37e5baa671cabe483b6c9f0
-  data.tar.gz: 27007ced57e661678ceba35749a1cdad47c764375cafeab094482626677a8a547cda788209a145fc21ae12449161cf520ec78f7da2d05f9a0b76d359f08666b3
+  metadata.gz: 7cae095e6a838c2e06094242f883ad3bd18db3841bd931abee97dcd8b507990ad5a1e851d241b85ddfa1de3d90ab5a465aac3b5bed809a4830317405a2cab543
+  data.tar.gz: b1649f83e589491f7da170b057be4121be762efc592f06cb7c228c92a2d2d3e74a871859b5cc2b6b80b777976f575b16d7c688e7c901699dbf8ddfef314ef183

data/.travis.yml

@@ -10,4 +10,3 @@ deploy:
     secure: fewAgjCXLYSkbRq57EQYRTjwPn/LfQgpvSh1HBdVG1Vjds2OCL+yl3d6x30o4q28GU7dMLKjEl2BZrrQ9TwPgit3LRPUwlsoZRvGQj+oztdNfshpWansne6coBYa5vx/tQFBSDWkTMdE2RMH1w7qP20Iqn44c4yQU1tQiqWoZMQ=
   on:
     tags: true
-    repo: nicknovitski/modifiers

data/README.md

@@ -5,33 +5,55 @@
 
 `Modifiers` is a collection of method modifiers, and a way to make more.
 
-_Method Modifiers_, obviously, are modifiers to methods.  Specifically, in Ruby
+_Method Modifiers_, obviously, modify methods.  Specifically, in Ruby
 terms, they are class methods which:
 
-1. Take a symbol argument which names an instance method of the same class, and
-2. Return the same symbol, but
-3. Alter the named method in some way.
+1. Take a symbol argument which names an instance method of the same class, _and_
+2. Return the same symbol, _but_
+3. Cause subsequent calls to the named method to change in some way.
 
-Ruby has shipped with four (4) modifiers since forever: the three access
-modifiers (`public`, `private`, and `protected`), and `module_function`.  This
-library [adds a few others, and a facility for creating even more](#usage).
+This library [includes a few, as well as ways to make more](#usage).
 
 ## Why is/are Modifiers?
 
-DRYing up code sometimes involves smaller fragments of shared behavior than a
-method.  Here's an example you've probably read and written before:
+The pursuit of DRY code can involve fragments of shared behavior smaller than a
+method.
+
+Here's an example that might feel familiar:
 ```ruby
-# old and busted
 def count_ducks
   @count_ducks ||= DuckFlock.all.map(&size).inject(0, &:+)
 end
 ```
 
-Why are you writing the characters 'count_ducks', in the _exact same order_
-__two whole times__?  If you already know how to implement memoization, why let
-your code challenge you to prove it every time you want it done?! Instead,
-implement it one final, flawless time, and tell the interpreter firmly, "No,
-_you_ type the name twice, my time is far too valuable."
+This method is quite small, but it still complects the concerns of counting
+ducks and of saving and reusing the result of a calculation, and that latter
+concern might be repeated any number of times in your codebase.
+
+With modifiers, we can encapsulate the implementation of the memoization, and
+keep the intent:
+```ruby
+def count_ducks
+  DuckFlock.all.map(&size).inject(0, &:+)
+end
+memoized :count_ducks
+```
+
+## Requirements
+
+Behind the scenes, `modifiers` uses `Module#prepend`, so it requires Ruby
+version 2.0.0 or higher.
+
+If you have at least version 2.1.0, you can call them in-line with your method
+definitions, which looks completely baller imo:
+```ruby
+# requires Ruby 2.1.0 or higher, cool kids only
+memoized query def fetch_from_api(params)
+  ApiFetcher.new(params).call
+end
+```
+
+(All other code examples in this document work on 2.0.)
 
 ## Installation
 
@@ -47,6 +69,36 @@ And then execute:
 
 ### built-in modifiers
 
+#### memoized
+
+Every now and then, you start to care how long it takes for a method to run.
+You may find yourself wishing it just re-used some hard-won values, rather than
+throwing them away and rebuilding them anew every time you call it.
+
+(You may recognize the example from earlier, but this one is more complete.)
+
+```ruby
+require 'modifiers/memoized'
+
+class DuckService
+  extend Modifiers
+
+  def count_ducks
+    DuckFlock.all.map(&size).inject(0, &:+)
+  end
+  memoized :count_ducks
+end
+```
+
+A method modified by `memoized` will run once normally, per unique combination
+of arguments, after which it will simply return the same result for the
+lifetime of the receiving object. Dazzle your friends with your terse, yet
+performant, fibonnaci implementations!
+
+(If you want all this and more, you can use
+[memoist](https://github.com/matthewrudy/memoist) (formerly
+`ActiveSupport::Memoizable`) instead, but I warn you: it involves `eval`.)
+
 #### deprecated
 
 Sometimes there's a method, and you want it to die, but not a clean, swift
@@ -60,9 +112,10 @@ require 'modifiers/deprecated'
 class BadHacks
   extend Modifiers
 
-  deprecated def awful_method
+  def awful_method
     # some ugly hack, probably involving define_method and ObjectSpace
   end
+  deprecated :awful_method
 end
 ```
 
@@ -73,36 +126,6 @@ BadHacks#awful_method called from app/controllers/ducks_controller.rb:782`
 (Please note that the `deprecated` method is deprecated, and you should
 definitely use `Gem.deprecate` instead.)
 
-#### memoized
-
-Every now and then, you will come to care how long it takes for a method to
-run.  You may find yourself wishing it just re-used some hard-won values,
-rather than throwing them away and rebuilding them anew every time you call it.
-
-To demonstrate this, on multiple levels, I will re-use the case from a previous
-section.
-
-```ruby
-require 'modifiers/memoized'
-
-class DuckService
-  extend Modifiers
-
-  memoized def count_ducks
-    DuckFlock.all.map(&size).inject(0, &:+)
-  end
-end
-```
-
-A method modified by `memoized` will run once normally, per unique combination
-of arguments, after which it will simply return the same result for the
-lifetime of the receiving object. Dazzle your friends with your terse, yet
-performant, fibonnaci implementations!
-
-(If you want all this and more, you can use
-[memoist](https://github.com/matthewrudy/memoist) (formerly
-`ActiveSupport::Memoizable`) instead, but I warn you: it involves `eval`.)
-
 #### commands and queries
 
 You may have heard of 'Command-Query Separation`, and the claim that code
@@ -118,15 +141,17 @@ sounds.
 Conversely (?), a method modified by `query` will never change the state of
 anything non-global and in-process.  This is also trivial, but it might seem
 more impressive.
+
 ```ruby
 require 'modifiers/command_query'
 
 class DuckFarmer < Struct.new(:hutches)
   extend Modifiers
 
-  query def fullest_hutch
+  def fullest_hutch
     hutches.max { |h1,h2| h1.count_eggs - h2.count_eggs }
   end
+  query :fullest_hutch
 end
 
 class DuckHutch < Struct.new(:num_eggs)
@@ -151,8 +176,6 @@ If this was an infomercial, now is when I would say something like "It's just
 that easy, Michael!", and you (your name is Michael in this scenario) would say
 "Now _that's_ incredible!" and the audience would applaud.
 
-I'm mildly proud of this library.
-
 ### defining new modifiers
 
 New modifiers can be defined in your own modules using the `define_modifier` method.
@@ -164,59 +187,90 @@ require 'modifiers/define_modifier'
 
 module DuckFarmModifiers
   extend Modifiers
-  define_modifier(:duck)
+  define_modifier(:duck) do |*args, &block|
+    super(*args, &block)
+  end
 end
 
 class DuckFarm
   extend DuckFarmModifiers
+  def farm
+    # raise, tend, cultivate
+  end
 
-  duck :some_method # => unchanged
+  duck :farm # => unchanged
 end
 ```
 
-Here's an identical implementation:
+Much as with `define_method`, the first argument to `define_modifier` gives us
+the name of the new modifier, and the block gives us the implementation of a
+given *modification*: a method which intercepts calls to the original method
+(in this case, `DuckFarm#farm`), does whatever it likes, then invokes the
+original method using `super`.
+
+(Sadly, just as with `define_method`, you have to use explicit arguments when
+calling `super`.  Sorry, doing otherwise involved too much oddity.)
+
+But maybe you don't want to call the original method at all!
 ```ruby
 module DuckFarmModifiers
-  define_modifier(:duck) do |method_invocation|
-    method_invocation.invoke
-  end
+  define_modifier(:x) { }
 end
 ```
 
-A block passed to `define_modifier` will become the new body of the methods
-modified by the modifier, kinda like with `define_method`.
-
-The argument passed to that block will be an object representing a particular
-call to the modified method.  As I showed you above, all you have to do
-continue that call as normal is `#invoke` it.
-
-Or not!
+Or maybe you don't want to call it with the same arguments!
 ```ruby
 module DuckFarmModifiers
-  define_modifier(:x) do
-    # temporarily disable a method and see if anyone notices
+  define_modifier(:int) do |*args, &block|
+    super(*args.map(&:to_i), &block)
   end
 end
-```
 
 You can do things before, after, or even "around" the invocation.
 ```ruby
 module DuckFarmModifiers
-  define_modifier(:perf_logged) do |invocation|
+  define_modifier(:perf_logged) do |*args, &block|
     start = Time.now
-    invocation.invoke
-    Rails.logger "#{invocation.method_identifier} finished in #{Time.now - start}s"
+    super(*args, &block)
+    Rails.logger "#{self.class.name}##{__method__} finished in #{Time.now - start}s"
   end
 end
 ```
 
-The method invocation object can also tell you the `#arguments` in the call,
-and its `#location` in the source, the `#method_name` of the method which was
-modified, or even the full `#method_identifier` in
-`Class.class_method`/`Class#instance_method` style.  All of the modifiers
-included in the library were made using it.
+### Extending modifiers
+
+The body of a modifier will be evaluated in the context of the receiver
+instance of the modified method, so you can refer to any other instance
+methods.  However, given that you probably wrote your modifier to be used from
+_any_ object, there isn't much you can rely on, so you may find yourself
+writing everything you need right there in the method, resulting in a long and
+ugly method body.
 
-What awesome ones will _you_ write?
+Luckily, there's a way out: if a given modification requires additional
+behavior, simply pass a module with all the other methods you need as the
+second argument to `define_modifier`.
+
+```ruby
+module DuckFarmModifiers
+  module Gracefully
+    private
+
+    def logger
+      Rails.logger
+    end
+
+    def log_exception(method_name, exception)
+      logger.warn("#{method_name} raised #{exception}")
+    end
+  end
+
+  define_modifier(:gracefully, Gracefully) do |*args, &block|
+    super(*args, &block)
+  rescue => e
+    log_exception(__method__, e)
+  end
+end
+```
 
 ## Contributing
 

data/lib/modifiers/define_modifier.rb

@@ -6,6 +6,7 @@ module Modifiers
       mod = Modification.new(modifier, self, modified, method_body)
       mod.send(:include, helper) if helper
       prepend mod
+      modified
     end
   end
   module_function :define_modifier

data/lib/modifiers/version.rb

@@ -1,3 +1,3 @@
 module Modifiers
-  VERSION = '1.0.0'
+  VERSION = '1.1.0'
 end

data/spec/shared_examples_for_modifiers.rb

@@ -24,6 +24,10 @@ RSpec.shared_examples 'a modifier' do |modifier, changes_return_value: false|
   let(:random_class_name) { (0...10).map { ('A'..'Z').to_a[rand(26)] }.join }
   subject(:instance) { test_class.new }
 
+  it 'returns the symbol it is passed' do
+    expect(test_class.send(modifier, :public_method)).to be :public_method
+  end
+
   unless changes_return_value
     it 'does not change the return value of the method' do
       test_class.send(modifier, :public_method)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: modifiers
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors:
 - Nick Novitski