minstrel 0.1.20101115013901

data/README.textile

@@ -0,0 +1,76 @@
+h1. Ruby Minstrel
+
+Minstrel allows you to wrap every method call for a given class so you can more
+easily observe how a class and its methods are being used.
+
+h2. Why?
+
+Fun. Also, sometimes ruby-prof and similar tools are overkill when I am trying
+to debug or dig into how a piece of code works.
+
+h2. Examples
+
+h3. From the commandline
+
+You can use minstrel to wrap classes with a default 'print' wrapper that simply
+prints what is called.  For example:
+
+<pre>
+% RUBY_INSTRUMENT=String ruby -rminstrel -e 'puts "hello world".capitalize.reverse'
+String#capitalize([])
+String#reverse([])
+dlrow olleH
+</pre>
+
+h3. From ruby
+
+Boilerplate:
+
+<pre>
+require "minstrel"
+
+instrument = Minstrel::Instrument.new()
+instrument.wrap(String) do |point, klass, method, *args|
+  #  * point is either :enter or :exit depending if this function is about to be
+  #    called or has finished being called.
+  #  * klass is the class object (String, etc)
+  #  * method is the method (a Symbol)
+  #  * *args is the arguments passed
+end
+</pre>
+
+Example:
+
+<pre>
+require "minstrel"
+
+class Foo
+  def bar(one, &block)
+    yield one
+  end
+  
+  def baz
+    puts "Baz!"
+  end 
+end
+
+instrument = Minstrel::Instrument.new
+instrument.wrap(Foo) do |point, klass, method, *args|
+  puts "#{point} #{klass.name}##{method}(#{args.inspect})"
+end
+
+foo = Foo.new
+foo.bar(123) { |arg| puts arg }
+foo.baz
+</pre>
+
+Output:
+
+<pre>
+enter Foo#bar([123])
+123
+exit Foo#bar([123])
+enter Foo#baz([])
+Baz!
+exit Foo#baz([])
+</pre>

data/lib/minstrel.rb

@@ -0,0 +1,68 @@
+# Wrap method calls for a class of your choosing.
+# Example:
+# instrument = Minstrel::Instrument.new()
+# instrument.wrap(String) do |point, klass, method, *args|
+#   ...
+# end
+#
+#  * point is either :enter or :exit depending if this function is about to be
+#    called or has finished being called.
+#  * klass is the class object (String, etc)
+#  * method is the method (a Symbol)
+#  * *args is the arguments passed
+#
+# You can also wrap from the command-line
+#
+# RUBY_INSTRUMENT=comma_separated_classnames ruby -rminstrel ./your/program.rb
+#
+module Minstrel; class Instrument
+  attr_accessor :counter
+
+  # Put methods we must not be wrapping here.
+  DONOTWRAP = [Kernel, Object, Module, Class, Minstrel::Instrument].collect do |obj|
+    obj.methods.collect { |m| m.to_sym }
+  end.flatten
+  DONOTWRAP << :to_sym
+
+  # Wrap a class's instance methods with your block.
+  # The block will be called with 4 arguments, and called
+  # before and after the original method.
+  # Arguments:
+  #   * point - the point (symbol, :entry or :exit) of call
+  #   * klass - the class (object) owning this method
+  #   * method - the method (symbol) being called
+  #   * *args - the arguments (array) passed to this method.
+  def wrap(klass, &block)
+    instrumenter = self
+    self.counter = 0
+
+    klass.instance_methods.each do |method|
+      next if DONOTWRAP.include?(method.to_sym)
+      klass.class_eval do
+        orig_method = "#{method}_original(wrapped)".to_sym
+        alias_method orig_method, method.to_sym
+        instrumenter.counter += 1
+        method = method.to_sym
+        define_method(method) do |*args, &argblock|
+          block.call(:enter, klass, method, *args)
+          val = send(orig_method, *args, &argblock)
+          block.call(:exit, klass, method, *args)
+          return val
+        end
+      end # klass.class_eval
+    end # klass.instance_methods.each
+  end # def wrap
+end; end # class Minstrel::Instrument
+
+# Provide a way to instrument a class using the command line:
+# RUBY_INSTRUMENT=String ruby -rminstrel ./your/program
+if ENV["RUBY_INSTRUMENT"]
+  ENV["RUBY_INSTRUMENT"].split(",").each do |klassname|
+    instrument = Minstrel::Instrument.new 
+    klass = eval(klassname)
+    instrument.wrap(klass) do |point, klass, method, *args|
+      next if point == :end
+      puts "#{point} #{klass.name}##{method}(#{args.inspect})"
+    end
+  end
+end

data/minstrel.gemspec

@@ -0,0 +1,21 @@
+Gem::Specification.new do |spec|
+  files = [
+    "./lib",
+    "./lib/minstrel.rb",
+    "./README.textile",
+    "./minstrel.gemspec",
+  ]
+
+  rev = Time.now.strftime("%Y%m%d%H%M%S")
+  spec.name = "minstrel"
+  spec.version = "0.1.#{rev}"
+  spec.summary = "minstrel - a ruby instrumentation tool"
+  spec.description = "Instrument class methods"
+  spec.files = files
+  spec.require_paths << "lib"
+
+  spec.author = "Jordan Sissel"
+  spec.email = "jls@semicomplete.com"
+  spec.homepage = "https://github.com/jordansissel/ruby-minstrel"
+end
+

metadata

@@ -0,0 +1,70 @@
+--- !ruby/object:Gem::Specification 
+name: minstrel
+version: !ruby/object:Gem::Version 
+  hash: 40202230027777
+  prerelease: false
+  segments: 
+  - 0
+  - 1
+  - 20101115013901
+  version: 0.1.20101115013901
+platform: ruby
+authors: 
+- Jordan Sissel
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-11-15 00:00:00 -08:00
+default_executable: 
+dependencies: []
+
+description: Instrument class methods
+email: jls@semicomplete.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- ./lib/minstrel.rb
+- ./README.textile
+- ./minstrel.gemspec
+has_rdoc: true
+homepage: https://github.com/jordansissel/ruby-minstrel
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.7
+signing_key: 
+specification_version: 3
+summary: minstrel - a ruby instrumentation tool
+test_files: []
+