report_print 0.1.1 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fa071844b22c0289ddea4f370860f29eed4d25e7acafe22c4cbdc02577b240ed
-  data.tar.gz: 550bcbe7efd3a01cecd72655ade451e6dd89dcfa5e5e66268f28bb872851a279
+  metadata.gz: 95d2ad3bb32255b708ff4f8b2e8f60e300cd40a1d7bab2e352ca1b355ddf8bad
+  data.tar.gz: 13740735a26e08b56e1f0d2e790524afd3ec73789465a65117f2f62555177220
 SHA512:
-  metadata.gz: 0411f46d291c9799c7bb9c411f6c06528a20b649e8163a6d926bee83e2db4101bcc23d721f39facba30873de5d369070dd24b01ac5144e2ad32176dd17be9fbf
-  data.tar.gz: c6f0e18ddc0e186035b4b737a4bbd0ccf553ba189d5fca5b271eda1126b1cb0cea0099e8a2c3091df5cd131fc67b428292d1b98c3f0003321496768769fd63c3
+  metadata.gz: 87218676c7e05ef0ec0f7243dc2558da038c4abac79f21a9eee2df00e730545e5add08761195d40238303241b9181198bab19da7acef422e57656d00f5b86db3
+  data.tar.gz: 5b17164200cdbc4fbb24a39e5206368766bead5277126c81753be4d9cfdcdf52df202d857eda1e15bc28b39bae95cd7641c015e0fc8eae6301fc48e18eef6884

data/README.md

