stack_frames 1.1, 2001-10-21
Copyright(c) 2001 by Wayne Conrad <wconrad@yagni.com>


WHAT IS STACK_FRAMES?

This is a patch for the Ruby language.  It adds a function and class to
get stack-frame information.  It's an improvement on "caller", the existing
global function for getting stack-frame information:

  1. "stack_frames" gives the following information that "caller" does not:

       class name
       object

  2. "caller" just gives a string, which you have to parse out to get
     the function, file, and line.  "stack_frames" returns these as
     separate fields of a new class, StackFrame.


LICENSE
 
The license is the same as Ruby's: A dual license with GPL being one
of your choices.


FUNCTIONS AND CLASSES

The new global function is called stack_frames, and it has exactly the
same argument as 'caller': A single optional fixnum, a number between
0 and the stack depth, which tells how far "up" the stack to start
when assembling the list of stack frames.  The default value is 1.  If
you call stack_frames with an argument that's too large, you get nil.
That's on purpose, to mimic the behavior of caller.

stack_frames returns an array of StackFrame, which has the following
methods:

  inspect    (String) Convert entire StackFrame to a string
  to_s       (String) Same as inspect
  class      (String) Return the class name
  function   (String) Return the function name
  object     (Object) Return the object
  file       (String) Return the file pathname
  line       (Fixnum) Return the line number


RUBY VERSIONS

This patch has been tested with Ruby 1.6.4, 1.6.5, and 1.6.7.


INSTALLING IT

In the Ruby source directory:

    patch -p1 <stack_frames.patch

Then compile in the usual way.


TESTING IT

Run stack_frames.test.rb using the patched ruby.  For example:
  
    /usr/src/ruby-1.6.5/ruby stack_frames.test.rb

If it prints out "OK," the patch worked.  If it prints out a stack
trace, something went wrong (in which case, feel free to email me).
Also, if your platform is different than mine (Ruby 1.6, i386, Linux),
the test might fail just because it's testing Ruby internals that can
change from platform to platform.  In that case, see "RECALIBRATING
THE TEST."


RECALIBRATING THE TEST.

The test checks the stack frame to see if it's correct.
Unfortunately, if you refactor the test, the stack frames that the
test sees can change.  It is also possible for different versions or
implementations of Ruby to cause the test to see different stack
frames than it did when I ran it on my box (stack_frame is peeking at
Ruby internals, after all).  That causes the unfortunate need to
change the stack frame asserts when refactoring or when starting
development on a different platform than mine (Ruby 1.6, Linux).

The stack frame asserts are laborious to generate by hand, so there's
an option to generate them automatically.  If you run the test with
the "--calibrate" option, it will assume that the current stack frames
are correct and will rewrite the asserts, which are contained in
StackFramesAsserts.rb


TRYING IT

Try it by loading irb using your patched version of ruby:

  wconrad@pluto$ /usr/src/ruby-1.6.5/ruby `type -p irb`
  irb(main):001:0> stack_frames
  [#<StackFrame class=Object object=#<Object:0x40172c90> function=irb_binding file=/usr/local/lib/ruby/1.6/irb/workspace.rb line=51>, #<StackFrame class=Object object=#<Object:0x40172c90> function=irb_binding file=/usr/local/lib/ruby/1.6/irb/workspace.rb line=51>]


THINGS I WANT TO CHANGE

There is no test for memory leaks and premature reclaimation.

I'm not super happy with a too-large argument returning nil.  I'd
prefer that an empty array be returned.  As you increase the argument,
the size of the array that is returned decreases until it becomes zero
-- an empty array.  Increase the argument one more than that, and you
get nil.  You should just continue to get [] for too-large arguments.


THINGS I PURPOSEFULLY DIDN'T DO

It might be a good idea to stick arguments in StackFrame, but I'll
wait until someone tells me it's needed.  I hate "because we might
need it" code.

There is quite a bit of common code between changes and stack_frames.
I did not factor that code out because I wanted this patch to be
easier for the Ruby community to evaluate.  If the patch is accepted
into base Ruby, then the common code should be factored out.