tracepoint 1.0.0 → 1.1

data/HISTORY

@@ -1,4 +1,15 @@
-= HISTORY
+= RELEASE HISTORY
+
+== 1.1 / 2009-12-26
+
+This release fixes multi-tracing and adds named traces.
+
+Changes:
+
+* Support for multiple traces.
+* Trace procedures can be named.
+* TracePoint has file name and line number.
+
 
 == 1.0.0 / 2009-07-10
 
@@ -6,7 +17,7 @@ Tracepoint is a spin-off of Ruby Facets. This is it's first release as
 a stand alone project. Tracepoint is a Binding with event information that
 can be used to trace execution, akin to #set_trace_func.
 
-* 1 major enhancement
+Changes:
 
-  * Birthday!
+* Happy Birthday!
 

data/LICENSE

@@ -1,4 +1,3 @@
-
 = GNU LESSER GENERAL PUBLIC LICENSE
 
 Version 3, 29 June 2007

data/MANIFEST

@@ -1,19 +1,20 @@
-test
-RELEASE
-LICENSE
-README
-HISTORY
-meta
+#!mast lib meta test [A-Z]*
+lib/tracepoint.rb
+meta/authors
+meta/collection
+meta/copyright
 meta/created
-meta/repository
+meta/description
 meta/homepage
-meta/summary
-meta/abstract
-meta/package
+meta/license
+meta/name
 meta/released
+meta/repository
+meta/summary
+meta/title
 meta/version
-meta/license
-meta/authors
-meta/project
-lib
-lib/tracepoint.rb
+test/demo/trace.qed
+LICENSE
+README
+HISTORY
+Syckfile

data/README

@@ -1,51 +1,79 @@
-= Tracepoint
+= TracePoint
 
-* http://death.rubyforge.org
-* http://death.rubyforge.org/tracepoint
+* http://rubyworks.github.com/tracepoint
+* http://github.com/rubyworks/tracepoint
 
-== DESCRIPTION:
 
-A TracePoint is a Binding with the addition of event information.
-Among other things, it functions very well as the join-point for AOP.
-In practice it provides a better means than #set_trace_func.
+== DESCRIPTION
 
-== FEATURES/PROBLEMS:
+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.
 
-* Easier and more versitle than #set_trace_func.
-* Set mutliple traces easily.
 
-== RELEASE/NOTES:
+== FEATURES
 
-Please see RELEASE file.
+* More versitle than #set_trace_func.
+* Easy to set mutliple traces.
 
-== SYNOPSIS:
 
-Let's watch everything that happens:
+== SYNOPSIS
 
-   TracePoint.trace { |tp|
-     puts "#{tp.self.class}\t#{tp.called}\t#{tp.event}\t#{tp.return?}\t#{tp.back == tp.bind}"
-   }
+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
+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.
+
 
-   Class   trace   return     true    false
-   Object          line       false   false
-   Fixnum  +       c-call     false   false
-   Fixnum  +       c-return   false   false
+== INSTALLATION
 
-See RDocs for more information.
+Follow the usual procedure for installing via RubyGems:
 
-== INSTALL:
+  $ sudo gem install tracepoint
 
-* sudo gem install tracepoint
 
-== LICENSE:
+== LICENSE
 
 (LGPL v3 License)
 
-Copyright (c) 2005,2009 The Coding Dead <death.rubyforge.org>
+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

data/Syckfile

@@ -0,0 +1,81 @@
+---
+box:
+  service: Box
+  types  : [gem, gz]
+  include: [bin, demo, lib, meta, test, "[A-Z]*"]
+  exclude: ~
+  master : false
+  active : true
+
+dnote:
+  service  : DNote
+  loadpath : ~
+  labels   : ~
+  output   : ~
+  format   : ~
+  active   : true
+
+stats:
+  service  : Stats
+  title    : ~
+  loadpath : ~
+  exclude  : ~
+  output   : ~
+  active   : true
+
+rdoc:
+  service  : RDoc
+  template : redfish
+  include  : ~
+  exclude  : ~
+  main     : ~
+  extra    : ~
+  active   : true
+
+ridoc:
+  service: RIDoc
+  include: ~
+  exclude: ~
+  active : true
+
+vclog:
+  service  : VClog
+#  format   : html   # xml, txt
+  layout   : rel    # gnu
+  typed    : true
+  output   : ~
+  active   : false
+
+email:
+  service : Email
+  file    : ~
+  subject : ~
+  mailto  : ruby-talk@ruby-lang.org
+  from    : <%= ENV['EMAIL_ACCOUNT'] %>
+  server  : <%= ENV['EMAIL_SERVER'] %>
+  port    : <%= ENV['EMAIL_PORT'] %>
+  account : <%= ENV['EMAIL_ACCOUNT'] %>
+  domain  : <%= ENV['EMAIL_DOMAIN'] %>
+  login   : <%= ENV['EMAIL_LOGIN'] %>
+  secure  : <%= ENV['EMAIL_SECURE'] %>
+  active  : true
+
+
+#testrb:
+#  service  : Testrb
+# tests    : ~
+#  exclude  : ~
+#  loadpath : ~
+#  requires : ~
+#  live     : false   
+#  active   : false
+
+#rubyforge:
+#  service : Rubyforge
+#  unixname: <%= suite %>
+#  groupid : ~
+#  package : <%= name %>
+#  sitemap:
+#    doc/rdoc: <%= name %>
+#  active  : false
+

