report_print 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: c0d7f2a1582aea408d911f88210e1b8c8ed606ce89f7bf21a7c7c26f27bb6bb7
+  data.tar.gz: dc9f17860c7ef6e576b06215ea6e8a5b1d605d2c7b6c115b8d951ad077b0d806
+SHA512:
+  metadata.gz: 30dde24a45f9e1207ec2bccdd747e5ffe74a197284226ec0d60d29cf94e56bf5b818ed63f632a3703746d13c0ee0b1b76a00af51dea2f6daf20430c2bd1c77a3
+  data.tar.gz: 12847ec207fc9537d16464ab39a1f27d3c034b1fe26ee74320786f17670893e3653849694bd090a7294d09a98a30c041f9d88567c9e240cd893ba5bb45d5ae1e

data/README.md

@@ -0,0 +1,37 @@
+# ReportPrint
+
+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.
+
+## Installation
+
+Install the gem and add to the application's Gemfile by executing:
+
+```bash
+bundle add report_print
+```
+
+If bundler is not being used to manage dependencies, install the gem by executing:
+
+```bash
+gem install report_print
+```
+
+## Usage
+
+```ruby
+require 'report_print'
+
+rp object
+```
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/BenoitHiller/report_print.

data/lib/report_print/core_extensions.rb

@@ -0,0 +1,127 @@
+using ReportPrint::Refinements
+
+class ::Object < ::BasicObject
+  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
+  end
+end
+
+class ::Module < ::Object
+  def report_print(rp)
+    rp.write(name.short_class_name)
+  end
+end
+
+class ::Symbol < ::Object
+  report_print_inspect!(color: :bright_blue)
+end
+
+class ::TrueClass < ::Object
+  report_print_inspect!(color: :bright_blue)
+end
+
+class ::FalseClass < ::Object
+  report_print_inspect!(color: :bright_blue)
+end
+
+class ::Numeric < ::Object
+  report_print_inspect!(color: :bright_magenta)
+end
+
+class ::String < ::Object
+  report_print_inspect!(color: :bright_green)
+end
+
+class ::NilClass < ::Object
+  report_print_inspect!(color: :bright_blue)
+end
+
+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
+
+class ::Hash < ::Object
+  def report_print(rp)
+    rp.write("{")
+    rp.multiline(after: "}", separator: ",") do
+      each do |key, value|
+        rp.inline(" ") do
+          case key
+          in Symbol
+            rp.write(key, ":", color: :bright_cyan)
+          else
+            rp.rp(key)
+            rp.write("=>")
+          end
+
+          rp.rp(value)
+        end
+      end
+    end
+  end
+end
+
+class ::Set < ::Object
+  def report_print(rp)
+    rp.inline("") do
+      rp.write("Set", color: :yellow)
+      rp.write("[")
+    end
+    rp.multiline(after: "]", separator: ",") do
+      to_a.each do |item|
+        rp.rp(item)
+      end
+    end
+  end
+end
+
+class ::Data < ::Object
+  def report_print(rp)
+    name = self.class.short_class_name
+    rp.inline("") do
+      rp.write(name, color: :blue)
+      rp.write("[")
+    end
+    rp.multiline(after: "]", separator: ",") do
+      self.to_h.each do |name, value|
+        rp.inline(": ") do
+          rp.write(name, color: :bright_cyan)
+          rp.rp(value)
+        end
+      end
+    end
+  end
+end
+
+class ::Struct < ::Object
+  def report_print(rp)
+    name = self.class.short_class_name
+    rp.inline(" ") do
+      rp.inline("") do
+        rp.write(name, color: :bright_yellow)
+        rp.write("(")
+      end
+      rp.write_object_id(self)
+    end
+    rp.multiline(after: ")", separator: ",") do
+      self.to_h.each do |name, value|
+        rp.inline(": ") do
+          rp.write(name, color: :bright_cyan)
+          rp.rp(value)
+        end
+      end
+    end
+  end
+end

data/lib/report_print/dsl.rb

@@ -0,0 +1,21 @@
+module ReportPrint
+  module Dsl
+    ##
+    # Render out the specified `object` using its Object#report_print method.
+    #
+    # Arguments:
+    #
+    # * `output:` specifies where the output should be written to, by default
+    #   it is `$>`, meaning standard output.
+    # * `color:` specifies whether the text should render colored output or
+    #   not. The default value of `:auto` indicates that it should use the
+    #   value of `output.tty?` to determine if color output is enabled or not.
+    def rp(object, output: $>, color: :auto)
+      printer = Printer.new(output, color:)
+      printer.rp(object)
+      output.write("\n")
+
+      nil
+    end
+  end
+end

