live_ast 0.6.3 → 0.7.0

data/CHANGES.rdoc

@@ -1,6 +1,15 @@
 
 = live_ast Changes
 
+== Version 0.7.0
+
+* eval replacement option now included in the gem
+* new 'boc' gem for eval replacement -- no more syntax restrictions
+* add require 'live_ast/full' -- shortcut for 'live_ast' + 'live_ast/replace_eval'
+* rubyspec conformance for require 'live_ast/full'
+* added required_ruby_version to gemspec
+* fixed error when IRB is partially required
+
 == Version 0.6.3
 
 * minor change for Ruby 1.9.3

data/MANIFEST

@@ -7,12 +7,15 @@ lib/live_ast.rb
 lib/live_ast/ast_eval.rb
 lib/live_ast/ast_load.rb
 lib/live_ast/base.rb
+lib/live_ast/common.rb
 lib/live_ast/error.rb
 lib/live_ast/evaler.rb
+lib/live_ast/full.rb
 lib/live_ast/irb_spy.rb
 lib/live_ast/linker.rb
 lib/live_ast/loader.rb
 lib/live_ast/reader.rb
+lib/live_ast/replace_eval.rb
 lib/live_ast/replace_load.rb
 lib/live_ast/replace_raise.rb
 lib/live_ast/to_ast.rb
@@ -53,6 +56,8 @@ test/readme_test.rb
 test/recursive_eval_test.rb
 test/redefine_method_test.rb
 test/reload_test.rb
+test/replace_eval_test.rb
+test/rubyspec_test.rb
 test/stdlib_test.rb
 test/thread_test.rb
 test/to_ast_feature_test.rb

data/README.rdoc

@@ -3,8 +3,7 @@
 
 == Summary
 
-A pure Ruby library for obtaining live abstract syntax trees of
-methods and procs.
+Live abstract syntax trees of methods and procs.
 
 == Synopsis
 
@@ -18,15 +17,12 @@ methods and procs.
 
   #### ASTs of methods
   
-  m = Greet.instance_method(:default)
-
-  p m.to_ast
+  p Greet.instance_method(:default).to_ast
   # => s(:defn, :default, s(:args), s(:scope, s(:block, s(:str, "hello"))))
 
   #### ASTs of lambdas, procs, blocks
 
   f = lambda { "foo" }
-
   p f.to_ast
   # => s(:iter, s(:call, nil, :lambda, s(:arglist)), nil, s(:str, "foo"))
 
@@ -39,18 +35,27 @@ methods and procs.
     "bar"
   end
 
-  #### ASTs from dynamic code
+  #### ASTs from dynamic code -- fully integrated version
 
-  f = ast_eval "lambda { 'dynamic' }", binding
+  require 'live_ast/full'
 
+  f = eval "lambda { 'dynamic1' }"
   p f.to_ast
-  # => s(:iter, s(:call, nil, :lambda, s(:arglist)), nil, s(:str, "dynamic"))
+  # => s(:iter, s(:call, nil, :lambda, s(:arglist)), nil, s(:str, "dynamic1"))
+
+  eval "def g ; 'dynamic2' ; end"
+  p method(:g).to_ast
+  # => s(:defn, :g, s(:args), s(:scope, s(:block, s(:str, "dynamic2"))))
+  
+  #### ASTs from dynamic code -- pure ruby version
 
-  ast_eval "def g ; 'dynamic' ; end", binding
-  m = method(:g)
+  u = ast_eval "lambda { 'dynamic3' }", binding
+  p u.to_ast
+  # => s(:iter, s(:call, nil, :lambda, s(:arglist)), nil, s(:str, "dynamic3"))
 
-  p m.to_ast
-  # => s(:defn, :g, s(:args), s(:scope, s(:block, s(:str, "dynamic"))))
+  ast_eval "def v ; 'dynamic4' ; end", binding
+  p method(:v).to_ast
+  # => s(:defn, :v, s(:args), s(:scope, s(:block, s(:str, "dynamic4"))))
   
 == Install
 
@@ -64,20 +69,19 @@ Or from inside an unpacked .tgz download, <code>rake install</code> /
 LiveAST enables a program to find the ASTs of objects created by
 dynamically generated code. It may be used in a strictly noninvasive
 manner, where no standard classes or methods are modified, or it may
-be transparently integrated into Ruby (experimental). The default
-setting is in between.
+be transparently integrated into Ruby. The default setting is in
+between.
 