@@ -26,6 +26,8 @@ require 'report_print'
 rp object
 ```
 
+See the [full documentation](https://benoithiller.github.io/report_print/) for more details.
+
 ## 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.

data/doc/.document

@@ -0,0 +1,2 @@
+*.md
+../lib

data/doc/Customization.md

@@ -0,0 +1,150 @@
+# Customization
+
+To set up customized printing for your own classes, you need to define the `report_print` instance method.
+
+When you then go to print the object, the method you defined will be called passing in a ReportPrint::Printer instance that you can use to print things.
+
+The printer is composed of the following 4 methods:
+
+* ReportPrint::Printer#multiline
+* ReportPrint::Printer#inline
+* ReportPrint::Printer#write
+* ReportPrint::Printer#rp
+
+The `multiline` and `inline` methods modify the behaviour of the `write` method to enable you to specify how elements are joined and lines are separated.
+
+The `rp` method simply calls the `report_print` method of the specified object passing in the printer.
+
+## `multiline`
+
+The `multiline` method creates a new multiline context and executes the provided block within it, resetting the printer context back at the end of the block.
+
+Inside a multiline context each call to `write` will write its output on a new line indented as per the current indent level.
+
+If you specify a `separator` for the multiline context, then that will be written before the newline on every line except the first line of the multiline context.
+
+At the end of a multiline context the content of `after` is written into the outer context, unless `after_empty` is false and nothing was written inside the context.
+
+Example:
+
+```
+class ::Array < ::Object
+  def report_print(rp)
+    rp.write("[")
+    rp.multiline(after: "]", separator: ",") do
+      to_a.each do |item|
+        rp.rp(item)
+      end
+    end
+  end
+end
+```
+
+In this example we also see the outline of the common pattern intended for when you are putting delimiters around a block. You write the opening token manually, but rely on the `after:` keyword argument to write the closing token.
+
+The value passed to `after:` will be written without any separator before it. This pattern allows us to do the above safely without wrapping things in an extra `inline` block to prevent a separator being placed before the `"]"`.
+
+## `inline`
+
+The `inline` method creates a new inline context and executes the provided block within it, resetting the printer context back at the end of the block.
+
+When an inline context is placed within a multiline context we will say that it defines a `line`.
+
+For each line the first call to `write` behaves the same as one in the containing multiline context.
+
+Within an inline context the `inline_separator` defines a sequence to be written between two writes in that context.
+
+When inline contexts are nested the rules are applied such that all of the writes within a child context are treated as one write for the purposes of joining.
+
+Example:
+
+```
+rp.inline("+") do
+  rp.inline("-") do
+    rp.write(1)
+  end
+  rp.inline("/") do
+    rp.write(2)
+  end
+end
+
+# => "1+2"
+
+rp.inline("+") do
+  rp.inline("-") do
+    rp.write(1)
+    rp.write(2)
+  end
+  rp.inline("/") do
+    rp.write(3)
+    rp.write(4)
+  end
+end
+
+# => "1-2+3/4"
+```
+
+## Writing Defensively
+
+When creating a `report_print` method it is very important to be explicit about how you want the text to be written.
+
+**You cannot safely assume anything about the outer context.**
+
+Thus if you want items to be rendered on the same line you always need to enclose them in an `inline` context. Same goes for multiple lines and a multiline context.
+
+Example:
+
+```
+# Bad: assumes that it is in an inline context with a blank inline_separator
+def report_print(rp)
+  rp.write("Item")
+  rp.write("[")
+  rp.multiline(after: "]", separator: ",") do
+    each do |sub_item|
+      rp.rp(sub_item)
+    end
+  end
+end
+
+# Good: sets up an inline context
+def report_print(rp)
+  rp.inline("") do
+    rp.write("Item")
+    rp.write("[")
+    rp.multiline(after: "]", separator: ",") do
+      each do |sub_item|
+        rp.rp(sub_item)
+      end
+    end
+  end
+end
+```
+
+## Only use Separators for Separators
+
+Separators are only written between two writes, so you probably don't want to use them for some things that feel like separators but don't have that same property.
+
+For example:
+
+```
+class Assignment
+  # Bad: if @rhs is empty we probably still want to render an =.
+  # Otherwise users won't be able to tell that it is an assignment being
+  # printed.
+  def report_print(rp)
+    rp.inline(" = ") do
+      rp.rp(@lhs)
+      rp.rp(@rhs) if @rhs
+    end
+  end
+
+  # Better
+  def report_print(rp)
+    rp.inline(" ") do
+      rp.rp(@lhs)
+      rp.write("=")
+      rp.rp(@rhs) if @rhs
+    end
+  end
+end
+```

data/doc/Formatters.md

@@ -0,0 +1,167 @@
+# Formatters
+
+The following formatter implementation are provided by default.
+
+They are implemented by adding the `report_print` method onto the specified class, and so will be inherited as expected and can be overwritten as needed.
+
+## Simple Values
+
+A number of simple value types are configured to produce colorized versions of their `inspect` output.
+
+    rp :symbols
+    rp "strings"
+
+    # All Numeric types
+    rp 1
+    rp 0.5
+    rp Float::INFINITY
+    rp 1i * 1i
+    rp Rational(2, 3)
+
+    # Constants
+    rp true
+    rp false
+    rp nil
+
+Output:
+
+<pre>
+<span style="color:var(--code-blue)">:symbols<span style="color:var(--code-green)">
+"strings"<span style="color:var(--code-purple)">
+1
+0.5
+Infinity
+(-1+0i)
+(2/3)<span style="color:var(--code-blue)">
+true
+false
+nil</span>
+</pre>
+
+## `Object`
+
+    class A
+      def initialize
+        @name = self.class.name
+      end
+    end
+
+    class B < A
+      def initialize
+        super
+        @field = A.new
+      end
+    end
+
+    rp B.new
+
+Output:
+
+<pre>
+<span style="color:var(--code-orange)">B</span> <span style="color:var(--code-gray)">0x2b0</span>
+  <span style="color:var(--code-cyan)">@name</span> = <span style="color:var(--code-green)">"B"</span>
+  <span style="color:var(--code-cyan)">@field</span> = <span style="color:var(--code-orange)">A</span> <span style="color:var(--code-gray)">0x2b8</span>
+    <span style="color:var(--code-cyan)">@name</span> = <span style="color:var(--code-green)">"A"</span>
+  <span style="color:var(--code-blue)">end
+end</span>
+</pre>
+
+## `Module`
+
+    rp Class
+
+Output:
+
+<pre>
+<span style="color:var(--code-orange)">Class</span>
+</pre>
+
+
+## `Array`
+
+    rp [1, "two", [[]]]
+
+Output:
+
+<pre>
+[
+  <span style="color:var(--code-purple)">1</span>,
+  <span style="color:var(--code-green)">"two"</span>,
+  [
+    []
+  ]
+]</span>
+</pre>
+
+## `Hash`
+
+    rp({
+      "one" => 1,
+      two: {
+        [1, 2] => {}
+      }
+    })
+
+Output:
+
+<pre>
+{
+  <span style="color:var(--code-green)">"one"</span> => <span style="color:var(--code-purple)">1</span>,
+  <span style="color:var(--code-cyan)">two:</span> {
+    [
+      <span style="color:var(--code-purple)">1</span>,
+      <span style="color:var(--code-purple)">2</span>
+    ] => {}
+  }
+}</span>
+</pre>
+
+## `Set`
+
+    rp Set[1, "thing", Set[]]
+
+Output:
+
+<pre>
+<span style="color:var(--code-orange)">Set</span>[
+  <span style="color:var(--code-purple)">1</span>,
+  <span style="color:var(--code-green)">"thing"</span>,
+  <span style="color:var(--code-orange)">Set</span>[]
+]</span>
+</pre>
+
+## `Data`
+
+    Direction = Data.define(:x, :y)
+    Velocity = Data.define(:speed, :direction)
+
+    rp Velocity[100, Direction[0.6, 0.8]]
+
+Output:
+
+<pre>
+<span style="color:var(--code-blue)">Velocity</span>[
+  <span style="color:var(--code-cyan)">speed</span>: <span style="color:var(--code-purple)">100</span>,
+  <span style="color:var(--code-cyan)">direction</span>: <span style="color:var(--code-blue)">Direction</span>[
+    <span style="color:var(--code-cyan)">x</span>: <span style="color:var(--code-purple)">0.6</span>,
+    <span style="color:var(--code-cyan)">y</span>: <span style="color:var(--code-purple)">0.8</span>
+  ]
+]</span>
+</pre>
+
+## `Struct`
+
+    Player = Struct.new(:health, :mana)
+
+    rp Player.new(100, 200)
+
+Output:
+
+<pre>
+<span style="color:var(--code-orange)">Player</span>( <span style="color:var(--code-gray)">0x298</span>
+  <span style="color:var(--code-cyan)">health</span>: <span style="color:var(--code-purple)">100</span>,
+  <span style="color:var(--code-cyan)">mana</span>: <span style="color:var(--code-purple)">200</span>
+)</span>
+</pre>
+
+Note that the object id is included for `Struct` but not for `Data` as the latter is a flyweight while the former is essentially an ordinary class.

data/doc/overview.md

@@ -0,0 +1,84 @@
+A hybrid between PrettyPrint and AwesomePrint/AmazingPrint. Providing you both a stylish readable default, and the ability to customize it as needed.
+
+The name ReportPrint comes from the desire to output detailed reports of the program state at a given point in time, rather than merely inspecting an object.
+
+## Usage
+
+    require 'report_print'
+
+    class Example
+      def initialize
+        @foo = { a: [1,2,3] }
+        @bar = Object.new
+      end
+    end
+
+    rp Example.new
+
+Output:
+
+<pre>
+<span style="color:var(--code-orange)">Example</span> <span style="color:var(--code-gray)">0x2a0</span>
+  <span style="color:var(--code-cyan)">@foo</span> = {
+    <span style="color:var(--code-cyan)">a:</span> [
+      <span style="color:var(--code-purple)">1</span>,
+      <span style="color:var(--code-purple)">2</span>,
+      <span style="color:var(--code-purple)">3</span>
+    ]
+  }
+  <span style="color:var(--code-cyan)">@bar</span> = <span style="color:var(--code-orange)">Object</span> <span style="color:var(--code-gray)">0x2a8<span style="color:var(--code-blue)">
+end</span>
+</pre>
+
+See ReportPrint::Dsl#rp for the documentation of the global `rp` method.
+
+## Features
+
+ReportPrint comes with custom printers for the following standard library classes:
+
+* `Object`
+* `Module`
+* `Array`
+* `Hash`
+* `Set`
+* `Data`
+* `Struct`
+
+In addition it will produce colorized `inspect` output for the following classes:
+
+* `Symbol`
+* `String`
+* `Numeric`
+* `TrueClass`
+* `FalseClass`
+* `NilClass`
+
+See the page on Formatters for examples of each.
+
+### Customization
+
+Similarly to PrettyPrint you can define the `report_print` method on a class to customize the rendering of instances of that class.
+
+    class Production
+      attr_accessor :left, :right
+
+      def report_print(rp)
+        rp.inline(" ") do
+          rp.rp(left)
+          rp.write("=>")
+          right.each do |token|
+            rp.rp(token)
+          end
+        end
+      end
+    end
+
+See Customization for a guide on how to use the various methods provided by the `rp` object above.
+
+See ReportPrint::Printer for the API documentation of printer object.
+
+### Design
+
+The printed output intentionally avoids the standard inspect format of `#<Object:0x000078c7430fd6c8>` in favour of relying primarily on line breaks and indentation to delimit the start and end of objects.
+
+Similarly a conscious choice was made not to attempt any kind of midline alignment like `ap` does. Midline alignment may sometimes be pretty but it pays a substantial readability penalty for it.

