cutter 0.8.6 → 0.8.7

data/README.md

@@ -2,6 +2,20 @@
 
 Two-methods-gem I use a lot for simple debugging & performance measuring purposes.
 
+```#inspect``` method shines when doing reverse engineering, it is especially useful, when it is needed to quickly hack on someone else's code. Also, it is very easy to become 'someone else' for self, when dealing with own code, if it was written very long time ago.
+
+Besides that ```#stamper``` allows doing some performance measuments in a handy manner, it can be used to create quick and neat demonstrations of how particular pieces of Ruby code perform. 
+
+The one interesting possible usage of ```#stamper``` is to optimize performance of templates on Rails View layer, because it often takes a large (compared to M and C layers) load impact because of Rails lazy-evaluation mechanisms.
+
+[![Build Status](https://secure.travis-ci.org/stanislaw/cutter.png)](http://travis-ci.org/stanislaw/cutter)
+
+## Prerequisites
+
+It works on 1.8.7, 1.9.3, JRuby and Rubinius
+
+## Installiation
+
 Include it into Gemfile:
 
 ```ruby
@@ -10,14 +24,20 @@ group :development, :test do
 end
 ```
 
-## I) #inspect! (or #iii - it is an alias)
+## Cutter::Inspection
+### I) #inspect!
 
-Insert #inspect! method into any of your methods:
+Insert ```#inspect!``` method into any of your methods:
 
 ```ruby
   def your_method *your_args
     # ...
+    
     inspect! {} # curly braces are important!    
+    
+    # or 
+    # iii {} as an alias
+    
     # ...
   end
 
@@ -30,12 +50,12 @@ Insert #inspect! method into any of your methods:
 
 It gives simple but nice trace for inspection: method's name and args that were passed to method.
 
-With ```inspect!(:instance){}``` we also see instance variables:
+With ```inspect!(:instance) {}``` we also see instance variables:
 
 ```ruby
   def your_method a, b 
     @instance_var = "blip!"
-    inspect!(:instance){}
+    inspect!(:instance) {}
   end
 
   # your_method 1, 2
@@ -48,7 +68,7 @@ With ```inspect!(:instance){}``` we also see instance variables:
   #     @instance_var: blip!
 ```
 
-With ```inspect!(:self){}``` we have self#inspect of class to which method belongs to:
+With ```inspect!(:self) {}``` we have ```self#inspect``` of class to which method belongs to:
 
 ```ruby  
   def your_method name, *args
@@ -68,12 +88,12 @@ With ```inspect!(:self){}``` we have self#inspect of class to which method belon
   #     #<SelfInspectDemo:0x82be488 @variable="I'm variable">
 ```
 
-Option :caller gives us caller methods chain:
+Option ```:caller``` gives us caller methods chain:
 
 ```ruby  
   def your_method name, *args
     # ...
-    inspect!(:caller)
+    inspect!(:caller) {}
   end
 
   # your_method(1,2,3,4,5) => 
@@ -90,13 +110,11 @@ Option :caller gives us caller methods chain:
   #     /home/stanislaw/.rvm/gems/ruby-1.9.2-p180@310/gems/rspec-core-2.6.4/lib/rspec/core/example.rb:48:in `instance_eval'
 ```
 
-And finally ```inspect!(:max){}``` produces maximum information: options
-:instance, :self, :caller are included + Ruby's ordinary #inspect method
-is called on every variable.
+And finally ```inspect!(:max) {}``` produces maximum information: options ```:instance```, ```:self```, ```:caller``` are included and **Ruby's ordinary ```#inspect``` method is called on every variable**.
 
 ```ruby
   def your_method *args
-    inspect!(:max){}
+    inspect!(:max) {}
   end
 
   # maximal(1, :two, "three", :four => 5) =>
@@ -117,7 +135,7 @@ is called on every variable.
   #   ...
 ```
 
-If you want all #inspect! methods fall silent at once, use
+If you want all ```#inspect!``` methods fall silent at once, use
 
 ```ruby
 Cutter::Inspection.quiet!
@@ -129,27 +147,135 @@ To make them sound again do
 Cutter::Inspection.loud!
 ```
 
-You can clone it and try 
+### Three-letters methods
+
+```ruby
+class Object
+  def rrr object = nil
+    raise object.inspect
+  end
+
+  def ppp object = nil
+    puts object.inspect
+  end
+
+  def lll object = nil
+    Rails.logger.info object.inspect
+  end if defined? Rails
+end
+```
+
+### #iii
+
+Instead of ```#inspect!``` you can use ```#iii``` - just an alias more convenient for typing. Finally, you have a group of 4 three-letters methods in your every day debugging workflow.
+
+## II) Cutter::Stamper
+
+Acts as ```benchmark {}``` in Rails or ```Benchmark.measure {}``` (common Ruby) but with stamps in any position in block executed.
+
+It is much simpler to write Stamper with Stamps than all these Measure-dos.
+
+### Minimal stamper
+
+```stamp!``` method is just an alias for ```stamp```, use whatever you like.
 
 ```ruby
-bundle exec rspec spec/inspection/demo_spec.rb
-```  
+puts "Minimal stamper"
+stamper do |s|
+  stamp
+  sleep 0.2
+  stamp!
+  sleep 0.2
+  stamp!
+end
+```
+
+Will produce:
 
-Very! Very simple!
+```text
+Minimal stamper
 
-### Notes
-1. Instead of #inspect! you can use #iii - just an alias more convenient for typing.
-2. #inspect! colorizes its output. If somebody suggests even better color scheme, I will be thankful.
+no name
+-------
+  stamp:       0 ms   
+  stamp:     200 ms   
+  stamp:     400 ms   
+-------
+  400ms
+```
 
-## II) #stamper
+### Stamper with named stamps
 
-Acts as benchmark{} in Rails or Benchmark.measure{} (common Ruby) but with stamps in any position in block executed.
-It is much simpler to write it quickly than all these Measure-dos.
+```ruby
+puts "Now with named stamps"
+
+Cutter::Stamper.scope :testing_method => "Demonstration of named stamping" do |tm|
+  tm.msg _1: "first piece"
+  tm.msg _2: "second piece"
+end
+
+Cutter::Stamper.scope :inner_scope => "Now internal things" do |i|
+  i.msg first: "I'm the first inner stamp"
+end
+
+stamper :testing_method do |tm|
+  sleep 0.3
+  tm.stamp! :_1
+  sleep 0.3
+  stamper :inner_scope do |i|
+    sleep 0.2
+    i.stamp! :first
+    sleep 0.2
+    i.stamp! "Stamp with custom text"
+  end
+  tm.stamp! :_2
+end
+```
+
+will result in
+
+```text
+Now with named stamps
+
+Demonstration of named stamping
+-------------------------------
+  stamp:     300 ms   first piece
+
+    Now internal things
+    -------------------
+    stamp:     201 ms   I'm the first inner stamp
+    stamp:     401 ms   Stamp with custom text
+    -------------------
+                  401ms
+
+  stamp:    1001 ms   second piece
+-------------------------------
+                         1001ms
+```
+
+## Notes
+
+* Both ```#inspect! {}``` and ```#stamper``` method colorize their output. You can see ```lib/cutter/colored_output.rb``` file to understand how it is done. I will really appreciate any suggestions of how current color scheme can be improved.
+
+## Specs and demos
+
+Clone it
+
+```bash
+$ git clone https://github.com/stanislaw/cutter
+$ cd cutter
+```
+
+Specs are just
+
+```ruby
+rake
+```
 
-Description is coming...
+See demos
 
 ```ruby
-bundle exec rspec spec/stamper/demo_spec.rb
+rake demo
 ```
 
 ## Contributors

data/lib/cutter/colored_outputs.rb

@@ -1,6 +1,12 @@
 require 'colorize'
+
 class Object
-  
+  def __colorize__ obj
+    colors = Cutter::ColoredOutputs.colors_config
+    color = colors[obj] || :default
+    color != :default ? to_s.send(color) : to_s
+  end
+
   def line sp = ""
     log_coloured sp, "------------------------------", color(:line)
   end
@@ -30,20 +36,22 @@ module Cutter
 
       def colors_config
         @colors ||= {
-                      :line => :blue, 
+                      # Colors for #stamper
+                      :line => :blue,
                       :time => :light_blue,
 
                       :message_name => :cyan,
                       :message_line => :cyan,
                       :total_line => :yellow,
                       :total_count => :yellow,
-                     
+
                       # Colors for #inspect!
                       #  :called_from => :light_magenta,
+
                       :class_name => :light_green,
                       :method => :red,
                       :method_name => :yellow,
-                      
+
                       # :source => :white,
                       # :source_path => :white,
                       # :source_number => :white,

data/lib/cutter/inspection.rb

@@ -17,10 +17,10 @@ module Cutter
 end
 
 class Object
-  
-  # #inspect! may be called inside any method as 'inspect! {}' or more rigorous: 'inspect!(binding)'
+
+  # #inspect! may be called inside any method as 'inspect! {}' or more rigorously as 'inspect!(binding)'
   # Binding is a Ruby class: http://www.ruby-doc.org/core/classes/Binding.html
-  
+
   def inspect! *options, &block
     return true if Cutter::Inspection.quiet?
 
@@ -28,16 +28,16 @@ class Object
     _binding = options.first if options.first.class == Binding
     raise ArgumentError, "Try inspect(binding) or inspect! {}", caller if (!block_given? && !_binding)
     _binding ||= block.binding
-    
+
     max = true if options.include? :max
     options << :instance << :max << :self << :caller if max
     options.uniq!
- 
+
     iv = true if options.include? :instance
 
     # Want caller methods chain to be traced? - pass option :caller to #inspect!
     _caller = true if options.include? :caller
-   
+
     self_inspection = eval('self.inspect', _binding) if options.include? :self
 
     # Basic info
@@ -48,53 +48,53 @@ class Object
       source_path, source_number = meth.source_location
     end
 
-    puts "\n%s `%s' %s" % ['method:'.to_colorized_string(:method), method_name.to_colorized_string(:method_name), ('(maximal tracing)' if max)]
+    puts "\n%s `%s' %s" % ['method:'.__colorize__(:method), method_name.__colorize__(:method_name), ('(maximal tracing)' if max)]
+
+    puts "  %s %s:%s" % ['source_location:'.__colorize__(:source), source_path.dup.__colorize__(:source_path), source_number.to_s.__colorize__(:source_number)] if source_path && source_number
 
-    puts "  %s %s:%s" % ['source:'.to_colorized_string(:source), source_path.dup.to_colorized_string(:source_path), source_number.to_s.to_colorized_string(:source_number)] if source_path && source_number
-   
-    puts "  %s %s" % ['called from class:'.to_colorized_string(:called_from), class_name.to_colorized_string(:class_name)]
+    puts "  %s %s" % ['called from class:'.__colorize__(:called_from), class_name.__colorize__(:class_name)]
 
     # Local Variables
     lvb = eval('local_variables',_binding)
-    puts "  %s %s" % ['local_variables:'.to_colorized_string(:lv), ("[]" if lvb.empty?)]
+    puts "  %s %s" % ['local_variables:'.__colorize__(:lv), ("[]" if lvb.empty?)]
 
     lvb.map do |lv|
       local_variable = eval(lv.to_s, _binding)
-      local_variable = (max ? local_variable.inspect : local_variable.to_real_string)
+      local_variable = (max ? local_variable.inspect : local_variable.__real_to_s__)
 
-      puts "    %s: %s" % [lv.to_colorized_string(:lv_names), local_variable.to_colorized_string(:lv_values)] 
+      puts "    %s: %s" % [lv.__colorize__(:lv_names), local_variable.__colorize__(:lv_values)]
     end if lvb
 
     # Instance Variables
     begin
       ivb = eval('instance_variables',_binding)
-      
-      puts "  %s %s" % ["instance_variables:".to_colorized_string(:iv), ("[]" if ivb.empty?)]
-      
+
+      puts "  %s %s" % ["instance_variables:".__colorize__(:iv), ("[]" if ivb.empty?)]
+
       ivb.map do |iv|
         instance_variable = eval(iv.to_s, _binding)
-        instance_variable = (max ? instance_variable.inspect : instance_variable.to_real_string)
-       
-        puts "    %s: %s" % [iv.to_colorized_string(:iv_names), instance_variable.to_colorized_string(:iv_values)] 
+        instance_variable = (max ? instance_variable.inspect : instance_variable.__real_to_s__)
+
+        puts "    %s: %s" % [iv.__colorize__(:iv_names), instance_variable.__colorize__(:iv_values)]
       end if ivb
     end if iv
 
-    # Self inspection 
+    # Self inspection
     begin
-      puts "  self inspection:".to_colorized_string(:self_inspection)
-      puts "  %s" % self_inspection.to_colorized_string(:self_inspection_trace)
+      puts "  self inspection:".__colorize__(:self_inspection)
+      puts "  %s" % self_inspection.__colorize__(:self_inspection_trace)
     end if self_inspection
 
     # Caller methods chain
     begin
-      puts "  caller methods: ".to_colorized_string(:caller_methods)
+      puts "  caller methods: ".__colorize__(:caller_methods)
       caller.each do |meth|
-        puts "  %s" % meth.to_colorized_string(:caller_method)
+        puts "  %s" % meth.__colorize__(:caller_method)
       end
     end if _caller
-   
+
     puts "\n"
-    
+
     # Yield mysterious things if they exist in block.
     yield if block_given?
   end
@@ -104,15 +104,13 @@ class Object
   protected
 
   # "Real string". It is now used to print Symbols with colons
-  def to_real_string
-    return ":#{self.to_s}" if self.class == Symbol
-    to_s
-  end
-
-  def to_colorized_string obj
-    colors = Cutter::ColoredOutputs.colors_config
-    color = colors[obj] || :default
-    color != :default ? to_s.send(color) : to_s
+  def __real_to_s__
+    case self
+    when Symbol, Array, Hash
+      inspect
+    else
+      to_s
+    end
   end
 end
 
@@ -121,7 +119,7 @@ class Object
     raise object.inspect
   end
 
-  def ppp object = nil 
+  def ppp object = nil
     puts object.inspect
   end
 

data/lib/cutter/stamper.rb

@@ -16,29 +16,41 @@ class Object
     end
     spaces = "    " * scope.indent
     puts "\n"
-    log_coloured spaces, "#{message}", color(:message_name)
-    log_coloured spaces, "#{'-'*message.length}", color(:message_line)
+    log_coloured spaces, "#{message}", __color__(:message_name)
+    log_coloured spaces, "#{'-'*message.length}", __color__(:message_line)
 
     scope.time_initial = time_now
+
+    self.class.send :define_method, :stamp do |*args|
+      scope.stamp args.first
+    end
+    self.class.send :alias_method, :stamp!, :stamp
+    
     yield scope
+
+    instance_eval do
+      undef :stamp if respond_to? :stamp
+      undef :stamp! if respond_to? :stamp!
+    end
+
     scope.indent -= 1 if scope.indent > 0
     stamper_class.pop
     time_passed = time_now - scope.time_initial
-   
+
     tps = "#{time_passed}ms"
     offset = message.length - tps.length
     offset = 0 if offset < 0
-    log_coloured spaces, "#{'-'*message.length}", color(:total_line)
-    log_coloured spaces + "#{' ' * (offset)}", tps, color(:total_count)
+    log_coloured spaces, "#{'-'*message.length}", __color__(:total_line)
+    log_coloured spaces + "#{' ' * (offset)}", tps, __color__(:total_count)
     puts "\n"
   end
 
   private
 
-  def color type
+  def __color__ type
     stamper_class.colors_config[type] if stamper_class.colors?
   end
-   
+
   def stamper_class
     Cutter::Stamper
   end
@@ -107,6 +119,7 @@ module Cutter
       print "  " * nindent
       printf("stamp: %7d ms   #{message}\n", time_passed)
     end
+    alias_method :stamp!, :stamp
 
     module ClassMethods
 

data/lib/cutter/version.rb

@@ -1,3 +1,3 @@
 module Cutter
-  VERSION="0.8.6"
+  VERSION="0.8.7"
 end

metadata

@@ -1,72 +1,89 @@
---- !ruby/object:Gem::Specification
+--- !ruby/object:Gem::Specification 
 name: cutter
-version: !ruby/object:Gem::Version
-  version: 0.8.6
+version: !ruby/object:Gem::Version 
+  hash: 49
   prerelease: 
+  segments: 
+  - 0
+  - 8
+  - 7
+  version: 0.8.7
 platform: ruby
-authors:
+authors: 
 - stanislaw
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-06-16 00:00:00.000000000 Z
-dependencies:
-- !ruby/object:Gem::Dependency
-  name: colorize
-  requirement: !ruby/object:Gem::Requirement
-    none: false
-    requirements:
-    - - ! '>='
-      - !ruby/object:Gem::Version
-        version: '0.5'
+
+date: 2012-06-30 00:00:00 Z
+dependencies: 
+- !ruby/object:Gem::Dependency 
   type: :runtime
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 1
+        segments: 
+        - 0
+        - 5
+        version: "0.5"
+  version_requirements: *id001
+  name: colorize
   prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
+- !ruby/object:Gem::Dependency 
+  type: :development
+  requirement: &id002 !ruby/object:Gem::Requirement 
     none: false
-    requirements:
-    - - ! '>='
-      - !ruby/object:Gem::Version
-        version: '0.5'
-- !ruby/object:Gem::Dependency
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  version_requirements: *id002
   name: bundler
-  requirement: !ruby/object:Gem::Requirement
-    none: false
-    requirements:
-    - - ! '>='
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
   prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
+- !ruby/object:Gem::Dependency 
+  type: :development
+  requirement: &id003 !ruby/object:Gem::Requirement 
     none: false
-    requirements:
-    - - ! '>='
-      - !ruby/object:Gem::Version
-        version: '0'
-- !ruby/object:Gem::Dependency
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  version_requirements: *id003
   name: jeweler
-  requirement: !ruby/object:Gem::Requirement
-    none: false
-    requirements:
-    - - ! '>='
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
   prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
+- !ruby/object:Gem::Dependency 
+  type: :development
+  requirement: &id004 !ruby/object:Gem::Requirement 
     none: false
-    requirements:
-    - - ! '>='
-      - !ruby/object:Gem::Version
-        version: '0'
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  version_requirements: *id004
+  name: rspec
+  prerelease: false
 description: Ruby tracing gem
 email: s.pankevich@gmail.com
 executables: []
+
 extensions: []
-extra_rdoc_files:
+
+extra_rdoc_files: 
 - LICENSE.txt
 - README.md
-files:
+files: 
 - lib/cutter.rb
 - lib/cutter/colored_outputs.rb
 - lib/cutter/inspection.rb
@@ -75,31 +92,37 @@ files:
 - LICENSE.txt
 - README.md
 homepage: http://github.com/stanislaw/cutter
-licenses:
+licenses: 
 - MIT
 post_install_message: 
 rdoc_options: []
-require_paths:
+
+require_paths: 
 - lib
-required_ruby_version: !ruby/object:Gem::Requirement
+required_ruby_version: !ruby/object:Gem::Requirement 
   none: false
-  requirements:
-  - - ! '>='
-    - !ruby/object:Gem::Version
-      version: '0'
-      segments:
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
       - 0
-      hash: 68698447
-required_rubygems_version: !ruby/object:Gem::Requirement
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
   none: false
-  requirements:
-  - - ! '>='
-    - !ruby/object:Gem::Version
-      version: '0'
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
 requirements: []
+
 rubyforge_project: 
 rubygems_version: 1.8.19
 signing_key: 
 specification_version: 3
 summary: Ruby tracing gem
 test_files: []
+