report_print 0.1.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fa071844b22c0289ddea4f370860f29eed4d25e7acafe22c4cbdc02577b240ed
-  data.tar.gz: 550bcbe7efd3a01cecd72655ade451e6dd89dcfa5e5e66268f28bb872851a279
+  metadata.gz: d6bc69172badef1f367d722882bf9dfc8dcaffb66926811cc37ddebcffac68a8
+  data.tar.gz: 1fdb2ce8ed7441c34f6cc792480fc9b7ad614c0d26204cf237ada5c52f9969bc
 SHA512:
-  metadata.gz: 0411f46d291c9799c7bb9c411f6c06528a20b649e8163a6d926bee83e2db4101bcc23d721f39facba30873de5d369070dd24b01ac5144e2ad32176dd17be9fbf
-  data.tar.gz: c6f0e18ddc0e186035b4b737a4bbd0ccf553ba189d5fca5b271eda1126b1cb0cea0099e8a2c3091df5cd131fc67b428292d1b98c3f0003321496768769fd63c3
+  metadata.gz: b701bc0e9ac1896140001a39967d96ea4acc369fc7ae8a619a0e62035aa16ace37dcebcb6757abb5f0d3deb93be1e1f8381b31cc90c1e7aadd4a687cbcec0bec
+  data.tar.gz: 74c6fb521894a4f14591d5d0e23f1b941c04b5209fe9dfb880b35f84041a27c6f917aee484e6402ec555e466fd5a6e3fb582ba60c3ad1432b452f1385c7b4baa

data/README.md

@@ -23,9 +23,33 @@ gem install report_print
 ```ruby
 require 'report_print'
 
-rp object
+class Example
+  def initialize
+    @foo = { a: [1,2,3] }
+    @bar = Object.new
+  end
+end
+
+rp Example.new
 ```
 
+Output:
+
+```text
+Example 0x378
+  @foo = {
+    a: [
+      1,
+      2,
+      3
+    ]
+  }
+  @bar = Object 0x3a8
+end
+```
+
+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,185 @@
+# 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"
+    rp /regex/
+
+    # 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-orange)">
+/regex/<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.
+
+## `Range` and `ArithmeticSequence`
+
+    rp(1..10)
+    rp(..10)
+    rp((1...10).step(2))
+    rp("a".."z")
+
+Output:
+
+<pre>
+(<span style="color:var(--code-purple)">1</span>..<span style="color:var(--code-purple)">10</span>)
+(..<span style="color:var(--code-purple)">10</span>)
+(<span style="color:var(--code-purple)">1</span>...<span style="color:var(--code-purple)">10</span>).step(<span style="color:var(--code-purple)">2</span>)
+(<span style="color:var(--code-green)">"a"</span>..<span style="color:var(--code-green)">"z"</span>)</span>
+</pre>

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,5 @@
+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.
+
+After requiring simply use the global `rp` method to print objects like you do with `pp` or `ap`.

data/lib/.document

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

data/lib/report_print/api.rb

@@ -0,0 +1,61 @@
+module ReportPrint
+  ##
+  # These are the extensions that are included into the Module class that
+  # enabled you to customize the behaviour of ReportPrint for your own classes.
+  module Api
+    ##
+    # Defines options used by the printer when printing instances of the
+    # current class.
+    #
+    # The currently supported options are:
+    #
+    # * `detect_cycles:` whether instances of this class should display just a
+    #   header and id when printed multiple times by the same report print
+    #   command.
+    #   <br>
+    #   Defaults to `true` except for in the case of the simple value types and
+    #   Data classes.
+    # * `color:` the color value to apply when using #report_print_inspect!.
+    #   <br>
+    #   Defaults to `nil`.
+    #
+    # #### Example Usage
+    #
+    # ```
+    # class WithColor
+    #   report_print_options(color: :bright_blue)
+    #   report_print_inspect!
+    # end
+    #
+    # class CustomContainer
+    #   report_print_options(detect_cycles: false)
+    # end
+    # ```
+    #
+    # #### Option Loading
+    #
+    # Setting any value to `nil` means: take the global value if it is defined.
+    #
+    # When ReportPrint fetches options for a given class it first fetches the
+    # superclass options (recursively), then it merges the options for the
+    # current class on top.
+    #
+    # After which it compacts the options (removing the nils) and merges them
+    # on top of any global options. Where the global options are currently
+    # specified by calling `ReportPrint.report_print_options`.
+    def report_print_options(**kwargs)
+      @report_print_options = (@report_print_options || {}).merge(kwargs)
+    end
+
+    ##
+    # Helper that defines a `report_print` method which calls `inspect` and
+    # applies the `color:` specified in #report_print_options.
+    def report_print_inspect!
+      define_method(:report_print) do |rp|
+        rp.write(inspect, color: rp.options_for(self)[:color])
+      end
+    end
+  end
+end
+
+Module.prepend(ReportPrint::Api)

