ruby_backtracer: output higher quality backtraces if an unhandled exception occurs.  Originally inspired by the frustration of seeling ...24 levels... a few too many times.

There are several options available (the more verbose ones rely on ruby-debug, which slows things down a bit).

ex:
a script used to output:
examples>ruby crash.rb
crash.rb:2:in `go2': unhandled exception
        from crash.rb:6:in `go'
        from crash.rb:9

Using backtracer, it now outputs:
examples>ruby -rbacktracer_locals crash.rb

unhandled exception: crash.rb:2:   raise
        locals: {"a"=>"3", "b"=>55}
          from:
        crash.rb:1 go2(a=>3, b=>55)
                locals: {"a"=>"3", "b"=>55}
        crash.rb:5 go(a=>3)
                locals: {"a"=>"3"}
or
examples>ruby -rbacktracer crash.rb
====
crash.rb:2:in `go2'
        raise
crash.rb:7:in `go'
        go2(a, 55)
crash.rb:10
        go '3'
====
crash.rb:2:in `go2': unhandled exception
        from crash.rb:7:in `go'
        from crash.rb:10


All the options are backtracer, backtracer_locals, backtracer_simple, backtracer_tracer


== Installation ==

== 1.9 ==

$ gem install ruby-debug19
$ gem sources add http://gemcutter.org # if necessary
$ gem install backtracer

run as above 
$ ruby -rbacktracer script_name

== 1.8.x ==

$ gem install ruby-debug
$ gem sources add http://gemcutter.org # if necessary
$ sudo gem install faster_rubygems # necessary to be able to load gems from the command line -- installs the file rubygemsf into your site_ruby
$ gem install backtracer

now run them like
$ ruby -rubygemsf -rbacktracer script_name

the rubygemsf is necessary because for some reason running
$ ruby -rubygems -rbacktracer script_name 

fails [probably a bug in ruby]

== Descriptions ==

Try these out if desired:
create a file like:

  def go(a)
   raise
  end
  go(3)

then run ruby against it like

ruby -rbacktracer name
  outputs full backtrace with code of each line [a la Python]
ruby -rbacktracer_locals name
  outputs full backtrace with local variables and parameters
ruby -rbacktracer_simple name
  outputs backtrace without the ...24 levels... [yea!]
ruby -backtracer_tracer name
  same as backtracer_locals except it shows traces of calls as they're made


or in 1.8.x
ruby -rubygemsf -rbacktracer name
etc.


== Other ==

Note that you can [if desired] load these within a script iself
require 'backtracer'

and it will output a backtrace if one exists at exit time.

You can also add it to your RUBYOPT variable if you always want it to run [backtracer_simple and backtracer don't cause any slowdown].
$ export RUBYOPT=-rbacktracer

if desired.

== Related projects ==
unroller, http://eigenclass.org/hiki/method+arguments+via+introspection, liveconsole, ruby-debug

Comments welcome to rdp on github.

http://github.com/rdp/backtracer