data/lib/tracepoint.rb

@@ -1,37 +1,5 @@
 # = TracePoint
 #
-# A TracePoint is a Binding with the addition event information.
-# And it's a better way to use set_trace_func.
-#
-# A TracePoint is a Binding with the addition of event information.
-# Among other things, it functions very well as the join-point for
-# Event-based AOP.
-#
-# == Usage
-#
-#   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
-#
-# == Notes
-#
-# You can't subclass Binding, so we delegate (which is better anyway).
-#
-# == Authors
-#
-# * Thomas Sawyer
-#
-# == Copying
-#
 # Copyright (c) 2005 Thomas Sawyer
 #
 # Ruby License
@@ -53,6 +21,9 @@ CodePoint = Binding
 
 # = TracePoint
 #
+# A TracePoint is a Binding with the addition event information.
+# And it's a better way to use set_trace_func.
+#
 # A TracePoint is a Binding with the addition of event information.
 # Among other things, it functions very well as the join-point for
 # Event-based AOP.
@@ -79,24 +50,31 @@ CodePoint = Binding
 class TracePoint  #< Codepoint
 
   # -- class ---------------------
+
   class << self
 
     @@active = false
 
-    def active ; @@active ; end
+    @@index = {}
+    @@procs = []
 
-    def active=(x)
-      @@active = x ? true : false
-      unless @@active
-        set_trace_func nil
-      end
+    # Trace execution using a TracePoint.
+    def trace(name=nil, &procedure)
+      @@index[name] = procedure if name
+      @@procs << procedure
     end
 
-    # Trace execution using a TracePoint.
-    def trace # :yield:
-      if active
-        bb_stack = []
-        set_trace_func proc{ |e, f, l, m, b, k|
+    # Is tracing active?
+    def active?
+      @@active
+    end
+
+    # Activate tracing.
+    def activate
+      @@active = true
+      bb_stack = []
+      fn = lambda do |e, f, l, m, b, k|
+        unless k == TracePoint or (k == Kernel && m = :set_trace_func)
           #(p e, f, l, m, b, k, @@bb_stack; puts "---") if $DEBUG
           if ['call','c-call','class'].include?(e)
             bb_stack << b
@@ -104,9 +82,28 @@ class TracePoint  #< Codepoint
             bb = bb_stack.pop
           end
           b = bb if ! b    # this sucks!
-          tp = TracePoint.new(e,m,b,bb)
-          yield(tp)
-        }
+          tp = TracePoint.new(e, f, l, m, b, bb)
+          @@procs.each{ |fn| fn.call(tp) }
+        end
+      end
+      set_trace_func(fn)
+    end
+
+    # Deactivate tracing.
+    def deactivate
+      @@active = false
+      set_trace_func nil
+    end
+
+    # Clear all trace procedures, or a specific trace by name. 
+    def clear(name=nil)
+      if name
+        raise "Undefined trace -- #{name}" unless @@index.key?(name)
+        @@procs.delete(@@index.delete(name))
+      else
+        deactivate
+        @@index = {}
+        @@procs = []
       end
     end
 
@@ -114,31 +111,42 @@ class TracePoint  #< Codepoint
 
   # -- instance -------------------
 
-  attr_accessor :event, :binding, :back_binding
+  attr_accessor :event, :file, :line, :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
+  def initialize( event, file, line, method, bind, back_binding=bind )
+    @event   = event
+    @file    = file
+    @line    = line
+    @method  = method
     @binding = bind
     @back_binding = back_binding
   end
 
-  # shorthand for binding
-  def bind ; @binding ; end
+  # Shorthand for #binding.
+  def bind
+    @binding
+  end
 
-  # shorthand for back_binding
-  def back ; @back_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
+  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 callee ; @method ; end
+
   #def method ; @method ; end            # TODO Conflict with Kernel#method?
   alias_method( :called, :callee )       # TODO deprecate
   alias_method( :method_name, :called )  # TODO deprecate
@@ -148,7 +156,7 @@ class TracePoint  #< Codepoint
   #  @binding.send(meth, *args, &blk)
   #end
 
