eager_beaver 0.0.1 → 0.0.2

data/.rspec

@@ -0,0 +1,2 @@
+--color
+--format documentation

data/README.md

@@ -1,10 +1,20 @@
 # EagerBeaver
 
-Facilitates method_missing, respond_to_missing?, and method-generation activities
-by providing a simple interface for adding method generators.  All related
-activities, such as registering with #method_missing and #respond_to_missing?
-are handled automatically.  Facilitates method name pattern-specific method
-generation as well.  Generated methods are added to the missing method receiver.
+## Overview
+
+`EagerBeaver` provides an interface for adding `#method_missing`-related abilities
+to a class or module.
+
+## Key Features
+
+- Method matchers can be added dynamically and cumulatively, reducing the risk
+  of accidentally altering or removing previously-added functionality.
+- Matched methods are automatically reflected in calls to `#respond_to?` and
+  `#method`, DRY-ing up code by centralizing method-matching logic.
+- Matched methods are automatically added to the including class/module and
+  invoked.  Subsequent calls won't trigger `#method_missing`.
+- When a method cannot be matched, `super`'s `#method_missing` is automatically
+  invoked.
 
 ## Installation
 
@@ -22,6 +32,12 @@ Or install it yourself as:
 
 ## Usage
 
+### Inclusion
+
+Any class or module which includes `EagerBeaver` will gain the `add_method_matcher`
+pseudo-keyword, which [indirectly] yields an `EagerBeaver::MethodMatcher` to the
+given block:
+
 ```ruby
 require 'eager_beaver'
 
@@ -29,27 +45,207 @@ class NeedsMethods
   include EagerBeaver
 
   add_method_matcher do |mm|
-    mm.matcher = Proc.new do
-      /\Amake_(\w+)\z/ =~ missing_method_name
-      @attr_name = Regexp.last_match ? Regexp.last_match[1] : nil
-      Regexp.last_match
-    end
-    mm.new_method_code_maker = Proc.new do
-      %Q{
-        def #{missing_method_name}(arg)
-          puts "#{@attr_name} \#{arg}"
+    ...
+  end
+end
+```
+
+In this case, the resulting `MethodMatcher` is added to the end of a `MethodMatcher` list
+associated with `NeedsMethods`.
+
+Each `MethodMatcher` needs two things: a lambda for matching missing method names
+and a lambda for creating the code for any method names it matches:
+
+```ruby
+  add_method_matcher do |mm|
+    mm.match = lambda { ... }
+    mm.new_method_code = lambda { ...}
+  end
+end
+```
+
+### Matching
+
+The `match` lambda should return a true value if the missing method name is one
+can be handled by the `MethodMatcher`.  The following example will match
+missing methods of the form `#make_<attr_name>`:
+
+```ruby
+    mm.match = lambda {
+      /\Amake_(\w+)\z/ =~ context.missing_method_name
+      context.attr_name = Regexp.last_match ? Regexp.last_match[1] : nil
+      return Regexp.last_match
+    }
+```
+
+### Context
+
+As the example shows, each `MethodMatcher` contains a `context` which provides:
+
+- the name of the missing method (`context.missing_method_name`)
+- the original method receiver instance (`context.original_receiver`)
+- a place to stash information (`context.<attr_name>` and `context.<attr_name>=`)
+
+This `context` is shared between the `match` and `new_method_code` lambdas, and
+is reset between uses of each `MethodMatcher`.
+
+### Code Generation
+
+The `new_method_code` lambda should return a string which will create the
+missing method in `NeedsMethods`:
+
+```ruby
+    mm.new_method_code = lambda {
+      code = %Q{
+        def #{context.missing_method_name}(arg)
+          puts "method \##{context.missing_method_name} has been called"
+          puts "\##{context.missing_method_name} was originally called on #{context.original_receiver}"
+          puts "#{context.attr_name} was passed from matching to code generation"
+          puts "the current call has arguments: \#{arg}"
+          return "result = \#{arg}"
         end
       }
-    end
+      return code
+    }
+```
+
+As the example shows, it is perfectly reasonable to take advantage of work done
+by the `match` lambda (in this case, the parsing of `<attr_name>`).
+
+After the generated code is inserted into `NeedsMethods`, the missing method 
+call is resent to the original receiver.
+
+### Complete Example
+
+```ruby
+require 'eager_beaver'
+
+class NeedsMethods
+  include EagerBeaver
+
+  add_method_matcher do |mm|
+    mm.match = lambda {
+      /\Amake_(\w+)\z/ =~ context.missing_method_name
+      context.attr_name = Regexp.last_match ? Regexp.last_match[1] : nil
+      return Regexp.last_match
+    }
+
+    mm.new_method_code = lambda {
+      code = %Q{
+        def #{context.missing_method_name}(arg)
+          puts "method \##{context.missing_method_name} has been called"
+          puts "\##{context.missing_method_name} was originally called on #{context.original_receiver}"
+          puts "#{context.attr_name} was passed from matching to code generation"
+          puts "the current call has arguments: \#{arg}"
+          return "result = \#{arg}"
+        end
+      }
+      return code
+    }
   end
 end
+```
+
+## Execution
+
+Given the `NeedsMethods` class in the example above, let's work through the
+following code:
+
+```ruby
+nm1 = NeedsMethods.new
+puts nm1.make_thingy(10)
+puts nm1.make_widget("hi")
+
+nm2 = NeedsMethods.new
+puts nm2.make_thingy(20)
+puts nm2.make_widget("hello")
+
+nm2.dont_make_this
+```
+
+As instances of `NeedsMethods`, `nm1` and `nm2` will automatically hande
+methods of the form `#make_<attr_name>`.
+
+The line:
+```ruby
+puts nm1.make_thingy(10)
+```
+will trigger `nm1`'s `#method_missing`, which `NeedsMethods` implements thanks to
+`EagerBeaver`.  Each `MethodMatcher` associated with `EagerBeaver` is run against
+the method name `make_thingy`, and sure enough one matches.  This causes the
+following methods to be inserted to `NeedsMethods`:
+```ruby
+  def make_thingy(arg)
+    puts "method #make_thingy has been called"
+    puts "#make_thingy was originally called on #<NeedsMethods:0x007fa1bc17f498>"
+    puts "thingy was passed from matching to code generation"
+    puts "the current call has arguments: #{arg}"
+    return "result = #{arg}"
+  end
+```
+and when `#make_thingy` is resent to `nm1`, the existing method is called and 
+outputs:
+
+> method \#make_thingy has been called<br/>
+> \#make_thingy was originally called on \#\<NeedsMethods:0x007fa1bc17f498\><br/>
+> thingy was passed from matching to code generation<br/>
+> the current call has arguments: 10<br/>
+> result = 10
+
+Similarly, the line:
+```ruby
+puts nm1.make_widget("hi")
+```
+generates the code:
+```ruby
+  def make_widget(arg)
+    puts "method #make_widget has been called"
+    puts "#make_widget was originally called on #<NeedsMethods:0x007fa1bc17f498>"
+    puts "widget was passed from matching to code generation"
+    puts "the current call has arguments: #{arg}"
+    return "result = #{arg}"
+  end
+```
+and outputs:
+> method \#make_widget has been called<br/>
+> \#make_widget was originally called on \#\<NeedsMethods:0x007fa1bc17f498\><br/>
+> widget was passed from matching to code generation<br/>
+> the current call has arguments: hi<br/>
+> result = hi
+
+Note that the following lines do NOT trigger `#method_missing` because both methods
+have already been added to `NeedsMethods`:
+```ruby
+puts nm2.make_thingy(20)
+puts nm2.make_widget("hello")
+```
+This can be seen by examining the identity of the original receiver in the output:
 