data/gem_description.rdoc

@@ -0,0 +1,9 @@
+A hybrid between PrettyPrint and AwesomePrint/AmazingPrint. Providing you both a stylish readable default, and the ability to customize it as needed.
+
+The name ReportPrint comes from the desire to output detailed reports of the program state at a given point in time, rather than merely inspecting an object.
+
+== Usage
+
+  require 'report_print'
+
+  rp object

data/lib/.document

@@ -0,0 +1,2 @@
+report_print/printer.rb
+report_print/dsl.rb

data/lib/report_print/core_extensions.rb

@@ -13,7 +13,7 @@ end
 
 class ::Module < ::Object
   def report_print(rp)
-    rp.write(name.short_class_name)
+    rp.write(short_class_name, color: :bright_yellow)
   end
 end
 
@@ -96,8 +96,11 @@ class ::Data < ::Object
     end
     rp.multiline(after: "]", separator: ",") do
       self.to_h.each do |name, value|
-        rp.inline(": ") do
-          rp.write(name, color: :bright_cyan)
+        rp.inline(" ") do
+          rp.inline("") do
+            rp.write(name, color: :bright_cyan)
+            rp.write(":")
+          end
           rp.rp(value)
         end
       end

data/lib/report_print/printer.rb

@@ -320,27 +320,6 @@ module ReportPrint
 
     private
 
