puppy 1.0.0

checksums.yaml

@@ -0,0 +1,15 @@
+---
+!binary "U0hBMQ==":
+  metadata.gz: !binary |-
+    ZjZlMjdlODQzNjlmYmNhMmU3ZTg3N2QyNzZlY2NhOWJkNjAxYWNjZg==
+  data.tar.gz: !binary |-
+    NGIwOWVhYmIzMjFlMGYxODc3Njg2NTMyMzBlOWFlMTAxZTQzNTZjOA==
+!binary "U0hBNTEy":
+  metadata.gz: !binary |-
+    NzkwYTUxZTI0NTg3ZGZiOTBlMDhkMTVkMTVkNzBkMzg3YzgzOWY2OTM5MWMy
+    ZTNjMDQ1YWUzNjdkNDNkN2EyZTAyZDVmZTNkZTY2NDQ2Mzg0ODVkMDViZTZi
+    NzVkMTY1N2QyYWJhN2I0MTZkOTMxODBlOWViZTc0M2MxYWY0MTc=
+  data.tar.gz: !binary |-
+    YjZhMzNkZjYxYzQ2OWE3YzcyM2IzOTRhZTNiZDRlNmM0MTcyMTA4NmU4ZjQz
+    MTA1ODI2NGEzNzIzZjA3OGQwNTE3NjNmNDZkYTVkODE5NGQ4YTdkYWE0NDBi
+    ZGRkY2NjNzQyMzcwZGExODUwOTU4Yjk3YWM3NGI0NzYxZmE5NTY=

data/Gemfile

@@ -0,0 +1,5 @@
+source 'https://rubygems.org'
+
+gemspec
+
+gem 'rake'

data/LICENSE

@@ -0,0 +1,28 @@
+Software License Agreement (BSD License)
+
+Copyright (c) 2013, Simone Margaritelli <http://www.evilsocket.net/>
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+  * Redistributions of source code must retain the above copyright notice,
+    this list of conditions and the following disclaimer.
+  * Redistributions in binary form must reproduce the above copyright
+    notice, this list of conditions and the following disclaimer in the
+    documentation and/or other materials provided with the distribution.
+  * Neither the name of Puppy nor the names of its contributors may be used
+    to endorse or promote products derived from this software without
+    specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
+LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+POSSIBILITY OF SUCH DAMAGE.

data/README.md

@@ -0,0 +1,77 @@
+Puppy
+========================
+
+Puppy is a tiny gem which will help you to perform easy object tracing and debugging.  
+It simply defines a *trace* instance method on the Object class, once this method is invoked on an object of any kind, 
+Puppy will start following and tracing like there's no tomorrow! :D
+
+Methods
+------------------------
+
+Basically the only method that you are going to use is *trace* defined on every Object derived class, which can be invoked with
+a set of options and with an optional code block to perform conditional tracing, original object instance, method and arguments 
+list are passed to the code block.
+
+Options are:
+
+- :as - how to represent the instance as string, if a Symbol is given it will be invoked as a method, otherwise as a string. Default: :class 
+- :caller - a boolean to enable or disable printing caller data. Default: true
+- :step - if true stop the execution on each method invoked and wait for the user to press a key. Default: false
+- :indent - if true method invocations will be indented as their nesting goes deeper. Default: true
+- :stream - the stream to use to print the report while tracing the object, must overload the << operator. Default: STDERR
+
+Examples
+------------------------
+
+Basic usage.
+
+    foo = 1.trace
+    puts foo
+
+Output:
+    
+    # Fixnum.to_ary() [puppy.rb:71:in `puts'] 
+    # Fixnum.respond_to?(:to_ary) [puppy.rb:71:in `puts'] 
+    # Fixnum.to_s() [puppy.rb:71:in `puts'] 
+    1
+    
+Follow the object without reporting the caller and represent it using its variable name instead of its class. 
+
+    bar = "something".trace :as => 'bar', :caller => false
+    puts bar
+
+Output:
+
+    # bar.to_ary() 
+    # bar.respond_to?(:to_ary) 
+    # bar.to_s() 
+    something
+
+Use a block to conditionally trace only when arguments list is filled with something.
+
+    count = 3.trace { |object,method,*args| args.size > 0 }
+    puts count.size    # this won't be traced
+    puts count.to_s(2) # this will
+
+Installation and Usage
+------------------------
+
+You can verify your installation using this piece of code:
+
+    gem install puppy
+
+And
+
+    require 'puppy'
+    1.respond_to? :trace
+
+License
+------------------------
+
+Released under the BSD license.  
+Copyright © 2013, Simone Margaritelli 
+
+<http://www.evilsocket.net/>
+All rights reserved.
+
+

data/Rakefile

@@ -0,0 +1,3 @@
+require 'rake/clean'
+CLEAN.include "**/*.rbc"
+CLEAN.include "**/.DS_Store"

data/lib/puppy.rb