-nm = NeedsMethods.new
+> **method \#make_thingy has been called**<br/>
+> **\#make_thingy was originally called on \#\<NeedsMethods:0x007fa1bc17f498\>**<br/>
+> **thingy was passed from matching to code generation**<br/>
+> the current call has arguments: 20<br/>
+> result = 20
 
-nm.make_thingy(10)    # thingy 10
-nm.make_widget("hi")  # widget hi
-nm.oh_no!             # (NoMethodError)
+> **method \#make_widget has been called**<br/>
+> **\#make_widget was originally called on \#\<NeedsMethods:0x007fa1bc17f498\>**<br/>
+> **widget was passed from matching to code generation**<br/>
+> the current call has arguments: hello<br/>
+> result = hello
+
+String substitutions which were part of the generated code body (emphasized)
+reflect the circumstances of the first set of method calls, as opposed to 
+those which reflect the current call's argument.
+
+Finally, the call:
 ```
+nm2.dont_make_this
+```
+will cause `NeedsMethods` to examine all of its `MethodMatcher`s and finally call
+`super`'s `#method_missing`.  Because no superclass of `NeedsMethods` handles
+`#dont_make_this`, the output is:
+
+> undefined method `dont_make_this' for \#\<NeedsMethods:0x007f8e2b991f90\> (NoMethodError)
 
 ## Contributing
 

data/eager_beaver.gemspec

@@ -12,6 +12,8 @@ Gem::Specification.new do |gem|
                          generation as well.  Generated methods are added to the missing method receiver.}
   gem.homepage      = "http://github.com/kevinburleigh75/eager_beaver"
 
+  gem.add_development_dependency "rspec", ["~>2.13.0"]
+
   gem.files         = `git ls-files`.split($\)
   gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
   gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})

data/lib/eager_beaver.rb

@@ -9,14 +9,12 @@ module EagerBeaver
 
   def method_missing(method_name, *args, &block)
     self.class.method_matchers.each do |method_matcher|
-      method_matcher.original_caller = self
-      if method_matcher.match?(method_name)
-        if method_matcher.new_method
-          self.class.send(:define_method, method_name, method_matcher.new_method)
-        elsif method_matcher.new_method_code_maker
-          method_string = method_matcher.instance_eval &method_matcher.new_method_code_maker
-          self.class.class_eval method_string, __FILE__, __LINE__ + 1
-        end
+      mm = method_matcher.dup
+      self.class.context = mm
+      mm.original_receiver = self
+      if mm.match?(method_name)
+        method_string = mm.evaluate mm.new_method_code_maker
+        self.class.class_eval method_string, __FILE__, __LINE__ + 1
         return self.send(method_name, *args, &block)
       end
     end
@@ -36,8 +34,10 @@ module EagerBeaver
     end
 
     def add_method_matcher(&block)
-      method_matchers << MethodMatcher.new(block)
+      method_matchers << MethodMatcher.new(&block)
     end
+
+    attr_accessor :context
   end
 
 end

data/lib/eager_beaver/method_matcher.rb

@@ -2,27 +2,59 @@ module EagerBeaver
 
   class MethodMatcher
 
-    attr_accessor :original_caller
+    attr_accessor :original_receiver
     attr_accessor :matcher
-    attr_accessor :new_method
     attr_accessor :new_method_code_maker
     attr_accessor :missing_method_name
 
-    def initialize(block)
+    def initialize(&block)
       block.call(self)
 
-      raise ArgumentError, "matcher Proc must be given" \
+      raise "matcher must be given" \
         if matcher.nil?
-      raise ArgumentError, "exactly one of new_method or new_method_code_maker Proc must be given" \
-        if (new_method && new_method_code_maker) || (new_method.nil? && new_method_code_maker.nil?)
+      raise "matcher lmust be a lambda" \
+        unless matcher.lambda?
+
+      raise "new_method_code_maker must be given" \
+        if new_method_code_maker.nil?
+      raise "new_method_code_maker must be a lambda" \
+        unless new_method_code_maker.lambda?
 
       self
     end
 
+    def match=(lambda_proc)
+      self.matcher = lambda_proc
+    end
+
     def match?(method_name)
       self.missing_method_name = method_name.to_s
-      self.instance_eval &matcher
+      return evaluate(matcher)
+    end
+
+    def new_method_code=(lambda_proc)
+      self.new_method_code_maker = lambda_proc
     end
+
+    def evaluate(inner)
+      outer = lambda { |*args|
+        args.shift
+        inner.call(*args)
+      }
+      self.instance_eval &outer
+    end
+
+    def method_missing(method_name, *args, &block)
+      if /\A(?<attr_name>\w+)=?\z/ =~ method_name
+        code = %Q{
+          attr_accessor :#{attr_name}
+        }
+        self.singleton_class.instance_eval code, __FILE__, __LINE__ + 1
+        return self.send(method_name, *args, &block)
+      end
+      super
+    end
+
   end
 
 end

data/lib/eager_beaver/version.rb

@@ -1,3 +1,3 @@
 module EagerBeaver
-  VERSION = "0.0.1"
+  VERSION = "0.0.2"
 end

data/spec/eager_beaver/context_spec.rb

@@ -0,0 +1,78 @@
+require 'spec_helper'
+
+describe "matcher context" do
+
+  describe "#missing_method_name" do
+    it "provides the name of the missing method" do
+      klass = Class.new do
+        include EagerBeaver
+
+        add_method_matcher do |mm|
+          mm.matcher = lambda {
+            raise context.missing_method_name \
+              unless context.missing_method_name == "aaa"
+            /\Aaaa\z/ =~ context.missing_method_name 
+          }
+          mm.new_method_code = lambda {
+            raise context.missing_method_name \
+              unless context.missing_method_name == "aaa"
+            %Q{
+              def #{context.missing_method_name}
+              end
+            }
+          }
+        end
+      end
+      expect{ klass.new.aaa }.to_not raise_exception
+    end
+  end
+
+  describe "#original_receiver" do
+    it "provides the orignal method receiver" do
+      klass = Class.new do
+        include EagerBeaver
+
+        add_method_matcher do |mm|
+          mm.matcher = lambda {
+            /\Aaaa\z/ =~ context.missing_method_name
+          }
+          mm.new_method_code = lambda {
+            %Q{
+              def #{context.missing_method_name}
+                #{context.original_receiver.__id__}
+              end
+            }
+          }
+        end
+      end
+
+      instance = klass.new
+      instance.aaa.should equal instance.__id__
+    end
+  end
+
+  describe "#<attr_name> and #<attr_name>=" do
+    it "provide a way to pass data between method matching and code generation" do
+      klass = Class.new do
+        include EagerBeaver
+
+        add_method_matcher do |mm|
+          mm.matcher = lambda {
+            context.my_data = "hello"
+            /\Aaaa\z/ =~ context.missing_method_name
+          }
+          mm.new_method_code = lambda {
+            %Q{
+              def #{context.missing_method_name}
+                "#{context.my_data}"
+              end
+            }
+          }
+        end
+      end
+
+      klass.new.aaa.should == "hello"
+    end
+  end
+
+end

data/spec/eager_beaver/eager_beaver_spec.rb

@@ -0,0 +1,135 @@
+require 'spec_helper'
+
+describe EagerBeaver do
+
+  describe ".included" do
+
+    before :each do
+      @klass = Class.new do
+        include EagerBeaver
+      end
+    end
+
+    it "adds Includer.add_method_matcher" do
+      expect(@klass.methods).to include :add_method_matcher
+    end
+
+    it "adds Includer.method_matchers" do
+      expect(@klass.methods).to include :method_matchers
+    end
+
+    it "adds Includer.context" do
+      expect(@klass.methods).to include :context
+    end
+
+    it "adds Includer.context=" do
+      expect(@klass.methods).to include :context=
+    end
+
+    it "adds Includer#method_missing" do
+      expect(@klass.instance_methods(:false)).to include :method_missing
+    end
+
+    it "adds Includer#respond_to_missing?" do
+      expect(@klass.instance_methods(:false)).to include :respond_to_missing?
+    end
+
+  end
+
+  describe "#add_method_matcher" do
+
+    it "registers a new method matcher" do
+      klass = Class.new do
+        include EagerBeaver
+
+        add_method_matcher do |mm|
+          mm.matcher = lambda { true }
+          mm.new_method_code = lambda {
+            return %Q{
+              def #{context.missing_method_name}
+              end
+            }
+          }
+        end
+      end
+
+      klass.method_matchers.size.should == 1
+    end
+
+  end
+
+  describe "#method_missing" do
+
+    context "method matching" do
+
+      it "invokes the first matching matcher" do
+        klass = Class.new do
+          include EagerBeaver
+
+          add_method_matcher do |mm|
+            mm.matcher = lambda { /\Aaaa\z/ =~ context.missing_method_name }
+            mm.new_method_code = lambda {
+              %Q{
+                def #{context.missing_method_name}
+                  1
+                end
+              }
+            }
+          end
+
+          add_method_matcher do |mm|
+            mm.matcher = lambda { /\Abbb\z/ =~ context.missing_method_name }
+            mm.new_method_code = lambda {
+              %Q{
+                def #{context.missing_method_name}
+                  2
+                end
+              }
+            }
+          end
+
+          add_method_matcher do |mm|
+            mm.matcher = lambda { /\Abbb\z/ =~ context.missing_method_name }
+            mm.new_method_code = lambda {
+              %Q{
+                def #{context.missing_method_name}
+                  3
+                end
+              }
+            }
+          end
+        end
+
+        klass.new.bbb.should == 2
+      end
+
+      it "calls super #method_missing if no matcher matches" do
+        klass1 = Class.new do
+          def method_missing(method_name, *args, &block)
+            10
+          end
+        end
+
+        klass2 = Class.new(klass1) do
+          include EagerBeaver
+
+          add_method_matcher do |mm|
+            mm.matcher = lambda { /\Aaaa\z/ =~ context.missing_method_name }
+            mm.new_method_code = lambda {
+              %Q{
+                def #{context.missing_method_name}
+                  1
+                end
+              }
+            }
+          end
+        end
+
+        klass2.new.bbb.should == 10
+      end
+
+    end
+
+  end
+
+end

data/spec/spec_helper.rb

@@ -0,0 +1,19 @@
+# This file was generated by the `rspec --init` command. Conventionally, all
+# specs live under a `spec` directory, which RSpec adds to the `$LOAD_PATH`.
+# Require this file using `require "spec_helper"` to ensure that it is only
+# loaded once.
+#
+# See http://rubydoc.info/gems/rspec-core/RSpec/Core/Configuration
+RSpec.configure do |config|
+  config.treat_symbols_as_metadata_keys_with_true_values = true
+  config.run_all_when_everything_filtered = true
+  config.filter_run :focus
+
+  # 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
+
+require 'eager_beaver'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: eager_beaver
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.2
   prerelease: 
 platform: ruby
 authors:
@@ -9,8 +9,24 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-04-04 00:00:00.000000000 Z
-dependencies: []
+date: 2013-04-09 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 2.13.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 2.13.0
 description: Facilitates method_missing, respond_to_missing?, and method-generation
   activities
 email:
@@ -20,6 +36,7 @@ extensions: []
 extra_rdoc_files: []
 files:
 - .gitignore
+- .rspec
 - Gemfile
 - LICENSE
 - README.md
@@ -28,6 +45,9 @@ files:
 - lib/eager_beaver.rb
 - lib/eager_beaver/method_matcher.rb
 - lib/eager_beaver/version.rb
+- spec/eager_beaver/context_spec.rb
+- spec/eager_beaver/eager_beaver_spec.rb
+- spec/spec_helper.rb
 homepage: http://github.com/kevinburleigh75/eager_beaver
 licenses: []
 post_install_message: 
@@ -56,4 +76,7 @@ summary: ! 'Facilitates method_missing, respond_to_missing?, and method-generati
   activities, such as registering with #method_missing and #respond_to_missing? are
   handled automatically.  Facilitates method name pattern-specific method generation
   as well.  Generated methods are added to the missing method receiver.'
-test_files: []
+test_files:
+- spec/eager_beaver/context_spec.rb
+- spec/eager_beaver/eager_beaver_spec.rb
+- spec/spec_helper.rb