-  ### methods for working with events
+  # methods for working with events
 
   EVENT_MAP = {
     :all     => ['call', 'c-call', 'return', 'c-return', 'line', 'class', 'end', 'raise'],
@@ -175,35 +183,9 @@ class TracePoint  #< Codepoint
   end
 
   # Creates an <event>? method for each of the above event mappings.
-  EVENT_MAP.each_pair { |m,v|
+  EVENT_MAP.each_pair do |m,v|
     define_method( "#{m}?" ){ v.include?(@event) }
-  }
+  end
 
 end
 
-
-
-#  _____         _
-# |_   _|__  ___| |_
-#   | |/ _ \/ __| __|
-#   | |  __/\__ \ |_
-#   |_|\___||___/\__|
-#
-
-# TODO
-
-=begin #test
-
-  # Note: TracePoint will probably prove tricky to test, since
-  # manipulating set_trace_func tends to wreak havoc on errors,
-  # the call stack, and so on.
-
-  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

data/meta/authors

@@ -1 +1 @@
-Trans <transfire@gmail.com>
+Thomas Sawyer <transfire@gmail.com>

data/meta/collection

@@ -0,0 +1 @@
+rubyworks

data/meta/copyright

@@ -0,0 +1 @@
+(c) 2005 Thomas Sawyer

data/meta/homepage

@@ -1 +1 @@
-http://death.rubyforge.org/tracepoint
+http://rubyworks.github.com/tracepoint

data/meta/repository

@@ -1 +1 @@
-svn://rubyforge.org/var/svn/death/tracepoint
+git://github.com/rubyworks/tracepoint.git

data/meta/title

@@ -0,0 +1 @@
+TracePoint

data/meta/version

@@ -1 +1 @@
-1.0.0
+1.1

data/test/demo/trace.qed

@@ -0,0 +1,32 @@
+= TracePoint 
+
+To demonstrate TracePoint, we will simply have it feed all
+even parameters into the log for a simple arethmetic call.
+
+First we need to load the tracepoint.rb library.
+
+  require 'tracepoint'
+
+Now we can setup the trace procedure.
+
+  trace_log = []
+
+  TracePoint.trace do |tp|
+    trace_log << [tp.self.class, tp.callee, tp.event, tp.return?, tp.back == tp.bind]
+  end
+
+And then we can activate the trace, call out arethmetic function,
+and deactivate the trace.
+
+  TracePoint.activate
+  1 + 1
+  TracePoint.deactivate
+
+We should now see in the log the set of events required to
+perform the addition operation.
+
+  trace_log[1].assert == [Fixnum, :'+', 'c-call',   false, false]
+  trace_log[2].assert == [Fixnum, :'+', 'c-return', false, false]
+
+For reference, trace_log[0] and trace_log[3] simply refer to the
+QED run context.

metadata

@@ -1,15 +1,15 @@
 --- !ruby/object:Gem::Specification 
 name: tracepoint
 version: !ruby/object:Gem::Version 
-  version: 1.0.0
+  version: "1.1"
 platform: ruby
 authors: 
-- Trans <transfire@gmail.com>
+- Thomas Sawyer <transfire@gmail.com>
 autorequire: 
 bindir: bin
 cert_chain: []
 
-date: 2009-07-11 00:00:00 -04:00
+date: 2009-12-27 00:00:00 -05:00
 default_executable: 
 dependencies: []
 
@@ -17,7 +17,7 @@ description: |-
   A TracePoint is a Binding with the addition of event information.
   Among other things, it functions very well as the join-point for AOP.
   In practice it provides a better alternative to using #set_trace_func.
-email: transfire@gmail.com
+email: 
 executables: []
 
 extensions: []
@@ -25,36 +25,38 @@ extensions: []
 extra_rdoc_files: 
 - README
 - MANIFEST
-- RELEASE
 - LICENSE
 - HISTORY
+- Syckfile
 files: 
-- RELEASE
-- LICENSE
-- README
-- HISTORY
+- lib/tracepoint.rb
+- meta/authors
+- meta/collection
+- meta/copyright
 - meta/created
-- meta/repository
+- meta/description
 - meta/homepage
-- meta/summary
-- meta/abstract
-- meta/package
+- meta/license
+- meta/name
 - meta/released
+- meta/repository
+- meta/summary
+- meta/title
 - meta/version
-- meta/license
-- meta/authors
-- meta/project
-- lib/tracepoint.rb
+- test/demo/trace.qed
+- LICENSE
+- README
+- HISTORY
+- Syckfile
 - MANIFEST
 has_rdoc: true
-homepage: http://death.rubyforge.org/tracepoint
+homepage: http://rubyworks.github.com/tracepoint
 licenses: []
 
 post_install_message: 
 rdoc_options: 
-- --inline-source
 - --title
-- tracepoint api
+- TracePoint API
 - --main
 - README
 require_paths: 
@@ -73,10 +75,10 @@ required_rubygems_version: !ruby/object:Gem::Requirement
   version: 
 requirements: []
 
-rubyforge_project: death
-rubygems_version: 1.3.4
+rubyforge_project: tracepoint
+rubygems_version: 1.3.5
 signing_key: 
 specification_version: 3
-summary: A TracePoint is a Binding with the addition of event information.
+summary: "An alternate to #set_trace_func."
 test_files: []
 

data/RELEASE

@@ -1,12 +0,0 @@
-= RELEASE NOTES
-
-Tracepoint is a spin-off of Ruby Facets. This is it's first release as
-a stand alone project. Tracepoint is a Binding with event information that
-can be used to trace execution, akin to #set_trace_func.
-
-### 1.0.0 / 2009-07-10
-
-* 1 major enhancement
-
-  * Birthday!
-

data/meta/project

@@ -1 +0,0 @@
-death