puts_debuggerer 0.6.1 → 0.8.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 23082ac8b052016747f52fc3ed37c17ee1f9c8d1
-  data.tar.gz: 8dd8dd68fabe0aaef0c6ba78912688cfa2160897
+SHA256:
+  metadata.gz: 8b80118305f3b8201241cb75a16fab616e1db9789daf829c5b4ea68ad7a6d94d
+  data.tar.gz: dd345085a3bcbf718cdb49983b3c2d1838b1914b231e6fc033ff30ea992fac32
 SHA512:
-  metadata.gz: 2b798fcdf87f121abda0664bbf190fb2de2ba258eb431dfd7a287061aaa03dc408e7101c5d96ceaa725a31294324eb68cb36fdeb44165b13abd434f296e1b12d
-  data.tar.gz: c884b97e883fb7b5e85c4e0a094dc87a463df2a4a7efef72b34fd7110d4358bbb5ff5ed7402895c79e4a6f3f6bdf47f4a98c78364779723508d4a521f8ee35a3
+  metadata.gz: 1ac9056936792d4f8c46e4ae4114b0911a6442ef5b6ee5a6a1aebd6e405c3abc37466d207f19e94c6eaf9bd58374cd30ab2f66581777b9e37b2f572953c9261a
+  data.tar.gz: 7e0bbb0fcb9c502a252227b74a68a91d39f8ecbbf5cf85a18c4f561dae0a71baa5d258680835c573d2c5f6555e142f1b911f6a3c94302022cbd3a3ac4caeda01

data/README.md

