peekaboo 0.1.0

data/CHANGELOG.md

@@ -0,0 +1,7 @@
+## 0.1.0 (October 25, 2010)
+
+Features:
+
+  - Adds support for instance method tracing
+  - Configurable tracer via `Peekaboo.configure`
+

data/README.md

@@ -0,0 +1,100 @@
+# Peekaboo: Unobtrusive method tracing for Ruby classes
+
+Do you find yourself constantly adding log statements to a lot of the methods in your project?
+Does it lead to a lot of duplication and make your code feel less "elegant"?
+Peekaboo offers an alternative approach to tracing method calls, their provided arguments, and their return values.
+Simply specify which methods you want to trace inside a class and let peekaboo take care of the rest.
+
+## Installation and usage
+
+Gem:
+
+    $ gem install peekaboo
+
+### How it works:
+
+Peekaboo uses method wrapping and an internal tracer to capture the data you want to know about your methods.
+Its tracer adheres to the API established by the Logger class ( i.e. debug, info, warn, etc... ).
+For now, the only trace level supported is "info", but there are plans to support all trace levels in the future.
+Also, this first cut only provides tracing for _instance_ methods.
+
+When creating a new class, include Peekaboo and then call `enable_tracing_on`, passing it a list of method names to trace.
+
+    class Example
+      include Peekaboo
+      enable_tracing_on :foo, :bar
+      
+      def foo
+        ...
+      end
+      
+      def bar
+        ...
+      end
+    end
+
+Sometimes you may want to trace methods in a class that has already been created.
+In that case, simply reopen the class definition and follow the same steps listed above.
+
+    # Example class already exists with instance methods #baz and #bif defined
+    
+    class Example
+      include Peekaboo
+      enable_tracing_on :baz, :bif
+    end
+
+Now, with tracing enabled, Peekaboo will report when/where those methods are called along with their input and output values.
+
+    # @obj is an instance of Example
+    # Peekaboo tracer receives the following message when #baz is called below:
+    #   "File:Line ( Example#baz called with [:one, 2, "three"] ==> Returning: 'whatever gets returned' )"
+    
+    @obj.baz :one, 2, "three"
+
+## Configuration
+
+The default tracer for Peekaboo is an instance of `Logger` streaming to `STDOUT`.
+If this doesn't suit your needs, it is a trivial task to set the tracer to another object using the Peekaboo configuration.
+
+    Peekaboo.configure do |config|
+      # file-based logging
+      config.trace_with Logger.new("some_file")
+      
+      # inside Rails
+      config.trace_with Rails.logger
+      
+      # any object that responds to debug, info, warn, error, fatal, unknown
+      config.trace_with @custom_logger_object
+    end
+
+## Issues
+
+Please report any bugs or issues to the [Issue Tracking System](http://github.com/sgarcia/peekaboo/issues/).
+
+## Development
+
+If you have any feature requests or ideas feel free to contact me directly.
+If you're looking to contribute please read the contribution guidelines before submitting patches or pull requests.
+
+## License
+
+Copyright (c) 2009 Sonny Ruben Garcia
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/lib/peekaboo/configuration.rb

@@ -0,0 +1,21 @@
+require 'logger'
+
+module Peekaboo
+  class Configuration
+    
+    TRACE_LEVELS = [ :debug, :info, :warn, :error, :fatal, :unknown ]
+    
+    def tracer
+      @tracer ||= Logger.new STDOUT
+    end
+    
+    def trace_with tracer
+      if TRACE_LEVELS.all? { |level| tracer.respond_to? level }
+        @tracer = tracer
+      else
+        raise 'Tracer must respond to debug(), info(), warn(), error(), fatal(), and unknown()'
+      end
+    end
+    
+  end
+end

data/lib/peekaboo/version.rb

@@ -0,0 +1,9 @@
+module Peekaboo
+  module Version
+    MAJOR = 0
+    MINOR = 1
+    PATCH = 0
+    
+    STRING = [MAJOR, MINOR, PATCH].join('.')
+  end
+end

data/lib/peekaboo.rb

@@ -0,0 +1,68 @@
+require 'peekaboo/configuration'
+
+module Peekaboo
+  
+  class << self
+    def configuration
+      @configuration ||= Configuration.new
+    end
+    
+    def configure
+      yield configuration
+    end
+    
+    def included klass
+      klass.const_set :PEEKABOO_METHOD_LIST, []
+      klass.extend SingletonMethods
+      
+      def klass.method_added name
+        Peekaboo.wrap_method self, name if peek_list.include? name
+      end
+    end
+    
+    # @note Should I add execution time to logs?
+    def wrap_method klass, name
+      return if @_adding_a_method
+      @_adding_a_method = true
+      
+      original_method = "original_#{name}"
+      method_wrapping = %{
+        alias_method :#{original_method}, :#{name}
+        def #{name} *args, &block
+          trace = "\#{caller(1)[0]}\n\t( Invoking: #{klass}\##{name} with \#{args.inspect} "
+          begin
+            result = #{original_method} *args, &block
+            trace << "==> Returning: \#{result.inspect} )"
+            result
+          rescue Exception => exe
+            trace << "!!! Raising: \#{exe.message.inspect} )"
+            raise exe
+          ensure
+            Peekaboo.configuration.tracer.info trace
+          end
+        end
+      }
+      klass.class_eval method_wrapping
+      
+      @_adding_a_method = false
+    end
+  end
+  
+  module SingletonMethods
+    def peek_list
+      self::PEEKABOO_METHOD_LIST
+    end
+    
+    def peeks_at *method_names
+      method_names.each do |method_name|
+        unless peek_list.include? method_name
+          peek_list << method_name
+          Peekaboo.wrap_method(self, method_name) if self.instance_methods(false).include? method_name.to_s
+        else
+          raise "Already tracing `#{method_name}'"
+        end
+      end
+    end
+  end
+  
+end

metadata

@@ -0,0 +1,118 @@
+--- !ruby/object:Gem::Specification 
+name: peekaboo
+version: !ruby/object:Gem::Version 
+  hash: 27
+  prerelease: false
+  segments: 
+  - 0
+  - 1
+  - 0
+  version: 0.1.0
+platform: ruby
+authors: 
+- Sonny Ruben Garcia
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-10-26 00:00:00 -05:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: rspec
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - "="
+      - !ruby/object:Gem::Version 
+        hash: 27
+        segments: 
+        - 1
+        - 3
+        - 0
+        version: 1.3.0
+  type: :development
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: rcov
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - "="
+      - !ruby/object:Gem::Version 
+        hash: 41
+        segments: 
+        - 0
+        - 9
+        - 9
+        version: 0.9.9
+  type: :development
+  version_requirements: *id002
+- !ruby/object:Gem::Dependency 
+  name: yard
+  prerelease: false
+  requirement: &id003 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - "="
+      - !ruby/object:Gem::Version 
+        hash: 5
+        segments: 
+        - 0
+        - 6
+        - 1
+        version: 0.6.1
+  type: :development
+  version_requirements: *id003
+description: Allows you to log method call information ( input arguments, class/method name, and return value ) without being overly intrusive.
+email: sonny.ruben@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- README.md
+- CHANGELOG.md
+- lib/peekaboo.rb
+- lib/peekaboo/configuration.rb
+- lib/peekaboo/version.rb
+has_rdoc: true
+homepage: http://github.com/sgarcia/peekaboo
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- 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: Beautiful "mixin" magic for tracing Ruby method calls.
+test_files: []
+