puts_debuggerer 0.7.1 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 15dfcef6a6e1e5beb4239710ba4b0fa7e7577b1b
-  data.tar.gz: cf41610d09b62afd8792dfe7665cca246b89402c
+  metadata.gz: 0f63870f52c5a1fcfde9556bca624180ad098c43
+  data.tar.gz: 5e4b9f5af1b8f2d3daabb519ecc5bb490779e7c8
 SHA512:
-  metadata.gz: e5b7a1e346bd3e8d084d367fabbacaf396b9117ead8c071c3cabaf2d6645222c2e521c63876e73a710fe740121472559a174a1e44b5f54dc067199293113ce8b
-  data.tar.gz: eac965aa078e785bc9a99b337e981dc43820af6a8c4a7bb1de8a5567b9937359315d303c221fedfa0ebd832658aac531deea44332de07d057c8ae71d960a7888
+  metadata.gz: 29c620c7faec7a524ee775cf3108aaad57a21ec3891763733a5222b552b7dc6507881b0b8dd173b42dacd668783d3d0fd95d4b63123943b02509b0cfb432ad62
+  data.tar.gz: f53bdfb0185323d065bca4dc15f8bbbf319d28c545b03441102f91d05ad5db3bb336997598334e0a5682d0aec972f91ffffa7df4c17828b15861ba6ef4b87a85

data/README.md

@@ -1,4 +1,4 @@
-# puts_debuggerer v0.7.1
+# puts_debuggerer v0.8.0
 [![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)
@@ -8,15 +8,79 @@ 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 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.)
+Enter puts_debuggerer. A guilt-free puts debugging Ruby gem FTW!
 
 Partially inspired (only partially ;) by this blog post:
 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)?
+Love PD?! Why not promote with [merchandise](https://www.zazzle.com/i+heart+pd+gifts)? Maybe I'll buy everyone wearing the merchandise a beer at software conferences.
+
+## Background
+
+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, leading to repetitive wasteful effort.
+
+puts_debuggerer automates that work via the short and simple `pd` command, automatically printing meaningful headers for output.
+
+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
+```
+
+Example with pd:
+
+```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.
 
 ## Instructions
 
@@ -25,7 +89,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.7.1'
+gem 'puts_debuggerer', '~> 0.8.0'
 ```
 
 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,7 +99,7 @@ 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.7.1
+gem install puts_debuggerer -v0.8.0
 ```
 
 ```ruby
@@ -44,11 +108,9 @@ require 'puts_debuggerer'
 
 ### Usage
 
-Simply invoke global `pd` method anywhere in your code passing an object or an expression argument.
+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).
 
-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).
-
-Example Code:
+Example:
 
 ```ruby
 # /Users/User/finance_calculator_app/pd_test.rb           # line 1
@@ -57,7 +119,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 +130,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 +149,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,19 +279,50 @@ 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: `lambda {|output| Rails.logger.debug(output)}`
+
+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 = `: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 [awesome_print](https://github.com/awesome-print/awesome_print). If it finds Rails loaded it defaults to `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
 ```
@@ -238,13 +332,7 @@ Prints out:
 ```bash
 [PD] /Users/User/example.rb:5
    > pd array
-  => [
-    [0] 1,
-    [1] [
-        [0] 2,
-        [1] 3
-    ]
-]
+  => [1, [2, 3]]
 ```
 
 #### `PutsDebuggerer.announcer`
@@ -475,6 +563,7 @@ Prints out `puts __caller_source_line__`
 
 ## Release Notes
 
+* 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
@@ -486,6 +575,10 @@ 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
+
+* display run_at run number in printout
+
 ## Contributing
 
 * Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet.

data/lib/puts_debuggerer.rb

@@ -4,8 +4,10 @@ require 'awesome_print'
 module PutsDebuggerer
   HEADER_DEFAULT = '*'*80
   FOOTER_DEFAULT = '*'*80
+  PRINTER_DEFAULT = :puts
   PRINT_ENGINE_DEFAULT = :ap
-  PRINT_ENGINE_MESSAGE_INVALID = 'print_engine must be a valid global method symbol (e.g. :p or :puts) or lambda/proc'
+  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]
@@ -105,10 +107,49 @@ 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 awesome_print loaded.
+    # 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 = lambda {|output| Rails.logger.debug(output)}
+        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:
     #
@@ -128,11 +169,7 @@ module PutsDebuggerer
 
     def print_engine=(engine)
       if engine.nil?
-        if Object.const_defined?(:Rails)
-          @print_engine = lambda {|object| Rails.logger.ap(object)}
-        else
-          @print_engine = PRINT_ENGINE_DEFAULT
-        end
+        @print_engine = PRINT_ENGINE_DEFAULT
       elsif engine.is_a?(Proc)
         @print_engine = engine
       else
@@ -248,6 +285,7 @@ module PutsDebuggerer
       {
         header: header,
         footer: footer,
+        printer: printer,
         print_engine: print_engine,
         app_path: app_path,
         announcer: announcer,
@@ -331,15 +369,15 @@ module PutsDebuggerer
       @run_at_global_number = value
     end
 
-    def init_run_at_global_number(object, run_at)
+    def init_run_at_global_number
       @run_at_global_number = 1
     end
 
-    def increment_run_at_global_number(object, run_at)
+    def increment_run_at_global_number
       @run_at_global_number += 1
     end
 
-    def reset_run_at_global_number(object, run_at)
+    def reset_run_at_global_number
       @run_at_global_number = nil
     end
 
@@ -366,9 +404,11 @@ module PutsDebuggerer
   end
 end
 
-PutsDebuggerer.print_engine = PutsDebuggerer::PRINT_ENGINE_DEFAULT
-PutsDebuggerer.announcer = PutsDebuggerer::ANNOUNCER_DEFAULT
-PutsDebuggerer.formatter = PutsDebuggerer::FORMATTER_DEFAULT
+# 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
@@ -408,7 +448,15 @@ def pd(object, options=nil)
   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
 
@@ -420,20 +468,20 @@ def __run_pd__(object, run_at)
   if run_at.nil?
     run_pd = true
   else
-    if PutsDebuggerer.run_at_global_number.nil?
-      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)
-    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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: puts_debuggerer
 version: !ruby/object:Gem::Version
-  version: 0.7.1
+  version: 0.8.0
 platform: ruby
 authors:
 - Andy Maleh
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-07-25 00:00:00.000000000 Z
+date: 2017-11-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: awesome_print