-RubyParser is responsible for parsing and building the ASTs, though
-another parser may be easily substituted (in fact the name +to_ast+ is
-used instead of +to_sexp+ because LiveAST has no understanding of what
-the parser outputs).
+RubyParser is the default parsing engine. To replace it with Ripper,
+<code>gem install live_ast_ripper</code> and then <code>require
+'live_ast_ripper'</code>. A simple plug-in interface allows LiveAST to
+work with any parser.
 
-Note that RubyParser does not currently support the newer Ruby 1.9
-syntax features (<code>Racc::ParseError</code> will be raised).
-
-To use the Ripper parser instead, <code>gem install
-live_ast_ripper</code> and then <code>require
-'live_ast_ripper'</code>.
+The advantage of RubyParser is that it gives the traditional ParseTree
+sexps used by tools such as <code>ruby2ruby</code>. The disadvantage
+is that the newer Ruby 1.9 syntax is not supported. However the 1.8
+syntax restriction only applies to files from which ASTs are actually
+requested. All other files may use 1.9 syntax.
 
 LiveAST is thread-safe.
 
@@ -92,15 +96,14 @@ Ruby 1.9.2 or higher is required.
 
 == +to_ruby+
 
-Although +ruby2ruby+ is not required by default,
+When the default parser is active,
 
   require 'live_ast/to_ruby'
 
-will require +ruby2ruby+ and define the +to_ruby+ method for +Method+,
-+UnboundMethod+, and +Proc+. These methods are one-liners which pass
-the extracted ASTs to +ruby2ruby+.
+will define the +to_ruby+ method for the +Method+, +UnboundMethod+,
+and +Proc+ classes. These methods are one-liners which pass the
+extracted ASTs to <code>ruby2ruby</code>.
 
-  require 'live_ast'
   require 'live_ast/to_ruby'
 
   p lambda { |x, y| x + y }.to_ruby # => "lambda { |x, y| (x + y) }"
@@ -114,38 +117,50 @@ the extracted ASTs to +ruby2ruby+.
   p A.instance_method(:f).to_ruby # => "def f\n  \"A#f\"\nend"
 
 In general, +to_ruby+ will hook into the unparser provided by the
-parser, if one is found.
+parser plug-in, if one is found.
 
-== Loading Source
+== Pure Ruby and +ast_eval+
 
-Objects created via +require+ and +load+ will be AST-accessible.
-However +ast_eval+ must be used instead of +eval+ for AST-accessible
-objects. +ast_eval+ has the same semantics as +eval+ except that the
-binding argument is required.
+An essential feature of <code>require 'live_ast'</code> is that it is
+implemented in pure ruby. However since pure ruby is not powerful
+enough to replace +eval+, one must use +ast_eval+ instead of +eval+
+for AST-accessible objects. +ast_eval+ has the same semantics as
++eval+ except that the binding argument is required.
 
   require 'live_ast'
+
+  u = ast_eval "lambda { 'dynamic3' }", binding
+  p u.to_ast
+  # => s(:iter, s(:call, nil, :lambda, s(:arglist)), nil, s(:str, "dynamic3"))
   
-  class A
-    ast_eval %{
-      def f
-        "A#f"
-      end
-
-      # nested evals OK
-      ast_eval %{
-        def g
-          "A#g"
-        end
-      }, binding
-
-    }, binding
-  end
+== Full integration
 
