call_stack

call_stack copyright (c) 2006 Mauricio Fernandez [e-mail] Use and redistribution subject to the same terms as Ruby.

== Overview

call_stack allows you to obtain backtrace data in your Ruby code. 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

== Installing

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.

== License

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