= TracePoint

== RESOURCES

* home: http://rubyworks.github.com/tracepoint
* code: 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 reactivated on the fly by calling #deactivate
and #activate.

To add additional trace procedures, simply call the #trace method again.
Trace procedures can also be named 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

(Apache 2.0 License)

Copyright (c) 2005,2010 Thomas Sawyer

Licensed under the Apache License, Version 2.0 (the "License");
you may not use any of the files packaged with this file
except in compliance with this License. You may obtain a copy 
of the License at

      http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.