-  p A.instance_method(:f).to_ast
-  # => s(:defn, :f, s(:args), s(:scope, s(:block, s(:str, "A#f"))))
+In order for LiveAST to be transparent to the user, +eval+ must be
+replaced. This requires the +boc+ gem (http://quix.github.com/boc)
+which at present only targets MRI 1.9.2 (other platforms are planned).
+
+To replace +eval+,
+
+  % gem install boc
+
+and then
+
+  require 'live_ast/full'
 
-  p A.instance_method(:g).to_ast
-  # => s(:defn, :g, s(:args), s(:scope, s(:block, s(:str, "A#g"))))
+The new AST-electrified +eval+, +instance_eval+, +module_eval+,
++class_eval+, and <code>Binding#eval</code> all pass RubySpec
+(http://rubyspec.org) with the minor exception of backtraces sometimes
+not matching that of the original +eval+. See the "Backtraces" section
+below for details.
+
+  require 'live_ast/full'
+
+  f = eval "lambda { 'dynamic1' }"
+  p f.to_ast
+  # => s(:iter, s(:call, nil, :lambda, s(:arglist)), nil, s(:str, "dynamic1"))
+
+Since LiveAST itself is pure ruby, any new platforms supported by
++boc+ will automatically work with <code>live_ast/full</code>.
 
 == Limitations
 
@@ -173,6 +188,49 @@ You can probably skip these next sections. Goodbye.
 
 ----
 
+== Backtraces
+
++ast_eval+ is meant to be compatible with +eval+. For instance the
+first line of +ast_eval+'s backtrace should be identical to that of
++eval+:
+
+  require 'live_ast'
+  
+  ast_eval %{ raise "boom" }, binding
+  # => test.rb:3:in `<main>': boom (RuntimeError)
+
+Let's make a slight change,
+
+  require 'live_ast'
+  
+  f = ast_eval %{ lambda { raise "boom" } }, binding
+  f.call
+  # => test.rb|ast@a:3:in `block in <main>': boom (RuntimeError)
+
+What the heck is '<code>|ast@a</code>' doing there? LiveAST's
+implementation has just been exposed: each source input is assigned a
+unique key which enables a Ruby object to find its own definition.
+
+In the first case above, +ast_eval+ has removed the key from the
+exception backtrace. But in the second case there is no opportunity to
+remove it since +ast_eval+ has already returned.
+
+If you find this to be problem---for example if you cannot add a
+filter for the jump-to-location feature in your editor---then +raise+
+may be redefined to strip these tokens,
+
+  require 'live_ast'
+  require 'live_ast/replace_raise'
+
+  f = ast_eval %{ lambda { raise "boom" } }, binding
+  f.call
+  # => test.rb:4:in `block in <main>': boom (RuntimeError)
+
+However this only applies to a +raise+ call originating from Ruby
+code. An exception from within a native method will likely still
+contain the token in its backtrace (e.g., in MRI the exception raised
+by <code>1/0</code> comes from C).
+
 == Replacing the Parser
 
 Despite its name, LiveAST knows nothing about ASTs. It merely reports
@@ -180,7 +238,7 @@ what it finds in the line-to-AST hash returned by the parser's +parse+
 method. Replacing the parser class is therefore easy: the only
 specification is that the +parse+ instance method return such a hash.
 
-To override the default parser,
+To override the default parser with your own,
 
   LiveAST.parser = YourParser
 
@@ -274,9 +332,10 @@ paranoia; the noninvasive option may be the most appropriate.
 
 +ast_eval+ and +load+ cache all incoming code, while
 <code>require</code>d files are cached on a need-to-know basis. When
-an AST is requested, the corresponding source is parsed and discarded,
-leaving behind method and block ASTs. +to_ast+ removes an AST from the
-cache and attaches it to the appropriate object (a Proc or Module).
+an AST is requested, the corresponding source file is parsed and
+discarded, leaving behind method and block ASTs. +to_ast+ removes an
+AST from the cache and attaches it to the appropriate object (a Proc
+or Module).
 
 Ignored, unextracted ASTs will therefore linger in the cache. Since
 sexps are generally small there is little need for concern unless one
@@ -311,69 +370,6 @@ only once. Furthermore, if a file has not been reloaded then it is
 assumed that the file is unmodified between the moment it is
 <code>require</code>d and the moment the first AST is pulled from it.
 
-== Backtraces
-
-+ast_eval+ is meant to be compatible with +eval+. For instance the
-first line of +ast_eval+'s backtrace should be identical to that of
-+eval+:
-
-  require 'live_ast'
-  
-  ast_eval %{ raise "boom" }, binding
-  # => test.rb:3:in `<main>': boom (RuntimeError)
-
-Let's make a slight change,
-
-  require 'live_ast'
-  
-  f = ast_eval %{ lambda { raise "boom" } }, binding
-  f.call
-  # => test.rb|ast@a:3:in `block in <main>': boom (RuntimeError)
-
-What the heck is '<code>|ast@a</code>' doing there? LiveAST's
-implementation has just been exposed: each source input is assigned a
-unique key which enables a Ruby object to find its own definition.
-
-In the first case above, +ast_eval+ has removed the key from the
-exception backtrace. But in the second case there is no opportunity to
-remove it since +ast_eval+ has already returned.
-
-If you find this to be problem---for example if you cannot add a
-filter for the jump-to-location feature in your editor---then +raise+
-may be redefined to strip these tokens,
-
-  require 'live_ast'
-  require 'live_ast/replace_raise'
-
-  f = ast_eval %{ lambda { raise "boom" } }, binding
-  f.call
-  # => test.rb:4:in `block in <main>': boom (RuntimeError)
-
-However this only applies to a +raise+ call originating from Ruby
-code. An exception raised within a native method will likely still
-contain the token in its backtrace (e.g., in MRI the exception raised
-by <code>1/0</code> comes from C). In principle this could be fixed by
-having the Ruby interpreter dynamically call +raise+.
-
-
-== Replacing +eval+
-
-If +ast_eval+ did not require a binding argument then it could assume
-the role of +eval+, thereby making LiveAST fully transparent to the
-user. Is this possible in pure Ruby?
-
-The only option which has been investigated thus far is MRI, which can
-summon <code>Binding.of_caller</code> (recently rewritten for 1.9.2)
-to fill in the missing binding argument. Unfortunately a limitation
-with tracing events in MRI places a few odd restrictions on the syntax
-surrounding +eval+, though all restrictions can be trivially
-sidestepped. Nonetheless it does work (it passes rubyspec minus the
-above backtrace issue) despite being somewhat impractical.
-
-This (mis)feature is maintained in a separate branch named
-+replace_eval+ on github (not part of the gem). For more information see
-replace_eval.rb[http://github.com/quix/live_ast/blob/replace_eval/lib/live_ast/replace_eval.rb].
-
 == Author
 
 * James M. Lawrence < quixoticsycophant@gmail.com >

data/Rakefile

@@ -2,11 +2,11 @@ require_relative 'devel/levitate'
 
 Levitate.new "live_ast" do |s|
   s.developers << ["James M. Lawrence", "quixoticsycophant@gmail.com"]
-  s.github_user = "quix"
+  s.username = "quix"
   s.rubyforge_info = ["quix", "liveast"]
   s.camel_name = "LiveAST"
-
-  s.rdoc_title = "LiveAST: Live Abstract Syntax Trees"
+  s.required_ruby_version = ">= 1.9.2"
+  s.dependencies << ["live_ast_ruby_parser", ">= 0.6.0"]
   s.rdoc_files = %w[
     lib/live_ast/ast_eval.rb
     lib/live_ast/base.rb
@@ -15,6 +15,4 @@ Levitate.new "live_ast" do |s|
     lib/live_ast/version.rb
   ]
   s.rdoc_options << "-a"
-  
-  s.dependencies << ["live_ast_ruby_parser", ">= 0.6.0"]
 end

data/devel/levitate.rb

@@ -219,31 +219,18 @@ class Levitate
       }
       contents
     end
-  end
-
-  module InstanceEvalWithArgs
-    module_function
 
-    def with_temp_method(instance, method_name, method_block)
-      (class << instance ; self ; end).class_eval do
-        define_method(method_name, &method_block)
+    def instance_exec2(obj, *args, &block)
+      method_name = ["_", obj.object_id, "_", Thread.current.object_id].join
+      (class << obj ; self ; end).class_eval do
+        define_method method_name, &block
         begin
-          yield method_name
+          obj.send(method_name, *args)
         ensure
-          remove_method(method_name)
+          remove_method method_name
         end
       end
     end
-
-    def call_temp_method(instance, method_name, *args, &method_block)
-      with_temp_method(instance, method_name, method_block) {
-        instance.send(method_name, *args)
-      }
-    end
-
-    def instance_eval_with_args(instance, *args, &block)
-      call_temp_method(instance, :__temp_method, *args, &block)
-    end
   end
 
   include AttrLazy
@@ -296,6 +283,10 @@ class Levitate
       mod.const_get(version_constant_name)
     end or "0.0.0"
   end
+
+  attribute :required_ruby_version do
+    ">= 0"
+  end
   
   attribute :readme_file do
     "README.rdoc"
@@ -362,6 +353,10 @@ class Levitate
     []
   end
 
+  attribute :extra_gemspec do
+    lambda { |spec| }
+  end
+
   attribute :files do
     if File.file? manifest_file
       File.read(manifest_file).split("\n")
@@ -381,7 +376,7 @@ class Levitate
   end
     
   attribute :rdoc_title do
-    "#{gem_name}: #{summary}"
+    "#{gem_name}: #{summary}".sub(/\.\Z/, "")
   end
 
   attribute :require_paths do
@@ -426,6 +421,8 @@ class Levitate
         rdoc_options
         extra_rdoc_files
         require_paths
+        required_ruby_version
+        extensions
       ].each do |param|
         t = send(param) and g.send("#{param}=", t)
       end
@@ -438,6 +435,7 @@ class Levitate
       development_dependencies.each { |dep|
         g.add_development_dependency(*dep)
       }
+      extra_gemspec.call(g)
     end
   end
 
@@ -490,22 +488,22 @@ class Levitate
   }
 
   attribute :url do
