paintbrush 0.1.0 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7c87f82d4c60332bb80901c9b53ba99d027190044b8b6a8a0d91f0577c870846
-  data.tar.gz: cb1e9bd1e7c4fc0b65ac0ae6e50ce02dd62e86d7845192b1b14d18a602f069ce
+  metadata.gz: 178fc999ac3d70a2f9dc640d1c3a187aac191019a1762af80f922144ab18aeb5
+  data.tar.gz: e1f996291bc1748c19ee6389415c896e14f98665b4297cc2217e20fc1657603e
 SHA512:
-  metadata.gz: 21bacc0759c545c65c66d70e0fbdb7b406ea1fa224ebcab36e02d9f82ba4e4c0bdbb33dc34f61f52224272ee8c49cae3641d7ca48fdaf0bd5278ae3a3fdf6b08
-  data.tar.gz: a1340e727fe19c354cb5ae43202afe2ddfbdb94d8748cb8cba16edac3c1d88f3293e6825156c65043329d81f84a78ae041adc6e7d99fad52d64fe8cfe5513ea6
+  metadata.gz: 6a05f14e7eb6ce19b86e8301e01000f51651ea01d93470a9a80928e3060e473800434141e537e71343995676c1131dbf69a4c6ecc271f9a2b37f52124fda5cf7
+  data.tar.gz: 4f4a5c99d916f055706e366fb7e56bec5a29223d04c604eb04686bcfa6cb596a78a6fdfd685b2a8df3804cf23bb60ce358d9b078d1426fd164b9c5e638d7b954

data/Gemfile

@@ -9,6 +9,7 @@ gem 'rake', '~> 13.0'
 
 gem 'devpack', '~> 0.4.1'
 gem 'rspec', '~> 3.0'
+gem 'rspec-documentation', '~> 0.0.2'
 gem 'rubocop', '~> 1.51'
 gem 'rubocop-rake', '~> 0.6.0'
 gem 'rubocop-rspec', '~> 2.22'

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    paintbrush (0.1.0)
+    paintbrush (0.1.2)
 
 GEM
   remote: https://rubygems.org/
@@ -10,23 +10,38 @@ GEM
     concurrent-ruby (1.2.2)
     devpack (0.4.1)
     diff-lcs (1.5.0)
+    htmlbeautifier (1.4.2)
     i18n (1.13.0)
       concurrent-ruby (~> 1.0)
     json (2.6.3)
+    kramdown (2.4.0)
+      rexml
+    kramdown-parser-gfm (1.1.0)
+      kramdown (~> 2.0)
     paint (2.3.0)
     parallel (1.23.0)
     parser (3.2.2.1)
       ast (~> 2.4.1)
     rainbow (3.1.1)
     rake (13.0.6)
+    redcarpet (3.6.0)
     regexp_parser (2.8.0)
     rexml (3.2.5)
+    rouge (4.1.1)
     rspec (3.12.0)
       rspec-core (~> 3.12.0)
       rspec-expectations (~> 3.12.0)
       rspec-mocks (~> 3.12.0)
     rspec-core (3.12.2)
       rspec-support (~> 3.12.0)
+    rspec-documentation (0.0.2)
+      htmlbeautifier (~> 1.4)
+      kramdown (~> 2.4)
+      kramdown-parser-gfm (~> 1.1)
+      paintbrush (~> 0.1.1)
+      redcarpet (~> 3.6)
+      rouge (~> 4.1)
+      rspec (~> 3.12)
     rspec-expectations (3.12.3)
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.12.0)
@@ -70,6 +85,7 @@ DEPENDENCIES
   paintbrush!
   rake (~> 13.0)
   rspec (~> 3.0)
+  rspec-documentation (~> 0.0.2)
   rubocop (~> 1.51)
   rubocop-rake (~> 0.6.0)
   rubocop-rspec (~> 2.22)

data/Rakefile

@@ -2,6 +2,7 @@
 
 require 'bundler/gem_tasks'
 require 'rspec/core/rake_task'
+require 'paintbrush'
 
 RSpec::Core::RakeTask.new(:spec)
 