data/lib/report_print/core_extensions.rb

@@ -1,47 +1,114 @@
 using ReportPrint::Refinements
 
-class ::Object < ::BasicObject
+class ::Module < ::Object
   def report_print(rp)
-    rp.unless_seen(self) do
-      rp.write_header(self)
-      rp.multiline(after: rp.color("end", :bright_blue), after_empty: false) do
-        rp.write_instance_variables(self)
-      end
-    end
+    rp.write(short_class_name, color: :bright_yellow)
   end
 end
 
-class ::Module < ::Object
+class ::Object < ::BasicObject
+  report_print_options(detect_cycles: true)
+
   def report_print(rp)
-    rp.write(name.short_class_name)
+    rp.write_header(self)
+    rp.multiline(after: rp.color("end", :bright_blue), after_empty: false) do
+      rp.write_instance_variables(self)
+    end
+  end
+
+  def report_print_cycle(rp)
+    rp.write_header(self)
   end
 end
 
 class ::Symbol < ::Object
-  report_print_inspect!(color: :bright_blue)
+  report_print_options(color: :bright_blue, detect_cycles: false)
+  report_print_inspect!
 end
 
 class ::TrueClass < ::Object
-  report_print_inspect!(color: :bright_blue)
+  report_print_options(color: :bright_blue, detect_cycles: false)
+  report_print_inspect!
 end
 
 class ::FalseClass < ::Object
-  report_print_inspect!(color: :bright_blue)
+  report_print_options(color: :bright_blue, detect_cycles: false)
+  report_print_inspect!
 end
 
 class ::Numeric < ::Object
-  report_print_inspect!(color: :bright_magenta)
+  report_print_options(color: :bright_magenta, detect_cycles: false)
+  report_print_inspect!
 end
 
 class ::String < ::Object
-  report_print_inspect!(color: :bright_green)
+  report_print_options(color: :bright_green, detect_cycles: false)
+  report_print_inspect!
 end
 
 class ::NilClass < ::Object
-  report_print_inspect!(color: :bright_blue)
+  report_print_options(color: :bright_blue, detect_cycles: false)
+  report_print_inspect!
+end
+
+class ::Regexp < ::Object
+  report_print_options(color: :yellow, detect_cycles: false)
+  report_print_inspect!
+end
+
+class ::Range < ::Object
+  report_print_options(detect_cycles: false)
+
+  def report_print(rp)
+    first = self.first rescue nil
+    last = self.last rescue nil
+
+    rp.inline("") do
+      rp.write("(")
+      unless first.nil?
+        rp.rp(first)
+      end
+      rp.write("..")
+      if exclude_end?
+        rp.write(".")
+      end
+      unless last.nil?
+        rp.rp(last)
+      end
+      rp.write(")")
+    end
+  end
+end
+
+class ::Enumerator::ArithmeticSequence ::Enumerator
+  report_print_options(detect_cycles: false)
+
+  def report_print(rp)
+    rp.inline("") do
+      rp.write("(")
+      unless self.begin.nil?
+        rp.rp(self.begin)
+      end
+      rp.write("..")
+      if exclude_end?
+        rp.write(".")
+      end
+      unless self.end.nil?
+        rp.rp(self.end)
+      end
+      rp.write(")")
+      unless step == 1
+        rp.write(".step(")
+        rp.rp(step)
+        rp.write(")")
+      end
+    end
+  end
 end
 
 class ::Array < ::Object
