tapping_device 0.4.7 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 72cee52830dca423c383eb154be4d7352b187cd2bcd848af5ed8d38af0f5ad40
-  data.tar.gz: 96d64f49adfd1de6b3174c9ecdb38d0f8d7e6f03bc0b1b85a79bf3b86613e349
+  metadata.gz: 9806974025c4e1ba9042bf2df5a4b4211a7e4a9630b291e05892d472e54263cc
+  data.tar.gz: fc609ed5be23cac4943e90c34d7126aaffd53816910320f7300d2a33a9d40585
 SHA512:
-  metadata.gz: a6675be23b1bbd4e0dfd6b1c4ea0ccbd39fba970af38a567928066935ab85a20003ecaf157f09f8e20223f2ec0717a72403261541d1b6836c393832c7240d35e
-  data.tar.gz: b93a1bd72210aa7f528687da0edaca7e812cb0849d7d0da8578ba8f5551a2134f6014a1f8c3b7989d750a15bdb734db1826d748de42bf4b995e3f7850cec00de
+  metadata.gz: 15ee39e171f665492e47c378bcffedd3d7bc1c8204269607e54c1ac174f44fe5ee4cc33a0ffcd82d4b732abc63def63eefb8b1fda386d4e40503a4bd959e71e2
+  data.tar.gz: 3b4bb1b05949fd4735fde568995e8c92c64634ad39f196f76649e2f401834d8fdc605080546655f90920e8c2cfc1cebb4bf686b7da34494217c677e058f6c73b

data/.github/workflows/ruby.yml

@@ -22,7 +22,7 @@ jobs:
     - name: Install sqlite
       run: |
         # See https://github.community/t5/GitHub-Actions/ubuntu-latest-Apt-repository-list-issues/td-p/41122/page/2
-        sudo rm -f /etc/apt/sources.list.d/dotnetdev.list /etc/apt/sources.list.d/microsoft-prod.list
+        for apt_file in `grep -lr microsoft /etc/apt/sources.list.d/`; do sudo rm $apt_file; done
         sudo apt-get update
         sudo apt-get install libsqlite3-dev
 

data/.ruby-version

@@ -0,0 +1 @@
+2.6.5

data/Gemfile.lock

@@ -1,37 +1,37 @@
 PATH
   remote: .
   specs:
-    tapping_device (0.4.7)
+    tapping_device (0.5.0)
       activerecord (>= 5.2)
 
 GEM
   remote: https://rubygems.org/
   specs:
-    activemodel (6.0.2.1)
-      activesupport (= 6.0.2.1)
-    activerecord (6.0.2.1)
-      activemodel (= 6.0.2.1)
-      activesupport (= 6.0.2.1)
-    activesupport (6.0.2.1)
+    activemodel (6.0.3.1)
+      activesupport (= 6.0.3.1)
+    activerecord (6.0.3.1)
+      activemodel (= 6.0.3.1)
+      activesupport (= 6.0.3.1)
+    activesupport (6.0.3.1)
       concurrent-ruby (~> 1.0, >= 1.0.2)
       i18n (>= 0.7, < 2)
       minitest (~> 5.1)
       tzinfo (~> 1.1)
-      zeitwerk (~> 2.2)
+      zeitwerk (~> 2.2, >= 2.2.2)
     coderay (1.1.2)
-    concurrent-ruby (1.1.5)
+    concurrent-ruby (1.1.6)
     database_cleaner (1.7.0)
     diff-lcs (1.3)
     docile (1.3.2)
-    i18n (1.7.0)
+    i18n (1.8.2)
       concurrent-ruby (~> 1.0)
     json (2.3.0)
     method_source (0.9.2)
-    minitest (5.13.0)
+    minitest (5.14.1)
     pry (0.12.2)
       coderay (~> 1.1.0)
       method_source (~> 0.9.0)
-    rake (10.0.4)
+    rake (13.0.1)
     rspec (3.8.0)
       rspec-core (~> 3.8.0)
       rspec-expectations (~> 3.8.0)
@@ -52,9 +52,9 @@ GEM
     simplecov-html (0.10.2)
     sqlite3 (1.4.1)
     thread_safe (0.3.6)
-    tzinfo (1.2.6)
+    tzinfo (1.2.7)
       thread_safe (~> 0.1)
-    zeitwerk (2.2.2)
+    zeitwerk (2.3.0)
 
 PLATFORMS
   ruby
@@ -63,11 +63,11 @@ DEPENDENCIES
   bundler (~> 2.0)
   database_cleaner
   pry
-  rake (~> 10.0)
+  rake (~> 13.0)
   rspec (~> 3.0)
   simplecov (= 0.17.1)
   sqlite3 (>= 1.3.6)
   tapping_device!
 
 BUNDLED WITH
-   2.0.2
+   2.1.1

data/README.md

@@ -1,406 +1,180 @@
 # TappingDevice
 