data/lib/paintbrush/bounded_color_element.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Paintbrush
+  # Wraps a Paintbrush::ColorElement instance and maps its start and end boundaries within a
+  # compiled escaped string by matching specific unique (indexed) escape codes. Provides
+  # `#surround?` for detecting if another element exists within the current element's boundaries.
+  class BoundedColorElement
+    def initialize(color_element:, escaped_output:)
+      @color_element = color_element
+      @escaped_output = escaped_output
+    end
+
+    def surround?(element)
+      return false if element == self
+      return false unless element.open_index.between?(open_index, close_index)
+      return false unless element.close_index.between?(open_index, close_index)
+
+      true
+    end
+
+    def inspect
+      "<#{self.class} boundaries=#{boundaries}>"
+    end
+
+    def index
+      color_element.index
+    end
+
+    def code
+      color_element.code
+    end
+
+    def boundaries
+      @boundaries ||= [open_index, close_index]
+    end
+
+    def open_index
+      @open_index ||= escaped_output.index(Escapes.open(index))
+    end
+
+    def close_index
+      escaped_output.index(Escapes.close(index))
+    end
+
+    private
+
+    attr_reader :escaped_output, :color_element
+  end
+end

data/lib/paintbrush/color_element.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Paintbrush
+  # Provides a substring enclosed in unique escape codes for later colorization when the full
+  # string has been created and all interpolation is completed. Adds itself to a provided stack
+  # of ColorElement objects on initialization.
+  class ColorElement
+    attr_reader :stack, :code, :string, :index
+    attr_accessor :open_index, :close_index
+
+    def initialize(stack:, code:, string:)
+      @stack = stack
+      @code = code
+      @string = string
+      @index = stack.size
+      stack << self
+    end
+
+    def to_s
+      "#{Escapes.open(index)}#{string}#{Escapes.close(index)}"
+    end
+
+    def inspect
+      "<#{self.class.name} index=#{index} code=#{code}>"
+    end
+  end
+end

data/lib/paintbrush/colorized_string.rb

@@ -5,44 +5,60 @@ module Paintbrush
   # sequences to store references to start and end of each coloring method to allow nested
   # colorizing with string interpolation within each individual call to `paintbrush`.
   class ColorizedString
-    def initialize(&block)
+    def initialize(colorize:, &block)
+      @colorize = colorize
       @block = block
-      @codes = []
+      @stack = []
     end
 
     # Returns a colorized string by injecting escape codes into the various calls to each color
     # method in the provided block, rebuilds the string and returns the value with regular ANSI
     # color codes ready to be output to a console.
     def colorized
-      colorized_string
+      Configuration.with_configuration(colorize: @colorize) do
+        colorized_string
+      end
     end
 
     private
 
-    attr_reader :block, :codes
+    attr_reader :block, :stack
+
+    def colorized_string(string: escaped_output, tree: element_tree)
+      tree[:children].reduce(string) do |output, child|
+        subbed = subbed_string(output, child[:node], tree[:node])
+        next subbed if child[:children].empty?
 
-    def colorized_string
-      codes.each.with_index.reduce(escaped_output) do |string, (code, index)|
-        restored_color_code = index + 1 == codes.size ? '0' : codes[index + 1]
-        subbed_string(string, index, code, restored_color_code)
+        colorized_string(string: subbed, tree: child)
       end
     end
 
-    def subbed_string(string, index, code, restored_color_code)
+    def bounded_color_elements
+      @bounded_color_elements ||= stack.map do |color_element|
+        BoundedColorElement.new(color_element: color_element, escaped_output: escaped_output)
+      end
+    end
+
+    def element_tree
+      @element_tree ||= ElementTree.new(bounded_color_elements: bounded_color_elements).tree
+    end
+
+    def subbed_string(string, color_element, parent_color_element)
+      restored_color_code = parent_color_element.nil? ? '0' : parent_color_element.code
       string
-        .sub("#{Colors::ESCAPE_START_OPEN}#{index}#{Colors::ESCAPE_START_CLOSE}", "\e[#{code}m")
-        .sub("#{Colors::ESCAPE_END_OPEN}#{index}#{Colors::ESCAPE_END_CLOSE}", "\e[0m\e[#{restored_color_code}m")
+        .sub(Escapes.open(color_element.index).to_s, "\e[#{color_element.code}m")
+        .sub(Escapes.close(color_element.index).to_s, "\e[0m\e[#{restored_color_code}m")
     end
 
     def escaped_output