@@ -1,22 +1,127 @@
-# puts_debuggerer v0.6.0
+# Puts Debuggerer (debugger-less debugging FTW)
 [![Gem Version](https://badge.fury.io/rb/puts_debuggerer.svg)](http://badge.fury.io/rb/puts_debuggerer)
 [![Build Status](https://travis-ci.org/AndyObtiva/puts_debuggerer.svg?branch=master)](https://travis-ci.org/AndyObtiva/puts_debuggerer)
 [![Coverage Status](https://coveralls.io/repos/github/AndyObtiva/puts_debuggerer/badge.svg?branch=master)](https://coveralls.io/github/AndyObtiva/puts_debuggerer?branch=master)
 
-Yes, many of us avoid debuggers like the plague and clamp on to our puts
-statements like an umbrella in a stormy day.
-Why not make it official and have puts debugging become its own perfectly
-legitimate thing?!!
+Debuggers are great! They help us troubleshoot complicated programming problems by inspecting values produced by code, line by line. They are invaluable when trying to understand what is going on in a large application composed of thousands or millions of lines of code.
 
-Enter puts_debuggerer. A guilt-free puts debugger Ruby gem FTW!
+In day-to-day test-driven development and simple debugging though, a puts statement can be a lot quicker in revealing what is going on than halting execution completely just to inspect a single value or a few. This is certainly true when writing the simplest possible code that could possibly work, and running a test every few seconds or minutes. Problem is you need to locate puts statements in large output logs, know which methods were invoked, find out what variable names are being printed, and see nicely formatted output. Enter puts_debuggerer. A guilt-free puts debugging Ruby gem FTW that prints file names, line numbers, code statements, and formats output nicely courtesy of awesome_print.
 
-In other words, puts_debuggerer is a Ruby library that provides improved puts debugging, automatically displaying bonus useful information such as source line numbers and source code, among many other goodies (mentioned in the README.)
+Basic Example:
 
-Partially inspired (only partially ;) by this blog post:
+```ruby
+# /Users/User/trivia_app.rb      # line 1
+require 'puts_debuggerer'        # line 2
+bug_or_band = 'beattle'          # line 3
+pd bug_or_band                   # line 4
+```
+
+Output:
+
+```bash
+[PD] trivia_app.rb:4
+   > pd bug_or_band                   # line 4
+  => "beattle"
+```
+
+## Background
+
+For initial background, please read this blog post by Aaron Patterson (part of the inspiration for this gem):
 https://tenderlovemaking.com/2016/02/05/i-am-a-puts-debuggerer.html
-(Credit to Tenderlove.)
 
-Love PD?! Why not promote with [merchandise](https://www.zazzle.com/i+heart+pd+gifts)?
+It can be quite frustrating to lose puts statements in a large output or log file. One way to help find them is add a header (e.g. `puts "The Order Total"`) or an announcer (e.g. `puts '*'*80`) before every puts statement. Unfortunately, that leads to repetitive wasteful effort that adds up quickly over many work sessions and interrupts thinking flow while solving problems.
+
+puts_debuggerer automates that work via the short and simple `pd` command, automatically printing meaningful headers for output and accelerating problem solving work due to ease of typing.
+
+Example without pd:
+
+```ruby
+puts order_total
+```
+
+Output:
+```
+195.50
+```
+
+Which gets lost in a logging stream such as:
+
+```
+   (2.7ms)  CREATE TABLE "ar_internal_metadata" ("key" character varying PRIMARY KEY, "value" character varying, "created_at" timestamp NOT NULL, "updated_at" timestamp NOT NULL)
+  ActiveRecord::InternalMetadata Load (0.4ms)  SELECT  "ar_internal_metadata".* FROM "ar_internal_metadata" WHERE "ar_internal_metadata"."key" = $1 LIMIT $2  [["key", :environment], ["LIMIT", 1]]
+   (0.2ms)  BEGIN
+  SQL (0.3ms)  INSERT INTO "ar_internal_metadata" ("key", "value", "created_at", "updated_at") VALUES ($1, $2, $3, $4) RETURNING "key"  [["key", "environment"], ["value", "development"], ["created_at", 2017-08-24 22:56:52 UTC], ["updated_at", 2017-08-24 22:56:52 UTC]]
+   (0.3ms)  COMMIT
+   195.50
+  ActiveRecord::InternalMetadata Load (0.3ms)  SELECT  "ar_internal_metadata".* FROM "ar_internal_metadata" WHERE "ar_internal_metadata"."key" = $1 LIMIT $2  [["key", :environment], ["LIMIT", 1]]
+   (0.2ms)  BEGIN
+   (0.2ms)  COMMIT
+```
+
+Problem can be mitigated by adding a few more puts statements:
+
+```ruby
+puts "*"*40
+puts "order_total"
+puts order_total
+```
+
+But those add up pretty quickly when inspecting multiple variables:
+
+```ruby
+puts "*"*40
+puts "order_total"
+puts order_total
+puts "*"*40
+puts "order_summary"
+puts order_summary
+puts "*"*40
+puts "order_details"
+puts order_details
+```
+
+Here is a simple example using `pd` instead:
+
+```ruby
+pd order_total
+```
+
+Output:
+
+```
+[PD] /Users/User/ordering/order.rb:39
+  > pd order_total  
+ => 195.50
+```
+
+This is not only easy to locate in a logging stream such as the one below, but also includes the `order_total` variable for easy findability among other pd statements.
+
+```
+   (2.7ms)  CREATE TABLE "ar_internal_metadata" ("key" character varying PRIMARY KEY, "value" character varying, "created_at" timestamp NOT NULL, "updated_at" timestamp NOT NULL)
+  ActiveRecord::InternalMetadata Load (0.4ms)  SELECT  "ar_internal_metadata".* FROM "ar_internal_metadata" WHERE "ar_internal_metadata"."key" = $1 LIMIT $2  [["key", :environment], ["LIMIT", 1]]
+[PD] /Users/User/ordering/order.rb:39
+  > pd order_total  
+ => 195.50
+   (0.2ms)  BEGIN
+  SQL (0.3ms)  INSERT INTO "ar_internal_metadata" ("key", "value", "created_at", "updated_at") VALUES ($1, $2, $3, $4) RETURNING "key"  [["key", "environment"], ["value", "development"], ["created_at", 2017-08-24 22:56:52 UTC], ["updated_at", 2017-08-24 22:56:52 UTC]]
+   (0.3ms)  COMMIT
+[PD] /Users/User/ordering/order.rb:72
+  > pd order_subtotal  
+ => 181.00
+  ActiveRecord::InternalMetadata Load (0.3ms)  SELECT  "ar_internal_metadata".* FROM "ar_internal_metadata" WHERE "ar_internal_metadata"."key" = $1 LIMIT $2  [["key", :environment], ["LIMIT", 1]]
+   (0.2ms)  BEGIN
+   (0.2ms)  COMMIT
+```
+
+And it is easy to search for using the `[PD]` announcer (customizable).
+
+When inspecting multiple variables, debugging code is still a snap:
+
+```ruby
+pd order_total
+pd order_summary
+pd order_details
+```
 
 ## Instructions
 
@@ -25,7 +130,7 @@ Love PD?! Why not promote with [merchandise](https://www.zazzle.com/i+heart+pd+g
 Add the following to bundler's `Gemfile`.
 
 ```ruby
-gem 'puts_debuggerer', '~> 0.6.0'
+gem 'puts_debuggerer', '~> 0.8.2'
 ```
 
 This is the recommended way for [Rails](rubyonrails.org) apps. Optionally, you may create an initializer under `config/initializers` named `puts_debuggerer_options.rb` to enable further customizations as per the [Options](#options) section below.
@@ -35,20 +140,29 @@ This is the recommended way for [Rails](rubyonrails.org) apps. Optionally, you m
 Or manually install and require library.
 
 ```bash
-gem install puts_debuggerer -v0.6.0
+gem install puts_debuggerer -v0.8.2
 ```
 
 ```ruby
 require 'puts_debuggerer'
 ```
 
-### Usage
+### Awesome Print
 
-Simply invoke global `pd` method anywhere in your code passing an object or an expression argument.
+puts_debuggerer comes with [awesome_print](https://github.com/awesome-print/awesome_print).
 
-It will then provide helpful debugging information by printing the source file, line number, and source code in addition to output (works even in IRB).
+You may disable when needed by not requiring in Ruby or by adding an explicit reference to awesome_print with `require: false` in bundler:
 
-Example Code:
+```ruby
+gem "awesome_print", require: false
+gem "puts_debugger"
+```
+
+### Usage
+
+First, add `pd` method anywhere in your code to display details about an object or expression (if you're used to awesome_print, you're in luck! puts_debuggerer includes awesome_print as the default print engine for output).
+
+Example:
 
 ```ruby
 # /Users/User/finance_calculator_app/pd_test.rb           # line 1
@@ -57,7 +171,7 @@ pd "Show me the source of the bug: #{bug}"                # line 3
 pd "Show me the result of the calculation: #{(12.0/3.0)}" # line 4
 ```
 
-Example Printout:
+Output:
 
 ```bash
 [PD] /Users/User/finance_calculator_app/pd_test.rb:3
@@ -68,17 +182,18 @@ Example Printout:
   => "Show me the result of the calculation: 4.0"
 ```
 
-Quickly locate printed lines using Find feature (e.g. CTRL+F) by looking for:
+In addition to the main object/expression output, you get to see the source file name, line number, and source code to help you debug and troubleshoot problems quicker (it even works in IRB).
+
+Second, quickly locate printed lines using the Find feature (e.g. CTRL+F) by looking for:
 * [PD]
 * file:line_number
 * known ruby expression.
 
-This gives you the added benefit of easily removing your `pd` statements later
-on once done debugging.
+Third, easily remove your ` pd ` statements via the source code Find feature once done debugging.
 
 Note that `pd` returns the passed in object or expression argument unchanged, permitting debugging with shorter syntax than tap, and supporting chaining of extra method invocations afterward.
 
-Example Code:
+Example:
 
 ```ruby
 # /Users/User/greeting_app/pd_test.rb                     # line 1
@@ -86,7 +201,7 @@ name = 'Robert'                                           # line 2
 greeting = "Hello #{pd(name)}"                            # line 3
 ```
 
-Example Printout:
+Output:
 
 ```bash
 [PD] /Users/User/greeting_app/pd_test.rb:3
@@ -216,20 +331,56 @@ Prints out:
 ********************************************************************************
 ```
 
+#### `PutsDebuggerer.printer`
+(default = `:puts`)
+
+Printer is a global method symbol or lambda expression to use in printing to the user.
+Examples of global methods are `:puts` and `:print`.
+An example of a lambda expression is `lambda {|output| Rails.logger.info(output)}`
+
+Defaults to `:puts`
+In Rails, it defaults to:
+```ruby
+lambda do |output|
+  puts output if Rails.env.test?
+  Rails.logger.debug(output)
+end
+```
+
+Example:
+
+```ruby
+# File Name: /Users/User/example.rb
+PutsDebuggerer.printer = lambda {|output| Rails.logger.error(output)}
+str = "Hello"
+pd str
+```
+
+Prints out in the Rails app log as error lines:
+
+```bash
+[PD] /Users/User/example.rb:5
+   > pd str
+  => Hello
+```
+
 #### `PutsDebuggerer.print_engine`
-(default = `:p`)
+(default = `:ap`)
 
-Print engine is a global method symbol or lambda expression to use in object printout. Examples of global methods are `:p`, `:ap`, and `:pp`. An example of a lambda expression is `lambda {|o| Rails.logger.info(o)}`
+Print engine is similar to `printer`, except it is focused on the scope of formatting
+the data object being printed (excluding metadata such as file name, line number,
+and expression, which are handled by the `printer`).
+As such, it is also a global method symbol or lambda expression.
+Examples of global methods are `:p`, `:ap`, and `:pp`.
+An example of a lambda expression is `lambda {|object| puts object.to_a.join(" | ")}`
 
-Defaults to Ruby's built-in `p` method identified by the symbol `:p`.
-If it finds [awesome_print](https://github.com/awesome-print/awesome_print) loaded, it defaults to `ap` as `:ap` instead. Also, if it finds Rails loaded without ap, it relies on `lambda {|o| Rails.logger.debug(o)}` as the print engine. Otherwise if both Rails and [awesome_print](https://github.com/awesome-print/awesome_print) are loaded, then it relies on `lambda {|o| Rails.logger.ap(o)}` instead
+Defaults to [awesome_print](https://github.com/awesome-print/awesome_print).
 
 Example:
 
 ```ruby
 # File Name: /Users/User/example.rb
-require 'awesome_print'
-PutsDebuggerer.print_engine = :ap
+PutsDebuggerer.print_engine = :p
 array = [1, [2, 3]]
 pd array
 ```
@@ -239,13 +390,7 @@ Prints out:
 ```bash
 [PD] /Users/User/example.rb:5
    > pd array
-  => [
-    [0] 1,
-    [1] [
-        [0] 2,
-        [1] 3
-    ]
-]
+  => [1, [2, 3]]
 ```
 
 #### `PutsDebuggerer.announcer`
@@ -348,20 +493,80 @@ Prints out:
      /Users/User/.rvm/rubies/ruby-2.4.0/lib/ruby/2.4.0/irb/context.rb:381:in \`evaluate\'
 ```
 
-### Bonus
+#### `PutsDebuggerer.run_at`
+(default = nil)
+
+Set condition for when to run as specified by an index, array, or range.
+* Default value is `nil` meaning always
+* Value as an Integer index (1-based) specifies at which run to print once
+* Value as an Array of indices specifies at which runs to print multiple times
+* Value as a range specifies at which runs to print multiple times,
+  indefinitely if it ends with ..-1 or ...-1
 
-puts_debuggerer comes with a number of bonus goodies.
+Can be set globally via `PutsDebuggerer.run_at` or piecemeal via `pd object, run_at: run_at_value`
 
-It comes with [awesome_print](https://github.com/awesome-print/awesome_print).
+Global usage should be good enough for most cases. When there is a need to track
+a single expression among several, you may add the option piecemeal, but it expects
+the same exact `object` passed to `pd` for counting.
 
-You may disable by not requiring in Ruby or by adding an explicit reference to awesome_print with `require: false` in bundler:
+Examples (global):
 
 ```ruby
-gem "awesome_print", require: false
-gem "puts_debugger"
+  PutsDebuggerer.run_at = 1
+  pd (x=1) # prints standard PD output
+  pd (x=1) # prints nothing
+
+  PutsDebuggerer.run_at = 2
+  pd (x=1) # prints nothing
+  pd (x=1) # prints standard PD output
+
+  PutsDebuggerer.run_at = [1, 3]
+  pd (x=1) # prints standard PD output
+  pd (x=1) # prints nothing
+  pd (x=1) # prints standard PD output
+  pd (x=1) # prints nothing
+
+  PutsDebuggerer.run_at = 3..5
+  pd (x=1) # prints nothing
+  pd (x=1) # prints nothing
+  pd (x=1) # prints standard PD output
+  pd (x=1) # prints standard PD output
+  pd (x=1) # prints standard PD output
+  pd (x=1) # prints nothing
+  pd (x=1) # prints nothing
+
+  PutsDebuggerer.run_at = 3...6
+  pd (x=1) # prints nothing
+  pd (x=1) # prints nothing
+  pd (x=1) # prints standard PD output
+  pd (x=1) # prints standard PD output
+  pd (x=1) # prints standard PD output
+  pd (x=1) # prints nothing
+
+  PutsDebuggerer.run_at = 3..-1
+  pd (x=1) # prints nothing
+  pd (x=1) # prints nothing
+  pd (x=1) # prints standard PD output
+  pd (x=1) # ... continue printing indefinitely on all subsequent runs
+
+  PutsDebuggerer.run_at = 3...-1
+  pd (x=1) # prints nothing
+  pd (x=1) # prints nothing
+  pd (x=1) # prints standard PD output
+  pd (x=1) # ... continue printing indefinitely on all subsequent runs
 ```
 
-Additionally, puts_debuggerer comes with the following bonus utility methods:
+You may reset the run_at number counter via:
+`PutsDebuggerer.reset_run_at_global_number` for global usage.
+
+And:
+`PutsDebuggerer.reset_run_at_number` or
+`PutsDebuggerer.reset_run_at_numbers`
+for piecemeal usage.
+
+### Bonus API
+
+puts_debuggerer comes with the following bonus API methods:
 
 #### `__caller_line_number__(caller_depth=0)`
 
@@ -405,6 +610,12 @@ Prints out `puts __caller_source_line__`
 
 ## Release Notes
 
+* v0.8.2: require 'stringio' for projects that don't require automatically via other gems
+* v0.8.1: `printer` option support for Rails test environment
+* v0.8.0: `printer` option support
+* v0.7.1: default print engine to :ap (AwesomePrint)
+* v0.7.0: `run_at` option, global and piecemeal.
+* v0.6.1: updated README and broke apart specs
 * v0.6.0: unofficial erb support, returning evaluated object/expression, removed static syntax support (replaced with header support)
 * v0.5.1: support for print engine lambdas and smart defaults for leveraging Rails and AwesomePrint debuggers in Rails
 * v0.5.0: custom formatter, caller backtrace, per-puts piecemeal options, and multi-line support
@@ -413,6 +624,13 @@ Prints out `puts __caller_source_line__`
 * v0.2.0: App path exclusion support, Rails root support, improved format
 * v0.1.0: File/line/expression print out
 
+## TODO
+
+* fix issue with printing in rspec inside a Rails project without having to do extra configuration
+* fix issue with erb support
+* display run_at run number in printout
+* implement fallback in irb for when line number cannot be discovered (issue happens in pry, perhaps this just means support pry)
+
 ## Contributing
 
 * Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet.

data/VERSION

@@ -0,0 +1 @@
+0.8.2

data/lib/puts_debuggerer.rb

@@ -1,10 +1,18 @@
 require 'ripper'
+require 'awesome_print'
+require 'stringio'
 
 module PutsDebuggerer
   HEADER_DEFAULT = '*'*80
   FOOTER_DEFAULT = '*'*80
-  PRINT_ENGINE_DEFAULT = :p
-  PRINT_ENGINE_MESSAGE_INVALID = 'print_engine must be a valid global method symbol (e.g. :p or :puts) or lambda/proc'
+  PRINTER_DEFAULT = :puts
+  PRINTER_RAILS = lambda do |output|
+    puts output if Rails.env.test?
+    Rails.logger.debug(output)
+  end
+  PRINT_ENGINE_DEFAULT = :ap
+  PRINTER_MESSAGE_INVALID = 'printer must be a valid global method symbol (e.g. :puts) or lambda/proc receiving a text arg'
+  PRINT_ENGINE_MESSAGE_INVALID = 'print_engine must be a valid global method symbol (e.g. :p, :ap or :pp) or lambda/proc receiving an object arg'
   ANNOUNCER_DEFAULT = '[PD]'
   FORMATTER_DEFAULT = -> (data) {
       puts data[:header] if data[:header]
@@ -14,6 +22,9 @@ module PutsDebuggerer
       puts data[:footer] if data[:footer]
     }
   CALLER_DEPTH_ZERO = 4 #depth includes pd + with_options method + nested block + build_pd_data method
+  OBJECT_RUN_AT = {}
+  STACK_TRACE_CALL_LINE_NUMBER_REGEX = /\:(\d+)\:in /
+  STACK_TRACE_CALL_SOURCE_FILE_REGEX = /[ ]*([^:]+)\:\d+\:in /
 
   class << self
     # Application root path to exclude when printing out file path
@@ -101,17 +112,55 @@ module PutsDebuggerer
       !!@footer
     end
 
-    # Print engine to use in object printout (e.g. `p`, `ap`, `pp`).
-    # It is represented by the print engine's global method name as a symbol
-    # (e.g. `:ap` for awesome_print).
-    # Defaults to Ruby's built-in `p` method identified by the symbol `:p`.
-    # If it finds awesome_print loaded, it defaults to `ap` as `:ap` instead.
+    # Printer is a global method symbol or lambda expression to use in printing to the user.
+    # Examples of global methods are `:puts` and `:print`.
+    # An example of a lambda expression is `lambda {|output| Rails.logger.ap(output)}`
+    #
+    # Defaults to `:puts`
+    # In Rails, it defaults to: `lambda {|output| Rails.logger.ap(output)}`
+    #
+    # Example:
+    #
+    # # File Name: /Users/User/example.rb
+    # PutsDebuggerer.printer = lambda {|output| Rails.logger.error(output)}
+    # str = "Hello"
+    # pd str
+    #
+    # Prints out in the Rails app log as error lines:
+    #
+    # [PD] /Users/User/example.rb:5
+    #    > pd str
+    #   => Hello
+    attr_reader :printer
+
+    def printer=(printer)
+      if printer.nil?
+        if Object.const_defined?(:Rails)
+          @printer = PRINTER_RAILS
+        else
+          @printer = PRINTER_DEFAULT
+        end
+      elsif printer.is_a?(Proc)
+        @printer = printer
+      else
+        @printer = method(printer).name rescue raise(PRINTER_MESSAGE_INVALID)
+      end
+    end
+
+    # Print engine is similar to `printer`, except it is focused on the scope of formatting
+    # the data object being printed (excluding metadata such as file name, line number,
+    # and expression, which are handled by the `printer`).
+    # As such, it is also a global method symbol or lambda expression.
+    # Examples of global methods are `:p`, `:ap`, and `:pp`.
+    # An example of a lambda expression is `lambda {|object| puts object.to_a.join(" | ")}`
+    #
+    # Defaults to [awesome_print](https://github.com/awesome-print/awesome_print).
     #
     # Example:
     #
     #   # File Name: /Users/User/example.rb
     #   require 'awesome_print'
-    #   PutsDebuggerer.print_engine = :ap
+    #   PutsDebuggerer.print_engine = :p
     #   array = [1, [2, 3]]
     #   pd array
     #
@@ -119,28 +168,15 @@ module PutsDebuggerer
     #
     #   [PD] /Users/User/example.rb:5
     #      > pd array
-    #     => [
-    #       [0] 1,
-    #       [1] [
-    #           [0] 2,
-    #           [1] 3
-    #       ]
+    #     => [1, [2, 3]]
     #   ]
     attr_reader :print_engine
 
     def print_engine=(engine)
       if engine.nil?
-        if Object.const_defined?(:Rails)
-          if Object.respond_to?(:ap, 'Hello')
-            @print_engine = lambda {|object| Rails.logger.ap(object)}
-          else
-            @print_engine = lambda {|object| Rails.logger.debug(object)}
-          end
-        else
-          @print_engine = method(:ap).name rescue PRINT_ENGINE_DEFAULT
-        end
+        @print_engine = PRINT_ENGINE_DEFAULT
       elsif engine.is_a?(Proc)
-        @print_engine = engine #TODO check that it takes one parameter or else fail fast
+        @print_engine = engine
       else
         @print_engine = method(engine).name rescue raise(PRINT_ENGINE_MESSAGE_INVALID)
       end
@@ -254,11 +290,13 @@ module PutsDebuggerer
       {
         header: header,
         footer: footer,
+        printer: printer,
         print_engine: print_engine,
         app_path: app_path,
         announcer: announcer,
         formatter: formatter,
-        caller: caller
+        caller: caller,
+        run_at: run_at
       }
     end
 
@@ -268,14 +306,117 @@ module PutsDebuggerer
         send("#{option}=", value)
       end
     end
+
+    # When to run as specified by an index, array, or range.
+    # * Default value is `nil` meaning always
+    # * Value as an Integer index (1-based) specifies at which run to print once
+    # * Value as an Array of indices specifies at which runs to print multiple times
+    # * Value as a range specifies at which runs to print multiple times,
+    #   indefinitely if it ends with ..-1
+    #
+    # Example:
+    #
+    #   PutsDebuggerer.run_at = 1
+    #   pd (x=1) # prints standard PD output
+    #   pd (x=1) # prints nothing
+    #
+    #   PutsDebuggerer.run_at = 2
+    #   pd (x=1) # prints nothing
+    #   pd (x=1) # prints standard PD output
+    #
+    #   PutsDebuggerer.run_at = [1, 3]
+    #   pd (x=1) # prints standard PD output
+    #   pd (x=1) # prints nothing
+    #   pd (x=1) # prints standard PD output
+    #   pd (x=1) # prints nothing
+    #
+    #   PutsDebuggerer.run_at = 3..5
+    #   pd (x=1) # prints nothing
+    #   pd (x=1) # prints nothing
+    #   pd (x=1) # prints standard PD output
+    #   pd (x=1) # prints standard PD output
+    #   pd (x=1) # prints standard PD output
+    #   pd (x=1) # prints nothing
+    #   pd (x=1) # prints nothing
+    #
+    #   PutsDebuggerer.run_at = 3...6
+    #   pd (x=1) # prints nothing
+    #   pd (x=1) # prints nothing
+    #   pd (x=1) # prints standard PD output
+    #   pd (x=1) # prints standard PD output
+    #   pd (x=1) # prints standard PD output
+    #   pd (x=1) # prints nothing
+    #
+    #   PutsDebuggerer.run_at = 3..-1
+    #   pd (x=1) # prints nothing
+    #   pd (x=1) # prints nothing
+    #   pd (x=1) # prints standard PD output
+    #   pd (x=1) ... continue printing indefinitely on all subsequent runs
+    #
+    #   PutsDebuggerer.run_at = 3...-1
+    #   pd (x=1) # prints nothing
+    #   pd (x=1) # prints nothing
+    #   pd (x=1) # prints standard PD output
+    #   pd (x=1) ... continue printing indefinitely on all subsequent runs
+    attr_reader :run_at
+
+    def run_at=(value)
+      @run_at = value
+    end
+
+    def run_at?
+      !!@run_at
+    end
+
+    attr_reader :run_at_global_number
+
+    def run_at_global_number=(value)
+      @run_at_global_number = value
+    end
+
+    def init_run_at_global_number
+      @run_at_global_number = 1
+    end
+
+    def increment_run_at_global_number
+      @run_at_global_number += 1
+    end
+
+    def reset_run_at_global_number
+      @run_at_global_number = nil
+    end
+
+    def run_at_number(object, run_at)
+      PutsDebuggerer::OBJECT_RUN_AT[[object,run_at]]
+    end
+
+    def init_run_at_number(object, run_at)
+      PutsDebuggerer::OBJECT_RUN_AT[[object,run_at]] = 1
+    end
+
+    def increment_run_at_number(object, run_at)
+      PutsDebuggerer::OBJECT_RUN_AT[[object,run_at]] += 1
+    end
+
+    def reset_run_at_number(object, run_at)
+      PutsDebuggerer::OBJECT_RUN_AT.delete([object, run_at])
+    end
+
+    def reset_run_at_numbers
+      PutsDebuggerer::OBJECT_RUN_AT.clear
+    end
+
   end
 end
 
-PutsDebuggerer.print_engine = PutsDebuggerer::PRINT_ENGINE_DEFAULT
-PutsDebuggerer.announcer = PutsDebuggerer::ANNOUNCER_DEFAULT
-PutsDebuggerer.formatter = PutsDebuggerer::FORMATTER_DEFAULT
-PutsDebuggerer.app_path = nil #TODO also have it set Rails root on first PD
+# setting values to nil defaults them properly
+PutsDebuggerer.printer = nil
+PutsDebuggerer.print_engine = nil
+PutsDebuggerer.announcer = nil
+PutsDebuggerer.formatter = nil
+PutsDebuggerer.app_path = nil
 PutsDebuggerer.caller = nil
+PutsDebuggerer.run_at = nil
 
 # Prints object with bonus info such as file name, line number and source
 # expression. Optionally prints out header and footer.
@@ -307,16 +448,56 @@ PutsDebuggerer.caller = nil
 #     => "Show me the source of the bug: beattle"
 #   [PD] /Users/User/finance_calculator_app/pd_test.rb:4 "What line number am I?"
 def pd(object, options=nil)
-  __with_pd_options__(options) do |print_engine_options|
-    formatter_pd_data = __build_pd_data__(object, print_engine_options) #depth adds build method
-    PutsDebuggerer.formatter.call(formatter_pd_data)
+  run_at = ((options && options[:run_at]) || PutsDebuggerer.run_at)
+
+  if __run_pd__(object, run_at)
+    __with_pd_options__(options) do |print_engine_options|
+      formatter_pd_data = __build_pd_data__(object, print_engine_options) #depth adds build method
+      stdout = $stdout
+      $stdout = sio = StringIO.new
+      PutsDebuggerer.formatter.call(formatter_pd_data)
+      $stdout = stdout
+      if PutsDebuggerer.printer.is_a?(Proc)
+        PutsDebuggerer.printer.call(sio.string)
+      else
+        send(PutsDebuggerer.send(:printer), sio.string)
+      end
+    end
   end
+
   object
 end
 
-
-STACK_TRACE_CALL_LINE_NUMBER_REGEX = /\:(\d+)\:in /
-STACK_TRACE_CALL_SOURCE_FILE_REGEX = /[ ]*([^:]+)\:\d+\:in /
+def __run_pd__(object, run_at)
+  run_pd = false
+  if run_at.nil?
+    run_pd = true
+  else
+    if PutsDebuggerer.run_at?
+      if PutsDebuggerer.run_at_global_number.nil?
+        PutsDebuggerer.init_run_at_global_number
+      else
+        PutsDebuggerer.increment_run_at_global_number
+      end
+      run_number = PutsDebuggerer.run_at_global_number
+    else
+      if PutsDebuggerer.run_at_number(object, run_at).nil?
+        PutsDebuggerer.init_run_at_number(object, run_at)
+      else
+        PutsDebuggerer.increment_run_at_number(object, run_at)
+      end
+      run_number = PutsDebuggerer.run_at_number(object, run_at)
+    end
+    if run_at.is_a?(Integer)
+      run_pd = true if run_at == run_number
+    elsif run_at.is_a?(Array)
+      run_pd = true if run_at.include?(run_number)
+    elsif run_at.is_a?(Range)
+      run_pd = true if run_at.cover?(run_number) || (run_at.end == -1 && run_number >= run_at.begin)
+    end
+  end
+  run_pd
+end
 
 # Provides caller line number starting 1 level above caller of
 # this method.
@@ -329,7 +510,7 @@ STACK_TRACE_CALL_SOURCE_FILE_REGEX = /[ ]*([^:]+)\:\d+\:in /
 #
 # prints out `3`
 def __caller_line_number__(caller_depth=0)
-  caller[caller_depth][STACK_TRACE_CALL_LINE_NUMBER_REGEX, 1].to_i
+  caller[caller_depth][PutsDebuggerer::STACK_TRACE_CALL_LINE_NUMBER_REGEX, 1].to_i
 end
 
 # Provides caller file starting 1 level above caller of
@@ -342,7 +523,7 @@ end
 #
 # prints out `lib/example.rb`
 def __caller_file__(caller_depth=0)
-  caller[caller_depth][STACK_TRACE_CALL_SOURCE_FILE_REGEX, 1]
+  caller[caller_depth][PutsDebuggerer::STACK_TRACE_CALL_SOURCE_FILE_REGEX, 1]
 end
 
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: puts_debuggerer
 version: !ruby/object:Gem::Version
-  version: 0.6.1
+  version: 0.8.2
 platform: ruby
 authors:
 - Andy Maleh
-autorequire: 
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2017-07-20 00:00:00.000000000 Z
+date: 2020-06-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: awesome_print
@@ -16,14 +16,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.7.0
+        version: 1.8.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.7.0
+        version: 1.8.0
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
@@ -67,71 +67,93 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '3.12'
 - !ruby/object:Gem::Dependency
-  name: bundler
+  name: jeweler
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.0'
+        version: 2.3.9
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.0'
+        version: 2.3.9
 - !ruby/object:Gem::Dependency
-  name: jeweler
+  name: bundler
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 2.3.0
+        version: 2.1.4
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 2.3.0
+        version: 2.1.4
 - !ruby/object:Gem::Dependency
   name: coveralls
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.8.5
+        version: 0.8.23
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.8.5
+        version: 0.8.23
 - !ruby/object:Gem::Dependency
   name: simplecov
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.10.0
+        version: 0.16.1
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.16.1
+- !ruby/object:Gem::Dependency
+  name: simplecov-lcov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.7.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.7.0
+- !ruby/object:Gem::Dependency
+  name: undercover
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.3.4
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.10.0
+        version: 0.3.4
 description: |
-  Yes, many of us avoid debuggers like the plague and clamp on to our puts statements like an umbrella in a stormy day. Why not make it official and have puts debugging become its own perfectly legitimate thing?!!
-
-  Enter puts_debuggerer. A guilt-free puts debugger Ruby gem FTW!
-
-  In other words, puts_debuggerer is a Ruby library for improved puts debugging, automatically displaying bonus useful information such as source line number and source code.
-
-  Partially inspired (only partially ;) by this blog post:
-  https://tenderlovemaking.com/2016/02/05/i-am-a-puts-debuggerer.html
-  (Credit to Tenderlove.)
+  Debuggers are great! They help us troubleshoot complicated programming problems by inspecting values produced by code, line by line. They are invaluable when trying to understand what is going on in a large application composed of thousands or millions of lines of code.
+  In day-to-day test-driven development and simple debugging though, a puts statement can be a lot quicker in revealing what is going on than halting execution completely just to inspect a single value or a few. This is certainly true when writing the simplest possible code that could possibly work, and running a test every few seconds or minutes. Problem is you need to locate puts statements in large output logs, know which methods were invoked, find out what variable names are being printed, and see nicely formatted output. Enter puts_debuggerer. A guilt-free puts debugging Ruby gem FTW that prints file names, line numbers, code statements, and formats output nicely courtesy of awesome_print.
+  Partially inspired by this blog post: https://tenderlovemaking.com/2016/02/05/i-am-a-puts-debuggerer.html (Credit to Tenderlove.)
 email: andy.am@gmail.com
 executables: []
 extensions: []
@@ -141,12 +163,13 @@ extra_rdoc_files:
 files:
 - LICENSE.txt
 - README.md
+- VERSION
 - lib/puts_debuggerer.rb
 homepage: http://github.com/AndyObtiva/puts_debuggerer
 licenses:
 - MIT
 metadata: {}
-post_install_message: 
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -161,9 +184,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubyforge_project: 
-rubygems_version: 2.6.10
-signing_key: 
+rubygems_version: 3.1.2
+signing_key:
 specification_version: 4
 summary: Ruby library for improved puts debugging, automatically displaying bonus
   useful information such as source line number and source code.