@@ -0,0 +1,111 @@
+# This is where the magic happens, open the Object class and define
+# the new #trace instance method for every object instances.
+class Object
+  # Starts tracing the object instance and prints every call to
+  # its instance methods with given arguments.
+  # Can be invoked with a code block to perform conditional tracing,
+  # original object instance, method and arguments list are passed
+  # to the code block.
+  #
+  # ==== Important Note:
+  # If you assign the traced variable to another object which is
+  # not traced, you will lose the ability to trace the new instance
+  # unless you call the #trace method explicitly.
+  #
+  # ==== Examples:
+  #
+  #   # The following will print:
+  #   #    Fixnum.to_ary() [puppy.rb:71:in `puts'] 
+  #   #    Fixnum.respond_to?(:to_ary) [puppy.rb:71:in `puts'] 
+  #   #    Fixnum.to_s() [puppy.rb:71:in `puts'] 
+  #   #    1
+  #   foo = 1.trace
+  #   puts foo
+  #
+  #   # Trace the object without reporting the caller and represent 
+  #   # it using its variable name instead of its #class, will print:
+  #   # # bar.to_ary() 
+  #   # # bar.respond_to?(:to_ary) 
+  #   # # bar.to_s() 
+  #   # something
+  #   bar = "something".trace :as => 'bar', :caller => false
+  #   puts bar
+  #
+  #   # Trace only when arguments list is filled with something.
+  #   count = 3.trace { |object,method,*args| args.size > 0 }
+  #   puts count.size    # this won't be traced
+  #   puts count.to_s(2) # this will
+  #
+  # ==== Options:
+  #
+  # - :as - how to represent the instance as string, if a Symbol is given it will be invoked as a method, otherwise as a string. Default: :class 
+  # - :caller - a boolean to enable or disable printing caller data. Default: true
+  # - :step - if true stop the execution on each method invoked and wait for the user to press a key. Default: false
+  # - :indent - if true method invocations will be indented as their nesting goes deeper. Default: true
+  # - :stream - the stream to use to print the report while tracing the object, must overload the << operator. Default: STDERR
+	def trace( options = {}, &block )
+		Puppy::TracedObject.new( self, options, &block )
+	end
+end
+
+module Puppy #:nodoc:
+  # This is the class which encapsulates every object instances once
+  # the Object#trace method is invoked.
+	class TracedObject 
+    # Undefine every instance method to use the #method_missing trick.
+		instance_methods.each do |m|
+			undef_method m unless m == :object_id || m == :__id__ || m == :__send__ 
+		end
+
+		DEFAULTS = {
+			:as     => :class,
+			:caller => true,
+			:step	  => false,
+      :indent => true,
+      :stream => STDERR
+		}
+
+    #:nodoc:
+		def initialize( obj, opts = {}, &block )
+			@object, @opts, @block = obj, DEFAULTS.merge(opts), block
+      @stream = @opts[:stream]
+		end
+
+    #:nodoc: We need this to directly use #inspect on the traced object
+    # without the invocation being traced itself.
+    def inspect
+      @object.send :inspect
+    end
+
+    #:nodoc: Here it goes, trace it baby!
+		def method_missing( m, *args )
+			begin
+				if @block == nil || @block.call( @object, m, *args ) == true
+          @stream << '# '
+
+          @stream << ' ' * caller.size unless !@opts[:indent]
+
+          as = @opts[:as]
+
+          @stream << if as.is_a? Symbol
+            @object.send as
+          elsif as != nil
+            as.to_s
+          elsif
+            @object.to_s
+          end
+
+          @stream << ".#{m}(#{args.map { |a| a.inspect }.join(', ')})"
+          @stream << " [#{caller[0]}] " unless @opts[:caller] == false
+          @stream << "\n"
+
+					gets unless !@opts[:step]
+				end
+
+				@object.send m, *args
+			rescue Exception => e
+				raise
+			end
+		end
+	end
+end

data/puppy.gemspec

@@ -0,0 +1,22 @@
+Gem::Specification.new do |s|
+  s.name = %q{puppy}
+  s.version = '1.0.0'
+  s.license = "BSD"
+
+  s.authors = ["Simone Margaritelli"]
+  s.description = %q{Puppy is a tiny gem to perform easy object tracing and debugging.}
+  s.email = %q{evilsocket@gmail.com}
+  s.files = Dir.glob("lib/**/*") + [
+     "LICENSE",
+     "README.md",
+     "Rakefile",
+     "Gemfile",
+     "puppy.gemspec"
+  ]
+  s.homepage = %q{http://github.com/evilsocket/puppy}
+  s.rdoc_options = ["--charset=UTF-8"]
+  s.require_paths = ["lib"]
+  s.summary = %q{Puppy is a tiny gem to perform easy object tracing and debugging.}
+end
+
+

metadata

@@ -0,0 +1,50 @@
+--- !ruby/object:Gem::Specification
+name: puppy
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Simone Margaritelli
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-08-14 00:00:00.000000000 Z
+dependencies: []
+description: Puppy is a tiny gem to perform easy object tracing and debugging.
+email: evilsocket@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/puppy.rb
+- LICENSE
+- README.md
+- Rakefile
+- Gemfile
+- puppy.gemspec
+homepage: http://github.com/evilsocket/puppy
+licenses:
+- BSD
+metadata: {}
+post_install_message: 
+rdoc_options:
+- --charset=UTF-8
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.0.6
+signing_key: 
+specification_version: 4
+summary: Puppy is a tiny gem to perform easy object tracing and debugging.
+test_files: []