-      context.instance_eval(&block)
+      @escaped_output ||= context.instance_eval(&block)
     end
 
     def context
       eval('self', block.binding, __FILE__, __LINE__).dup.tap do |context|
         context.send(:include, Paintbrush::Colors) if context.respond_to?(:include)
         context.send(:extend, Paintbrush::Colors) if context.respond_to?(:extend)
-        context.send(:instance_variable_set, :@__codes, codes)
+        context.send(:instance_variable_set, :@__stack, stack)
       end
     end
   end

data/lib/paintbrush/colors.rb

@@ -6,11 +6,6 @@ module Paintbrush
   # string to be reconstituted afterwards with nested strings restoring the previous color once
   # they have terminated.
   module Colors
-    ESCAPE_START_OPEN = "\e[3;15;17]OPEN:"
-    ESCAPE_START_CLOSE = "\e[3;15;17]CLOSE:"
-    ESCAPE_END_OPEN = "\e[17;15;3]OPEN:"
-    ESCAPE_END_CLOSE = "\e[17;15;3]CLOSE:"
-
     COLOR_CODES = {
       black: '30',
       red: '31',
@@ -25,10 +20,11 @@ module Paintbrush
 
     COLOR_CODES.each do |name, code|
       define_method name do |string|
-        @__codes.push(code)
-        "#{ESCAPE_START_OPEN}#{@__codes.size - 1}#{ESCAPE_START_CLOSE}" \
-          "#{string}" \
-          "#{ESCAPE_END_OPEN}#{@__codes.size - 1}#{ESCAPE_END_CLOSE}"
+        if Configuration.colorize?
+          ColorElement.new(stack: @__stack, code: code, string: string).to_s
+        else
+          string
+        end
       end
     end
   end

data/lib/paintbrush/configuration.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Paintbrush
+  # Provides a configuration interface for Paintbrush features, allows disabling colorization.
+  #
+  # Usage:
+  #
+  # ```ruby
+  # Paintbrush::Configuration.colorize = false
+  # ```
+  module Configuration
+    @defaults = {
+      colorize: true
+    }
+
+    @configuration = {}
+
+    class << self
+      attr_reader :configuration, :defaults
+
+      def colorize=(val)
+        configuration[:colorize] = val
+      end
+
+      def colorize?
+        configuration.fetch(:colorize, defaults[:colorize])
+      end
+
+      def reset
+        @configuration = {}
+      end
+
+      def with_configuration(**options, &block)
+        previous = configuration.dup
+        options.compact.each { |key, value| configuration[key] = value unless configuration.key?(key) }
+        block.call.tap { @configuration = previous }
+      end
+    end
+  end
+end

data/lib/paintbrush/element_tree.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Paintbrush
+  # A tree of BoundedColorElement objects. Used to build a full tree of colorized substrings in
+  # order to allow discovery of parent substrings and use their color code to restore to when the
+  # substring is terminated. Allows deeply-nested colorized strings.
+  class ElementTree
+    attr_reader :tree
+
+    def initialize(bounded_color_elements:)
+      @bounded_color_elements = bounded_color_elements
+      @tree = { node: nil, children: [] }
+      build_tree(boundary_end: bounded_color_elements.map(&:close_index).max)
+    end
+
+    def build_tree(boundary_end:, root: @tree, elements: bounded_color_elements, boundary_start: 0)
+      root_nodes, non_root_nodes = partitioned_elements(elements, boundary_start, boundary_end)
+
+      root_nodes.each do |node|
+        root[:children] << child_node(node)
+        build_tree(
+          root: root[:children].last,
+          elements: non_root_nodes,
+          boundary_start: node.open_index,
+          boundary_end: node.close_index
+        )
+      end
+    end
+
+    private
+
+    attr_reader :bounded_color_elements
+
+    def child_node(node)
+      { node: node, children: [] }
+    end
+
+    def partitioned_elements(elements, boundary_start, boundary_end)
+      elements.partition do |element|
+        next false if elements.any? { |child| child.surround?(element) }
+
+        element.boundaries.all? { |index| index.between?(boundary_start, boundary_end) }
+      end
+    end
+  end
+end

data/lib/paintbrush/escapes.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Paintbrush
+  # Provides an authority on escape code generation. Provides `.close` and `.open`, both of which
+  # receive an index (i.e. the current size of the stack). Used for escape code insertion and comparison.
+  module Escapes
+    def self.open(index)
+      "\e[3;15;17]START_OPEN:#{index}:\e[3;15;17]START_CLOSE"
+    end
+
+    def self.close(index)
+      "\e[17;15;3]END_OPEN:#{index}:\e[17;15;3]END_CLOSE"
+    end
+  end
+end

data/lib/paintbrush/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Paintbrush
-  VERSION = '0.1.0'
+  VERSION = '0.1.2'
 end

data/lib/paintbrush.rb

@@ -1,8 +1,13 @@
 # frozen_string_literal: true
 
 require_relative 'paintbrush/version'
+require_relative 'paintbrush/configuration'
+require_relative 'paintbrush/escapes'
 require_relative 'paintbrush/colors'
 require_relative 'paintbrush/colorized_string'
+require_relative 'paintbrush/color_element'
+require_relative 'paintbrush/bounded_color_element'
+require_relative 'paintbrush/element_tree'
 
 # Colorizes a string, provides `#paintbrush`. When included/extended in a class, call
 # `#paintbrush` and pass a block to use the provided dynamically defined methods, e.g.:
@@ -16,9 +21,11 @@ require_relative 'paintbrush/colorized_string'
 #   end
 # ```
 module Paintbrush
-  class Error < StandardError; end
+  def self.paintbrush(colorize: nil, &block)
+    ColorizedString.new(colorize: colorize, &block).colorized
+  end
 
-  def paintbrush(&block)
-    ColorizedString.new(&block).colorized
+  def paintbrush(colorize: nil, &block)
+    Paintbrush.paintbrush(colorize: colorize, &block)
   end
 end

data/rspec-documentation/pages/Introduction.md

@@ -0,0 +1,36 @@
+# Paintbrush
+
+Simple and concise string colorization for _Ruby_ without overloading `String` methods or requiring verbose class/method invocation.
+
+_Paintbrush_ has zero dependencies and does not pollute any namespaces or objects outside of the `#paintbrush` method wherever you include the `Paintbrush` module.
+
+Nesting is supported, allowing you to use multiple colors within the same string. The previous color is automatically restored.
+
+```rspec:ansi
+require 'paintbrush'
+
+extend Paintbrush
+
+output = paintbrush { purple "You used #{green 'four'} #{blue "(#{cyan '4'})"} #{yellow 'colors'} today!" }
+it_documents output do
+  expect(output).to eql "\e[35mYou used \e[32mfour\e[0m\e[35m " \
+                        "\e[34m(\e[36m4\e[0m\e[34m)\e[0m\e[35m " \
+                        "\e[33mcolors\e[0m\e[35m today!\e[0m\e[0m"
+end
+```
+
+```rspec:ansi
+require 'paintbrush'
+
+extend Paintbrush
+
+output = paintbrush do
+  "#{blue 'foo'} #{green "bar #{cyan %w[foo bar baz].join(', ')} with #{cyan 'qux'} and quux"} and corge"
+end
+
+it_documents output do
+  expect(output).to eql "\e[34mfoo\e[0m\e[0m \e[32mbar \e[36mfoo, bar, baz" \
+                        "\e[0m\e[32m with \e[36mqux\e[0m\e[32m "\
+                        "and quux\e[0m\e[0m and corge"
+end
+```

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: paintbrush
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.2
 platform: ruby
 authors:
 - Bob Farrell
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2023-05-24 00:00:00.000000000 Z
+date: 2023-05-30 00:00:00.000000000 Z
 dependencies: []
 description: Provides a set of encapsulated methods for nested colorization of strings.
 email:
@@ -28,10 +28,16 @@ files:
 - Rakefile
 - doc/example.png
 - lib/paintbrush.rb
+- lib/paintbrush/bounded_color_element.rb
+- lib/paintbrush/color_element.rb
 - lib/paintbrush/colorized_string.rb
 - lib/paintbrush/colors.rb
+- lib/paintbrush/configuration.rb
+- lib/paintbrush/element_tree.rb
+- lib/paintbrush/escapes.rb
 - lib/paintbrush/version.rb
 - paintbrush.gemspec
+- rspec-documentation/pages/Introduction.md
 - sig/paintbrush.rbs
 homepage: https://github.com/bobf/paintbrush
 licenses: []