binding_of_caller 0.3.0 → 0.6.0

data/README.md

@@ -3,25 +3,55 @@ 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 and 1.9.3**
 
 * 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
+```ruby
+def a
+  var = 10
+  b
+  puts var
+end
+
+def b
+  c
+end
+
+def c
+  binding.of_caller(2).eval('var = :hello')
+end
+
+a()
+
+# OUTPUT
+# => hello
+```
+
+Spinoff project
+-------
 
-    puts "example code"
+This project is a spinoff from the [Pry REPL project.](http://pry.github.com)
 
 Features and limitations
 -------------------------
 
-Feature List Preamble
+* Only works with MRI 1.9.2 and 1.9.3
+* 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 +62,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

@@ -52,7 +52,7 @@ namespace :ruby do
   end
 end
 
-desc "build the biinaries"
+desc "build the binaries"
 task :compile do
   chdir "./ext/#{PROJECT_NAME}/" do
     sh "ruby extconf.rb"
@@ -72,7 +72,7 @@ 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,15 +1,31 @@
 /* (c) 2011 John Mair (banisterfiend), MIT license */
 
 #include <ruby.h>
-
-# include <ruby/io.h>
-# include <ruby/re.h>
-# include "vm_core.h"
-# include "gc.h"
+#include "vm_core.h"
+#include "gc.h"
 
 typedef enum { false, true } bool;
 
-const int max_frame_errors = 4;
+static VALUE
+string2sym(const char * string)
+{
+  return ID2SYM(rb_intern(string));
+}
+
+static inline const rb_data_type_t *
+threadptr_data_type(void)
+{
+  static const rb_data_type_t *thread_data_type;
+  if (!thread_data_type) {
+    VALUE current_thread = rb_thread_current();
+    thread_data_type = RTYPEDDATA_TYPE(current_thread);
+  }
+  return thread_data_type;
+}
+
+#define ruby_thread_data_type *threadptr_data_type()
+
+#define ruby_current_thread ((rb_thread_t *)RTYPEDDATA_DATA(rb_thread_current()))
 
 static size_t
 binding_memsize(const void *ptr)
@@ -58,62 +74,140 @@ binding_alloc(VALUE klass)
   return obj;
 }
 
