trace_spy 0.0.1 → 0.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a36db56361a6223b879ca27adfedfbb65660a7617bd5e24fca290a876be6df92
-  data.tar.gz: 68506cf1d4bb171fc998761190a680547d238418e43e04f51a432af10be5f9ff
+  metadata.gz: 3831d476b8d255dbec62c68b430fbd5733a8ff9a517c16d61a5be2ccac842a59
+  data.tar.gz: 4247e3304fd6cb2ef1e81187e1a29e8457ca4225c6414d5a171aed34775739ca
 SHA512:
-  metadata.gz: 6155fea20309cba45610af5d966eab12e348769dfb1d376894e97eda9b7bd7fda593fa0f3fdd4947a2637016bb6a3a1b3f3b454318a28bd2c85465e7cd0ada7c
-  data.tar.gz: 543c16db8f7d8055137d22b1959f97f216b8f117136d7e1eb5453a33263ce13aa4de108c38cca56caa0cedd0ea93efaa1796b43ed2178554cdaa4d4f2daea6bf
+  metadata.gz: 69c58ab72a6908eee036ecebbae4ee3b1337ef6d8baa921d2d885bc017781a86fa5ea09a4892b6a575b9d82e4190c8785c43b8af9825543e71c2c5c0208b4b9a
+  data.tar.gz: 3226f8d53fd8cceb8403bfda5f90a5cfa3938d77c71bfbdcb5f131098e55fee9642492bd60028fb78d42cceb78423abbc5aedfa368328ea36957b020c953764c

data/README.md

@@ -13,10 +13,15 @@ I can create a nice API, and we'll work from there.
 
 ## Usage
 
+The methods themselves are documented, and I'll work on expanding this section later with more examples and ideas
+as I can.
+
 ```ruby
 def testing(a, b, c)
   raise 'heck' if a.is_a?(Numeric) && a > 20
 
+  d = 5 if c.is_a?(Numeric) && c > 3
+
   a + b + c
 end
 
@@ -42,31 +47,42 @@ testing_spy = TraceSpy::Method.new(:testing) do |spy|
   # On a return value, will yield the return to the block
   spy.on_return do |m|
     m.when(String) do |v|
-      puts "Strings in, Strings out no?: #{v}"
+      puts "Strings in, Strings out no?: #{v}. I got this in though: #{spy.current_arguments}"
     end
 
     m.when(:even?) do |v|
       puts "I got an even return: #{v}"
     end
   end
+
+  # On a local variable being present:
+  spy.on_locals do |m|
+    m.when(d: 5) do |v|
+      puts "I saw d was a local in here!: #{v}. I could also ask this: #{spy.current_local_variables}"
+    end
+  end
 end
 
 testing_spy.enable
 # => false
 
-testing(1, 2, 3)
+p testing(1, 2, 3)
 # My args were 1, 2, 3: {:a=>1, :b=>2, :c=>3}
 # I got an even return: 6
 # => 6
 
-testing(21, 2, 3)
+p testing(21, 2, 3) rescue 'nope'
 # I encountered an error: heck
-# RuntimeError: heck
-# from (pry):2:in `testing'
+# => 'nope'
 
-testing(*%w(foo bar baz))
+p testing(*%w(foo bar baz))
 # Oh hey! You called me with strings: {:a=>"foo", :b=>"bar", :c=>"baz"}
 # Strings in, Strings out no?: foobarbaz
