#:title: TracePoint
#--
# TracePoint
# v 0.2.0
#
# Copyright (c) 2005 Thomas Sawyer
#
# $Id: tracepoint.rb,v 0.2.0 2005/04/24 03:10:10 transami Exp $
#
# ==========================================================================
# Revision History ::
# YYYY.MM.DD  Developer       Description
# --------------------------------------------------------------------------
# 2003.05.24  Trans           Minor modifications to documentation.
# ==========================================================================
#++

# = Description
# 
# A TracePoint is a CodePoint (i.e. a Binding) with the addition of event information.
# Among other things, it functions very well as the join-point for Event-based AOP.
# 
# == Usage
# 
#   require 'raspberry/tracepoint'
# 
#   TracePoint.trace { |tp|
#     puts "#{tp.self.class}\t#{tp.called}\t#{tp.event}\t#{tp.return?}\t#{tp.back == tp.bind}"
#   }
# 
#   1 + 1
#     
# produces
#   
#   Class   trace   return     true    false
#   Object          line       false   false
#   Fixnum  +       c-call     false   false
#   Fixnum  +       c-return   false   false
# 

require 'facet/binding'

# This is the same as a Binding. Not really needed, but I like consistency :)
CodePoint = Binding

# You can't subclass Binding, so we delegate (which is better anyway).
class TracePoint  #< CodePoint
  VERSION = '0.2.0'

  # -- class ---------------------
  class << self
  
    @@active = false
  
    def active ; @@active ; end
    
    def active=(x)
      @@active = x ? true : false
      unless @@active
        set_trace_func nil
      end
    end
  
    # Trace execution using a TracePoint.
    def trace # :yield:
      if active
        bb_stack = []
        set_trace_func proc{ |e, f, l, m, b, k|
          #(p e, f, l, m, b, k, @@bb_stack; puts "---") if $DEBUG
          if ['call','c-call','class'].include?(e)
            bb_stack << b
          elsif ['return','c-return','end'].include?(e)
            bb = bb_stack.pop
          end
          b = bb if ! b    # this sucks!
          tp = TracePoint.new(e,m,b,bb)
          yield(tp)
        }
      end
    end
    
  end #class
  
  # -- instance -------------------
  
  attr_accessor :event, :binding, :back_binding

  # Until Ruby has a built-in way to get the name of the calling method
  # that information must be passed into the TracePoint.
  def initialize( event, method, bind, back_binding=bind )
    @event = event
    @method = method
    @binding = bind
    @back_binding = back_binding
  end

  # shorthand for binding
  def bind ; @binding ; end
  
  # shorthand for back_binding
  def back ; @back_binding ; end
  
  # Delegates "self" to the binding which
  # in turn delegates the binding object.
  def self ; @binding.self ; end

  # Returns the name of the event's method.
  # This could delegate to the binding if Ruby had 
  # an internal way to retrieve the current method name.
  def called ; @method ; end
  alias_method( :method_name, :called )
  alias_method( :me, :called )
  
  # delegate to binding
  #def method_missing(meth, *args, &blk)
  #  @binding.send(meth, *args, &blk)
  #end
  
  ### methods for working with events

  EVENT_MAP = {
    :all     => ['call', 'c-call', 'return', 'c-return', 'line', 'class', 'end', 'raise'],
    :before  => ['call', 'c-call'],
    :after   => ['return', 'c-return'],
    :call    => ['call'],
    :return  => ['return'],
    :ccall   => ['c-call'],
    :creturn => ['c-return'],
    :line    => ['line'],
    :class   => ['class'],
    :end     => ['end'],
    :raise   => ['raise']
  }
  def event_map(e) ; EVENT_MAP[e] ; end
  
  # Is the trace point defined or undefined?
  def event? ; !! @event ; end
  def eventless? ; ! @event ; end
    
  # For use in case conditions
  def ===(e)
    EVENT_MAP[e].include?(@event)
  end
  
  # Creates an <event>? method for each of the above event mappings.
  EVENT_MAP.each_pair { |m,v|
    define_method( "#{m}?" ){ v.include?(@event) }
  }

end



# Development testing

=begin

  if $0 == __FILE__
  
    TracePoint.active = true
  
    TracePoint.trace { |tp|
      puts "#{tp.self.class}\t#{tp.called}\t#{tp.event}\t#{tp.return?}\t#{tp.back == tp.bind}"
    }
  
    1 + 1
  
  end

=end