-![](https://github.com/st0012/tapping_device/workflows/Ruby/badge.svg)
+![GitHub Action](https://github.com/st0012/tapping_device/workflows/Ruby/badge.svg)
+[![Gem Version](https://badge.fury.io/rb/tapping_device.svg)](https://badge.fury.io/rb/tapping_device)
 [![Maintainability](https://api.codeclimate.com/v1/badges/3e3732a6983785bccdbd/maintainability)](https://codeclimate.com/github/st0012/tapping_device/maintainability)
 [![Test Coverage](https://api.codeclimate.com/v1/badges/3e3732a6983785bccdbd/test_coverage)](https://codeclimate.com/github/st0012/tapping_device/test_coverage)
 [![Open Source Helpers](https://www.codetriage.com/st0012/tapping_device/badges/users.svg)](https://www.codetriage.com/st0012/tapping_device)
 
-## Related Posts
-- [Debug Rails issues effectively with tapping_device](https://dev.to/st0012/debug-rails-issues-effectively-with-tappingdevice-c7c)
-- [Want to know more about your Rails app? Tap on your objects!](https://dev.to/st0012/want-to-know-more-about-your-rails-app-tap-on-your-objects-bd3)
-
-## Table of Content
-- [Introduction](#introduction)
-	- [Track Method Calls](#track-method-calls)
-	- [Track Association Calls](#track-association-calls)
-	- [Track Calls that Generates SQL Queries](#track-calls-that-generates-sql-queries)
-- [Installation](#installation)
-- [Usages](#usages)
-	- Tapping Methods
-		- [tap_init!](#tap_init)
-		- [tap_on!](#tap_on)
-		- [tap_passed!](#tap_passed)
-		- [tap_assoc!](#tap_assoc)
-		- [tap_sql!](#tap_sql)
-	- [Options](#options)
-	- [Payload](#payload-of-the-call)
-	- [Advance Usages](#advance-usages)
 
 ## Introduction
-`tapping_device` is a gem built on top of Ruby’s `TracePoint` class that allows you to tap method calls of specified objects. The purpose for this gem is to make debugging Rails applications easier.  Here are some sample usages:
+`TappingDevice` makes the objects tell you what they do, so you don't need to track them yourself.
 
-### Track Method Calls
+#### Contract Tracing For Objects
 
-```ruby
-class PostsController < ApplicationController
-  include TappingDevice::Trackable
-
-  def show
-    @post = Post.find(params[:id])
-    tap_on!(@post).and_print(:method_name_and_location)
-  end
-end
-```
+The concept is very simple. It's basically like [contact tracing](https://en.wikipedia.org/wiki/Contact_tracing) for your Ruby objects. You can use 
 
-And you can see these in log:
+- `print_calls(object)` to see what the object does
+- `print_traces(object)` to see how the object interacts with other objects (like used as an argument)
 
-```
-name FROM /PROJECT_PATH/sample/app/views/posts/show.html.erb:5
-user_id FROM /PROJECT_PATH/sample/app/views/posts/show.html.erb:10
-to_param FROM /RUBY_PATH/gems/2.6.0/gems/actionpack-5.2.0/lib/action_dispatch/routing/route_set.rb:236
-```
+Still sounds vague? Let's see some examples:
 
-### Track Association Calls
+### `print_calls` To Track Method Calls
 
-Or you can use `tap_assoc!`. This is very useful for tracking potential n+1 query calls, here’s a sample from my work
+In [Discourse](https://github.com/discourse/discourse), it uses the `Guardian` class for authorization (like policy objects). It's barely visible in controller actions, but it does many checks under the hood. Now, let's say we want to know what the `Guadian` would do when a user creates a post; here's the controller action:
 
 ```ruby
-tap_assoc!(order).and_print(:method_name_and_location)
-```
-
-```
-payments FROM /RUBY_PATH/gems/2.6.0/gems/jsonapi-resources-0.9.10/lib/jsonapi/resource.rb:124
-line_items FROM /MY_PROJECT/app/models/line_item_container_helpers.rb:44
-effective_line_items FROM /MY_PROJECT/app/models/line_item_container_helpers.rb:110
-amending_orders FROM /MY_PROJECT/app/models/order.rb:385
-amends_order FROM /MY_PROJECT/app/models/order.rb:432
-```
-
-### Track Calls that Generates SQL Queries
-
-`tap_sql!` method helps you track which method calls generate sql queries. This is particularly helpful when tracking calls created from a reused `ActiveRecord::Relation` object.
-
-```ruby
-class PostsController < ApplicationController
-  def index
-    # simulate current_user
-    @current_user = User.last
-    # reusable ActiveRecord::Relation
-    @posts = Post.all
-
-    tap_sql!(@posts) do |payload|
-      puts("Method: #{payload[:method_name]} generated sql: #{payload[:sql]} from #{payload[:filepath]}:#{payload[:line_number]}")
+  def create
+    @manager_params = create_params
+    @manager_params[:first_post_checks] = !is_api?
+
+    manager = NewPostManager.new(current_user, @manager_params)
+
+    if is_api?
+      memoized_payload = DistributedMemoizer.memoize(signature_for(@manager_params), 120) do
+        result = manager.perform
+        MultiJson.dump(serialize_data(result, NewPostResultSerializer, root: false))
+      end
+
+      parsed_payload = JSON.parse(memoized_payload)
+      backwards_compatible_json(parsed_payload, parsed_payload['success'])
+    else
+      result = manager.perform
+      json = serialize_data(result, NewPostResultSerializer, root: false)
+      backwards_compatible_json(json, result.success?)
     end
   end
-end
-```
-
-```erb
-<h1>Posts (<%= @posts.count %>)</h1>
-......
-  <% @posts.each do |post| %>
-    ......
-  <% end %>
-......
-<p>Posts created by you: <%= @posts.where(user: @current_user).count %></p>
-```
-
-And the output would be
-
-```
-Method: count generated sql: SELECT COUNT(*) FROM "posts" from /PROJECT_PATH/rails-6-sample/app/views/posts/index.html.erb:3
-Method: each generated sql: SELECT "posts".* FROM "posts" from /PROJECT_PATH/rails-6-sample/app/views/posts/index.html.erb:16
-Method: count generated sql: SELECT COUNT(*) FROM "posts" WHERE "posts"."user_id" = ? from /PROJECT_PATH/rails-6-sample/app/views/posts/index.html.erb:31
 ```
 
-However, depending on the size of your application, tapping any object could **harm the performance significantly**. **Don’t use this on production**
+As you can see, it doesn't even exist in the controller action, which makes tracking it by reading code very hard to do.
 
-## Installation
-Add this line to your application’s Gemfile:
+But with `TappingDevice`. You can use `print_calls` to show what method calls the object performs
 
 ```ruby
-gem 'tapping_device', group: :development
+  def create
+    # you can retrieve the current guardian object by calling guardian in the controller
+    print_calls(guardian)
+    @manager_params = create_params
+   
+    # .....
 ```
 
-And then execute:
+Now, if you execute the code, like via tests:
 
-```
-$ bundle
+```shell
+$ rspec spec/requests/posts_controller_spec.rb:603
 ```
 
-Or install it yourself as:
+You can get all the method calls it performs with basically everything you need to know
 
-```
-$ gem install tapping_device
-```
+<img src="https://github.com/st0012/tapping_device/blob/master/images/print_calls.png" alt="image of print_calls output" width="50%">
 
-## Usages
-In order to use `tapping_device`, you need to include `TappingDevice::Trackable` module in where you want to track your code and call the following helpers.
+Let's take a closer look at each entry. Everyone of them contains the method call's
+- method name 
+- method source class/module
+- call site
+- arguments
+- return value
 
-### tap_init!
+![explanation of individual entry](https://github.com/st0012/tapping_device/blob/master/images/print_calls%20-%20single%20entry.png)
 
-`tap_init!(class)` -  tracks a class’ instance initialization
+These are the information you'd have to look up one by one manually (probably with many debug code writing). Now you can get all of them in just one line of code.
 
-```ruby
-calls = []
-tap_init!(Student) do |payload|
-  calls << [payload[:method_name], payload[:arguments]]
-end
 
-Student.new("Stan", 18)
-Student.new("Jane", 23)
+### `print_traces` To See The Object's Traces
 
-puts(calls.to_s) #=> [[:initialize, {:name=>"Stan", :age=>18}], [:initialize, {:name=>"Jane", :age=>23}]]
-```
-
-### tap_on!
-
- `tap_on!(object)` - tracks any calls received by the object
+If you're not interested in what an object does, but what it interacts with other parts of the program, e.g., used as arguments. You can use the `print_traces` helper. Let's see how `Discourse` uses the `manager` object when creating a post
 
 ```ruby
-class PostsController < ApplicationController
-  include TappingDevice::Trackable
+  def create
+    @manager_params = create_params
+    @manager_params[:first_post_checks] = !is_api?
+   
+    manager = NewPostManager.new(current_user, @manager_params)
 
-  before_action :set_post, only: [:show, :edit, :update, :destroy]
-
-  def show
-    tap_on!(@post).and_print(:method_name_and_location)
-  end
-end
+    print_traces(manager)
+    # .....
 ```
 
-And you can see these in log:
-
-```
-name FROM /PROJECT_PATH/sample/app/views/posts/show.html.erb:5
-user_id FROM /PROJECT_PATH/sample/app/views/posts/show.html.erb:10
-to_param FROM /RUBY_PATH/gems/2.6.0/gems/actionpack-5.2.0/lib/action_dispatch/routing/route_set.rb:236
-```
-
-Also check the `track_as_records` option if you want to track `ActiveRecord` records.
-
-### tap_passed!
+And after running the test case
 
-`tap_passed!(target)` tracks method calls that **takes the target as its argument**. This is particularly useful when debugging libraries. It saves your time from jumping between files and check which path the object will go.
-
-```ruby
-class PostsController < ApplicationController
-  include TappingDevice::Trackable
-  # GET /posts/new
-  def new
-    @post = Post.new
-
-    tap_passed!(@post) do |payload|
-      puts(payload.passed_at(with_method_head: true))
-    end
-  end
-end
-```
-
-```
-Passed as 'record' in method ':polymorphic_mapping'
-  > def polymorphic_mapping(record)
-  at /Users/st0012/.rbenv/versions/2.6.3/lib/ruby/gems/2.6.0/gems/actionpack-6.0.0/lib/action_dispatch/routing/polymorphic_routes.rb:131
-Passed as 'klass' in method ':get_method_for_class'
-  > def get_method_for_class(klass)
-  at /Users/st0012/.rbenv/versions/2.6.3/lib/ruby/gems/2.6.0/gems/actionpack-6.0.0/lib/action_dispatch/routing/polymorphic_routes.rb:269
-Passed as 'record' in method ':handle_model'
-  > def handle_model(record)
-  at /Users/st0012/.rbenv/versions/2.6.3/lib/ruby/gems/2.6.0/gems/actionpack-6.0.0/lib/action_dispatch/routing/polymorphic_routes.rb:227
-Passed as 'record_or_hash_or_array' in method ':polymorphic_method'
-  > def self.polymorphic_method(recipient, record_or_hash_or_array, action, type, options)
-  at /Users/st0012/.rbenv/versions/2.6.3/lib/ruby/gems/2.6.0/gems/actionpack-6.0.0/lib/action_dispatch/routing/polymorphic_routes.rb:139
+```shell
+$ rspec spec/requests/posts_controller_spec.rb:603
 ```
 
-### tap_assoc!
+You will see that it performs 2 calls: `perform` and `perform_create_post`. And it's also used as `manager` argument in various of calls of the `NewPostManager` class.
 
-`tap_assoc!(activerecord_object)` tracks association calls on a record, like `post.comments`
+![image of print_traces output](https://github.com/st0012/tapping_device/blob/master/images/print_traces.png)
 
-```ruby
-tap_assoc!(order).and_print(:method_name_and_location)
-```
+**You can try these examples on [my fork of discourse](https://github.com/st0012/discourse/tree/demo-for-tapping-device)**
 
-```
-payments FROM /RUBY_PATH/gems/2.6.0/gems/jsonapi-resources-0.9.10/lib/jsonapi/resource.rb:124
-line_items FROM /MY_PROJECT/app/models/line_item_container_helpers.rb:44
-effective_line_items FROM /MY_PROJECT/app/models/line_item_container_helpers.rb:110
-amending_orders FROM /MY_PROJECT/app/models/order.rb:385
-amends_order FROM /MY_PROJECT/app/models/order.rb:432
-```
 
-### tap_sql!
-
-`tap_sql!(anything_that_generates_sql_queries)` tracks sql queries generated from the target
+## Installation
+Add this line to your application's Gemfile:
 
 ```ruby
-class PostsController < ApplicationController
-  def index
-    # simulate current_user
-    @current_user = User.last
-    # reusable ActiveRecord::Relation
-    @posts = Post.all
-
-    tap_sql!(@posts) do |payload|
-      puts("Method: #{payload[:method_name]} generated sql: #{payload[:sql]} from #{payload[:filepath]}:#{payload[:line_number]}")
-    end
-  end
-end
+gem 'tapping_device', group: :development
 ```
 
-```erb
-<h1>Posts (<%= @posts.count %>)</h1>
-......
-  <% @posts.each do |post| %>
-    ......
-  <% end %>
-......
-<p>Posts created by you: <%= @posts.where(user: @current_user).count %></p>
-```
+And then execute:
 
 ```
-Method: count generated sql: SELECT COUNT(*) FROM "posts" from /PROJECT_PATH/rails-6-sample/app/views/posts/index.html.erb:3
-Method: each generated sql: SELECT "posts".* FROM "posts" from /PROJECT_PATH/rails-6-sample/app/views/posts/index.html.erb:16
-Method: count generated sql: SELECT COUNT(*) FROM "posts" WHERE "posts"."user_id" = ? from /PROJECT_PATH/rails-6-sample/app/views/posts/index.html.erb:31
-```
-
-
-### Options
-#### with_trace_to
-It takes an integer as the number of traces we want to put into `trace`. Default is `nil`, so `trace` would be empty. 
-
-```ruby
-stan = Student.new("Stan", 18)
-tap_on!(stan, with_trace_to: 5)
-
-stan.name
-
-puts(device.calls.first.trace) #=>
-/Users/st0012/projects/tapping_device/spec/tapping_device_spec.rb:287:in `block (4 levels) in <top (required)>'
-/Users/st0012/.rbenv/versions/2.5.1/lib/ruby/gems/2.5.0/gems/rspec-core-3.8.2/lib/rspec/core/example.rb:257:in `instance_exec'
-/Users/st0012/.rbenv/versions/2.5.1/lib/ruby/gems/2.5.0/gems/rspec-core-3.8.2/lib/rspec/core/example.rb:257:in `block in run'
-/Users/st0012/.rbenv/versions/2.5.1/lib/ruby/gems/2.5.0/gems/rspec-core-3.8.2/lib/rspec/core/example.rb:503:in `block in with_around_and_singleton_context_hooks'
-/Users/st0012/.rbenv/versions/2.5.1/lib/ruby/gems/2.5.0/gems/rspec-core-3.8.2/lib/rspec/core/example.rb:460:in `block in with_around_example_hooks'
-/Users/st0012/.rbenv/versions/2.5.1/lib/ruby/gems/2.5.0/gems/rspec-core-3.8.2/lib/rspec/core/hooks.rb:464:in `block in run'
+$ bundle
 ```
 
-#### track_as_records
-It makes the device to track objects as they are ActiveRecord instances. For example:
+Or install it directly:
 
-```ruby
-tap_on!(@post, track_as_records: true)
-post = Post.find(@post.id) # same record but a different object
-post.title #=> this call will be recorded as well
 ```
-
-#### exclude_by_paths
-It takes an array of call path patterns that we want to skip. This could be very helpful when working on large project like Rails applications.
-
-```ruby
-tap_on!(@post, exclude_by_paths: [/active_record/]).and_print(:method_name_and_location)
+$ gem install tapping_device
 ```
 
-```
-_read_attribute FROM  /RUBY_PATH/gems/2.6.0/gems/activerecord-5.2.0/lib/active_record/attribute_methods/read.rb:40
-name FROM  /PROJECT_PATH/sample/app/views/posts/show.html.erb:5
-_read_attribute FROM  /RUBY_PATH/gems/2.6.0/gems/activerecord-5.2.0/lib/active_record/attribute_methods/read.rb:40
-user_id FROM  /PROJECT_PATH/sample/app/views/posts/show.html.erb:10
-.......
+**Depending on the size of your application, `TappingDevice` could harm the performance significantly.  So make sure you don't put it inside the production group**
 
-# versus
 
-name FROM  /PROJECT_PATH/sample/app/views/posts/show.html.erb:5
-user_id FROM  /PROJECT_PATH/sample/app/views/posts/show.html.erb:10
-to_param FROM  /RUBY_PATH/gems/2.6.0/gems/actionpack-5.2.0/lib/action_dispatch/routing/route_set.rb:236
-```
+### Advance Usages & Options 
 
-#### filter_by_paths
-
-Like `exclude_by_paths`, but work in an opposite way.
-
-
-### Payload of The Call
-All tapping methods (start with `tap_`) takes a block and yield a `Payload` object as block argument. It responds to
-
-- `target` - the target for `tap_x` call
-- `receiver` - the receiver object
-- `method_name` - method’s name (symbol) 
-	- e.g. `:name`
-- `method_object` - the method object that’s being called. It might be `nil` in some edge cases.
-- `arguments` - arguments of the method call
-	- e.g. `{name: “Stan”, age: 25}`
-- `return_value` - return value of the method call
-- `filepath` - path to the file that performs the method call
-- `line_number` 
-- `defined_class` - in which class that defines the method being called
-- `trace` - stack trace of the call. Default is an empty array unless `with_trace_to` option is set
-- `sql` - sql that generated from the call (only present in `tap_sql!` payloads)
-- `tp` - trace point object of this call
-
-
-#### Symbols for Payload Helpers
-- `FROM` for method call’s location
-- `<=` for arguments
-- `=>` for return value
-- `@` for defined class
-
-#### Payload Helpers
-- `method_name_and_location` - `initialize FROM /PROJECT_PATH/tapping_device/spec/payload_spec.rb:7`
-- `method_name_and_arguments` - `initialize <= {:name=>\"Stan\", :age=>25}`
-- `method_name_and_return_value` - `ten => 10`
-- `method_name_and_defined_class` - `initialize @ Student`
-- `passed_at` - 
-```
-Passed as 'object' in method ':initialize'
-  at /Users/st0012/.rbenv/versions/2.6.3/lib/ruby/gems/2.6.0/gems/actionview-6.0.0/lib/action_view/helpers/tags/label.rb:60
-```
+#### Add Conditions With `.with`
 
-You can also set `passed_at(with_method_head: true)` to see the method’s head
+Sometimes we don't need to know all the calls or traces of an object; we just want some of them. In those cases, we can chain the helpers with `.with` to filter the calls/traces.
 
-```
-Passed as 'object' in method ':initialize'
-  > def initialize(template_object, object_name, method_name, object, tag_value)
-  at /Users/st0012/.rbenv/versions/2.6.3/lib/ruby/gems/2.6.0/gems/actionview-6.0.0/lib/action_view/helpers/tags/label.rb:60
+```ruby
+# only prints calls with name matches /foo/
+print_calls(object).with do |payload|
+  payload.method_name.to_s.match?(/foo/)
+end
 ```
 
-- `detail_call_info` 
-
-```
-initialize @ Student
-  <= {:name=>"Stan", :age=>25}
-  => 25
-  FROM /Users/st0012/projects/tapping_device/spec/payload_spec.rb:7
-```
+#### `colorize: false`
 
-### Advance Usages
+By default `print_calls` and `print_traces` colorize their output. If you don't want the colors, you can use `colorize: false` to disable it.
 
-Tapping methods introduced above like `tap_on!` are designed for simple use cases. They’re actually short for
 
 ```ruby
-device = TappingDevice.new { # tapping action }
-device.tap_on!(object)
+print_calls(object, colorize: false)
 ```
 
-And if you want to do some more configurations like stopping them manually or setting stop condition, you must have a `TappingDevie` instance. You can either get them like the above code, or save the return value of `tap_*!` method calls.
 
-#### Stop tapping
+#### `inspect: true`
 
-Once you have a `TappingDevice` instance in hand, you will be able to stop the tapping by
-1. Manually calling `device.stop!`
-2. Setting stop condition with `device.stop_when`, like
+As you might have noticed, all the objects are converted into strings with `#to_s` instead of `#inspect`.  This is because when used on some Rails objects, `#inspect` can generate a significantly larger string than `#to_s`. For example:
 
-```ruby
-device.stop_when do |payload|
-  device.calls.count >= 10 # stop after gathering 10 calls’ data
-end
+``` ruby
+post.to_s #=> #<Post:0x00007f89a55201d0>
+post.inspect #=> #<Post id: 649, user_id: 3, topic_id: 600, post_number: 1, raw: "Hello world", cooked: "<p>Hello world</p>", created_at: "2020-05-24 08:07:29", updated_at: "2020-05-24 08:07:29", reply_to_post_number: nil, reply_count: 0, quote_count: 0, deleted_at: nil, off_topic_count: 0, like_count: 0, incoming_link_count: 0, bookmark_count: 0, score: nil, reads: 0, post_type: 1, sort_order: 1, last_editor_id: 3, hidden: false, hidden_reason_id: nil, notify_moderators_count: 0, spam_count: 0, illegal_count: 0, inappropriate_count: 0, last_version_at: "2020-05-24 08:07:29", user_deleted: false, reply_to_user_id: nil, percent_rank: 1.0, notify_user_count: 0, like_score: 0, deleted_by_id: nil, edit_reason: nil, word_count: 2, version: 1, cook_method: 1, wiki: false, baked_at: "2020-05-24 08:07:29", baked_version: 2, hidden_at: nil, self_edits: 0, reply_quoted: false, via_email: false, raw_email: nil, public_version: 1, action_code: nil, image_url: nil, locked_by_id: nil, image_upload_id: nil>
 ```
 
-#### Device states & Managing Devices
 
-Each `TappingDevice` instance can have 3 states:
+### Lower-Level Helpers
+`print_calls` and `print_traces` aren't the only helpers you can get from `TappingDevice`. They are actually built on top of other helpers, which you can use as well. To know more about them, please check [this page](https://github.com/st0012/tapping_device/wiki/Advance-Usages)
 
-- `Initial` - means the instance is initialized but hasn’t tapped on anything.
-- `Enabled` - means the instance are tapping on something (has called `tap_*` methods).
-- `Disabled` - means the instance has been disabled. It will no longer receive any call info.
 
-When debugging, we may create many device instances and tap objects in several places. Then it’ll be quite annoying to manage their states. So `TappingDevice` has several class methods that allows you to manage all `TappingDevice` instances:
+### Related Blog Posts
+- [Optimize Your Debugging Process With Object-Oriented Tracing and tapping_device](http://bit.ly/object-oriented-tracing) 
+- [Debug Rails issues effectively with tapping_device](https://dev.to/st0012/debug-rails-issues-effectively-with-tappingdevice-c7c)
+- [Want to know more about your Rails app? Tap on your objects!](https://dev.to/st0012/want-to-know-more-about-your-rails-app-tap-on-your-objects-bd3)
 
-- `TappingDevice.devices` - Lists all registered devices with `initial` or `enabled` state. Note that any instance that’s been stopped  will be removed from the list.
-- `TappingDevice.stop_all!` - Stops all registered devices and remove them from the `devices` list.
-- `TappingDevice.suspend_new!` - Suspends any device instance from changing their state from `initatial` to `enabled`. Which means any  `tap_*` calls after it will no longer work. 
-- `TappingDevice.reset!` - Cancels `suspend_new` (if called) and stops/removes all created devices. Useful to reset environment between test cases.
 
 ## Development
-
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
 
 To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
@@ -411,8 +185,8 @@ Bug reports and pull requests are welcome on GitHub at https://github.com/st0012
 
 ## License
 
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+The gem is available as open-source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
 
 ## Code of Conduct
 
-Everyone interacting in the TappingDevice project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/[USERNAME]/tapping_device/blob/master/CODE_OF_CONDUCT.md).
+Everyone interacting in the TappingDevice project's codebases, issue trackers, chat rooms, and mailing lists is expected to follow the [code of conduct](https://github.com/[USERNAME]/tapping_device/blob/master/CODE_OF_CONDUCT.md).

data/lib/tapping_device.rb

@@ -2,6 +2,7 @@ require "active_record"
 require "tapping_device/version"
 require "tapping_device/manageable"
 require "tapping_device/payload"
+require "tapping_device/output_payload"
 require "tapping_device/trackable"
 require "tapping_device/exceptions"
 require "tapping_device/sql_tapping_methods"
@@ -25,12 +26,16 @@ class TappingDevice
     @options = process_options(options)
     @calls = []
     @disabled = false
+    @with_condition = nil
     self.class.devices << self
   end
 
   def tap_init!(klass)
     raise "argument should be a class, got #{klass}" unless klass.is_a?(Class)
-    track(klass, condition: :tap_init?)
+    track(klass, condition: :tap_init?) do |payload|
+      payload[:return_value] = payload[:receiver]
+      payload[:receiver] = klass
+    end
   end
 
   def tap_on!(object)
@@ -46,8 +51,21 @@ class TappingDevice
     track(record, condition: :tap_associations?)
   end
 
-  def and_print(payload_method)
-    @output_block = -> (payload) { puts(payload.send(payload_method)) }
+  def and_print(payload_method = nil, &block)
+    @output_block =
+      if block
+        -> (output_payload) { puts(block.call(output_payload)) }
+      elsif payload_method
+        -> (output_payload) { puts(output_payload.send(payload_method)) }
+      else
+        raise "need to provide either a payload method name or a block"
+      end
+
+    self
+  end
+
+  def with(&block)
+    @with_condition = block
   end
 
   def set_block(&block)
@@ -81,15 +99,17 @@ class TappingDevice
 
   private
 
-  def track(object, condition:)
+  def track(object, condition:, &payload_block)
     @target = object
-    @trace_point = TracePoint.new(:return) do |tp|
+    @trace_point = TracePoint.new(options[:event_type]) do |tp|
       if send(condition, object, tp)
         filepath, line_number = get_call_location(tp)
 
         next if should_be_skipped_by_paths?(filepath)
 
-        payload = build_payload(tp: tp, filepath: filepath, line_number: line_number)
+        payload = build_payload(tp: tp, filepath: filepath, line_number: line_number, &payload_block)
+
+        next unless with_condition_satisfied?(payload)
 
         record_call!(payload)
 
@@ -130,15 +150,12 @@ class TappingDevice
   end
 
   def build_payload(tp:, filepath:, line_number:)
-    arguments = {}
-    tp.binding.local_variables.each { |name| arguments[name] = tp.binding.local_variable_get(name) }
-
-    Payload.init({
+    payload = Payload.init({
       target: @target,
       receiver: tp.self,
       method_name: tp.callee_id,
       method_object: get_method_object_from(tp.self, tp.callee_id),
-      arguments: arguments,
+      arguments: collect_arguments(tp),
       return_value: (tp.return_value rescue nil),
       filepath: filepath,
       line_number: line_number,
@@ -146,6 +163,10 @@ class TappingDevice
       trace: get_traces(tp),
       tp: tp
     })
+
+    yield(payload) if block_given?
+
+    payload
   end
 
   def tap_init?(klass, tp)
@@ -176,15 +197,7 @@ class TappingDevice
     return false if is_from_target?(self, tp)
     return false if tp.defined_class == TappingDevice::Trackable || tp.defined_class == TappingDevice
 
-    method_object = get_method_object_from(tp.self, tp.callee_id)
-    return false unless method_object.is_a?(Method)
-    # if a no-arugment method is called, tp.binding.local_variables will be those local variables in the same scope
-    # so we need to make sure the method takes arguments, then we can be sure that the locals are arguments
-    return false unless method_object && method_object.arity.to_i > 0
-
-    argument_values = tp.binding.local_variables.map { |name| tp.binding.local_variable_get(name) }
-
-    argument_values.any? do |value|
+    collect_arguments(tp).values.any? do |value|
       # during comparison, Ruby might perform data type conversion like calling `to_sym` on the value
       # but not every value supports every conversion methods
       object == value rescue false
@@ -204,11 +217,25 @@ class TappingDevice
     nil
   end
 
+  def collect_arguments(tp)
+    parameters =
+      if RUBY_VERSION.to_f >= 2.6
+        tp.parameters
+      else
+        get_method_object_from(tp.self, tp.callee_id)&.parameters || []
+      end.map { |parameter| parameter[1] }
+
+    tp.binding.local_variables.each_with_object({}) do |name, args|
+      args[name] = tp.binding.local_variable_get(name) if parameters.include?(name)
+    end
+  end
+
   def process_options(options)
     options[:filter_by_paths] ||= []
     options[:exclude_by_paths] ||= []
     options[:with_trace_to] ||= 50
     options[:root_device] ||= self
+    options[:event_type] ||= :return
     options[:descendants] ||= []
     options[:track_as_records] ||= false
     options
@@ -237,7 +264,7 @@ class TappingDevice
   def record_call!(payload)
     return if @disabled
 
-    @output_block.call(payload) if @output_block
+    @output_block.call(OutputPayload.init(payload)) if @output_block
 
     if @block
       root_device.calls << @block.call(payload)
@@ -245,4 +272,8 @@ class TappingDevice
       root_device.calls << payload
     end
   end
+
+  def with_condition_satisfied?(payload)
+    @with_condition.blank? || @with_condition.call(payload)
+  end
 end

data/lib/tapping_device/output_payload.rb

@@ -0,0 +1,145 @@
+class TappingDevice
+  class OutputPayload < Payload
+    alias :raw_arguments :arguments
+    alias :raw_return_value :return_value
+
+    def method_name(options = {})
+      ":#{super(options)}"
+    end
+
+    def arguments(options = {})
+      generate_string_result(raw_arguments, options[:inspect])
+    end
+
+    def return_value(options = {})
+      generate_string_result(raw_return_value, options[:inspect])
+    end
+
+    def self.full_color_code(code)
+    end
+
+    COLOR_CODES = {
+      green: 10,
+      yellow: 11,
+      blue: 12,
+      megenta: 13,
+      cyan: 14,
+      orange: 214
+    }
+
+    COLORS = COLOR_CODES.each_with_object({}) do |(name, code), hash|
+      hash[name] = "\u001b[38;5;#{code}m"
+    end.merge(
+      reset: "\u001b[0m",
+      nocolor: ""
+    )
+
+    PAYLOAD_ATTRIBUTES = {
+      method_name: {symbol: "", color: COLORS[:blue]},
+      location: {symbol: "from:", color: COLORS[:green]},
+      sql: {symbol: "QUERIES", color: COLORS[:nocolor]},
+      return_value: {symbol: "=>", color: COLORS[:megenta]},
+      arguments: {symbol: "<=", color: COLORS[:orange]},
+      defined_class: {symbol: "#", color: COLORS[:yellow]}
+    }
+
+    PAYLOAD_ATTRIBUTES.each do |attribute, attribute_options|
+      color = attribute_options[:color]
+
+      alias_method "original_#{attribute}".to_sym, attribute
+
+      # regenerate attributes with `colorize: true` support
+      define_method attribute do |options = {}|
+        call_result = send("original_#{attribute}", options)
+
+        if options[:colorize]
+          "#{color}#{call_result}#{COLORS[:reset]}"
+        else
+          call_result
+        end
+      end
+
+      define_method "#{attribute}_with_color" do |options = {}|
+        send(attribute, options.merge(colorize: true))
+      end
+
+      PAYLOAD_ATTRIBUTES.each do |and_attribute, and_attribute_options|
+        next if and_attribute == attribute
+
+        define_method "#{attribute}_and_#{and_attribute}" do |options = {}|
+          "#{send(attribute, options)} #{and_attribute_options[:symbol]} #{send(and_attribute, options)}"
+        end
+
+        define_method "#{attribute}_and_#{and_attribute}_with_color" do |options = {}|
+          send("#{attribute}_and_#{and_attribute}", options.merge(colorize: true))
+        end
+      end
+    end
+
+    def passed_at(options = {})
+      with_method_head = options.fetch(:with_method_head, false)
+      arg_name = raw_arguments.keys.detect { |k| raw_arguments[k] == target }
+
+      return unless arg_name
+
+      arg_name = ":#{arg_name}"
+      arg_name = value_with_color(arg_name, :orange) if options[:colorize]
+      msg = "Passed as #{arg_name} in '#{defined_class(options)}##{method_name(options)}' at #{location(options)}"
+      msg += "\n  > #{method_head.strip}" if with_method_head
+      msg
+    end
+
+    def detail_call_info(options = {})
+      <<~MSG
+      #{method_name_and_defined_class(options)}
+          from: #{location(options)}
+          <= #{arguments(options)}
+          => #{return_value(options)}
+
+      MSG
+    end
+
+    private
+
+    def value_with_color(value, color)
+      "#{COLORS[color]}#{value}#{COLORS[:reset]}"
+    end
+
+    def generate_string_result(obj, inspect)
+      case obj
+      when Array
+        array_to_string(obj, inspect)
+      when Hash
+        hash_to_string(obj, inspect)
+      when String
+        "\"#{obj}\""
+      else
+        inspect ? obj.inspect : obj.to_s
+      end
+    end
+
+    def array_to_string(array, inspect)
+      elements_string = array.map do |elem|
+        generate_string_result(elem, inspect)
+      end.join(", ")
+      "[#{elements_string}]"
+    end
+
+    def hash_to_string(hash, inspect)
+      elements_string = hash.map do |key, value|
+        "#{key.to_s}: #{generate_string_result(value, inspect)}"
+      end.join(", ")
+      "{#{elements_string}}"
+    end
+
+    def obj_to_string(element, inspect)
+      to_string_method = inspect ? :inspect : :to_s
+
+      if !inspect && element.is_a?(String)
+        "\"#{element}\""
+      else
+        element.send(to_string_method)
+      end
+    end
+  end
+end

data/lib/tapping_device/payload.rb

@@ -6,7 +6,7 @@ class TappingDevice
     ]
 
     ATTRS.each do |attr|
-      define_method attr do
+      define_method attr do |options = {}|
         self[attr]
       end
     end
@@ -19,45 +19,13 @@ class TappingDevice
       h
     end
 
-    def passed_at(with_method_head: false)
-      arg_name = arguments.keys.detect { |k| arguments[k] == target }
-      return unless arg_name
-      msg = "Passed as '#{arg_name}' in method ':#{method_name}'"
-      msg += "\n  > #{method_head.strip}" if with_method_head
-      msg += "\n  at #{location}"
-      msg
-    end
-
     def method_head
       source_file, source_line = method_object.source_location
       IO.readlines(source_file)[source_line-1]
     end
 
-    def location
+    def location(options = {})
       "#{filepath}:#{line_number}"
     end
-
-    SYMBOLS = {
-      location: "FROM",
-      sql: "QUERIES",
-      return_value: "=>",
-      arguments: "<=",
-      defined_class: "@"
-    }
-
-    SYMBOLS.each do |name, symbol|
-      define_method "method_name_and_#{name}" do
-        "#{method_name} #{symbol} #{send(name)}"
-      end
-    end
-
-    def detail_call_info
-      <<~MSG
-      #{method_name_and_defined_class}
-        <= #{arguments}
-        => #{return_value || "nil"}
-        FROM #{location}
-      MSG
-    end
   end
 end

data/lib/tapping_device/trackable.rb

@@ -6,8 +6,33 @@ class TappingDevice
       end
     end
 
+    def print_traces(target, options = {})
+      options[:event_type] = :call
+      inspect = options.delete(:inspect)
+      colorize = options.fetch(:colorize, true)
+
+      device_1 = tap_on!(target, options).and_print do |output_payload|
+        "Called #{output_payload.method_name_and_location(inspect: inspect, colorize: colorize)}"
+      end
+      device_2 = tap_passed!(target, options).and_print do |output_payload|
+        output_payload.passed_at(inspect: inspect, colorize: colorize)
+      end
+      [device_1, device_2]
+    end
+
+    def print_calls(target, options = {})
+      inspect = options.delete(:inspect)
+      colorize = options.fetch(:colorize, true)
+
+      tap_on!(target, options).and_print do |output_payload|
+        output_payload.detail_call_info(inspect: inspect, colorize: colorize)
+      end
+    end
+
     def new_device(options, &block)
       TappingDevice.new(options, &block)
     end
   end
 end
+
+include TappingDevice::Trackable

data/lib/tapping_device/version.rb

@@ -1,3 +1,3 @@
 class TappingDevice
-  VERSION = "0.4.7"
+  VERSION = "0.5.0"
 end

data/tapping_device.gemspec

@@ -8,8 +8,8 @@ Gem::Specification.new do |spec|
   spec.authors       = ["st0012"]
   spec.email         = ["stan001212@gmail.com"]
 
-  spec.summary       = %q{tapping_device provides useful helpers to intercept method calls}
-  spec.description   = %q{tapping_device provides useful helpers to intercept method calls}
+  spec.summary       = %q{tapping_device lets you understand what your Ruby objects do without digging into the code}
+  spec.description   = %q{tapping_device lets you understand what your Ruby objects do without digging into the code} 
   spec.homepage      = "https://github.com/st0012/tapping_device"
   spec.license       = "MIT"
 
@@ -36,7 +36,7 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency "database_cleaner"
   spec.add_development_dependency "bundler", "~> 2.0"
   spec.add_development_dependency "pry"
-  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "rake", "~> 13.0"
   spec.add_development_dependency "rspec", "~> 3.0"
   spec.add_development_dependency "simplecov", "0.17.1"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: tapping_device
 version: !ruby/object:Gem::Version
-  version: 0.4.7
+  version: 0.5.0
 platform: ruby
 authors:
 - st0012
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2019-12-29 00:00:00.000000000 Z
+date: 2020-05-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -86,14 +86,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '10.0'
+        version: '13.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '10.0'
+        version: '13.0'
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
@@ -122,17 +122,20 @@ dependencies:
     - - '='
       - !ruby/object:Gem::Version
         version: 0.17.1
-description: tapping_device provides useful helpers to intercept method calls
+description: tapping_device lets you understand what your Ruby objects do without
+  digging into the code
 email:
 - stan001212@gmail.com
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".DS_Store"
 - ".github/workflows/gempush.yml"
 - ".github/workflows/ruby.yml"
 - ".gitignore"
 - ".rspec"
+- ".ruby-version"
 - ".travis.yml"
 - CODE_OF_CONDUCT.md
 - Gemfile
@@ -142,9 +145,13 @@ files:
 - Rakefile
 - bin/console
 - bin/setup
+- images/print_calls - single entry.png
+- images/print_calls.png
+- images/print_traces.png
 - lib/tapping_device.rb
 - lib/tapping_device/exceptions.rb
 - lib/tapping_device/manageable.rb
+- lib/tapping_device/output_payload.rb
 - lib/tapping_device/payload.rb
 - lib/tapping_device/sql_tapping_methods.rb
 - lib/tapping_device/trackable.rb
@@ -175,5 +182,6 @@ requirements: []
 rubygems_version: 3.0.3
 signing_key: 
 specification_version: 4
-summary: tapping_device provides useful helpers to intercept method calls
+summary: tapping_device lets you understand what your Ruby objects do without digging
+  into the code
 test_files: []