binding_of_caller 0.2.0 → 0.3.1

data/.gitignore

@@ -0,0 +1,7 @@
+Makefile
+*.so
+*.o
+*.def
+doc/
+pkg/
+.yardoc/

data/.yardopts

@@ -0,0 +1 @@
+--markup markdown

data/LICENSE

@@ -0,0 +1,25 @@
+License
+-------
+
+(The MIT License) 
+
+Copyright (c) 2011 John Mair (banisterfiend)
+
+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.

data/README.md

@@ -3,25 +3,50 @@ binding_of_caller
 
 (C) John Mair (banisterfiend) 2011
 
-FIXME: _tagline_
+_Retrieve the binding of a method's caller in MRI 1.9.2_
 
-FIXME: _description goes here_
+The `binding_of_caller` gem provides the `Binding#of_caller` method.
+
+Using `binding_of_caller` we can grab bindings from higher up the call
+stack and evaluate code in that context. Allows access to bindings arbitrarily far up the
+call stack, not limited to just the immediate caller.
+
+**Recommended for use only in debugging situations. Do not use this in production apps.**
+
+**Only works in MRI Ruby 1.9.2**
 
 * Install the [gem](https://rubygems.org/gems/binding_of_caller): `gem install binding_of_caller`
-* Read the [documentation](http://rdoc.info/github/banister/binding_of_caller/master/file/README.markdown)
 * See the [source code](http://github.com/banister/binding_of_caller)
 
-Example: Example description
+Example: Modifying a local inside the caller of a caller
 --------
 
-Example preamble
+    def a
+      var = 10
+      b
+      puts var
+    end
+
+    def b
+      c
+    end
+
+    def c
+      binding.of_caller(2).eval('var = :hello')
+    end
+
+    a()
 
-    puts "example code"
+    # OUTPUT
+    # => hello
 
 Features and limitations
 -------------------------
 
-Feature List Preamble
+* Only works with MRI 1.9.2
+* Broken in 1.9.3, support will hopefully be provided in the near
+* future.
+* Does not work in 1.8.7, but there is a well known (continuation-based) hack to get a `Binding#of_caller` there.
 
 Contact
 -------
@@ -32,7 +57,7 @@ Problems or questions contact me at [github](http://github.com/banister)
 License
 -------
 
-(The MIT License) 
+(The MIT License)
 
 Copyright (c) 2011 (John Mair)
 

data/Rakefile

@@ -1,11 +1,12 @@
 dlext = Config::CONFIG['DLEXT']
-direc = File.dirname(__FILE__)
+
+$:.unshift 'lib'
 
 PROJECT_NAME = "binding_of_caller"
 
 require 'rake/clean'
 require 'rake/gempackagetask'
-require "#{direc}/lib/#{PROJECT_NAME}/version"
+require "#{PROJECT_NAME}/version"
 
 CLOBBER.include("**/*.#{dlext}", "**/*~", "**/*#*", "**/*.log", "**/*.o")
 CLEAN.include("ext/**/*.#{dlext}", "ext/**/*.log", "ext/**/*.o",
@@ -14,84 +15,64 @@ CLEAN.include("ext/**/*.#{dlext}", "ext/**/*.log", "ext/**/*.o",
 
 def apply_spec_defaults(s)
   s.name = PROJECT_NAME
-  s.summary = "FIX ME"
+  s.summary = "Retrieve the binding of a method's caller. Can also retrieve bindings even further up the stack. Currently only works for MRI 1.9.2."
   s.version = BindingOfCaller::VERSION
   s.date = Time.now.strftime '%Y-%m-%d'
   s.author = "John Mair (banisterfiend)"
   s.email = 'jrmair@gmail.com'
   s.description = s.summary
   s.require_path = 'lib'
-  s.add_development_dependency("bacon",">=1.1.0")
-  s.homepage = "http://banisterfiend.wordpress.com"
+  s.add_development_dependency("bacon","~>1.1.0")
+  s.homepage = "http://github.com/banister/binding_of_caller"
   s.has_rdoc = 'yard'
-  s.files = Dir["ext/**/extconf.rb", "ext/**/*.h", "ext/**/*.c", "lib/**/*.rb",
-                     "test/*.rb", "HISTORY", "README.md", "Rakefile"]
+  s.files = `git ls-files`.split("\n")
+  s.test_files = `git ls-files -- test/*`.split("\n")
 end
 
-desc "run tests"
+desc "Run tests"
 task :test do
-  sh "bacon -k #{direc}/test/test.rb"
+  sh "bacon -Itest -rubygems test.rb -q"
 end
 
-[:mingw32, :mswin32].each do |v|
-  namespace v do
-    spec = Gem::Specification.new do |s|
-      apply_spec_defaults(s)        
-      s.platform = "i386-#{v}"
-      s.files += FileList["lib/**/*.#{dlext}"].to_a
-    end
-
-    Rake::GemPackageTask.new(spec) do |pkg|
-      pkg.need_zip = false
-      pkg.need_tar = false
-    end
-  end
+task :pry do
+  puts "loading binding_of_caller into pry"
+  sh "pry -r ./lib/binding_of_caller"
 end
 
 namespace :ruby do
   spec = Gem::Specification.new do |s|
-    apply_spec_defaults(s)        
+    apply_spec_defaults(s)
     s.platform = Gem::Platform::RUBY
     s.extensions = ["ext/#{PROJECT_NAME}/extconf.rb"]
   end
-  
+
   Rake::GemPackageTask.new(spec) do |pkg|
     pkg.need_zip = false
     pkg.need_tar = false
   end
 end
 
-directories = ["#{direc}/lib/1.8", "#{direc}/lib/1.9"]
-directories.each { |d| directory d }
-
-desc "build the 1.8 and 1.9 binaries from source and copy to lib/"
-task :compile => directories do
-  build_for = proc do |pik_ver, ver|
-    sh %{ \
-          c:\\devkit\\devkitvars.bat && \
-          pik #{pik_ver} && \
-          ruby extconf.rb && \
-          make clean && \
-          make && \
-          cp *.so #{direc}/lib/#{ver} \
-        }
-  end
-  
-  chdir("#{direc}/ext/#{PROJECT_NAME}") do
-    build_for.call("187", "1.8")
-    build_for.call("192", "1.9")
+desc "build the binaries"
+task :compile do
+  chdir "./ext/#{PROJECT_NAME}/" do
+    sh "ruby extconf.rb"
+    sh "make clean"
+    sh "make"
+    sh "cp *.#{dlext} ../../lib/"
   end
 end
 
 desc "build all platform gems at once"
-task :gems => [:clean, :rmgems, "mingw32:gem", "mswin32:gem", "ruby:gem"]
+task :gems => [:clean, :rmgems, "ruby:gem"]
+
+task :gem => [:gems]
 
 desc "remove all platform gems"
 task :rmgems => ["ruby:clobber_package"]
 
 desc "build and push latest gems"
 task :pushgems => :gems do
-  chdir("#{direc}/pkg") do
+  chdir("./pkg") do
     Dir["*.gem"].each do |gemfile|
       sh "gem push #{gemfile}"
     end

data/examples/example.rb

@@ -0,0 +1,41 @@
+unless Object.const_defined? :BindingOfCaller
+  $:.unshift File.expand_path '../../lib', __FILE__
+  require 'binding_of_caller'
+  require 'binding_of_caller/version'
+end
+
+outer = 10
+
+class Z
+  def z
+    u = 10
+    A.new.a
+  end
+end
+
+class A
+  def a
+    y = 10
+    B.new.b
+  end
+end
+
+class B
+  def b
+    x = 10
+    puts binding.of_caller(0).eval('local_variables')
+    puts binding.of_caller(1).eval('local_variables')
+    puts binding.of_caller(2).eval('local_variables')
+    puts binding.of_caller(3).eval('local_variables')
+    puts binding.of_caller(400).eval('local_variables')
+  end
+end
+
+Z.new.z
+
+# output:
+# => x
+# => y
+# => u
+# => outer
+# Exception

data/ext/binding_of_caller/binding_of_caller.c

@@ -1,22 +1,15 @@
 /* (c) 2011 John Mair (banisterfiend), MIT license */
 
 #include <ruby.h>
-//#include "compat.h"
-
-//#ifdef RUBY_19
-# include <ruby/io.h>
-# include <ruby/re.h>
-# include "vm_core.h"
-# include "gc.h"
-/* #else */
-/* # include "re.h" */
-/* # include "env.h" */
-/* # include "node.h" */
-/* # include "rubysig.h" */
-/* # include "rubyio.h" */
-/* #endif */
-
-extern rb_thread_t *ruby_current_thread;
+
+#include <ruby/io.h>
+#include <ruby/re.h>
+#include "vm_core.h"
+#include "gc.h"
+
+typedef enum { false, true } bool;
+
+const int max_frame_errors = 4;
 
 static size_t
 binding_memsize(const void *ptr)
@@ -65,8 +58,6 @@ binding_alloc(VALUE klass)
   return obj;
 }
 
-typedef enum { false, true } bool;
-
 static bool valid_frame_p(rb_control_frame_t * cfp) {
   return cfp->iseq && !NIL_P(cfp->self);
 }
@@ -74,7 +65,7 @@ static bool valid_frame_p(rb_control_frame_t * cfp) {
 static rb_control_frame_t * find_valid_frame(rb_control_frame_t * cfp) {
   int error_count = 0;
 
-  while (error_count <= 4) {
+  while (error_count <= max_frame_errors) {
     cfp = RUBY_VM_PREVIOUS_CONTROL_FRAME(cfp);
 
     if (valid_frame_p(cfp))
@@ -95,9 +86,11 @@ static VALUE binding_of_caller(VALUE self, VALUE rb_level)
   rb_control_frame_t *cfp = RUBY_VM_PREVIOUS_CONTROL_FRAME(th->cfp);
   int level = FIX2INT(rb_level);
 
+  // attempt to locate the nth parent control frame
   for (int i = 0; i < level; i++)
     cfp = RUBY_VM_PREVIOUS_CONTROL_FRAME(cfp);
 
+  // if did not find a valid one, then search for a valid one
   if (!valid_frame_p(cfp))
     cfp = find_valid_frame(cfp);
 
@@ -118,7 +111,9 @@ static VALUE binding_of_caller(VALUE self, VALUE rb_level)
 void
 Init_binding_of_caller()
 {
-  rb_define_method(rb_cObject, "binding_of_caller", binding_of_caller, 1);
+  VALUE mBindingOfCaller = rb_define_module("BindingOfCaller");
 
+  rb_define_method(mBindingOfCaller, "of_caller", binding_of_caller, 1);
+  rb_include_module(rb_cBinding, mBindingOfCaller);
 }
 

data/lib/binding_of_caller/version.rb

@@ -1,3 +1,3 @@
 module BindingOfCaller
-  VERSION = "0.2.0"
-end     
+  VERSION = "0.3.1"
+end

data/test/test.rb

@@ -1,12 +1,59 @@
-direc = File.dirname(__FILE__)
-
-require 'rubygems'
-require "#{direc}/../lib/binding_of_caller"
-require 'bacon'
+unless Object.const_defined? :BindingOfCaller
+  $:.unshift File.expand_path '../../lib', __FILE__
+  require 'binding_of_caller'
+  require 'binding_of_caller/version'
+end
 
-puts "Testing binding_of_caller version #{BindingOfCaller::VERSION}..." 
+puts "Testing binding_of_caller version #{BindingOfCaller::VERSION}..."
 puts "Ruby version: #{RUBY_VERSION}"
 
 describe BindingOfCaller do
+  it "should fetch immediate caller's binding when 0 is passed" do
+    o = Object.new
+    def o.a
+      var = 1
+      binding.of_caller(0).eval('var')
+    end
+
+   o. a.should == 1
+  end
+
+  it "should fetch parent of caller's binding when 1 is passed" do
+    o = Object.new
+    def o.a
+      var = 1
+      b
+    end
+
+    def o.b
+      binding.of_caller(1).eval('var')
+    end
+
+   o.a.should == 1
+  end
+
+  it "should modify locals in parent of caller's binding" do
+    o = Object.new
+    def o.a
+      var = 1
+      b
+      var
+    end
+
+    def o.b
+      binding.of_caller(1).eval('var = 20')
+    end
+
+   o.a.should == 20
+  end
+
+  it "should raise an exception when retrieving an out of band binding" do
+    o = Object.new
+    def o.a
+      binding.of_caller(100)
+    end
+
+    lambda { o.a }.should.raise RuntimeError
+  end
 end
 

metadata

@@ -2,7 +2,7 @@
 name: binding_of_caller
 version: !ruby/object:Gem::Version 
   prerelease: 
-  version: 0.2.0
+  version: 0.3.1
 platform: ruby
 authors: 
 - John Mair (banisterfiend)
@@ -10,7 +10,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-10-17 00:00:00 Z
+date: 2011-10-18 00:00:00 Z
 dependencies: 
 - !ruby/object:Gem::Dependency 
   name: bacon
@@ -18,12 +18,12 @@ dependencies:
   requirement: &id001 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
-    - - ">="
+    - - ~>
       - !ruby/object:Gem::Version 
         version: 1.1.0
   type: :development
   version_requirements: *id001
-description: FIX ME
+description: Retrieve the binding of a method's caller. Can also retrieve bindings even further up the stack. Currently only works for MRI 1.9.2.
 email: jrmair@gmail.com
 executables: []
 
@@ -32,8 +32,16 @@ extensions:
 extra_rdoc_files: []
 
 files: 
+- .gemtest
+- .gitignore
+- .yardopts
+- HISTORY
+- LICENSE
+- README.md
+- Rakefile
+- examples/example.rb
+- ext/binding_of_caller/binding_of_caller.c
 - ext/binding_of_caller/extconf.rb
-- ext/binding_of_caller/compat.h
 - ext/binding_of_caller/ruby_headers/192/debug.h
 - ext/binding_of_caller/ruby_headers/192/dln.h
 - ext/binding_of_caller/ruby_headers/192/eval_intern.h
@@ -82,14 +90,9 @@ files:
 - ext/binding_of_caller/ruby_headers/193/vm_exec.h
 - ext/binding_of_caller/ruby_headers/193/vm_insnhelper.h
 - ext/binding_of_caller/ruby_headers/193/vm_opts.h
-- ext/binding_of_caller/binding_of_caller.c
 - lib/binding_of_caller/version.rb
-- lib/binding_of_caller.rb
 - test/test.rb
-- HISTORY
-- README.md
-- Rakefile
-homepage: http://banisterfiend.wordpress.com
+homepage: http://github.com/banister/binding_of_caller
 licenses: []
 
 post_install_message: 
@@ -115,6 +118,6 @@ rubyforge_project:
 rubygems_version: 1.8.11
 signing_key: 
 specification_version: 3
-summary: FIX ME
-test_files: []
-
+summary: Retrieve the binding of a method's caller. Can also retrieve bindings even further up the stack. Currently only works for MRI 1.9.2.
+test_files: 
+- test/test.rb

data/ext/binding_of_caller/compat.h

@@ -1,57 +0,0 @@
-/* contains basic macros to facilitate ruby 1.8 and ruby 1.9 compatibility */
-
-#ifndef GUARD_COMPAT_H
-#define GUARD_COMPAT_H
-
-#include <ruby.h>
-
-/* test for 1.9 */
-#if !defined(RUBY_19) && defined(ROBJECT_EMBED_LEN_MAX)
-# define RUBY_19
-#endif
-
-/* macros for backwards compatibility with 1.8 */
-#ifndef RUBY_19
-# define RCLASS_M_TBL(c) (RCLASS(c)->m_tbl)
-# define RCLASS_SUPER(c) (RCLASS(c)->super)
-# define RCLASS_IV_TBL(c) (RCLASS(c)->iv_tbl)
-# define OBJ_UNTRUSTED OBJ_TAINTED
-# include "st.h"
-#endif
-
-#ifdef RUBY_19
-inline static VALUE
-class_alloc(VALUE flags, VALUE klass)
-{
-  rb_classext_t *ext = ALLOC(rb_classext_t);
-  NEWOBJ(obj, struct RClass);
-  OBJSETUP(obj, klass, flags);
-  obj->ptr = ext;
-  RCLASS_IV_TBL(obj) = 0;
-  RCLASS_M_TBL(obj) = 0;
-  RCLASS_SUPER(obj) = 0;
-  RCLASS_IV_INDEX_TBL(obj) = 0;
-  return (VALUE)obj;
-}
-#endif
-
-inline static VALUE
-create_class(VALUE flags, VALUE klass)
-{
-#ifdef RUBY_19
-  VALUE new_klass = class_alloc(flags, klass);
-#else
-  NEWOBJ(new_klass, struct RClass);
-  OBJSETUP(new_klass, klass, flags);
-#endif
-
-  return (VALUE)new_klass;
-}
-  
-# define FALSE 0
-# define TRUE 1
-
-/* a useful macro. cannot use ordinary CLASS_OF as it does not return an lvalue */
-#define KLASS_OF(c) (RBASIC(c)->klass)
-
-#endif

data/lib/binding_of_caller.rb

@@ -1,22 +0,0 @@
-# binding_of_caller.rb
-# (C) John Mair (banisterfiend); MIT license
-
-direc = File.dirname(__FILE__)
-
-require "#{direc}/binding_of_caller/version"
-
-begin
-  if RUBY_VERSION =~ /1.9/
-    require "#{direc}/1.9/binding_of_caller"
-  else
-    require "#{direc}/1.8/binding_of_caller"
-  end
-rescue LoadError => e
-  require "rbconfig"
-  dlext = Config::CONFIG['DLEXT']
-  require "#{direc}/binding_of_caller.#{dlext}"
-end
-
-module BindingOfCaller
-end  
-