mvz-live_ast 1.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 4396a6fdc53cf54aeb3b6266167f0068549d7d2c
+  data.tar.gz: bdd39a8334d5f29c054d72c5125d21347b0dfa19
+SHA512:
+  metadata.gz: 81b894dcecb96cb803a65c06d77f99f374a91c877721dd5d6fd220b7f5bf79fe5a951d0426d65973d99d404146d146977995942b0ee7344bf3c6c685f2d128c6
+  data.tar.gz: 8ff9b6c24ff52fffd01bb0acca72c391fdab696b5954892da9a98441859eaf109da06798a9362ff347cc221204325ccafdf4c743cc3c08a71e0c3f1d69b3eb10

data/CHANGES.rdoc

@@ -0,0 +1,93 @@
+
+= live_ast Changes
+
+== Version 1.1.0
+
+* incorporate default parser in the main gem
+* update RubyParser dependency
+* use binding_of_caller gem instead of boc
+
+== Version 1.0.2
+
+* handle -unix, -dos, -mac special encoding suffixes
+
+== Version 1.0.1
+
+* add tests for "def self.f" and "def A.f" (plugins were missing this construct)
+
+== Version 1.0.0
+
+* no known bugs; API is settled
+* ast_load respects $VERBOSE=true
+
+== Version 0.7.3
+
+* live_ast/full now available for jruby (via boc gem)
+* fix instance_eval with BasicObject instance
+
+== Version 0.7.2
+
+* fix old find&replace accident with boc; rubyspec test now enabled by default
+
+== Version 0.7.1
+
+* fix rubygems problem when parser not loaded after live_ast/full
+
+== 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
+
+== Version 0.6.2
+
+* simplified irb handling; readline no longer required
+* add -e notes to readme
+
+== Version 0.6.1
+
+* enable usage inside irb
+
+== Version 0.6.0
+
+* removed FlushError and NoSourceError -- not possible to distinguish these
+* added more tests
+* refined testing API for plugins
+
+== Version 0.5.2
+
+* fix default plugin version
+
+== Version 0.5.1
+
+* protect against user needlessly requiring default parser
+
+== Version 0.5.0
+
+* new parser plugin API
+
+== Version 0.2.3
+
+* fix a utf-8 BOM issue
+
+== Version 0.2.2
+
+* handle utf-8 BOMs in loading
+
+== Version 0.2.1
+
+* fixed some rdoc issues
+* removed rubyforge references
+* update ruby_parser
+* less MRI-centric tests
+
+== Version 0.2.0
+
+* initial release

data/README.rdoc