-    "http://#{github_user}.github.com/#{gem_name}"
+    "http://#{username}.github.com/#{gem_name}"
   end
 
-  attribute :github_user do
-    raise "github_user not set"
+  attribute :username do
+    raise "username not set"
   end
 
   attribute :rubyforge_info do
     nil
   end
 
-  attribute :authors do
+  def authors
     developers.map { |d| d[0] }
   end
 
-  attribute :email do
+  def email
     developers.map { |d| d[1] }
   end
 
@@ -521,6 +519,10 @@ class Levitate
     []
   end
 
+  attribute :extensions do
+    ["ext/#{gem_name}/extconf.rb"].select { |f| File.file? f }
+  end
+
   def define_clean
     require 'rake/clean'
     task :clean do 
@@ -800,6 +802,35 @@ class Levitate
       puts gemspec.to_ruby
     end
   end
+
+  def define_extension
+    unless extensions.empty?
+      require 'rbconfig'
+      require 'rake/extensiontask'
+      
+      Rake::ExtensionTask.new gem_name, gemspec do |ext|
+        ext.cross_compile = true
+        ext.cross_platform = 'i386-mswin32'
+        ext.cross_compiling do |gemspec|
+          gemspec.post_install_message =
+            "U got dat binary versionation of this gemination!"
+        end
+      end
+
+      so = "lib/#{gem_name}.#{RbConfig::CONFIG["DLEXT"]}"
+      if Rake::Task[so].needed?
+        task :test => so
+      end
+
+      task :cross_native_gem do
+        Rake::Task[:gem].reenable
+        Rake.application.top_level_tasks.replace %w[cross native gem]
+        Rake.application.top_level
+      end
+
+      task :gem => :cross_native_gem
+    end
+  end
   
   def open_browser(*files)
     sh(*([browser].flatten + files))
