= TracePoint

* http://rubyworks.github.com/tracepoint
* http://github.com/rubyworks/tracepoint


== DESCRIPTION

TracePoint is a Binding with the addition of event information.
In theory it would function very well as the join-point for AOP.
In practice it provides a better approach to #set_trace_func.


== FEATURES

* More versitle than #set_trace_func.
* Easy to set mutliple traces.


== SYNOPSIS

Using TracePoint is simply a matter of setting the #trace procedure.
For example to watch everything that happens during a Ruby process:

   TracePoint.trace do |tp|
     puts "#{tp.self.class}\t#{tp.callee}\t#{tp.event}\t#{tp.return?}"
   end

   TracePoint.activate

   1 + 1

Produces:

   Object       line       false
   Fixnum   +   c-call     false
   Fixnum   +   c-return   false

Tracing can be deactived and reactivates on the fly by calling #deactivate
and #activate.

To add an additional trace procedure, simple call the #trace method again.
Trace procedures can also be nameed by providing a name argument to the
#trace method. This allows traces to be added and removed without affecting
other traces.

   TracePoint.trace(:class_trace) do |tp|
     puts tp.self.class
   end

   TracePoint.trace(:method_trace) do |tp|
     puts tp.callee
   end

   # ...

   TracePoint.clear(:class_trace)

Calling #clear with no arguments will remove all trace procedures and
deactivate tracing.

Please see the API documentation for more information.


== INSTALLATION

Follow the usual procedure for installing via RubyGems:

  $ sudo gem install tracepoint


== LICENSE

(LGPL v3 License)

Copyright (c) 2005,2009 Thomas Sawyer

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU Lesser General Public License as published
by the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU Lesser General Public License
along with this program.  If not, see <http://www.gnu.org/licenses/>.