+  report_print_options(detect_cycles: false)
+
   def report_print(rp)
     rp.write("[")
     rp.multiline(after: "]", separator: ",") do
@@ -53,6 +120,8 @@ class ::Array < ::Object
 end
 
 class ::Hash < ::Object
+  report_print_options(detect_cycles: false)
+
   def report_print(rp)
     rp.write("{")
     rp.multiline(after: "}", separator: ",") do
@@ -74,6 +143,8 @@ class ::Hash < ::Object
 end
 
 class ::Set < ::Object
+  report_print_options(detect_cycles: false)
+
   def report_print(rp)
     rp.inline("") do
       rp.write("Set", color: :yellow)
@@ -88,6 +159,8 @@ class ::Set < ::Object
 end
 
 class ::Data < ::Object
+  report_print_options(detect_cycles: false)
+
   def report_print(rp)
     name = self.class.short_class_name
     rp.inline("") do
@@ -96,8 +169,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/dsl.rb

@@ -19,3 +19,5 @@ module ReportPrint
     end
   end
 end
+
+Kernel.prepend(ReportPrint::Dsl)

data/lib/report_print/printer.rb

@@ -13,16 +13,12 @@ module ReportPrint
       :next_inline_separator,
       :after,
       :start_of_line,
-      :start_of_block
+      :start_of_block,
+      :start_of_output
     ) do
-      # Ruby type checking can't really handle this type of dynamic programming
-      # very well yet, so we just skip type checking here as there is only the
-      # one short function.
-      # steep:ignore:start
       def inline?
         mode == :inline
       end
-      # steep:ignore:end
     end
 
     ##
@@ -32,10 +28,7 @@ module ReportPrint
     def initialize(output = $>, color: :auto)
       @output = output
       if color == :auto
-        # Ignore block performing runtime type check.
-        # steep:ignore:start
         color = output.respond_to?(:tty?) && output.tty?
-        # steep:ignore:end
       end
       @rainbow = Rainbow::Wrapper.new(color)
 
@@ -47,9 +40,12 @@ module ReportPrint
         inline_separator: "",
         next_inline_separator: nil,
         after: nil,
-        start_of_line: false,
-        start_of_block: true
+        start_of_line: true,
+        start_of_block: true,
+        start_of_output: true
       ]
+
+      @options = ScopedOptions.new(ReportPrint.report_print_options)
     end
 
     ##
@@ -60,7 +56,14 @@ module ReportPrint
     def rp(object)
       case object
       when Object
-        object.report_print(self)
+        if @seen.include?(object.__id__)
+          object.report_print_cycle(self)
+        else
+          if options_for(object)[:detect_cycles]
+            @seen.add(object.__id__)
+          end
+          object.report_print(self)
+        end
       else
         write("BasicObject", color: :bright_yellow)
       end
@@ -120,7 +123,8 @@ module ReportPrint
       if @state.inline?
         set_state(
           start_of_line: @state.start_of_line && result.start_of_line,
-          start_of_block: @state.start_of_block && result.start_of_block
+          start_of_block: @state.start_of_block && result.start_of_block,
+          start_of_output: @state.start_of_output && result.start_of_output
         )
         if @state.next_inline_separator != result.next_inline_separator
           # If the inner inline state is requesting a separator, then that
@@ -129,7 +133,8 @@ module ReportPrint
         end
       else
         set_state(
-          start_of_block: @state.start_of_block && result.start_of_block
+          start_of_block: @state.start_of_block && result.start_of_block,
+          start_of_output: @state.start_of_output && result.start_of_output
         )
       end
     end