+# => 'foobarbaz'
+
+p testing(1, 2, 4)
+# I saw d was a local in here!: {:a=>1, :b=>2, :c=>4, :d=>5}
+# => 7
 ```
 
 ## Installation

data/lib/trace_spy.rb

@@ -2,12 +2,25 @@ require "trace_spy/version"
 
 require 'qo'
 
+# A Wrapper around TracePoint to provide a more flexible API
+#
+# @author baweaver
+# @since 0.0.1
+#
 module TraceSpy
-  class Error < StandardError; end
-
+  # Method call events
   CALL_EVENT   = Set.new([:call, :c_call])
+
+  # Method return events
   RETURN_EVENT = Set.new([:return, :c_return])
+
+  # Exception events
   RAISE_EVENT  = Set.new([:raise])
+
+  # Line execution events
+  LINE_EVENT  = Set.new([:line])
+
+  # TODO: Implement other event types
 end
 
 require 'trace_spy/method'

data/lib/trace_spy/method.rb

@@ -1,35 +1,220 @@
 module TraceSpy
+  # Implements a TraceSpy on a Method
+  #
+  # @author baweaver
+  # @since 0.0.1
+  #
+  # @note
+  #   Tracer spies all rely on Qo for pattern-matching syntax. In order to more
+  #   effectively leverage this gem it would be a good idea to look through
+  #   the Qo documentation present here: https://github.com/baweaver/qo
+  #
+  # @example
+  #   A simple use-case would be monitoring for a line in which c happens to be
+  #   equal to 5. Now this value could be a range or other `===` respondant type
+  #   if desired, which gives quite a bit of flexibility in querying.
+  #
+  #   ```ruby
+  #   def testing(a, b)
+  #     c = 5
+  #
+  #     a + b + c
+  #   end
+  #
+  #   trace_spy = TraceSpy::Method.new(:testing) do |spy|
+  #     spy.on_locals do |m|
+  #       m.when(c: 5) { |locals| p locals }
+  #     end
+  #   end
+  #
+  #   trace_spy.enable
+  #   # => false
+  #
+  #   testing(1, 2)
+  #   # {:a=>1, :b=>2, :c=>5}
+  #   # => 8
+  #   ```
   class Method
-    def initialize(method_name, &fn)
-      @method_name = method_name
-      @spies       = Hash.new { |h,k| h[k] = [] }
-      @tracepoint  = nil
+    # The current trace being executed upon, can be used in matcher
+    # blocks to get the entire trace context instead of just a part.
+    attr_reader :current_trace
+
+    # Creates a new method trace
+    #
+    # @param method_name [Symbol, String]
+    #   Name of the method to watch, will be compared with `===` for flexibility
+    #   which enables the use of regex and other more powerful matching
+    #   techniques.
+    #
+    # @param from_class: Any [Any]
+    #   Either a Class for type-matching, or other `===` respondant type for flexibility
+    #
+    # @param &fn [Proc]
+    #   Self-yielding proc used to initialize a spy in one block function
+    #
+    # @yields self
+    #
+    # @return [TraceSpy::Method]
+    def initialize(method_name, from_class: Any, &fn)
+      @method_name   = method_name
+      @from_class    = from_class
+      @spies         = Hash.new { |h,k| h[k] = [] }
+      @tracepoint    = nil
+      @current_trace = nil
 
       yield(self) if block_given?
     end
 
+    # Creates a Spy on function arguments
+    #
+    # @since 0.0.1
+    #
+    # @example
+    #   Consider, you'd like to monitor if a particular argument is nil:
+    #
+    #   ```ruby
+    #   def testing(a) a + 2 end
+    #
+    #   trace_spy = TraceSpy::Method.new(:testing) do |spy|
+    #     spy.on_arguments do |m|
+    #       m.when(a: nil) { |args| binding.pry }
+    #     end
+    #   end
+    #   ```
+    #
+    #   You could use this to find out if there's a type-mismatch, or what
+    #   the context is around a particular error due to an argument being
+    #   a particular value.
+    #
+    # @param &matcher_fn [Proc]
+    #   Qo Matcher
+    #
+    # @return [Array[Qo::Matcher]]
+    #   Currently added Qo matchers
     def on_arguments(&matcher_fn)
       @spies[:arguments] << Qo.match(&matcher_fn)
     end
 