@@ -0,0 +1,419 @@
+
+= LiveAST
+
+== Summary
+
+Live abstract syntax trees of methods and procs. Fork of +live_ast+
+(http://quix.github.com/live_ast).
+
+== Synopsis
+
+  require 'live_ast'
+
+  class Greet
+    def default
+      "hello"
+    end
+  end
+
+  #### ASTs of methods
+  
+  p Greet.instance_method(:default).to_ast
+  # => s(:defn, :default, s(:args), s(:str, "hello"))
+
+  #### ASTs of lambdas, procs, blocks
+
+  f = lambda { "foo" }
+  p f.to_ast
+  # => s(:iter, s(:call, nil, :lambda), s(:args), s(:str, "foo"))
+
+  def query(&block)
+    p block.to_ast
+    # => s(:iter, s(:call, nil, :query), s(:args), s(:str, "bar"))
+  end
+
+  query do
+    "bar"
+  end
+
+  #### ASTs from dynamic code -- pure ruby version
+
+  u = ast_eval "lambda { 'dynamic3' }", binding
+  p u.to_ast
+  # => s(:iter, s(:call, nil, :lambda), s(:args), s(:str, "dynamic3"))
+
+  ast_eval "def v ; 'dynamic4' ; end", binding
+  p method(:v).to_ast
+  # => s(:defn, :v, s(:args), s(:str, "dynamic4"))
+  
+  #### ASTs from dynamic code -- fully integrated version
+
+  require 'live_ast/full'
+
+  f = eval "lambda { 'dynamic1' }"
+  p f.to_ast
+  # => s(:iter, s(:call, nil, :lambda), s(:args), s(:str, "dynamic1"))
+
+  eval "def g ; 'dynamic2' ; end"
+  p method(:g).to_ast
+  # => s(:defn, :g, s(:args), s(:str, "dynamic2"))
+  
+== Install
+
+  % gem install mvz-live_ast
+
+== Description
+
+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. The default setting is in
+between.
+
+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.
+
+The advantage of RubyParser is that it gives the traditional ParseTree
+sexps used by tools such as <code>ruby2ruby</code>.
+
+LiveAST is thread-safe.
+
+Ruby 1.9.2 or higher is required.
+
+== Links
+
+* Home: https://github.com/mvz/live_ast
+* Feature Requests, Bug Reports: https://github.com/mvz/live_ast/issues
+
+== +to_ruby+
+
+When the default parser is active,
+
+  require 'live_ast/to_ruby'
+
+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/to_ruby'
+
+  p lambda { |x, y| x + y }.to_ruby # => "lambda { |x, y| (x + y) }"
+
+  class A
+    def f
+      "A#f"
+    end
+  end
+
+  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 plug-in, if one is found.
+
+== Pure Ruby and +ast_eval+
+
+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+, in this case +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.
+
+  require 'live_ast'
+
+  u = ast_eval "lambda { 'dynamic3' }", binding
+  p u.to_ast
+  # => s(:iter, s(:call, nil, :lambda), s(:args), s(:str, "dynamic3"))
+  
+== Full Integration
+
+In order for LiveAST to be transparent to the user, +eval+ must be
+replaced. This is accomplished with the help of the +binding_of_caller+ gem
+(https://github.com/banister/binding_of_caller).
+
+To replace +eval+,
+
+  require 'live_ast/full'
+
+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(:args), s(:str, "dynamic1"))
+
+Since LiveAST itself is pure ruby, any platforms supported by
++binding_of_caller+ should work with <code>live_ast/full</code>.
+
+== Limitations
+
+A method or block definition must not share a line with other methods
+or blocks in order for its AST to be accessible.
+
+  require 'live_ast'
+  
+  class A
+    def f ; end ; def g ; end
+  end
+  A.instance_method(:f).to_ast # => raises LiveAST::MultipleDefinitionsOnSameLineError
+  
+  a = lambda { } ; b = lambda { }
+  a.to_ast # => raises LiveAST::MultipleDefinitionsOnSameLineError
+  
+Code given to the <code>-e</code> command-line switch is not
+AST-accessible.
+
+Evaled code appearing before <code>require 'live_ast/full'</code> is
+not AST-accessible.
+
+In some circumstances +ast_eval+ and the replaced +eval+ will not give
+the same backtrace as the original +eval+ (next section).
+
+----
+== <em>Technical Issues</em>
+
+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
+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 with your own,
+
+  LiveAST.parser = YourParser
+
+To test it, provide some examples of what the ASTs look like in
+<code>YourParser::Test</code>. See +live_ast/ruby_parser+ for
+reference.
+
+== Noninvasive Mode
+
+For safety purposes, <code>require 'live_ast'</code> performs the
+invasive act of redefining +load+ (but not +require+); otherwise bad
+things can happen to the unwary. The addition of +to_ast+ to a few
+standard Ruby classes is also a meddlesome move.
+
+To avoid these modifications,
+
+  require 'live_ast/base'
+
+will provide the essentials of LiveAST but will not touch core classes
+or methods.
+
+To select features individually,
+
+  require 'live_ast/to_ast'       # define to_ast for Method, UnboundMethod, Proc
+  require 'live_ast/to_ruby'      # define to_ruby for Method, UnboundMethod, Proc
+  require 'live_ast/ast_eval'     # define Kernel#ast_eval
+  require 'live_ast/ast_load'     # define Kernel#ast_load (mentioned below)
+  require 'live_ast/replace_load' # redefine Kernel#load
+
+== Noninvasive Interface
+
+The following alternative interface is available.
+
+  require 'live_ast/base'
+
+  class A
+    def f
+      "A#f"
+    end
+  end
+
+  p LiveAST.ast(A.instance_method(:f))
+  # => s(:defn, :f, s(:args), s(:str, "A#f"))
+
+  p LiveAST.ast(lambda { })
+  # => s(:iter, s(:call, nil, :lambda), s(:args))
+
+  f = LiveAST.eval("lambda { }", binding)
+
+  p LiveAST.ast(f) 
+  # => s(:iter, s(:call, nil, :lambda), s(:args))
+  
+  ast_eval  # => raises NameError
+
+== Reloading Files In Noninvasive Mode
+
+Use +ast_load+ or (equivalently) <code>LiveAST.load</code> when
+reloading an AST-aware file.
+
+  require 'live_ast/ast_load'
+  require 'live_ast/to_ast'
+  
+  require "foo"
+  Foo.instance_method(:bar).to_ast  # caches AST
+  
+  # ... the bar method is changed in foo.rb ...
+  
+  ast_load "foo.rb"
+  p Foo.instance_method(:bar).to_ast  # => updated AST
+
+Note if +load+ is called instead of +ast_load+ then the last line will
+give the old AST,
+
+  load "foo.rb"                       # oops! forgot to use ast_load
+  p Foo.instance_method(:bar).to_ast  # => stale AST
+
+Realize that <code>foo.rb</code> may be referenced by an unknown
+number of methods and blocks. If the original <code>foo.rb</code>
+source were dumped in favor of the modified <code>foo.rb</code>, then
+an unknown number of those references would be invalidated (and some
+may even point to the wrong AST).
+
+This is the reason for the caching that results in the stale AST
+above. It should now be clear why the default behavior of
+<code>require 'live_ast'</code> is to redefine +load+: doing so
+prevents this problem entirely. On the other hand if it is fully known
+where files are being reloaded (if at all) then there's no need for
+paranoia; the noninvasive option may be the most appropriate.
+
+== The Source/AST Cache
+
++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 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
+is continually evaling/reloading <em>and</em> failing to extract the
+sexps. Nevertheless it is possible that old ASTs will eventually need
+to be garbage collected. To flush the cache,
+
+(1) Check that +to_ast+ has been called on all objects whose ASTs are
+desired.
+
+(2) Call <code>LiveAST.flush_cache</code>.
+
+Calling +to_ast+ prevents the object's AST from being flushed (since
+it grafts the AST onto the object).
+
+ASTs of procs and methods whose sources lie in <code>require</code>d
+files will never be flushed. However a method redefined via +ast_eval+
+or +load+ is susceptible to +flush_cache+ even when its original
+definition pointed to a <code>require</code>d file.
+
+== About +require+
+
+No measures have been taken to detect manipulations of
+<code>$LOADED_FEATURES</code> which would cause +require+ to load the
+same file twice. Though +require+ <em>could</em> be replaced in
+similar fashion to +load+---heading off problems arising from such
+"raw" reloads---the overhead would seem inappropriate in relation to
+the rarity of this case.
+
+Therefore the working assumption is that +require+ will load a file
+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.
+
+== Authors
+
+* James M. Lawrence < quixoticsycophant@gmail.com >
+* Matijs van Zuijlen < matijs@matijs.net >
+
+== License
+  
+  Copyright (c) 2011 James M. Lawrence. All rights reserved.
+  Copyright (c) 2014 Matijs van Zuijlen. All rights reserved.
+  
+  Permission is hereby granted, free of charge, to any person
+  obtaining a copy of this software and associated documentation files
+  (the "Software"), to deal in the Software without restriction,
+  including without limitation the rights to use, copy, modify, merge,
+  publish, distribute, sublicense, and/or sell copies of the Software,
+  and to permit persons to whom the Software is furnished to do so,
+  subject to the following conditions:
+  
+  The above copyright notice and this permission notice shall be
+  included in all copies or substantial portions of the Software.
+  
+  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+  EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+  MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+  NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
+  BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
+  ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+  CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+  SOFTWARE.
+
+LiveAST includes the source code of live_ast_ruby_parser, which is licensed as
+follows:
+
+  Copyright (c) 2011 James M. Lawrence. All rights reserved.
+  
+  Permission is hereby granted, free of charge, to any person
+  obtaining a copy of this software and associated documentation files
+  (the "Software"), to deal in the Software without restriction,
+  including without limitation the rights to use, copy, modify, merge,
+  publish, distribute, sublicense, and/or sell copies of the Software,
+  and to permit persons to whom the Software is furnished to do so,
+  subject to the following conditions:
+  
+  The above copyright notice and this permission notice shall be
+  included in all copies or substantial portions of the Software.
+  
+  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+  EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+  MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+  NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
+  BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
+  ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+  CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+  SOFTWARE.