tco_method 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 5b38db19eea395f824f107cdf26128b24f4a0de7
-  data.tar.gz: 061f302f00571f8d3290b2c33deb15c8e3e12c85
+  metadata.gz: 15a6ac46846b32e0e851d33bc6285481da316a59
+  data.tar.gz: b3e6b3fb09936ff95b3342e009c6216edbf756d6
 SHA512:
-  metadata.gz: 5582d4e9e64fc235526dc5c5504ad041e1736252f9017c45934990f0bbd8c005327dc12ecad192373a1cce42a00e76209b5abff4038248170105860b79222987
-  data.tar.gz: 8e38fa82f97b0cb9f60678ef5342f59f7c7042ed5cd4104f90b49a66cb82de4e9c6571cd36aaa9ea8695d2f3c4d885c718794372c19a8f15bd5f7a0e21d7503f
+  metadata.gz: 7651b179452b164aabba4ef9b7435f06c81f84f50496555a7eb2e05ed0fefcc8e47144c18902fb57f96cc331c5e1c52ea6dba8c8c3f4de30c6c689bc89a94737
+  data.tar.gz: 876eadb63edf03f8ea5b05f2e53a5d69dc5d9b9ec12a86de083a78c1b2e137f149db166be7e3d61c065fb467e6fb4258bb60eabd46b7020061b090573dc6fcba

data/README.md

