call_stack: backtrace data and 1.8.5-safe breakpoint/Binding.of_caller

People are reporting problems with call_stack; use ruby-debug instead.

• Overview
• Installing
• RubyGems
• Installing from the tarball
• Usage
• Binding.of_caller compatibility
• Use with Ruby on Rails
• License

Overview

call_stack allows you to obtain backtrace data in your Ruby code. It also includes a new Binding.of_caller implementation that works with Ruby 1.8.5, and which can be used with ruby-breakpoint and Rails' breakpointer.

Installing

The last version is call_stack-0.1.0 (release notes).

RubyGems

You can

gem install call_stack

(Note: it usually takes a while after a release before the packages propagate to RubyForge's mirrors)

A mswin32 binary package is also available.

Installing from the tarball

De-compress the archive and enter its top directory. Then type:

  ($ su)
   # ruby setup.rb

Run ruby setup.rb --help for information on the install options.

Usage

It is used as follows:

   require 'call_stack'
    
   call_stack_on    # start recording information
    
    #.... somewhere else
   def b; foo end
   def foo
     backtrace = call_stack(-1)
   end
    
   b     # => [[:unknown, :unknown, "-", 3, nil, nil], 
               [Object, :b, "-", 7, #<Binding:0xa7dbe6b8>, :Ruby], 
	[Object, :foo, "-", 8, #<Binding:0xa7dbe690>, :Ruby]]
    
   call_stack_off

Kernel#call_stack returns an array of [class, mid, filename, line, binding, language] arrays, where language is either :Ruby, :C or nil. Older stack frames come first, newer last.

Information from stack frames which existed before #call_stack_on was called will be incomplete.

With no arguments, #call_stack will return an array with only one element (with the structure described above), corresponding to the context where #call_stack was called, e.g.

   require 'call_stack'
   call_stack_on
   def foo; call_stack end
   foo          # => [[Object, :foo, "-", 4, #<Binding:0xa7d90880>, :Ruby]]

With a negative argument, #call_stack returns the whole call stack. If a positive argument is given, as many levels as indicated will be returned; call_stack() is equivalent to call_stack(1).

Binding.of_caller compatibility

binding_of_caller.rb contains an implementation of Binding.of_caller built on top of call_stack. It will make your program somewhat slower, so you might want to write your own (it takes 3 lines of code) and postpone the call to #call_stack_on until it's needed.

Use with Ruby on Rails

Rails' breakpoint functionality doesn't work with 1.8.5, since it depends on the "standard" Binding.of_caller, which won't run on Ruby > 1.8.4.

This can be overcome by using call_stack with Rails' breakpointer as follows:

   ruby -rbreakpoint185 script/server

and then, in another console

   script/breakpointer

License

call_stack is licensed under the same terms as Ruby. See LICENSE.