@@ -167,7 +172,8 @@ module ReportPrint
       )
 
       set_state(
-        start_of_block: @state.start_of_block && result.start_of_block
+        start_of_block: @state.start_of_block && result.start_of_block,
+        start_of_output: @state.start_of_output && result.start_of_output
       )
 
       did_write = !result.start_of_block
@@ -205,7 +211,7 @@ module ReportPrint
     # first concatenated into a single string, as in `IO#write`. Meaning no
     # separators or line breaks will be rendered between them.
     def write(*strings, color: nil)
-      if @state.start_of_line
+      if @state.start_of_line && !@state.start_of_output
         unless @state.start_of_block
           @output.write(@state.separator)
         end
@@ -226,12 +232,14 @@ module ReportPrint
         set_state(
           start_of_line: false,
           start_of_block: false,
+          start_of_output: false,
           next_inline_separator: @state.inline_separator
         )
       else
         set_state(
           start_of_block: false,
-          start_of_line: true
+          start_of_line: true,
+          start_of_output: false
         )
       end
     end
@@ -309,38 +317,17 @@ module ReportPrint
       end
     end
 
-    def unless_seen(object)
-      if @seen.include?(object.__id__)
-        write_header(object)
-      else
-        @seen.add(object.__id__)
-        yield
-      end
+    ##
+    # Fetch the options which are set for the class of `object`.
+    #
+    # See Api#report_print_options for more details about the available
+    # options.
+    def options_for(object)
+      @options.options_for(object.class)
     end
 
     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/refinements.rb

@@ -1,14 +1,5 @@
 module ReportPrint
   module Refinements
-    refine Object.singleton_class do
-      def report_print_inspect!(color: nil)
-        define_method(:report_print) do |rp|
-          # @type self: Object
-          rp.write(inspect, color:)
-        end
-      end
-    end
-
     refine Module do
       def short_class_name
         name.sub(/^.*::/, "")

data/lib/report_print/scoped_options.rb

@@ -0,0 +1,21 @@
+module ReportPrint
+  class ScopedOptions
+    def initialize(global_options)
+      @global_options = global_options
+      @cache = {
+        Object => Object.report_print_options,
+        BasicObject => {}
+      }
+    end
+
+    def options_for(klass)
+      @global_options.merge(self_options_for(klass).compact)
+    end
+
+    private def self_options_for(klass)
+      @cache[klass] ||= (
+        self_options_for(klass.superclass).merge(klass.report_print_options)
+      )
+    end
+  end
+end

data/lib/report_print/version.rb

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

data/lib/report_print.rb

@@ -1,10 +1,11 @@
 require_relative "report_print/version"
 require_relative "report_print/refinements"
+require_relative "report_print/api"
+require_relative "report_print/scoped_options"
 require_relative "report_print/printer"
 require_relative "report_print/core_extensions"
 require_relative "report_print/dsl"
 
-module ReportPrint; end
-
-# :enddoc:
-Kernel.prepend(ReportPrint::Dsl)
+module ReportPrint
+  @report_print_options = {}
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: report_print
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.2.0
 platform: ruby
 authors:
 - Benoit Hiller
@@ -23,10 +23,12 @@ 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.
+
+  After requiring simply use the global `rp` method to print objects like you do with `pp` or `ap`.
 email:
 - benoit.hiller@gmail.com
 executables: []
@@ -35,18 +37,26 @@ 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/api.rb
 - lib/report_print/core_extensions.rb
 - lib/report_print/dsl.rb
 - lib/report_print/printer.rb
 - lib/report_print/refinements.rb
+- lib/report_print/scoped_options.rb
 - lib/report_print/version.rb
-homepage: https://github.com/BenoitHiller/report_print
+homepage: https://benoithiller.github.io/report_print/
 licenses:
 - MIT-0
 metadata:
   allowed_push_host: https://rubygems.org
-  homepage_uri: https://github.com/BenoitHiller/report_print
+  homepage_uri: https://benoithiller.github.io/report_print/
   source_code_uri: https://github.com/BenoitHiller/report_print
 rdoc_options: []
 require_paths: