tco_method 0.0.1 → 0.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 74462b42288aee51eb1533d2a233c9a39c4bea07
-  data.tar.gz: 8a4ebe308889ee0edf86489e4491ea3d9d656f52
+  metadata.gz: fa6f5ef52346f81e6dda4617f58c78d8ea6268fd
+  data.tar.gz: 3d38f3813816bc489c5329fe006e679f67041432
 SHA512:
-  metadata.gz: b3cdc64cac48fd98ca99c52fdc076b9e58e2f209bd8bbb7d5b10bf4feb81af392c4077a891652fadad165d5c3086e200254ef51753eabd45e1e01ec0049210c1
-  data.tar.gz: 807f4ae4f07dbaf15412c9b4dbfe66e1e856e06e647dcd2028b498bac587f4b8dddba890de212ef4250f188ea51a162e796164d3010c09ce22a6a6e50564f32c
+  metadata.gz: 3ab604141152bb7c7fc76846a4ecb7edd216b73dd4d134bb07faa13bda12901aa780a5dc34262ec0259d04ab9123a2b486228980dca9684440b3443c16a057e7
+  data.tar.gz: 7f1ced9785c6aebf644253d52a2a1c0973d94a1efe2fcc84e6aef3ca099c57e54bbc72c5767b0ea61ffb5b33dcc9d34e85b154843ff0a664881097d22fc05281

data/README.md

@@ -8,15 +8,15 @@
 
 Provides `TCOMethod::Mixin` for extending Classes and Modules with helper methods
 to facilitate evaluating code and some types of methods with tail call
-optimization enabled. Also provides `TCOMethod.tco_eval` providing an easy means
-to evaluate code strings with tail call optimization enabled.
+optimization enabled. Also provides `TCOMethod.tco_eval` providing a direct and
+easy means to evaluate code strings with tail call optimization enabled.
 
 ## Installation
 
 Add this line to your application's Gemfile:
 
-```bash
-gem 'tco_method'
+```ruby
+gem "tco_method"
 ```
 
 And then execute:
@@ -33,13 +33,18 @@ $ gem install tco_method
 
 ## Usage
 
-Require the `TCOMethod` library:
+Require the [`TCOMethod`](http://www.rubydoc.info/gems/tco_method/TCOMethod)
+library:
 
 ```ruby
 require "tco_method"
 ```
 
-Extend a class with the `TCOMethod::Mixin` and enjoy!
+Extend a class with the [`TCOMethod::Mixin`](http://www.rubydoc.info/gems/tco_method/TCOMethod/Mixin)
+and let the fun begin!
+
+To redefine an instance method with tail call optimization enabled, use
+[`tco_method`](http://www.rubydoc.info/gems/tco_method/TCOMethod/Mixin:tco_method):
 
 ```ruby
 class MyClass
@@ -51,12 +56,31 @@ class MyClass
   tco_method :factorial
 end
 
-MyClass.new.factorial(10_000).to_s.length
+puts MyClass.new.factorial(10_000).to_s.length
 # => 35660
 ```
 
-Or, use `TCOMethod.tco_eval` directly. Cumbersome, but much more flexible and
-powerful:
+Or alternatively, use [`tco_module_method`](http://www.rubydoc.info/gems/tco_method/TCOMethod/Mixin:tco_module_method)
+or [`tco_class_method`](http://www.rubydoc.info/gems/tco_method/TCOMethod/Mixin:tco_module_method)
+for a Module or Class method:
+
+```ruby
+module MyFibonacci
+  extend TCOMethod::Mixin
+
+  def self.fibonacci(index, back_one = 1, back_two = 0)
+    index < 1 ? back_two : fibonacci(index - 1, back_one + back_two, back_one)
+  end
+  tco_module_method :fibonacci
+end
+
+puts MyFibonacci.fibonacci(10_000).to_s.length
+# => 2090
+```
+
+Or, for more power and flexibility (at the cost of stringified code blocks) use
+[`TCOMethod.tco_eval`](http://www.rubydoc.info/gems/tco_method/TCOMethod/Mixin:tco_eval)
+directly:
 
 ```ruby
 TCOMethod.tco_eval(<<-CODE)
@@ -71,15 +95,63 @@ MyClass.new.factorial(10_000).to_s.length
 # => 35660
 ```
 
-## Gotchas
+You can kind of get around this by dynamically reading the code you want to
+compile with tail call optimization, but this approach also has downsides in
+that it goes around the standard Ruby `require` model. For example, consider the
+Fibonacci example broken across two scripts, one script serving as a loader and
+the other script acting as a more standard library:
+
+```ruby
+# loader.rb
+
+require "tco_method"
+fibonacci_lib = File.read(File.expand_path("../fibonacci.rb", __FILE__))
+TCOMethod.tco_eval(fibonacci_lib)
 