-static bool valid_frame_p(rb_control_frame_t * cfp) {
+static bool valid_frame_p(rb_control_frame_t * cfp, rb_control_frame_t * limit_cfp) {
   return cfp->iseq && !NIL_P(cfp->self);
 }
 
-static rb_control_frame_t * find_valid_frame(rb_control_frame_t * cfp) {
-  int error_count = 0;
-
-  while (error_count <= max_frame_errors) {
+static rb_control_frame_t * find_valid_frame(rb_control_frame_t * cfp, rb_control_frame_t * limit_cfp) {
+  while (cfp < limit_cfp) {
     cfp = RUBY_VM_PREVIOUS_CONTROL_FRAME(cfp);
 
-    if (valid_frame_p(cfp))
+    if (cfp >= limit_cfp)
+      return NULL;
+
+    if (valid_frame_p(cfp, limit_cfp))
       return cfp;
-    else
-      error_count += 1;
   }
 
-  rb_raise(rb_eRuntimeError, "No valid stack frame found.");
+  // beyond end of stack
+  return NULL;
+}
 
-  // never reached
-  return 0;
+static VALUE
+frametype_name(VALUE flag)
+{
+  switch (flag & VM_FRAME_MAGIC_MASK) {
+  case VM_FRAME_MAGIC_METHOD: return string2sym("method");
+  case VM_FRAME_MAGIC_BLOCK:  return string2sym("block");
+  case VM_FRAME_MAGIC_CLASS:  return string2sym("class");
+  case VM_FRAME_MAGIC_TOP:    return string2sym("top");
+  case VM_FRAME_MAGIC_FINISH: return string2sym("finish");
+  case VM_FRAME_MAGIC_CFUNC:  return string2sym("cfunc");
+  case VM_FRAME_MAGIC_PROC:   return string2sym("proc");
+  case VM_FRAME_MAGIC_IFUNC:  return string2sym("ifunc");
+  case VM_FRAME_MAGIC_EVAL:   return string2sym("eval");
+  case VM_FRAME_MAGIC_LAMBDA: return string2sym("lambda");
+  default:
+    rb_raise(rb_eRuntimeError, "Unknown frame type! got flag: %d", FIX2INT(flag));
+  }
 }
 
 static VALUE binding_of_caller(VALUE self, VALUE rb_level)
 {
-  rb_thread_t *th = GET_THREAD();
+  rb_thread_t *th;
+  GetThreadPtr(rb_thread_current(), th);
+
   rb_control_frame_t *cfp = RUBY_VM_PREVIOUS_CONTROL_FRAME(th->cfp);
+  rb_control_frame_t *limit_cfp = (void *)(th->stack + th->stack_size);
   int level = FIX2INT(rb_level);
 
   // attempt to locate the nth parent control frame
-  for (int i = 0; i < level; i++)
+  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);
+    if (cfp >= limit_cfp)
+      rb_raise(rb_eRuntimeError, "Invalid frame, gone beyond end of stack!");
+
+    // skip invalid frames
+    if (!valid_frame_p(cfp, limit_cfp))
+      cfp = find_valid_frame(cfp, limit_cfp);
+  }
 
   VALUE bindval = binding_alloc(rb_cBinding);
   rb_binding_t *bind;
 
-  if (cfp == 0) {
+  if (cfp == 0)
     rb_raise(rb_eRuntimeError, "Can't create Binding Object on top of Fiber.");
-  }
 
   GetBindingPtr(bindval, bind);
   bind->env = rb_vm_make_env_object(th, cfp);
   bind->filename = cfp->iseq->filename;
   bind->line_no = rb_vm_get_sourceline(cfp);
+
+  rb_iv_set(bindval, "@frame_type", frametype_name(cfp->flag));
+  rb_iv_set(bindval, "@frame_description", cfp->iseq->name);
+
   return bindval;
 }
 
+static VALUE
+frame_type(VALUE self)
+{
+  return rb_iv_get(self, "@frame_type");
+}
+
+static VALUE
+frame_description(VALUE self)
+{
+  return rb_iv_get(self, "@frame_description");
+}
+
+static VALUE frame_count(VALUE self)
+{
+  rb_thread_t *th;
+  GetThreadPtr(rb_thread_current(), th);
+
+  rb_control_frame_t *cfp = RUBY_VM_PREVIOUS_CONTROL_FRAME(th->cfp);
+  rb_control_frame_t *limit_cfp = (void *)(th->stack + th->stack_size);
+
+  int i = 1;
+  while (cfp < limit_cfp) {
+    cfp = RUBY_VM_PREVIOUS_CONTROL_FRAME(cfp);
+
+    if (cfp >= limit_cfp)
+      return INT2FIX(i);
+
+    // skip invalid frames
+    if (!valid_frame_p(cfp, limit_cfp))
+      cfp = find_valid_frame(cfp, limit_cfp);
+
+    i++;
+  }
+
+  return INT2FIX(i);
+}
+
+static VALUE
+callers(VALUE self)
+{
+  VALUE ary = rb_ary_new();
+
+  for (int i = 0; i < FIX2INT(frame_count(self)); i++)
+    rb_ary_push(ary, binding_of_caller(self, INT2FIX(i)));
+
+  return ary;
+}
+
 void
 Init_binding_of_caller()
 {
   VALUE mBindingOfCaller = rb_define_module("BindingOfCaller");
 
   rb_define_method(mBindingOfCaller, "of_caller", binding_of_caller, 1);
+  rb_define_method(mBindingOfCaller, "frame_count", frame_count, 0);
+  rb_define_method(mBindingOfCaller, "frame_type", frame_type, 0);
+  rb_define_method(mBindingOfCaller, "frame_description", frame_description, 0);
+  rb_define_method(mBindingOfCaller, "callers", callers, 0);
   rb_include_module(rb_cBinding, mBindingOfCaller);
 }
 

data/lib/binding_of_caller/version.rb

@@ -1,3 +1,3 @@
 module BindingOfCaller
-  VERSION = "0.3.0"
+  VERSION = "0.6.0"
 end

data/test/test.rb

@@ -8,52 +8,87 @@ 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')
+  describe "of_caller" 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
 
-   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
 
-  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
 
-    def o.b
-      binding.of_caller(1).eval('var')
+      o.a.should == 1
     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
 
-  it "should modify locals in parent of caller's binding" do
-    o = Object.new
-    def o.a
-      var = 1
-      b
-      var
+      o.a.should == 20
     end
 
-    def o.b
-      binding.of_caller(1).eval('var = 20')
+    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
 
-   o.a.should == 20
+  describe "frame_count" do
+    it 'frame_count should equal callers.count' do
+      binding.frame_count.should == binding.callers.count
+    end
   end
 
-  it "should raise an exception when retrieving an out of band binding" do
-    o = Object.new
-    def o.a
-      binding.of_caller(100)
+  describe "frame_type" do
+    it 'should return the correct frame types' do
+      o = Object.new
+
+      # method frame
+      def o.a
+        b
+      end
+
+      # method frame
+      def o.b
+        # block frame
+        proc do
+          binding.callers
+        end.call
+      end
+      caller_bindings = o.a
+      caller_bindings[0].frame_type.should == :block
+      caller_bindings[1].frame_type.should == :method
+      caller_bindings[2].frame_type.should == :method
     end
 
-    lambda { o.a }.should.raise RuntimeError
+    it 'should raise when invoked on an ordinary binding (i.e one not generated through Binding#of_caller)' do
+      lambda { binding.frame_type }.should.raise RuntimeError
+    end
   end
 end
 

metadata

@@ -1,37 +1,35 @@
---- !ruby/object:Gem::Specification 
+--- !ruby/object:Gem::Specification
 name: binding_of_caller
-version: !ruby/object:Gem::Version 
+version: !ruby/object:Gem::Version
+  version: 0.6.0
   prerelease: 
-  version: 0.3.0
 platform: ruby
-authors: 
+authors:
 - John Mair (banisterfiend)
 autorequire: 
 bindir: bin
 cert_chain: []
-
-date: 2011-10-18 00:00:00 Z
-dependencies: 
-- !ruby/object:Gem::Dependency 
+date: 2011-11-28 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
   name: bacon
-  prerelease: false
-  requirement: &id001 !ruby/object:Gem::Requirement 
+  requirement: &70166101101640 !ruby/object:Gem::Requirement
     none: false
-    requirements: 
+    requirements:
     - - ~>
-      - !ruby/object:Gem::Version 
+      - !ruby/object:Gem::Version
         version: 1.1.0
   type: :development
-  version_requirements: *id001
-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.
+  prerelease: false
+  version_requirements: *70166101101640
+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: []
-
-extensions: 
+extensions:
 - ext/binding_of_caller/extconf.rb
 extra_rdoc_files: []
-
-files: 
+files:
 - .gemtest
 - .gitignore
 - .yardopts
@@ -39,9 +37,8 @@ files:
 - LICENSE
 - README.md
 - Rakefile
+- examples/example.rb
 - ext/binding_of_caller/binding_of_caller.c
-- ext/binding_of_caller/compat.h
-- ext/binding_of_caller/example.rb
 - ext/binding_of_caller/extconf.rb
 - ext/binding_of_caller/ruby_headers/192/debug.h
 - ext/binding_of_caller/ruby_headers/192/dln.h
@@ -95,30 +92,28 @@ files:
 - test/test.rb
 homepage: http://github.com/banister/binding_of_caller
 licenses: []
-
 post_install_message: 
 rdoc_options: []
-
-require_paths: 
+require_paths:
 - lib
-required_ruby_version: !ruby/object:Gem::Requirement 
+required_ruby_version: !ruby/object:Gem::Requirement
   none: false
-  requirements: 
-  - - ">="
-    - !ruby/object:Gem::Version 
-      version: "0"
-required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
-  requirements: 
-  - - ">="
-    - !ruby/object:Gem::Version 
-      version: "0"
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
 requirements: []
-
 rubyforge_project: 
-rubygems_version: 1.8.11
+rubygems_version: 1.8.10
 signing_key: 
 specification_version: 3
-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: 
+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/ext/binding_of_caller/example.rb

@@ -1,39 +0,0 @@
-require './binding_of_caller'
-
-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
-
-def a; b; end; def b; binding_of_caller(10); end; a;
-
-# Z.new.z
-
-# output:
-# => x
-# => y
-# => u
-# => outer
-# Exception