-    def write_after(value)
-      if @state.start_of_line
-        break_line
-      end
-
-      @output.write(value)
-
-      if @state.inline?
-        set_state(
-          start_of_line: false,
-          start_of_block: false,
-          next_inline_separator: @state.inline_separator
-        )
-      else
-        set_state(
-          start_of_block: false,
-          start_of_line: true
-        )
-      end
-    end
-
     def break_line
       @output.write("\n")
       @output.write(" " * @state.indent)

data/lib/report_print/version.rb

@@ -1,3 +1,3 @@
 module ReportPrint
-  VERSION = "0.1.1"
+  VERSION = "0.1.2"
 end

data/lib/report_print.rb

@@ -6,5 +6,4 @@ require_relative "report_print/dsl"
 
 module ReportPrint; end
 
-# :enddoc:
 Kernel.prepend(ReportPrint::Dsl)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: report_print
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.1.2
 platform: ruby
 authors:
 - Benoit Hiller
@@ -23,10 +23,16 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.1'
-description: 'A hybrid between PrettyPrint and AwesomePrint/AmazingPrint. Providing
-  you both a stylish readable default, and the ability to customize it as needed.
+description: |
+  A hybrid between PrettyPrint and AwesomePrint/AmazingPrint. Providing you both a stylish readable default, and the ability to customize it as needed.
 
-  '
+  The name ReportPrint comes from the desire to output detailed reports of the program state at a given point in time, rather than merely inspecting an object.
+
+  == Usage
+
+    require 'report_print'
+
+    rp object
 email:
 - benoit.hiller@gmail.com
 executables: []
@@ -35,6 +41,12 @@ extra_rdoc_files: []
 files:
 - LICENSE
 - README.md
+- doc/.document
+- doc/Customization.md
+- doc/Formatters.md
+- doc/overview.md
+- gem_description.rdoc
+- lib/.document
 - lib/report_print.rb
 - lib/report_print/core_extensions.rb
 - lib/report_print/dsl.rb