sourcify 0.3.0 → 0.4.0

data/.infinity_test

@@ -0,0 +1,32 @@
+# Hacking RVM
+module RVM
+  module Shell
+    class AbstractWrapper
+      def raw_stdout_to_parts(c)
+        raise IncompleteCommandError if !command_complete?(c)
+        before, after = c.split(COMMAND_EPILOG_START, 2)
+        epilog, after = after.split(COMMAND_EPILOG_END, 2)
+        # HACK .. need to apply gsub to prevent yaml-related error
+        return before, YAML.load(epilog.strip.gsub("\\\"\n","\"\n")), after
+      end
+    end
+  end
+end
+
+# See http://github.com/tomas-stefano/infinity_test/wiki/Customize-Infinity-Test
+infinity_test do
+
+  # Sets bacon mute to avoid excessive noise that makes it hard to pinpoint errors
+  ENV['MUTE_BACON'] = 'true'
+
+  use \
+    :test_framework => :bacon,
+    :rubies => %w(
+      ruby-1.8.6-p399@parsetree
+      ruby-1.8.7-p302
+      ree-1.8.7-2010.02
+      ruby-1.9.1-p376
+      ruby-1.9.2-p0
+      jruby-1.5.3
+    )
+end

data/HISTORY.txt

@@ -1,3 +1,15 @@
+=== 0.4.0 (Oct 15, 2010)
+
+* adds Proc#to_source(:strip_enclosure => ...) (& the Proc#to_sexp equivalent) to ease
+  stripping of enclosing 'proc {|params| ... }', returning only the inner code body
+  '...' [#ngty]
+* adds Proc#to_source(:attached_to => ..., :ignore_nested => ..., &body_matcher) (& the
+  Proc#to_sexp equivalent) to narrow down code scanning, avoiding unnecessary
+  Sourcify::MultipleMatchingProcsPerLineError, useful for libs that can anticipate
+  how the proc should look like [#ngty]
+* adds support for running in MRI-1.9.2 [#ngty]
+* fixes '/' operator always treated as start of regexp [#ngty & #seamusabshere]
+
 === 0.3.0 (Sep 23, 2010)
 
 * Proc#to_source & friends now work in IRB as well [#ngty]

data/README.rdoc

@@ -5,7 +5,8 @@ ParseTree[http://github.com/seattlerb/parsetree] is great, it accesses the runti
 S-expression, BUT ParseTree doesn't work for 1.9.* & JRuby.
 
 RubyParser[http://github.com/seattlerb/ruby_parser] is great, and it works for any rubies
-(of course, not 100% compatible for 1.9.* syntax yet), BUT it works only with static code.
+(of course, not 100% compatible for 1.8.7 & 1.9.* syntax yet), BUT it works only with
+static code.
 
 I truely enjoy using the above tools, but with my other projects, the absence of ParseTree
 on the different rubies is forcing me to hand-baked my own solution each time to extract
@@ -14,8 +15,8 @@ never perfect, and i'm reinventing the wheel each time just to address a particu
 pattern of usage (using regexp kungfu).
 
 Enough is enough, and now we have Sourcify, a unified solution to extract proc code.
-When ParseTree is available, it simply works as a wrapper round it, otherwise, it uses
-a home-baked ragel-generated scanner to extract the proc code. Further processing
+When ParseTree is available, it simply works as a thin wrapper round it, otherwise, it
+uses a home-baked ragel-generated scanner to extract the proc code. Further processing
 with RubyParser & Ruby2Ruby to ensure 100% with ParseTree (yup, there is no denying that
 i really like ParseTree).
 
@@ -39,29 +40,40 @@ Returns the code representation of the proc:
 
   require 'sourcify'
 
-  proc1 = lambda { x + y }
-  puts proc1.to_source # proc { (x + y) }
+  lambda { x + y }.to_source
+  # >> "proc { (x + y) }"
 
-  proc2 = proc { x + y }
-  puts proc2.to_source # proc { (x + y) }
+  proc { x + y }.to_source
+  # >> "proc { (x + y) }"
 
 Like it or not, a lambda is represented as a proc when converted to source (exactly the
-same way as ParseTree).
+same way as ParseTree). It is possible to only extract the body of the proc by passing
+in {:strip_enclosure => true}:
+
+  lambda { x + y }.to_source(:strip_enclosure => true)
+  # >> "(x + y)"
+
+  lambda {|i| i + 2 }.to_source(:strip_enclosure => true)
+  # >> "(i + 2)"
 
 === 2. Proc#to_sexp
 
 Returns the S-expression of the proc:
 
   require 'sourcify'
-  require 'pp'
 
   x = 1
-  pp lambda { x + y }.to_sexp
+  lambda { x + y }.to_sexp
   # >> s(:iter,
   # >>  s(:call, nil, :proc, s(:arglist)),
   # >>   nil,
   # >>    s(:call, s(:lvar, :x), :+, s(:arglist, s(:call, nil, :y, s(:arglist)))))
 
+To extract only the body of the proc:
+
+  lambda { x + y }.to_sexp(:strip_enclosure => true)
+  # >> s(:call, s(:lvar, :x), :+, s(:arglist, s(:call, nil, :y, s(:arglist)))))
+
 === 3. Proc#source_location
 
 By default, this is only available on 1.9.*, it is added (as a bonus) to provide
@@ -69,9 +81,8 @@ consistency under 1.8.*:
 
   # /tmp/test.rb
   require 'sourcify'
-  require 'pp'
 
-  pp lambda { x + y }.source_location
+  lambda { x + y }.source_location
   # >> ["/tmp/test.rb", 5]
 
 == Performance
@@ -105,10 +116,10 @@ will not work:
     eval('lambda { x + y }')
   end
 
-  pp test.source_location
+  test.source_location
   # >> ["(eval)", 1]
 
-  puts test.to_source
+  test.to_source
   # >> Sourcify::CannotParseEvalCodeError
 
 The same applies to *Blah#to_proc* & *&:blah*:
@@ -131,7 +142,7 @@ subject proc has arity that is unique from others:
 
   # Yup, this works as expected :)
   b1 = lambda {|a| a+1 }; b2 = lambda { 1+2 }
-  puts b2.to_source
+  b2.to_source
   # >> proc { (1 + 2) }
 
   # Nope, this won't work :(
@@ -139,33 +150,56 @@ subject proc has arity that is unique from others:
   b2.to_source
   # >> raises Sourcify::MultipleMatchingProcsPerLineError
 
-Using Proc#arity is a pretty good way to uniquely identify the subject proc, since having
-too many procs per line is not a good practice as it reduces readability. However, the
-following bug[http://redmine.ruby-lang.org/issues/show/574] under 1.8.* may trip u over:
+As observed, the above does not work when there are multiple procs having the same arity,
+on the same line. Furthermore, this bug[http://redmine.ruby-lang.org/issues/show/574]
+under 1.8.* affects the accuracy of this approach.
+
+To better narrow down the scanning, try:
+
+* passing in the {:attached_to => ...} option
+
+    x = lambda { proc { :blah } }
+
+    x.to_source
+    # >> Sourcify::MultipleMatchingProcsPerLineError
+
+    x.to_source(:attached_to => :lambda)
+    # >> "proc { proc { :blah } }"
 
-  lambda { }.arity         # 1.8.* (-1) / 1.9.* (0)  (?!)
-  lambda {|| }.arity       # 1.8.* (0)  / 1.9.* (0)
-  lambda {|x| }.arity      # 1.8.* (1)  / 1.9.* (1)
-  lambda {|x,y| }.arity    # 1.8.* (2)  / 1.9.* (2)
-  lambda {|*x| }.arity     # 1.8.* (-1) / 1.9.* (-1)
-  lambda {|x, *y| }.arity  # 1.8.* (-2) / 1.9.* (-2)
-  lambda {|(x,y)| }.arity  # 1.8.* (1)  / 1.9.* (1)
+* passing in the {:ignore_nested => ...} option
 
-This is another reason to install ParseTree when u are on 1.8.*. On JRuby, where u don't
-have the choice, just avoid multiple procs per line.
+    x = lambda { lambda { :blah } }
+
+    x.to_source
+    # >> Sourcify::MultipleMatchingProcsPerLineError
+
+    x.to_source(:ignore_nested => true)
+    # >> "proc { lambda { :blah } }"
+
+* attaching a body matcher proc
+
+    x, y = lambda { def secret; 1; end }, lambda { :blah }
+
+    x.to_source
+    # >> Sourcify::MultipleMatchingProcsPerLineError
+
+    x.to_source{|body| body =~ /^(.*\W|)def\W/ }
+    # >> 'proc { def secret; 1; end }'
+
+Pls refer to the rdoc for more details.
 
 === 3. Occasional Racc::ParseError
 
 Under the hood, sourcify relies on RubyParser to yield s-expression, and since RubyParser
-does not yet fully handle 1.8.7/1.9.* syntax, you will get a nasty Racc::ParseError when
+does not yet fully handle 1.8.7 & 1.9.* syntax, you will get a nasty Racc::ParseError when
 you have any code that is not compatible with 1.8.6.
 
-== Is it working ??
+== Is it really working ??
 
 Sourcify spec suite currently passes in the following rubies:
 * MRI-1.8.6 (ParseTree mode ONLY)
 * MRI-1.8.7, REE-1.8.7 (ParseTree & static scanner modes)
-* JRuby-1.5.1+, MRI-1.9.1 (static scanner ONLY)
+* JRuby-1.5.1+, MRI-1.9.1, MRI-1.9.2 (static scanner ONLY)
 
 Besides its own spec suite, sourcify has also been tested to handle:
 
@@ -177,6 +211,11 @@ For projects:
 
 (TODO: the more the merrier)
 
+== Projects using it
+
+Projects using sourcify include:
+* wrong[http://github.com/sconover/wrong]
+
 == Additional Resources
 
 Sourcify is heavily inspired by many ideas gathered from the ruby community:

data/Rakefile

@@ -13,16 +13,15 @@ begin
     gem.authors = ["NgTzeYang"]
     gem.required_ruby_version = '>= 1.8.6'
     gem.add_dependency 'ruby2ruby', '>= 1.2.5'
+    gem.add_dependency "sexp_processor", ">= 3.0.5"
     gem.add_development_dependency "bacon", ">= 0"
-    gem.add_development_dependency "otaku", ">= 0.4.0"
     # Plus one of the following groups:
     #
     # 1). ParseTree (better performance + dynamic goodness, but not supported on java & 1.9.*)
     # >> gem.add_dependency "ParseTree", ">= 3.0.6"
     #
-    # 2). RubyParser (supported for all)
+    # 2). RubyParser (supported for all except 1.8.6)
     # >> gem.add_dependency "ruby_parser", ">= 2.0.5"
-    # >> gem.add_dependency "sexp_processor", ">= 3.0.5"
     # >> gem.add_dependency "file-tail", ">= 1.0.5"
   end
   Jeweler::GemcutterTasks.new

data/VERSION

@@ -1 +1 @@
-0.3.0
+0.4.0

data/lib/sourcify.rb

@@ -1,5 +1,6 @@
 require 'rubygems'
 require 'ruby2ruby'
+require 'sexp_processor'
 
 begin
   require 'parse_tree'
@@ -7,11 +8,10 @@ begin
 rescue LoadError
   raise if RUBY_VERSION == '1.8.6' # support for code scanner in 1.8.6 is too tedious
   require 'ruby_parser'
-  require 'sexp_processor'
   require 'file/tail'
 end
 
-module Sourcify
+module Sourcify #:nodoc:
   class << self
 
     def require_rb(*args)

data/lib/sourcify/proc.rb

@@ -1,85 +1,164 @@
 module Sourcify
 
   class MultipleMatchingProcsPerLineError < Exception; end
+  class NoMatchingProcError < Exception; end
   class ParserInternalError < Exception; end
   class CannotParseEvalCodeError < Exception; end
   class CannotHandleCreatedOnTheFlyProcError < Exception; end
 
   module Proc
-    def self.included(base)
-      base.class_eval do
-
-        ref_proc = lambda {}
-
-        # == Proc#source_location
-
-        unless ref_proc.respond_to?(:source_location)
-
-          # Added as a bonus, by default, only 1.9.* implements this.
-          def source_location
-            unless created_on_the_fly?
-              @source_location ||= (
-                file, line = /^#<Proc:0x[0-9A-Fa-f]+@(.+):(\d+).*?>$/.match(inspect)[1..2]
-                [file, line.to_i]
-              )
-            end
-          end
-
-          # HACK to make it easy to determine if a proc is created on the fly
-          ::Proc.class_eval do
-            attr_writer :created_on_the_fly
-            def created_on_the_fly?
-              !!@created_on_the_fly
-            end
-          end
-
-          [::Method, ::Symbol].each do |klass|
-            begin
-              klass.class_eval do
-                alias_method :__pre_sourcified_to_proc, :to_proc
-                def to_proc
-                  (_proc = __pre_sourcified_to_proc).created_on_the_fly = true
-                  _proc
-                end
-              end
-            rescue NameError
-            end
-          end
-
-        end
-
-        # == Proc#to_source
-
-        if Object.const_defined?(:ParseTree)
 
-          # When ParseTree is available, we just make use of all the convenience it offers :)
-          alias_method :to_source, :to_ruby
-
-        elsif !ref_proc.respond_to?(:to_source)
-
-          # Otherwise, we are going to do abit of static text parsing :(
-          def to_source
-            Sourcify.require_rb('proc', 'parser')
-            (@parser ||= Parser.new(self)).source
-          end
-
-        end
+    def self.included(base) #:nodoc:
+      base.class_eval do
+        Sourcify.require_rb('proc', 'methods')
+        include Methods::SourceLocation
+        include Methods::ToSource
+        include Methods::ToSexp
+      end
+    end
 
-        # == Proc#to_sexp
+    module Stubs
+
+      ###
+      # Returns the ruby source filename and line number containing this proc.
+      #
+      #   # /tmp/test.rb
+      #   x = lambda { 1 }
+      #   x.source_location # >> ["/tmp/test.rb", 2]
+      #
+      # When proc is not defined in ruby (i.e. native), or when the proc is created using
+      # Method#to_proc or Symbol#to_proc, nil is returned.
+      #
+      #   class AA
+      #     class << self
+      #       def m1; 1; end
+      #       def m2(&block); block; end
+      #     end
+      #   end
+      #
+      #   AA.method(:m1).to_proc.source_location # >> nil
+      #   AA.m2(&:m1).source_location            # >> nil
+      #
+      # For 1.9.2, the proc obtained using Method#to_proc by default yields info pointing
+      # to where the method is located. Sourcify respects this builtin implementation and
+      # assumes you usually want it. It is possible to get info that is consistent with all
+      # other rubies by passing in +get_original+ as false:
+      #
+      #   # /tmp/test.rb
+      #   class AA
+      #     def m; 1; end
+      #   end
+      #
+      #   x = AA.new.method(:m).to_proc
+      #   x.source_location        # >> ["/tmp/test.rb", 2]
+      #   x.source_location(false) # >> nil
+      #
+      def source_location(get_original = true)
+        # NOTE: this is a stub for the actual one in Methods::SourceLocation
+      end
 
-        unless ref_proc.respond_to?(:to_sexp)
-          def to_sexp
-            Sourcify.require_rb('proc', 'parser')
-            (@parser ||= Parser.new(self)).sexp
-          end
-        end
+      ###
+      # Returns the code representation of this proc.
+      #
+      #   lambda {|i| i+1 }.to_source
+      #   # >> "proc {|i| i+1 }"
+      #
+      # The following options are supported:
+      #
+      # * +:strip_enclosure+ when set to true, strips the enclosing "proc { ... }" to get
+      #   just the meat within.
+      #
+      #     lambda {|i| i+1 }.to_source(:strip_enclosure => true)
+      #     # >> "i+2"
+      #
+      #   (this option is effective regardless of presence of ParseTree)
+      #
+      # * +:attached_to+ is useful to avoid the nasty
+      #   Sourcify::MultipleMatchingProcsPerLineError (as a result of ambiguities when doing
+      #   static code analysis), it declares the condition that must be met prior grabbing
+      #   the code block:
+      #
+      #     x = lambda { proc { :blah } }
+      #
+      #     x.to_source
+      #     # >> Sourcify::MultipleMatchingProcsPerLineError
+      #
+      #     x.to_source(:attached_to => :lambda)
+      #     # >> "proc { proc { :blah } }"
+      #
+      #   Sometimes more control is needed:
+      #
+      #     # We want to ignore everything associated with ignore
+      #     def ignore(&block); block; end
+      #     x = lambda { ignore { :blah } }
+      #
+      #     x.to_source
+      #     # >> Sourcify::MultipleMatchingProcsPerLineError
+      #
+      #     x.to_source(:attached_to => /^(.*\W|)(lambda|proc)\W/)
+      #     # >> "proc { ignore { :blah } }"
+      #
+      #   (this option is effective ONLY when ParseTree is not available)
+      #
+      # * +:ignore_nested+ is useful when only the outermost proc matters and we want to
+      #   ignore all other nested proc(s):
+      #
+      #     x = lambda { lambda { :blah } }
+      #
+      #     x.to_source
+      #     # >> Sourcify::MultipleMatchingProcsPerLineError
+      #
+      #     x.to_source(:ignore_nested => true)
+      #     # >> "proc { lambda { :blah } }"
+      #
+      #   However, since code scanning stops at the outermost proc, beware of the following:
+      #
+      #     x = lambda {|_| lambda { lambda { :blah } } }.call(nil)
+      #
+      #     x.to_source
+      #     # >> "proc { lambda { :blah } }"
+      #
+      #     x.to_source(:ignore_nested => true)
+      #     # >> Sourcify::NoMatchingProcError
+      #
+      #   (this option is effective ONLY when ParseTree is not available)
+      #
+      # When in static code analysis (non-ParseTree) mode, it is even possible to
+      # specify how the proc body should look like by passing in a code block:
+      #
+      #     x, y = lambda { def secret; 1; end }, lambda { :blah }
+      #
+      #     x.to_source
+      #     # >> Sourcify::MultipleMatchingProcsPerLineError
+      #
+      #     x.to_source{|body| body =~ /^(.*\W|)def\W/ }
+      #     # >> "proc { def secret; 1; end }"
+      #
+      def to_source(opts={}, &body_matcher)
+        # NOTE: this is a stub for the actual one in Methods::ToSource
+      end
 
+      ###
+      # Returns the S-expression representation of this proc.
+      #
+      #   lambda {|i| i+1 }.to_sexp
+      #   # >> s(:iter,
+      #   # >>   s(:call, nil, :proc, s(:arglist)),
+      #   # >>   s(:lasgn, :i),
+      #   # >>   s(:call, s(:lvar, :i), :+, s(:arglist, s(:lit, 1))))
+      #
+      # (pls see #to_source for options/arguments supported)
+      #
+      def to_sexp(opts={}, &body_matcher)
+        # NOTE: this is a stub for the actual one in Methods::ToSexp
       end
+
     end
+
   end
 
 end
 
-::Proc.class_eval do
+Proc.class_eval do
   include Sourcify::Proc
 end