data/lib/report_print/printer.rb

@@ -0,0 +1,363 @@
+require "rainbow"
+using ReportPrint::Refinements
+
+module ReportPrint
+  ##
+  # The class of the printer instances provided to Object#report_print methods.
+  class Printer
+    State = Data.define( # :nodoc:
+      :mode,
+      :indent,
+      :separator,
+      :inline_separator,
+      :next_inline_separator,
+      :after,
+      :start_of_line,
+      :start_of_block
+    ) 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
+
+    ##
+    # Returns a new printer object writing to the specified `output`.
+    #
+    # **Intended only for internal use.** See Dsl#rp for more details.
+    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)
+
+      @seen = ::Set.new
+      @state = State[
+        mode: :multiline,
+        indent: 0,
+        separator: "",
+        inline_separator: "",
+        next_inline_separator: nil,
+        after: nil,
+        start_of_line: false,
+        start_of_block: true
+      ]
+    end
+
+    ##
+    # Print an `object` using its Object#report_print method.
+    #
+    # Note: if an argument is provided which does not inherit from Object, then
+    # `"BasicObject"` will be printed.
+    def rp(object)
+      case object
+      when Object
+        object.report_print(self)
+      else
+        write("BasicObject", color: :bright_yellow)
+      end
+    end
+
+    ##
+    # Wrap the provided input string in a `Rainbow::Presenter` and color it using
+    # `Rainbow::Presenter#color` passing the provided values.
+    #
+    # This uses a `Rainbow::Wrapper` instantiated by the Printer which uses the
+    # user specified settings for whether color printing is enabled.
+    #
+    # Additionally if `values` is a single symbol matching `/bright_(\w+)/`,
+    # then it will first apply the specified color, then apply
+    # `Rainbow::Presenter#bright` to the output.
+    #
+    # Thus the following are equivalent:
+    #
+    # ```
+    # rp.color("string", :bright_blue)
+    # rp.color("string", :blue).bright
+    # ```
+    def color(input, *values)
+      wrapped = @rainbow.wrap(input.to_s)
+      case values
+      in [Symbol => name]
+        if (matches = name.match(/bright_(\w+)/))
+          wrapped.color(matches[1].to_sym).bright
+        else
+          wrapped.color(name)
+        end
+      in []
+        wrapped
+      else
+        wrapped.color(*values)
+      end
+    end
+
+    ##
+    # Define a block which prints each item on the same line separated by
+    # `inline_separator`.
+    #
+    # If called inside another #inline block, it only customize the separator
+    # between the elements printed within the block.
+    #
+    # If no `inline_separator` is specified, then the `inline_separator` of the
+    # containing inline block will be used, or `""` if there is no containing
+    # inline block.
+    #
+    # If you want to reset the separator to the empty value you will thus need
+    # to pass `nil` or `""`.
+    def inline(inline_separator = :inherit, &block)
+      if inline_separator == :inherit
+        inline_separator = @state.inline_separator
+      end
+      result = with_state(mode: :inline, inline_separator:, &block)
+      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
+        )
+        if @state.next_inline_separator != result.next_inline_separator
+          # If the inner inline state is requesting a separator, then that
+          # means we should request the current separator instead.
+          set_state(next_inline_separator: @state.inline_separator)
+        end
+      else
+        set_state(
+          start_of_block: @state.start_of_block && result.start_of_block
+        )
+      end
+    end
+
+    ##
+    # Define a block which prints each item or #inline block on a separate line.
+    #
+    # Accepts the following options:
+    #
+    # * `separator:` a separator to print before each newline, or `:inherit` to
+    #   use the separator of the containing multiline block.
+    # * `after:` a string to print after the end of the block.
+    # * `after_empty:` if true, print `after:` even when nothing was written
+    #   inside the block.
+    # * `indent:` the number of spaces to increase the indent by inside the block.
+    def multiline(
+      separator: nil,
+      after: nil,
+      after_empty: true,
+      indent: 2,
+      &block
+    )
+      if separator == :inherit
+        separator = @state.separator
+      end
+
+      result = with_state(
+        mode: :multiline,
+        start_of_line: true,
+        start_of_block: true,
+        indent: @state.indent + indent,
+        next_inline_separator: nil,
+        separator:,
+        &block
+      )
+
+      set_state(
+        start_of_block: @state.start_of_block && result.start_of_block
+      )
+
+      did_write = !result.start_of_block
+
+      if did_write || after_empty
+        unless after.nil?
+          if did_write
+            break_line
+          end
+          @output.write(after)
+          set_state(start_of_block: false)
+
+          did_write = true
+        end
+      end
+
+      if did_write
+        if @state.inline?
+          set_state(next_inline_separator: @state.inline_separator)
+        else
+          # This is to cleanup the special case handling of the outermost state.
+          # Likely this would be more clear with an explicit flag.
+          set_state(start_of_line: true)
+        end
+      end
+    end
+
+    ##
+    # Write out the provided `strings` given the current printer state.
+    #
+    # If `color:` is provided it will be interpreted the same as in the case
+    # where #color is given a singular argument.
+    #
+    # When multiple strings are provided, they will be rendered as if they were
+    # 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
+        unless @state.start_of_block
+          @output.write(@state.separator)
+        end
+        break_line
+      elsif @state.next_inline_separator
+        @output.write(@state.next_inline_separator)
+      end
+
+      if color
+        strings = strings.map do |string|
+          self.color(string, color)
+        end
+      end
+
+      @output.write(*strings)
+
+      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
+
+    ##
+    # Write the class name and the object id joined with a space.
+    #
+    # <pre>
+    # <span style="color:var(--code-orange)"
+    # >Object</span> <span style="color:var(--code-gray)"
+    # >0xabcd1234</span>
+    # </pre>
+    def write_header(object, write_id: true)
+      inline(" ") do
+        write(object.class.short_class_name, color: :bright_yellow)
+        if write_id
+          write_object_id(object)
+        end
+      end
+    end
+
+    ##
+    # Write the id of the object as hex.
+    #
+    # <pre>
+    # <span style="color:var(--code-gray)">0xabcd1234</span>
+    # </pre>
+    def write_object_id(object)
+      write(sprintf("%#x", object.__id__), color: :bright_black)
+    end
+
+    ##
+    # Write out the instance variables of an object.
+    #
+    # If an array of symbols is provided as `variables`, only those will be
+    # considered, otherwise all variables returned by Object#instance_variables
+    # will be used.
+    #
+    # ```
+    # class Example
+    #   def new(value)
+    #     @value = value
+    #     @string = value.to_s
+    #   end
+    # end
+    #
+    # rp.write_instance_variables(Example.new(1))
+    # rp.write_instance_variables(Example.new(:two), [:@value])
+    # ```
+    #
+    # Output:
+    #
+    # <pre>
+    # <span style="color:var(--code-cyan)"
+    # >@value</span> = <span style="color:var(--code-purple)"
+    # >1</span>
+    # <span style="color:var(--code-cyan)"
+    # >@string</span> = <span style="color:var(--code-green)"
+    # >"1"</span>
+    # <span style="color:var(--code-cyan)"
+    # >@value</span> = <span style="color:var(--code-blue)"
+    # >:two</span>
+    # </pre>
+    def write_instance_variables(object, variables = :all)
+      if variables == :all
+        variables = object.instance_variables
+      end
+
+      variables.each do |name|
+        inline(" ") do
+          write(name, color: :bright_cyan)
+          write("=")
+          rp(object.instance_variable_get(name))
+        end
+      end
+    end
+
+    def unless_seen(object)
+      if @seen.include?(object.__id__)
+        write_header(object)
+      else
+        @seen.add(object.__id__)
+        yield
+      end
+    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)
+    end
+
+    def with_state(**kwargs)
+      previous = @state
+      @state = previous.with(**kwargs)
+
+      yield
+
+      result, @state = @state, previous
+      result
+    end
+
+    def set_state(**kwargs)
+      @state = @state.with(**kwargs)
+    end
+  end
+end

data/lib/report_print/refinements.rb

@@ -0,0 +1,18 @@
+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(/^.*::/, "")
+      end
+    end
+  end
+end

data/lib/report_print/version.rb

@@ -0,0 +1,3 @@
+module ReportPrint
+  VERSION = "0.1.0"
+end

data/lib/report_print.rb

@@ -0,0 +1,10 @@
+require_relative "report_print/version"
+require_relative "report_print/refinements"
+require_relative "report_print/printer"
+require_relative "report_print/core_extensions"
+require_relative "report_print/dsl"
+
+module ReportPrint; end
+
+# :enddoc:
+Kernel.prepend(ReportPrint::Dsl)

metadata

@@ -0,0 +1,66 @@
+--- !ruby/object:Gem::Specification
+name: report_print
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Benoit Hiller
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rainbow
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !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.
+
+  '
+email:
+- benoit.hiller@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/report_print.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/version.rb
+homepage: https://github.com/BenoitHiller/report_print
+licenses: []
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/BenoitHiller/report_print
+  source_code_uri: https://github.com/BenoitHiller/report_print
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.10
+specification_version: 4
+summary: A hybrid between PrettyPrint and AwesomePrint/AmazingPrint
+test_files: []