-The list so far:
+puts MyFibonacci.fibonacci(10_000).to_s.length
+# => 2090
 
-- Currently only works with methods defined using the `def` keyword.
-- Class annotations use the [`method_source` gem](https://github.com/banister/method_source)
+
+# fibonacci.rb
+
+module MyFibonacci
+  def self.fibonacci(index, back_one = 1, back_two = 0)
+    index < 1 ? back_two : fibonacci(index - 1, back_one + back_two, back_one)
+  end
+end
+```
+
+If you really want to get crazy, you could include the `TCOMethod::Mixin` module
+in the Module class and add these behaviors to all Modules and Classes. To quote
+VIM plugin author extraordinaire Tim Pope, "I don't like to get crazy." Consider
+yourself warned.
+
+```ruby
+# Don't say I didn't warn you...
+
+Module.include(TCOMethod::Mixin)
+
+module MyFibonacci
+  def self.fibonacci(index, back_one = 1, back_two = 0)
+    index < 1 ? back_two : fibonacci(index - 1, back_one + back_two, back_one)
+  end
+  tco_module_method :fibonacci
+end
+
+puts MyFibonacci.fibonacci(10_000).to_s.length
+# => 2090
+```
+
+## Gotchas
+
+Quirks with Module and Class annotations:
+- Annotations only work with methods defined using the `def` keyword.
+- Annotations use the [`method_source` gem](https://github.com/banister/method_source)
   to retrieve the method source to reevaluate. As a result, class annotations
   can act strangely when used in more dynamic contexts like `irb` or `pry`.
-
+- Annotations reopen the Module or Class by name to redefine the given method.
+  This process will fail for dynamic Modules and Classes that aren't assigned to
+  constants and, ergo, don't have names.
 
 I'm sure there are more and I will document them here as I come across them.
 

data/lib/tco_method/mixin.rb

@@ -4,18 +4,18 @@ module TCOMethod
   # call optimization enabled and re-evaluating existing methods with tail call
   # optimization enabled.
   module Mixin
-    # Class annotation causing the class or module method identified by the
-    # given method name to be reevaluated with tail call optimization enabled.
-    # Only works for methods defined using the `def` keyword.
+    # Module or Class annotation causing the class or module method identified
+    # by the given method name to be reevaluated with tail call optimization
+    # enabled. Only works for methods defined using the `def` keyword.
     #
     # @param [String, Symbol] method_name The name of the class or module method
     #   that should be reeevaluated with tail call optimization enabled.
     # @return [Symbol] The symbolized method name.
     # @see TCOMethod.reevaluate_method_with_tco
-    def tco_class_method(method_name)
-      TCOMethod.reevaluate_method_with_tco(self, method_name, :class)
+    def tco_module_method(method_name)
+      TCOMethod.reevaluate_method_with_tco(self, method_name, :module)
     end
-    alias_method :tco_module_method, :tco_class_method
+    alias_method :tco_class_method, :tco_module_method
 
     # Evaluate the given code String with tail call optimization enabled.
     #
@@ -39,7 +39,6 @@ module TCOMethod
     # @see TCOMethod.reevaluate_method_with_tco
     def tco_method(method_name)
       TCOMethod.reevaluate_method_with_tco(self, method_name, :instance)
-      method_name.to_sym
     end
   end
 end

data/lib/tco_method/version.rb

@@ -1,4 +1,4 @@
 module TCOMethod
   # The version of the TCOMethod gem.
-  VERSION = "0.0.1"
+  VERSION = "0.0.2"
 end

data/lib/tco_method.rb

@@ -47,8 +47,9 @@ module TCOMethod
     if method_info.type != :method
       raise TypeError, "Invalid method type: #{method_info.type}"
     end
+    receiver_class = receiver.is_a?(Class) ? :class : :module
     code = <<-CODE
-      class #{receiver.name}
+      #{receiver_class} #{receiver.name}
         #{existing_method.source}
       end
     CODE

data/test/unit/mixin_test.rb

@@ -3,37 +3,67 @@ require "test_helper"
 class MixinTest < TCOMethod::TestCase
   include TCOMethod::TestHelpers::FactorialStackBusterHelper
 
-  TestClass = Class.new do
-    extend TCOMethod::Mixin
-  end
+  TestClass = Class.new { extend TCOMethod::Mixin }
+  TestModule = Module.new { extend TCOMethod::Mixin }
+
 
-  subject { TestClass }
+  context "Module extensions" do
+    subject { TestModule }
 
-  [:tco_class_method, :tco_module_method].each do |method_alias|
-    context "##{method_alias}" do
+    context "#tco_module_method" do
       should "call TCOMethod.reevaluate_method_with_tco with expected arguments" do
         method_name = :some_method
-        args = [TestClass, method_name, :class]
+        args = [subject, method_name, :module]
         TCOMethod.expects(:reevaluate_method_with_tco).with(*args)
-        subject.send(method_alias, method_name)
+        subject.tco_module_method(method_name)
+      end
+    end
+
+    context "#tco_eval" do
+      should "call TCOMethod.eval with expected arguments" do
+        code = "some_code"
+        TCOMethod.expects(:tco_eval).with(code)
+        subject.tco_eval(code)
       end
     end
-  end
 
-  context "#tco_eval" do
-    should "call TCOMethod.eval with expected arguments" do
-      code = "some_code"
-      TCOMethod.expects(:tco_eval).with(code)
-      subject.tco_eval(code)
+    context "#tco_method" do
+      should "call TCOMethod.reevaluate_method_with_tco with expected arguments" do
+        method_name = :some_method
+        args = [subject, method_name, :instance]
+        TCOMethod.expects(:reevaluate_method_with_tco).with(*args)
+        subject.tco_method(method_name)
+      end
     end
   end
 
-  context "#tco_method" do
-    should "call TCOMethod.reevaluate_method_with_tco with expected arguments" do
-      method_name = :some_method
-      args = [TestClass, method_name, :instance]
-      TCOMethod.expects(:reevaluate_method_with_tco).with(*args)
-      subject.tco_method(method_name)
+  context "Class extensions" do
+    subject { TestClass }
+
+    context "#tco_class_method" do
+      should "call TCOMethod.reevaluate_method_with_tco with expected arguments" do
+        method_name = :some_method
+        args = [subject, method_name, :module]
+        TCOMethod.expects(:reevaluate_method_with_tco).with(*args)
+        subject.tco_class_method(method_name)
+      end
+    end
+
+    context "#tco_eval" do
+      should "call TCOMethod.eval with expected arguments" do
+        code = "some_code"
+        TCOMethod.expects(:tco_eval).with(code)
+        subject.tco_eval(code)
+      end
+    end
+
+    context "#tco_method" do
+      should "call TCOMethod.reevaluate_method_with_tco with expected arguments" do
+        method_name = :some_method
+        args = [subject, method_name, :instance]
+        TCOMethod.expects(:reevaluate_method_with_tco).with(*args)
+        subject.tco_method(method_name)
+      end
     end
   end
 end

data/test/unit/tco_method_test.rb

@@ -5,13 +5,21 @@ class TCOMethodTest < TCOMethod::TestCase
 
   Subject = TCOMethod
 
-  TestClass = Class.new do
+  test_subject_builder = proc do
     extend TCOMethod::Mixin
 
-    class << self;
-      define_method(:class_block_method) { }
+    class << self
+      define_method(:singleton_block_method) { }
     end
 
+    # Equivalent to the below, but provides a target for verifying that
+    # tco_module_method works on Classes and tco_class_method works on Modules.
+    def self.module_factorial(n, acc = 1)
+      n <= 1 ? acc : module_factorial(n - 1, n * acc)
+    end
+
+    # Equivalent to the above, but provides a target for verifying that
+    # tco_module_method works on Classes and tco_class_method works on Modules.
     def self.class_factorial(n, acc = 1)
       n <= 1 ? acc : class_factorial(n - 1, n * acc)
     end
@@ -23,6 +31,9 @@ class TCOMethodTest < TCOMethod::TestCase
     end
   end
 
+  TestModule = Module.new(&test_subject_builder)
+  TestClass = Class.new(&test_subject_builder)
+
   subject { Subject }
 
   context Subject.name do
@@ -67,73 +78,105 @@ class TCOMethodTest < TCOMethod::TestCase
   context "::reevaluate_method_with_tco" do
     subject { Subject.method(:reevaluate_method_with_tco) }
 
-    context "validation" do
-      should "raise ArgumentError unless receiver given" do
-        assert_raises(ArgumentError) do
-          subject.call(nil, :nil?, :instance)
-        end
-      end
+    [TestClass, TestModule].each do |method_owner|
+      method_owner_class = method_owner.class.name.downcase.to_sym
 
-      should "raise ArgumentError unless method name given" do
-        assert_raises(ArgumentError) do
-          subject.call(TestClass, nil, :instance)
+      context "validation" do
+        should "raise ArgumentError unless receiver given" do
+          assert_raises(ArgumentError) do
+            subject.call(nil, :nil?, :instance)
+          end
         end
-      end
 
-      should "raise ArgumentError unless method owner given" do
-        assert_raises(ArgumentError) do
-          subject.call(TestClass, :class_factorial, nil)
+        should "raise ArgumentError unless method name given" do
+          assert_raises(ArgumentError) do
+            subject.call(method_owner, nil, :instance)
+          end
         end
-      end
 
-      should "raise TypeError for block methods" do
-        assert_raises(TypeError) do
-          subject.call(TestClass, :class_block_method, :class)
-        end
-        assert_raises(TypeError) do
-          subject.call(TestClass, :instance_block_method, :instance)
+        should "raise ArgumentError unless method owner given" do
+          assert_raises(ArgumentError) do
+            subject.call(method_owner, :class_factorial, nil)
+          end
         end
-      end
-    end
 
-    context "with class method" do
-      should "raise NameError if no class method with given name defined" do
-        assert_raises(NameError) do
-          subject.call(TestClass, :marmalade, :class)
+        should "raise TypeError for block methods" do
+          assert_raises(TypeError) do
+            subject.call(method_owner, :singleton_block_method, :class)
+          end
+          assert_raises(TypeError) do
+            subject.call(method_owner, :instance_block_method, :instance)
+          end
         end
       end
 
-      should "re-compile the given method with tail call optimization" do
-        # Exceed maximum available stack depth by 100 for good measure
-        factorial_seed = factorial_stack_buster_stack_depth_remaining + 100
-        assert_raises(SystemStackError) do
-          TestClass.class_factorial(factorial_seed)
-        end
+      context "#{method_owner_class} receiver" do
+        context "with module method" do
+          should "raise NameError if no #{method_owner_class} method with given name defined" do
+            assert_raises(NameError) do
+              subject.call(method_owner, :marmalade, method_owner_class)
+            end
+          end
 
-        subject.call(TestClass, :class_factorial, :class)
-        expected_result = iterative_factorial(factorial_seed)
-        assert_equal expected_result, TestClass.class_factorial(factorial_seed)
-      end
-    end
+          should "re-compile the given method with tail call optimization" do
+            # Exceed maximum available stack depth by 100 for good measure
+            factorial_seed = factorial_stack_buster_stack_depth_remaining + 100
+            assert_raises(SystemStackError) do
+              method_owner.module_factorial(factorial_seed)
+            end
 
-    context "with instance method" do
-      should "raise NameError if no instance method with given name defined" do
-        assert_raises(NameError) do
-          subject.call(TestClass, :marmalade, :instance)
+            subject.call(method_owner, :module_factorial, :module)
+            expected_result = iterative_factorial(factorial_seed)
+            assert_equal expected_result, method_owner.module_factorial(factorial_seed)
+          end
         end
-      end
 
-      should "re-compile the given method with tail call optimization" do
-        # Exceed maximum available stack depth by 100 for good measure
-        factorial_seed = factorial_stack_buster_stack_depth_remaining + 100
-        assert_raises(SystemStackError) do
-          TestClass.new.instance_factorial(factorial_seed)
+        context "with class method" do
+          should "raise NameError if no class method with given name defined" do
+            assert_raises(NameError) do
+              subject.call(method_owner, :marmalade, :class)
+            end
+          end
+
+          should "re-compile the given method with tail call optimization" do
+            # Exceed maximum available stack depth by 100 for good measure
+            factorial_seed = factorial_stack_buster_stack_depth_remaining + 100
+            assert_raises(SystemStackError) do
+              method_owner.class_factorial(factorial_seed)
+            end
+
+            subject.call(method_owner, :class_factorial, method_owner_class)
+            expected_result = iterative_factorial(factorial_seed)
+            assert_equal expected_result, method_owner.class_factorial(factorial_seed)
+          end
         end
 
-        subject.call(TestClass, :instance_factorial, :instance)
-        expected_result = iterative_factorial(factorial_seed)
-        assert_equal expected_result, TestClass.new.instance_factorial(factorial_seed)
+        context "with instance method" do
+          should "raise NameError if no instance method with given name defined" do
+            assert_raises(NameError) do
+              subject.call(method_owner, :marmalade, :instance)
+            end
+          end
+
+          should "re-compile the given method with tail call optimization" do
+            # Exceed maximum available stack depth by 100 for good measure
+            factorial_seed = factorial_stack_buster_stack_depth_remaining + 100
+            instance_class = instance_class_for_receiver(method_owner)
+            assert_raises(SystemStackError) do
+              instance_class.new.instance_factorial(factorial_seed)
+            end
+
+            subject.call(method_owner, :instance_factorial, :instance)
+            expected_result = iterative_factorial(factorial_seed)
+            assert_equal expected_result, instance_class.new.instance_factorial(factorial_seed)
+          end
+        end
       end
     end
   end
+
+  def instance_class_for_receiver(receiver)
+    return receiver if receiver.is_a?(Class)
+    Class.new { include receiver }
+  end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: tco_method
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.2
 platform: ruby
 authors:
 - Danny Guinther
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-03-12 00:00:00.000000000 Z
+date: 2015-03-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: method_source