+    # Creates a Spy on local method variables
+    #
+    # @since 0.0.2
+    #
+    # @example
+    #   Consider, a local variable is inexplicably getting set equal to nil,
+    #   and you don't know where it's happening:
+    #
+    #   ```ruby
+    #   def testing(a)
+    #     b = nil
+    #     a + 2
+    #   end
+    #
+    #   trace_spy = TraceSpy::Method.new(:testing) do |spy|
+    #     spy.on_locals do |m|
+    #       m.when(b: nil) { |args| binding.pry }
+    #     end
+    #   end
+    #   ```
+    #
+    #   You can use this to stop your program precisely where the offending code
+    #   is located without needing to know where it is beforehand.
+    #
+    # @param &matcher_fn [Proc]
+    #   Qo Matcher
+    #
+    # @return [Array[Qo::Matcher]]
+    #   Currently added Qo matchers
+    def on_locals(&matcher_fn)
+      @spies[:locals] << Qo.match(&matcher_fn)
+    end
+
+    # Creates a Spy on function returns
+    #
+    # @since 0.0.1
+    #
+    # @example
+    #   Consider, you'd like to know when your logging method is returning
+    #   an empty string:
+    #
+    #   ```ruby
+    #   def logger(msg)
+    #     rand(10) < 5 ? msg : ""
+    #   end
+    #
+    #   trace_spy = TraceSpy::Method.new(:logger) do |spy|
+    #     spy.on_return do |m|
+    #       m.when("") { |v| binding.pry }
+    #     end
+    #   end
+    #   ```
+    #
+    #   This could be used to find out the remaining context around what caused
+    #   the blank message, like getting arguments from the `spy.current_trace`.
+    #
+    # @param &matcher_fn [Proc]
+    #   Qo Matcher
+    #
+    # @return [Array[Qo::Matcher]]
+    #   Currently added Qo matchers
     def on_return(&matcher_fn)
       @spies[:return] << Qo.match(&matcher_fn)
     end
 
+    # Creates a Spy on a certain type of exception
+    #
+    # @since 0.0.1
+    #
+    # @example
+    #   Consider, you'd like to find out where that error is coming from in
+    #   your function:
+    #
+    #   ```ruby
+    #   def testing(a)
+    #     raise 'heck'
+    #     a + 2
+    #   end
+    #
+    #   trace_spy = TraceSpy::Method.new(:testing) do |spy|
+    #     spy.on_exception do |m|
+    #       m.when(RuntimeError) { |args| binding.pry }
+    #     end
+    #   end
+    #   ```
+    #
+    #   Like return, you can use this to find out the context around why this
+    #   particular error occurred.
+    #
+    # @param &matcher_fn [Proc]
+    #   Qo Matcher
+    #
+    # @return [Array[Qo::Matcher]]
+    #   Currently added Qo matchers
     def on_exception(&matcher_fn)
       @spies[:exception] << Qo.match(&matcher_fn)
     end
 
+    # "Enables" the current tracepoint by defining it, caching it, and enabling it
+    #
+    # @since 0.0.1
+    #
+    # @return [FalseClass]
+    #   Still not sure why TracePoint#enable returns `false`, but here we are
     def enable
       @tracepoint = TracePoint.new do |trace|
         begin
-          next unless trace.method_id == @method_name
+          next unless matches?(trace)
+
+          @current_trace = trace
 
           call_with  = -> with { -> spy { spy.call(with) } }
 
+
           @spies[:arguments].each(&call_with[extract_args(trace)])    if CALL_EVENT.include?(trace.event)
+          @spies[:locals].each(&call_with[extract_locals(trace)])     if LINE_EVENT.include?(trace.event)
           @spies[:return].each(&call_with[trace.return_value])        if RETURN_EVENT.include?(trace.event)
           @spies[:exception].each(&call_with[trace.raised_exception]) if RAISE_EVENT.include?(trace.event)
+
+          @current_trace = nil
         rescue RuntimeError => e
           # Stupid hack for now
           p e
@@ -39,14 +224,142 @@ module TraceSpy
       @tracepoint.enable
     end
 
+    # Disables the TracePoint, or pretends it did if one isn't enabled yet
+    #
+    # @since 0.0.1
+    #
+    # @return [Boolean]
     def disable
-      @tracepoint&.disable
+      !!@tracepoint&.disable
     end
 