@@ -827,7 +858,6 @@ class Levitate
 
   class << self
     include Util
-    include InstanceEvalWithArgs
 
     # From minitest, part of the Ruby source; by Ryan Davis.
     def capture_io
@@ -867,7 +897,7 @@ class Levitate
         actual = Ruby.run_file_and_capture(temp_file.path).chomp
       }
 
-      instance_eval_with_args(instance, expected, actual, index, &block)
+      instance_exec2(instance, expected, actual, index, &block)
     end
 
     def run_doc_section(file, section, instance, &block)

data/lib/live_ast/base.rb

@@ -1,5 +1,6 @@
 require 'thread'
 
+require 'live_ast/common'
 require 'live_ast/reader'
 require 'live_ast/evaler'
 require 'live_ast/linker'
@@ -61,5 +62,12 @@ module LiveAST
     def load(file, wrap = false)  #:nodoc:
       Loader.load(file, wrap)
     end
+
+    #
+    # strip the revision token from a string
+    #
+    def strip_token(file)  #:nodoc:
+      file.sub(/#{Regexp.quote Linker::REVISION_TOKEN}[a-z]+/, "")
+    end
   end
 end

data/lib/live_ast/common.rb

@@ -0,0 +1,48 @@
+
+module LiveAST
+  module Common
+    module_function
+    
+    def arg_to_str(arg)
+      begin
+        arg.to_str
+      rescue NameError
+        thing = if arg.nil? then nil else arg.class end
+
+        raise TypeError, "can't convert #{thing.inspect} into String"
+      end
+    end
+
+    def check_arity(args, range)
+      unless range.include? args.size
+        range = 0 if range == (0..0)
+
+        raise ArgumentError,
+        "wrong number of arguments (#{args.size} for #{range})"
+      end
+    end
+
+    def check_type(obj, klass)
+      unless obj.is_a? klass
+        raise TypeError, "wrong argument type #{obj.class} (expected #{klass})"
+      end
+    end
+
+    def location_for_eval(*args)
+      bind, *location = args
+
+      if bind
+        case location.size
+        when 0
+          NATIVE_EVAL.call("[__FILE__, __LINE__]", bind)
+        when 1
+          [location.first, 1]
+        else
+          location
+        end
+      else
+        ["(eval)", 1]
+      end
+    end
+  end
+end