@@ -6,11 +6,29 @@
 [![Code Climate](https://codeclimate.com/github/tdg5/tco_method/badges/gpa.svg)](https://codeclimate.com/github/tdg5/tco_method)
 [![Dependency Status](https://gemnasium.com/tdg5/tco_method.svg)](https://gemnasium.com/tdg5/tco_method)
 
-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 in MRI Ruby. Also provides `TCOMethod.tco_eval` providing a
-direct and easy means to evaluate code strings with tail call optimization
-enabled.
+The `tco_method` gem provides a number of different APIs to facilitate
+evaluating code with tail call optimization enabled in MRI Ruby.
+
+The `TCOMethod.with_tco` method is perhaps the simplest means of evaluating code
+with tail call optimization enabled. `TCOMethod.with_tco` takes a block and
+compiles all code **in that block** with tail call optimization enabled.
+
+The `TCOMethod::Mixin` module extends Classes and Modules with helper methods
+(kind of like method annotations) to facilitate compiling some types of methods
+with tail call optimization enabled.
+
+The `TCOMethod.tco_eval` method provides a direct means to evaluate code strings
+with tail call optimization enabled. This API is the most cumbersome, but it can
+be useful for loading full files with tail call optimization enabled (see
+examples below). It is also the foundation of all of the other `TCOMethod` APIs.
+
+Be warned, there are a few gotchas. For example, even when using one of the APIs
+provided by the `tco_method` gem, `require`, `load`, and `Kernel#eval` still
+won't evaluate code with tail call optimization enabled without changing the
+`RubyVM` settings globally.  More on the various limitations of the `tco_method`
+gem are outlined in the docs in the
+[Gotchas](http://www.rubydoc.info/gems/tco_method/file/README.md#Gotchas)
+section.
 
 ## Installation
 
@@ -41,8 +59,38 @@ library:
 require "tco_method"
 ```
 
-Extend a class with the [`TCOMethod::Mixin`](http://www.rubydoc.info/gems/tco_method/TCOMethod/Mixin)
-and let the fun begin!
+### `TCOMethod.with_tco`
+
+The fastest road to tail call optimized glory is the
+[`TCOMethod.with_tco`](http://www.rubydoc.info/gems/tco_method/TCOMethod#with_tco-class_method)
+method. Using
+[`TCOMethod.with_tco`](http://www.rubydoc.info/gems/tco_method/TCOMethod#with_tco-class_method)
+you can evaluate a block of code with tail call optimization enabled liked so:
+
+```ruby
+TCOMethod.with_tco do
+  class MyClass
+    def factorial(n, acc = 1)
+      n <= 1 ? acc : factorial(n - 1, n * acc)
+    end
+  end
+end
+
+puts MyClass.new.factorial(10_000).to_s.length
+# => 35660
+```
+
+It's worth noting that in the example above the actual optimized tail call
+occurs outside of the `TCOMethod.with_tco` block. `TCOMethod.with_tco` is used
+to compile code in such a way that tail call optimization is enabled. Once
+compiled, the tail call optimized code can be invoked from anywhere in the
+program.
+
+### `TCOMethod::Mixin`
+
+Alternatively, you can extend a Class or Module with the
+[`TCOMethod::Mixin`](http://www.rubydoc.info/gems/tco_method/TCOMethod/Mixin)
+and let the TCO fun begin using helpers that act like method annotations.
 
 To redefine an instance method with tail call optimization enabled, use
 [`tco_method`](http://www.rubydoc.info/gems/tco_method/TCOMethod/Mixin:tco_method):
@@ -79,9 +127,16 @@ 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`
+
+Finally, depending on your needs (and your love for stringified code blocks),
+you can also use
 [`TCOMethod.tco_eval`](http://www.rubydoc.info/gems/tco_method/TCOMethod/Mixin:tco_eval)
-directly:
+directly.
+[`TCOMethod.tco_eval`](http://www.rubydoc.info/gems/tco_method/TCOMethod/Mixin:tco_eval)
+can be useful in situations where the `method_source` gem is unable to determine
+the source of a particular block or for loading entire files with tail call
+optimization enabled.
 
 ```ruby
 TCOMethod.tco_eval(<<-CODE)
@@ -96,11 +151,12 @@ MyClass.new.factorial(10_000).to_s.length
 # => 35660
 ```
 
-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:
+You can kind of get around the need for stringified code blocks by reading the
+code you want to compile with tail call optimization dynamically at runtime, but
+this approach also has downsides in that it goes around the standard Ruby
+`require`/`load` process. 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
@@ -122,9 +178,9 @@ module MyFibonacci
 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
+If you really want to get crazy, you can include the `TCOMethod::Mixin` module
+in the `Module` class to 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
@@ -144,17 +200,36 @@ puts MyFibonacci.fibonacci(10_000).to_s.length
 ```
 
 ## Gotchas
-
-Quirks with Module and Class annotations:
+**Quirks with the `method_source` gem**:
+- Annotations and `TCOMethod.with_tco` use the
+  [`method_source` gem](https://github.com/banister/method_source) to retrieve
+  the method source to evaluate. As a result, class annotations and
+  `TCOMethod.with_tco` can act strangely when used in more dynamic contexts like
+  `irb` or `pry`.  Additionally, if the code to be evaluated is formatted in
+  unconventional ways, it can make it difficult for `method_source` and/or
+  `tco_method` to determine the unambiguous source of the method or code block.
+  Most of these ambiguities can be solved by following standard Ruby formating
+  conventions.
+
+**Quirks with `TCOMethod.with_tco`**:
+- Because the source code of the specified block is determined using the
+  `method_source` gem, the given block will be evaluated with a binding
+  different from the one it was defined in. Attempts have been made to get around
+  this, but so far, no dice. Seems like a job for a C extension.
+- `require`, `load`, and `eval` will still load code **without tail call
+  optimization enabled** even when called from within a block given to
+  `TCOMethod.with_tco`. Each of these methods compiles code using the primary
+  `RubyVM::InstructionSequence` object which honors the configuration specified
+  by `RubyVM::InstructionSequence.compile_option`.
+
+**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.
+  constants and, ergo, don't have names that can be used for lookup.
 
-I'm sure there are more and I will document them here as I come across them.
+There are almost certainly more gotchas, so check back for more in the future if
+you run into weirdness while using this gem. Issues are welcome.
 
 ## Contributing
 
@@ -169,10 +244,10 @@ I'm sure there are more and I will document them here as I come across them.
 - Class annotations are based on [Nithin Bekal's blog post *Tail Call
   Optimization in Ruby*](http://nithinbekal.com/posts/ruby-tco/) which follows
   his efforts to create a method decorator to recompile methods with tail call
-  optimization
+  optimization.
 - For more background on how tail call optimization is implemented in MRI Ruby,
-  see [Danny Guinther's *Tail Call Optimization in Ruby: Deep Dive*](http://blog.tdg5.com/tail-call-optimization-ruby-deep-dive/)
+  see [Danny Guinther's *Tail Call Optimization in Ruby: Deep Dive*](http://blog.tdg5.com/tail-call-optimization-ruby-deep-dive/).
 - For those on flavors of Ruby other than MRI, check out [Magnus Holm's *Tailin'
   Ruby*](http://timelessrepo.com/tailin-ruby) for some insight into how else
   tail call optimization (or at least tail call optimization like behavior) can
-  be achieved in Ruby
+  be achieved in Ruby.

data/lib/tco_method.rb

@@ -1,7 +1,7 @@
 require "method_source"
 require "tco_method/version"
-require "tco_method/method_info"
 require "tco_method/mixin"
+require "tco_method/block_with_tco"
 
 # The namespace for the TCOMethod gem. Home to private API methods employed by
 # the {TCOMethod::Mixin} module to provide tail call optimized behavior to
@@ -17,48 +17,6 @@ module TCOMethod
     trace_instruction: false,
   }.freeze
 
-  # Reevaluates a method with tail call optimization enabled.
-  #
-  # @note This method is not part of the public API and should not be used
-  #   directly. See {TCOMethod::Mixin} for a module that provides publicly
-  #   supported access to the behaviors provided by this method.
-  # @param [Class, Module] receiver The Class or Module for which the specified
-  #   module, class, or instance method should be reevaluated with tail call
-  #   optimization enabled.
-  # @param [String, Symbol] method_name The name of the method that should be
-  #   reevaluated with tail call optimization enabled.
-  # @param [Symbol] method_owner A symbol representing whether the specified
-  #   method is expected to be owned by a class, module, or instance.
-  # @return [Symbol] The symbolized method name.
-  # @raise [ArgumentError] Raised if receiver, method_name, or method_owner
-  #   argument is omitted.
-  # @raise [TypeError] Raised if the specified method is not a method that can
-  #   be reevaluated with tail call optimization enabled.
-  def self.reevaluate_method_with_tco(receiver, method_name, method_owner)
-    raise ArgumentError, "Receiver required!" unless receiver
-    raise ArgumentError, "Method name required!" unless method_name
-    raise ArgumentError, "Method owner required!" unless method_owner
-    if method_owner == :instance
-      existing_method = receiver.instance_method(method_name)
-    elsif method_owner == :class || method_owner== :module
-      existing_method = receiver.method(method_name)
-    end
-    method_info = MethodInfo.new(existing_method)
-    if method_info.type != :method
-      raise TypeError, "Invalid method type: #{method_info.type}"
-    end
-    receiver_class = receiver.is_a?(Class) ? :class : :module
-    code = <<-CODE
-      #{receiver_class} #{receiver.name}
-        #{existing_method.source}
-      end
-    CODE
-
-    file, line = existing_method.source_location
-    tco_eval(code, file, File.dirname(file), line - 1)
-    method_name.to_sym
-  end
-
   # Provides a mechanism for evaluating Strings of code with tail call
   # optimization enabled.
   #
@@ -71,4 +29,36 @@ module TCOMethod
     raise ArgumentError, "Invalid code string!" unless code.is_a?(String)
     RubyVM::InstructionSequence.new(code, file, path, line, ISEQ_OPTIONS).eval
   end
+
+  # Allows for executing a block of code with tail call optimization enabled.
+  #
+  # All code that is evaluated in the block will be evaluated with tail call
+  # optimization enabled, however here be dragons, so be warned of a few things:
+  #
+  # 1. Though it may not be obvious, any call to `require`, `load`, or similar
+  # methods from within the block will be evaluated by another part of the VM
+  # and will not be tail call optimized. This applies for `tco_eval` as well.
+  #
+  # 2. The block will be evaluated with a different binding than the binding it
+  # was defined in. That means that references to variables or other binding
+  # context will result in method errors. For example:
+  #
+  #     some_variable = "Hello, World!"
+  #     womp_womp = TCOMethod.with_tco { some_variable }
+  #     # => NameError: Undefined local variable or method 'some_variable'
+  #
+  # 3. Though this approach is some what nicer than working with strings of
+  # code, it comes with the tradeoff that it relies on the the `method_source`
+  # gem to do the work of finding the source of the block. There are situations
+  # where `method_source` can't accurately determine the source location of a
+  # block. That said, if you don't format your code like a maniac, you should be
+  # fine.
+  #
+  # @param [Proc] block The proc to evaluate with tail call optimization
+  #   enabled.
+  # @return [Object] Returns whatever the result of evaluating the given block.
+  def self.with_tco(&block)
+    raise ArgumentError, "Block required" unless block_given?
+    BlockWithTCO.new(&block).result
+  end
 end

data/lib/tco_method/ambiguous_source_error.rb

@@ -0,0 +1,42 @@
+module TCOMethod
+  # Exception raised when it's not possible to reliably determine the source
+  # code of a block.
+  class AmbiguousSourceError < StandardError
+    # Default message template.
+    MESSAGE = "Could not determine source of block".freeze
+
+    # Returns the exception that this exception was created to wrap if any such
+    # exception exists. Used only when this exception is created to wrap
+    # another.
+    attr_accessor :original_exception
+
+    # Create an exception from a problematic block.
+    #
+    # @param [Proc] block The block for which the source is ambiguous.
+    # @return [AmbiguousBlockError] A new exception instance wrapping the given
+    #   exception.
+    def self.from_proc(block)
+      new(MESSAGE + " #{block.inspect}")
+    end
+
+    # Wrap another exception with an AmbiguousBlockError. Useful for wrapping
+    # errors raised by MethodSource.
+    #
+    # @param [Exception] exception The exception instance that should be
+    #   wrapped.
+    # @return [AmbiguousBlockError] A new exception instance wrapping the given
+    #   exception.
+    def self.wrap(exception)
+      error = new(exception.message)
+      error.original_exception = exception
+      error
+    end
+
+    # Creates a new instance of the exception.
+    #
+    # @param [String] message The message to use with the exception.
+    def initialize(message = MESSAGE)
+      super
+    end
+  end
+end

data/lib/tco_method/block_extractor.rb

@@ -0,0 +1,107 @@
+require "tco_method/ambiguous_source_error"
+require "method_source"
+require "ripper"
+
+module TCOMethod
+  # Object encapsulating the logic to extract the source code of a given block.
+  class BlockExtractor
+    DO_STR = "do".freeze
+    END_STR = "end".freeze
+
+    attr_reader :source
+
+    def initialize(block)
+      source = block.source
+      type = block.lambda? ? :lambda : :proc
+      start_offset, end_offset = determine_offsets(block, source)
+      @source = "#{type} #{source[start_offset..end_offset]}"
+    rescue MethodSource::SourceNotFoundError => ex
+      raise AmbiguousSourceError.wrap(ex)
+    end
+
+    private
+
+    # Encapsulates the logic required to determine the offset of the end of the
+    # block. The end of the block is characterized by a matching curly brace
+    # (`}`) or the `end` keyword.
+    def determine_end_offset(block, tokens, source, expected_matcher)
+      lines = source.lines
+      last_line_number = lines.length
+      end_offset = nil
+      tokens.reverse_each do |token|
+        # Break once we're through with the last line.
+        break if token[0][0] != last_line_number
+
+        # Look for expected match to block opener
+        next if token[1] != expected_matcher
+        next if token[1] == :on_kw && token[2] != END_STR
+
+        # Raise if we've already found something that looks like a block end.
+        raise AmbiguousSourceError.from_proc(block) if end_offset
+        # Ending offset is the position of the ending token, plus the length of
+        # that token.
+        end_offset = token[0][1] + token[2].length
+      end
+      raise AmbiguousSourceError.from_proc(block) unless end_offset
+      determine_end_offset_relative_to_source(end_offset, lines.last.length)
+    end
+
+    # We subract the length of the last line from end offset to determine the
+    # negative offset into the source string. However we must subtract 1 to
+    # correct for the negative offset referring to the character after the
+    # desired terminal character.
+    def determine_end_offset_relative_to_source(end_offset, last_line_length)
+      end_offset - last_line_length - 1
+    end
+
+    # Tokenizes the source of the block as determined by the `method_source` gem
+    # and determines the beginning and end of the block.
+    #
+    # In both cases the entire line is checked to ensure there's no unexpected
+    # ambiguity as to the start or end of the block. See the test file for this
+    # class for examples of ambiguous situations.
+    #
+    # @param [Proc] block The proc for which the starting offset of its source
+    # code should be determined.
+    # @param [String] source The source code of the provided block.
+    # @raise [AmbiguousSourceError] Raised when the source of the block cannot
+    #   be determined unambiguously.
+    # @return [Array<Integer>] The start and end offsets of the block's source
+    #   code as 2-element Array.
+    def determine_offsets(block, source)
+      tokens = Ripper.lex(source)
+      start_offset, start_token = determine_start_offset(block, tokens)
+      expected_match = start_token == :on_kw ? :on_kw : :on_rbrace
+      end_offset = determine_end_offset(block, tokens, source, expected_match)
+      [start_offset, end_offset]
+    end
+
+    # The logic required to determine the starting offset of the block. The
+    # start of the block is characterized by the opening left curly brace (`{`)
+    # of the block or the `do` keyword. Everything prior to the start of the
+    # block is ignored because we can determine whether the block should be a
+    # lambda or a proc by asking the block directly, and we may not always have
+    # such a keyword available to us, e.g. a method that takes a block like
+    # TCOMethod.with_tco.
+    def determine_start_offset(block, tokens)
+      start_offset = start_token = nil
+      # The start of the block should occur somewhere on line 1.
+      # Check the whole line to ensure there aren't multiple blocks on the line.
+      tokens.each do |token|
+        # Break after line 1.
+        break if token[0][0] != 1
+
+        # Look for a left brace (`{`) or `do` keyword.
+        if token[1] == :on_lbrace || (token[1] == :on_kw && token[2] == DO_STR)
+          # Raise if we've already found something that looks like a block
+          # start.
+          raise AmbiguousSourceError.from_proc(block) if start_offset
+          start_token = token[1]
+          start_offset = token[0][1]
+        end
+      end
+      raise AmbiguousSourceError.from_proc(block) unless start_offset
+      [start_offset, start_token]
+    end
+  end
+end