-    def extract_args(trace)
+    # Returns the local variables of the currently active trace
+    #
+    # @since 0.0.2
+    #
+    # @example
+    #   This is a utility function for use with `spy` inside the matcher
+    #   block.
+    #
+    #   ```ruby
+    #   trace_spy = TraceSpy::Method.new(:testing) do |spy|
+    #     spy.on_exception do |m|
+    #       m.when(RuntimeError) do |v|
+    #         p spy.current_local_variables
+    #       end
+    #     end
+    #   end
+    #   ```
+    #
+    #   It's meant to be used to expose the current local variables
+    #   within a trace's scope in any type of matcher.
+    #
+    # @return [Hash[Symbol, Any]]
+    def current_local_variables
+      return {} unless @current_trace
+
+      extract_locals(@current_trace)
+    end
+
+    # Returns the arguments of the currently active trace
+    #
+    # @since 0.0.2
+    #
+    # @note
+    #   This method will attempt to avoid running in contexts where
+    #   argument retrieval will give a runtime error.
+    #
+    # @example
+    #   This is a utility function for use with `spy` inside the matcher
+    #   block.
+    #
+    #   ```ruby
+    #   trace_spy = TraceSpy::Method.new(:testing) do |spy|
+    #     spy.on_return do |m|
+    #       m.when(String) do |v|
+    #         binding.pry if spy.current_arguments[:a] == 'foo'
+    #       end
+    #     end
+    #   end
+    #   ```
+    #
+    #   It's meant to expose the current arguments present in a trace's
+    #   scope.
+    #
+    # @return [Hash[Symbol, Any]]
+    def current_arguments
+      return {} unless @current_trace
+      return {} if RAISE_EVENT.include?(@current_trace.event)
+
+      extract_args(@current_trace)
+    end
+
+    # Whether the current trace matches our current preconditions
+    #
+    # @since 0.0.1
+    #
+    # @param trace [Trace]
+    #   Currently active Trace
+    #
+    # @return [Boolean]
+    #   Whether or not the trace matches
+    private def matches?(trace)
+      method_matches?(trace) && class_matches?(trace)
+    end
+
+    # Whether the current trace fits the class constraints
+    #
+    # @since 0.0.1
+    #
+    # @param trace [Trace]
+    #   Currently active Trace
+    #
+    # @return [Boolean]
+    #   Whether or not the trace matches
+    private def class_matches?(trace)
+      return true if @from_class == Any
+
+      @from_class == trace.defined_class || @from_class === trace.defined_class
+    end
+
+    # Whether the current trace fits the method constraints
+    #
+    # @since 0.0.1
+    #
+    # @param trace [Trace]
+    #   Currently active Trace
+    #
+    # @return [Boolean]
+    #   Whether or not the trace matches
+    private def method_matches?(trace)
+      @method_name === trace.method_id
+    end
+
+    # Extracts the arguments from a given trace
+    #
+    # @since 0.0.1
+    #
+    # @param trace [Trace]
+    #
+    # @return [Hash[Symbol, Any]]
+    #   Hash mapping argument names to their respective values
+    private def extract_args(trace)
       param_names = trace.parameters.map(&:last)
 
       param_names.map { |n| [n, trace.binding.eval(n.to_s)] }.to_h
     end
+
+    # Extracts the local variables from a given trace
+    #
+    # @since 0.0.1
+    #
+    # @param trace [Trace]
+    #
+    # @return [Hash[Symbol, Any]]
+    #   Hash mapping local variable names to their respective values
+    private def extract_locals(trace)
+      local_names = trace.binding.eval('local_variables')
+      local_names.map { |n| [n, trace.binding.eval(n.to_s)] }.to_h
+    end
   end
 end

data/lib/trace_spy/version.rb

@@ -1,3 +1,3 @@
 module TraceSpy
-  VERSION = "0.0.1"
+  VERSION = "0.0.2"
 end

data/trace_spy.gemspec

@@ -22,7 +22,7 @@ Gem::Specification.new do |spec|
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ["lib"]
 
-  spec.add_runtime_dependency "qo"
+  spec.add_runtime_dependency "qo", "~> 0.5"
 
   spec.add_development_dependency "bundler", "~> 1.17"
   spec.add_development_dependency "rake", "~> 10.0"

metadata

@@ -1,29 +1,29 @@
 --- !ruby/object:Gem::Specification
 name: trace_spy
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.2
 platform: ruby
 authors:
 - Brandon Weaver
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2019-01-26 00:00:00.000000000 Z
+date: 2019-01-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: qo
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '0.5'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '0.5'
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement