tracepoint 1.0.0

data/HISTORY

@@ -0,0 +1,12 @@
+= HISTORY
+
+== 1.0.0 / 2009-07-10
+
+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
+
+  * Birthday!
+

data/LICENSE

@@ -0,0 +1,167 @@
+
+= GNU LESSER GENERAL PUBLIC LICENSE
+
+Version 3, 29 June 2007
+
+Copyright (C) 2007 Free Software Foundation, Inc. <http://fsf.org/>
+Everyone is permitted to copy and distribute verbatim copies
+of this license document, but changing it is not allowed.
+
+This version of the GNU Lesser General Public License incorporates
+the terms and conditions of version 3 of the GNU General Public
+License, supplemented by the additional permissions listed below.
+
+== 0. Additional Definitions.
+
+As used herein, "this License" refers to version 3 of the GNU Lesser
+General Public License, and the "GNU GPL" refers to version 3 of the GNU
+General Public License.
+
+"The Library" refers to a covered work governed by this License,
+other than an Application or a Combined Work as defined below.
+
+An "Application" is any work that makes use of an interface provided
+by the Library, but which is not otherwise based on the Library.
+Defining a subclass of a class defined by the Library is deemed a mode
+of using an interface provided by the Library.
+
+A "Combined Work" is a work produced by combining or linking an
+Application with the Library.  The particular version of the Library
+with which the Combined Work was made is also called the "Linked
+Version".
+
+The "Minimal Corresponding Source" for a Combined Work means the
+Corresponding Source for the Combined Work, excluding any source code
+for portions of the Combined Work that, considered in isolation, are
+based on the Application, and not on the Linked Version.
+
+The "Corresponding Application Code" for a Combined Work means the
+object code and/or source code for the Application, including any data
+and utility programs needed for reproducing the Combined Work from the
+Application, but excluding the System Libraries of the Combined Work.
+
+== 1. Exception to Section 3 of the GNU GPL.
+
+You may convey a covered work under sections 3 and 4 of this License
+without being bound by section 3 of the GNU GPL.
+
+== 2. Conveying Modified Versions.
+
+If you modify a copy of the Library, and, in your modifications, a
+facility refers to a function or data to be supplied by an Application
+that uses the facility (other than as an argument passed when the
+facility is invoked), then you may convey a copy of the modified
+version:
+
+a) under this License, provided that you make a good faith effort to
+ensure that, in the event an Application does not supply the
+function or data, the facility still operates, and performs
+whatever part of its purpose remains meaningful, or
+
+b) under the GNU GPL, with none of the additional permissions of
+this License applicable to that copy.
+
+== 3. Object Code Incorporating Material from Library Header Files.
+
+The object code form of an Application may incorporate material from
+a header file that is part of the Library.  You may convey such object
+code under terms of your choice, provided that, if the incorporated
+material is not limited to numerical parameters, data structure
+layouts and accessors, or small macros, inline functions and templates
+(ten or fewer lines in length), you do both of the following:
+
+a) Give prominent notice with each copy of the object code that the
+Library is used in it and that the Library and its use are
+covered by this License.
+
+b) Accompany the object code with a copy of the GNU GPL and this license
+document.
+
+== 4. Combined Works.
+
+You may convey a Combined Work under terms of your choice that,
+taken together, effectively do not restrict modification of the
+portions of the Library contained in the Combined Work and reverse
+engineering for debugging such modifications, if you also do each of
+the following:
+
+a) Give prominent notice with each copy of the Combined Work that
+the Library is used in it and that the Library and its use are
+covered by this License.
+
+b) Accompany the Combined Work with a copy of the GNU GPL and this license
+document.
+
+c) For a Combined Work that displays copyright notices during
+execution, include the copyright notice for the Library among
+these notices, as well as a reference directing the user to the
+copies of the GNU GPL and this license document.
+
+d) Do one of the following:
+
+d.0) Convey the Minimal Corresponding Source under the terms of this
+License, and the Corresponding Application Code in a form
+suitable for, and under terms that permit, the user to
+recombine or relink the Application with a modified version of
+the Linked Version to produce a modified Combined Work, in the
+manner specified by section 6 of the GNU GPL for conveying
+Corresponding Source.
+
+d.1) Use a suitable shared library mechanism for linking with the
+Library.  A suitable mechanism is one that (a) uses at run time
+a copy of the Library already present on the user's computer
+system, and (b) will operate properly with a modified version
+of the Library that is interface-compatible with the Linked
+Version.
+
+e) Provide Installation Information, but only if you would otherwise
+be required to provide such information under section 6 of the
+GNU GPL, and only to the extent that such information is
+necessary to install and execute a modified version of the
+Combined Work produced by recombining or relinking the
+Application with a modified version of the Linked Version. (If
+you use option 4d0, the Installation Information must accompany
+the Minimal Corresponding Source and Corresponding Application
+Code. If you use option 4d1, you must provide the Installation
+Information in the manner specified by section 6 of the GNU GPL
+for conveying Corresponding Source.)
+
+== 5. Combined Libraries.
+
+You may place library facilities that are a work based on the
+Library side by side in a single library together with other library
+facilities that are not Applications and are not covered by this
+License, and convey such a combined library under terms of your
+choice, if you do both of the following:
+
+a) Accompany the combined library with a copy of the same work based
+on the Library, uncombined with any other library facilities,
+conveyed under the terms of this License.
+
+b) Give prominent notice with the combined library that part of it
+is a work based on the Library, and explaining where to find the
+accompanying uncombined form of the same work.
+
+== 6. Revised Versions of the GNU Lesser General Public License.
+
+The Free Software Foundation may publish revised and/or new versions
+of the GNU Lesser General Public License from time to time. Such new
+versions will be similar in spirit to the present version, but may
+differ in detail to address new problems or concerns.
+
+Each version is given a distinguishing version number. If the
+Library as you received it specifies that a certain numbered version
+of the GNU Lesser General Public License "or any later version"
+applies to it, you have the option of following the terms and
+conditions either of that published version or of any later version
+published by the Free Software Foundation. If the Library as you
+received it does not specify a version number of the GNU Lesser
+General Public License, you may choose any version of the GNU Lesser
+General Public License ever published by the Free Software Foundation.
+
+If the Library as you received it specifies that a proxy can decide
+whether future versions of the GNU Lesser General Public License shall
+apply, that proxy's public statement of acceptance of any version is
+permanent authorization for you to choose that version for the
+Library.
+

data/MANIFEST

@@ -0,0 +1,19 @@
+test
+RELEASE
+LICENSE
+README
+HISTORY
+meta
+meta/created
+meta/repository
+meta/homepage
+meta/summary
+meta/abstract
+meta/package
+meta/released
+meta/version
+meta/license
+meta/authors
+meta/project
+lib
+lib/tracepoint.rb

data/README

@@ -0,0 +1,62 @@
+= Tracepoint
+
+* http://death.rubyforge.org
+* http://death.rubyforge.org/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.
+
+== FEATURES/PROBLEMS:
+
+* Easier and more versitle than #set_trace_func.
+* Set mutliple traces easily.
+
+== RELEASE/NOTES:
+
+Please see RELEASE file.
+
+== SYNOPSIS:
+
+Let's watch everything that happens:
+
+   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
+
+See RDocs for more information.
+
+== INSTALL:
+
+* sudo gem install tracepoint
+
+== LICENSE:
+
+(LGPL v3 License)
+
+Copyright (c) 2005,2009 The Coding Dead <death.rubyforge.org>
+
+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/>.
+

data/RELEASE

@@ -0,0 +1,12 @@
+= 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/lib/tracepoint.rb

@@ -0,0 +1,209 @@
+# = 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
+#
+# This module is free software. You may use, modify, and/or redistribute this
+# software under the same terms as Ruby.
+#
+# 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.
+
+require 'facets/binding'
+
+# = CodePoint
+#
+# This is the same as a Binding. Not really needed, but I like consistency :)
+
+CodePoint = Binding
+
+# = TracePoint
+#
+# 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).
+
+class TracePoint  #< Codepoint
+
+  # -- 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 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
+
+  # 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
+
+
+
+#  _____         _
+# |_   _|__  ___| |_
+#   | |/ _ \/ __| __|
+#   | |  __/\__ \ |_
+#   |_|\___||___/\__|
+#
+
+# 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/abstract

@@ -0,0 +1,3 @@
+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.

data/meta/authors

@@ -0,0 +1 @@
+Trans <transfire@gmail.com>

data/meta/created

@@ -0,0 +1 @@
+2008-08-08 23:09:48 -0400

data/meta/homepage

@@ -0,0 +1 @@
+http://death.rubyforge.org/tracepoint

data/meta/license

@@ -0,0 +1 @@
+LGPL v3

data/meta/package

@@ -0,0 +1 @@
+tracepoint

data/meta/project

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

data/meta/released

@@ -0,0 +1 @@
+2009-07-11

data/meta/repository

@@ -0,0 +1 @@
+svn://rubyforge.org/var/svn/death/tracepoint

data/meta/summary

@@ -0,0 +1 @@
+An alternate to #set_trace_func.

data/meta/version

@@ -0,0 +1 @@
+1.0.0

metadata

@@ -0,0 +1,82 @@
+--- !ruby/object:Gem::Specification 
+name: tracepoint
+version: !ruby/object:Gem::Version 
+  version: 1.0.0
+platform: ruby
+authors: 
+- Trans <transfire@gmail.com>
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-07-11 00:00:00 -04:00
+default_executable: 
+dependencies: []
+
+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
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README
+- MANIFEST
+- RELEASE
+- LICENSE
+- HISTORY
+files: 
+- RELEASE
+- LICENSE
+- README
+- HISTORY
+- meta/created
+- meta/repository
+- meta/homepage
+- meta/summary
+- meta/abstract
+- meta/package
+- meta/released
+- meta/version
+- meta/license
+- meta/authors
+- meta/project
+- lib/tracepoint.rb
+- MANIFEST
+has_rdoc: true
+homepage: http://death.rubyforge.org/tracepoint
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --inline-source
+- --title
+- tracepoint api
+- --main
+- README
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: death
+rubygems_version: 1.3.4
+signing_key: 
+specification_version: 3
+summary: A TracePoint is a Binding with the addition of event information.
+test_files: []
+