paintbrush 0.1.2 → 0.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 178fc999ac3d70a2f9dc640d1c3a187aac191019a1762af80f922144ab18aeb5
-  data.tar.gz: e1f996291bc1748c19ee6389415c896e14f98665b4297cc2217e20fc1657603e
+  metadata.gz: 69b5f9f4807975898e5e3c9ee9a96b183df59a1e57cd642305710479c43e2482
+  data.tar.gz: d2b507b2d2ce9a562bdba5066b8d5331faa9f8e1c11dbeb7e75320bb46dac26d
 SHA512:
-  metadata.gz: 6a05f14e7eb6ce19b86e8301e01000f51651ea01d93470a9a80928e3060e473800434141e537e71343995676c1131dbf69a4c6ecc271f9a2b37f52124fda5cf7
-  data.tar.gz: 4f4a5c99d916f055706e366fb7e56bec5a29223d04c604eb04686bcfa6cb596a78a6fdfd685b2a8df3804cf23bb60ce358d9b078d1426fd164b9c5e638d7b954
+  metadata.gz: 321564b1aaa6befd52e1b2703b6ac3345824188434f3634f333c39577b1b50fc7517a91c3490a0e34b865b63bb5e55e101ce287fb570a5e22a763c22cf2aa92a
+  data.tar.gz: 77e3ab29dd45a4bf28a6b6a1a6e6afdc49414de62b58d801eb5d453167a0d87e359613642ca4b9bcb4345565ae619ba56f0002bdc1c09b46057d669c18a5e003

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    paintbrush (0.1.2)
+    paintbrush (0.1.3)
 
 GEM
   remote: https://rubygems.org/

data/Makefile

@@ -1,5 +1,14 @@
+project=paintbrush
+
 .PHONY: test
 test:
 	bundle exec rspec
 	bundle exec rubocop
 	bundle exec strong_versions
+	bundle exec rspec-documentation
+
+.PHONY: publish
+publish:
+	@RSPEC_DOCUMENTATION_URL_ROOT='/$(project)' bundle exec rspec-documentation
+	@rsync --delete -r rspec-documentation/bundle/ docs01.bob.frl:/mnt/docs/$(project)/
+	@echo 'Published.'

data/README.md

@@ -42,11 +42,14 @@ Include the `Paintbrush` module anywhere and call `#paintbrush` to generate a co
 * `#white`
 * `#default`
 
+Hex colors are also available as `#hex_ff00ff` and `#hex_f0f`, allowing a much wider range of colors.
+
 Use [string interpolation](https://docs.ruby-lang.org/en/3.2/syntax/literals_rdoc.html#label-String+Literals) to nest multiple colors:
 
 ```ruby
 include Paintbrush
 puts paintbrush { green "some green text, #{yellow "some yellow text"} and some green again" }
+puts paintbrush { hex_ff00ff "some magenta #{hex_ffff00 "and some yellow"} and magenta again" }
 ```
 
 ## Alternatives

data/lib/paintbrush.rb

@@ -1,13 +1,14 @@
 # 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'
+require_relative 'paintbrush_support/version'
+require_relative 'paintbrush_support/configuration'
+require_relative 'paintbrush_support/escapes'
+require_relative 'paintbrush_support/colors'
+require_relative 'paintbrush_support/colorized_string'
+require_relative 'paintbrush_support/color_element'
+require_relative 'paintbrush_support/hex_color_code'
+require_relative 'paintbrush_support/bounded_color_element'
+require_relative 'paintbrush_support/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.:
@@ -22,7 +23,15 @@ require_relative 'paintbrush/element_tree'
 # ```
 module Paintbrush
   def self.paintbrush(colorize: nil, &block)
-    ColorizedString.new(colorize: colorize, &block).colorized
+    PaintbrushSupport::ColorizedString.new(colorize: colorize, &block).colorized
+  end
+
+  def self.configure
+    yield PaintbrushSupport::Configuration
+  end
+
+  def self.with_configuration(**options, &block)
+    PaintbrushSupport::Configuration.with_configuration(**options, &block)
   end
 
   def paintbrush(colorize: nil, &block)

data/lib/{paintbrush → paintbrush_support}/bounded_color_element.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-module Paintbrush
+module PaintbrushSupport
   # 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.

data/lib/{paintbrush → paintbrush_support}/color_element.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-module Paintbrush
+module PaintbrushSupport
   # 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.

data/lib/{paintbrush → paintbrush_support}/colorized_string.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-module Paintbrush
+module PaintbrushSupport
   # Core string colorization, provides various methods for colorizing a string, uses escape
   # 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`.
@@ -56,8 +56,8 @@ module Paintbrush
 
     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(:include, PaintbrushSupport::Colors) if context.respond_to?(:include)
+        context.send(:extend, PaintbrushSupport::Colors) if context.respond_to?(:extend)
         context.send(:instance_variable_set, :@__stack, stack)
       end
     end

data/lib/{paintbrush → paintbrush_support}/colors.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-module Paintbrush
+module PaintbrushSupport
   # Provides methods that are temporarily injected into block context. Each method returns an
   # escaped string including the current stack size with start and end escape codes, allowing the
   # string to be reconstituted afterwards with nested strings restoring the previous color once
@@ -15,9 +15,19 @@ module Paintbrush
       purple: '35',
       cyan: '36',
       white: '37',
-      default: '39'
+      default: '39',
+      black_b: '90',
+      red_b: '91',
+      green_b: '92',
+      yellow_b: '93',
+      blue_b: '94',
+      purple_b: '95',
+      cyan_b: '96',
+      white_b: '97'
     }.freeze
 
+    HEX_CODE_REGEXP = /(?:hex_[a-fA-F0-9]{3}){1,2}/.freeze
+
     COLOR_CODES.each do |name, code|
       define_method name do |string|
         if Configuration.colorize?
@@ -27,5 +37,24 @@ module Paintbrush
         end
       end
     end
+
+    def method_missing(method_name, *args)
+      return super unless method_name.match?(HEX_CODE_REGEXP)
+      return string unless Configuration.colorize?
+
+      return unless Configuration.colorize?
+
+      ColorElement.new(
+        stack: @__stack,
+        code: HexColorCode.new(hex_code: method_name).escape_sequence,
+        string: args.first
+      ).to_s
+    end
+
+    def respond_to_missing?(*)
+      return super unless method_name.match?(HEX_CODE_REGEXP)
+
+      true
+    end
   end
 end

data/lib/{paintbrush → paintbrush_support}/configuration.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-module Paintbrush
+module PaintbrushSupport
   # Provides a configuration interface for Paintbrush features, allows disabling colorization.
   #
   # Usage:

data/lib/{paintbrush → paintbrush_support}/element_tree.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-module Paintbrush
+module PaintbrushSupport
   # 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.

data/lib/{paintbrush → paintbrush_support}/escapes.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-module Paintbrush
+module PaintbrushSupport
   # 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

data/lib/paintbrush_support/hex_color_code.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module PaintbrushSupport
+  # Translates a string in format `hex_ff00ff` or `hex_f0f` into an RGB escape code sequence.
+  # Allows calling e.g.:
+  #
+  # paintbrush { hex_ff0ff 'hello in magenta' }
+  #
+  class HexColorCode
+    def initialize(hex_code:)
+      @hex_code = hex_code
+    end
+
+    def escape_sequence
+      (%w[38 2] + encoded_pairs).join(';')
+    end
+
+    private
+
+    attr_reader :hex_code
+
+    def encoded_pairs
+      pairs.map { |pair| pair.to_i(16).to_s }
+    end
+
+    def pairs
+      normalized_hex_string.chars.each_slice(2).map(&:join)
+    end
+
+    def hex_string
+      @hex_string ||= hex_code.to_s.partition('hex_').last
+    end
+
+    def normalized_hex_string
+      return hex_string if hex_string.size == 6
+
+      hex_string.chars.map { |char| "#{char}#{char}" }.join
+    end
+  end
+end

data/lib/paintbrush_support/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module PaintbrushSupport
+  VERSION = '0.1.3'
+end

data/paintbrush.gemspec

@@ -1,12 +1,13 @@
 # frozen_string_literal: true
 
-require_relative 'lib/paintbrush/version'
+require_relative 'lib/paintbrush_support/version'
 
 Gem::Specification.new do |spec|
   spec.name = 'paintbrush'
-  spec.version = Paintbrush::VERSION
+  spec.version = PaintbrushSupport::VERSION
   spec.authors = ['Bob Farrell']
   spec.email = ['git@bob.frl']
+  spec.licenses = ['MIT']
 
   spec.summary = 'Hassle-free text coloring for console applications.'
   spec.description = 'Provides a set of encapsulated methods for nested colorization of strings.'

data/rspec-documentation/pages/000-Introduction.md

@@ -0,0 +1,23 @@
+# Introduction
+
+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.
+
+## Quick Example
+
+```rspec:ansi
+require 'paintbrush'
+
+include Paintbrush
+
+subject { paintbrush { purple "You used #{green 'four'} #{blue "(#{cyan '4'})"} #{yellow 'colors'} today!" } }
+
+it 'outputs simple colorized strings' do
+  expect(subject).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
+```

data/rspec-documentation/pages/010-Colors.md

@@ -0,0 +1,52 @@
+# Colors
+
+_Paintbrush_ defines the following colors. Each color is avaiable as a method call inside a block passed to the `paintbrush` method.
+
+## Basic Colors
+
+* `black`
+* `red`
+* `green`
+* `yellow`
+* `blue`
+* `purple`
+* `cyan`
+* `white`
+* `default`
+
+```rspec:ansi
+subject { paintbrush { purple 'a purple string' } }
+
+it { is_expected.to include "\e[35ma purple string" }
+```
+
+## Bright Colors
+
+Add the `_b` suffix to get the "bright" version of the relevant color.
+
+* `black_b`
+* `red_b`
+* `green_b`
+* `yellow_b`
+* `blue_b`
+* `purple_b`
+* `cyan_b`
+* `white_b`
+
+```rspec:ansi
+subject { paintbrush { purple_b 'a bright purple string' } }
+
+it { is_expected.to include "\e[95ma bright purple string" }
+```
+
+## RGB Colors
+
+As well as the colors listed below, any RGB hex color code (e.g. `ff00ff`) is available as a method prefixed with `hex_`, e.g. use `hex_ff00ff` for magenta.
+
+The shorthand versions `#hex_f0f` are also provided, i.e. `#hex_f0f` is equivalent to `#hex_ff00ff`.
+
+```rspec:ansi
+subject { paintbrush { hex_f0f 'a magenta string' } }
+
+it { is_expected.to include "\e[38;2;255;0;255ma magenta string" }
+```

data/rspec-documentation/pages/020-Examples/010-Basic Usage.md

@@ -0,0 +1,19 @@
+# Basic Usage
+
+The most basic usage of _Paintbrush_ is with no colorization at all:
+
+```rspec:ansi
+subject { paintbrush { 'an uncolorized string' } }
+
+it { is_expected.to eql 'an uncolorized string' }
+```
+
+As you can see, a duplicate of the original string is returned intact with no modifications.
+
+The second-most basic usage of _Paintbrush_ is with a single color:
+
+```rspec:ansi
+subject { paintbrush { green 'some green text' } }
+
+it { is_expected.to include 'some green text' }
+```

data/rspec-documentation/pages/020-Examples/020-Bright Colors.md

@@ -0,0 +1,15 @@
+# Bright Colors
+
+Use the `_b` suffix for a color name to make a **bright** color. See [Colors](../colors.html) for more details.
+
+```rspec:ansi
+subject { paintbrush { blue_b "bright blue" } }
+
+it { is_expected.to include 'bright blue' }
+```
+
+```rspec:ansi
+subject { paintbrush { "#{blue "some blue text"} #{blue_b "and some bright blue text"}" } }
+
+it { is_expected.to include 'bright blue' }
+```

data/rspec-documentation/pages/020-Examples/030-Nested Colors.md

@@ -0,0 +1,13 @@
+# Nested Colors
+
+_Paintbrush_ supports unlimited levels of nesting, allowing you to use one color inside another color and have the text revert back to its previous color. This lets you create complex colorized strings without having to manually revert back manually.
+
+```rspec:ansi
+subject do
+  paintbrush do
+    green "green, #{blue "blue, #{cyan "cyan #{yellow "and yellow"}, back to cyan"}, back to blue"}, and back to green"
+  end
+end
+
+it { is_expected.to include "and yellow" }
+```

data/rspec-documentation/pages/020-Examples/040-RGB Colors.md

@@ -0,0 +1,29 @@
+# RGB Colors
+
+Using _RGB_ colors gives you the full range of over 16 Million colors to use in your terminal. We won't provide an example for each color but here are a few to give you an idea of how it works.
+
+```rspec:ansi
+subject do
+  paintbrush do
+    "#{hex_f00 'R'}#{hex_ffa500 'A'}#{hex_ff0 'I'}#{hex_080 'N'}" \
+    "#{hex_00f 'B'}#{hex_4b0082 'O'}#{hex_ee82ee 'W'}"
+  end
+end
+
+it 'outputs a rainbow' do
+  expect(subject).to eql(
+    "\e[38;2;255;0;0mR\e[0m\e[0m\e[38;2;255;165;0mA\e[0m\e[0m" \
+    "\e[38;2;255;255;0mI\e[0m\e[0m\e[38;2;0;136;0mN\e[0m\e[0m" \
+    "\e[38;2;0;0;255mB\e[0m\e[0m\e[38;2;75;0;130mO\e[0m\e[0m" \
+    "\e[38;2;238;130;238mW\e[0m\e[0m"
+  )
+end
+```
+
+Note that both the full hex code and the abbreviated versions are supported, i.e. `hex_ff0` produces the same output as `hex_ffff00`:
+
+```rspec:ansi
+subject { paintbrush { hex_ff0 'yellow' } }
+
+it { is_expected.to eql(paintbrush { hex_ffff00 'yellow' }) }
+```

data/rspec-documentation/pages/020-Examples/050-Dynamic Usage.md

@@ -0,0 +1,29 @@
+# Dynamic Usage
+
+You may have situations where the color you wish to use depends on some state that is unknown until your application is running, and may change between each invocation.
+
+Since _Paintbrush_ colors are regular methods, you can call `public_send` within the block passed to `paintbrush`.
+
+
+```rspec:ansi
+subject do
+  paintbrush { blue "The action #{public_send outcome_color, outcome} this time!" }
+end
+
+let(:outcome_color) { :green }
+let(:outcome) { 'succeeded' }
+
+it { is_expected.to include "\e[32msucceeded\e[0m" }
+
+```
+
+```rspec:ansi
+subject do
+  paintbrush { blue "The action #{public_send outcome_color, outcome} this time!" }
+end
+
+let(:outcome_color) { :red }
+let(:outcome) { 'failed' }
+
+it { is_expected.to include "\e[31mfailed\e[0m" }
+```

data/rspec-documentation/pages/020-Examples/060-Without Including.md

@@ -0,0 +1,15 @@
+# Usage Without `include Paintbrush`
+
+_Paintbrush_ is designed to minimize namespace pollution when used with `include`.
+
+Only one instance method (`#paintbrush`) is defined on the module, so only one method will be reached by your object's method resolver.
+
+_Paintbrush_ also uses a separate namespace for its internals, `PaintbrushSupport`, to minimize adding unwanted constants into an instance's namespace when using `include Paintbrush`.
+
+You may still prefer to not include _Paintbrush_ into your namespace. Simply call `Paintbrush.paintbrush` instead.
+
+```rspec:ansi
+subject { Paintbrush.paintbrush { red "I prefer not to #{cyan "include"} Paintbrush" } }
+
+it { is_expected.to include "I prefer not" }
+```

data/rspec-documentation/pages/020-Examples.md

@@ -0,0 +1,20 @@
+# Examples
+
+See the individual example pages for usage patterns. Examples are provided to cover basic usage as well as more complex nested colors with multiple color variants. Remember to `include Paintbrush` anywhere you wish to use it.
+
+Experiment with _Paintbrush_ from a terminal to get a feel for it:
+
+```irb
+irb(main):001:0> require 'paintbrush'
+=> true
+irb(main):002:0> include Paintbrush
+=> Object
+irb(main):003:0> puts(paintbrush { green "hello #{cyan 'new'} #{blue 'Paintbrush'} user" })
+hello new Paintbrush user
+```
+
+```rspec:ansi
+subject { paintbrush { green "hello #{cyan 'new'} #{blue 'Paintbrush'} user" } }
+
+it { is_expected.to include 'Paintbrush' }
+```

data/rspec-documentation/pages/030-Configuration.md

@@ -0,0 +1,63 @@
+# Configuration
+
+_Paintbrush_ provides one simple configuration option, allowing you to enable or disable colorization either globally, per-invocation, or within a block.
+
+Note that global configuration overrides block configuration, and block configuration overrides per-invocation configuration. i.e. any method-level configurations have no impact if a global configuration is set.
+
+## Global Configuration
+
+Disable colorization globally by adding the following code somewhere near the beginning of your application's start-up process (e.g. in _Rails_, an initializer is a good place to put this):
+
+```ruby
+# config/initializers/paintbrush.rb
+
+Paintbrush.configure do |config|
+  config.colorize = false if Rails.env.production?
+end
+```
+
+All calls to `#paintbrush` will now return a regular, uncolorized string.
+
+## Block Configuration
+
+_Paintbrush_ can be configured for the duration of a block by calling `Paintbrush.with_configuration`. e.g. you may want to disable colorization in your tests to make testing output a bit easier. If you're using _RSpec_ you can add the following to `spec/spec_helper.rb`:
+
+```ruby
+# spec/spec_helper.rb
+
+RSpec.configure do |config|
+  config.around { |example| Paintbrush.with_configuration(colorize: false) { example.call } }
+end
+```
+
+```rspec:ansi
+subject do
+  Paintbrush.with_configuration(colorize: false) { paintbrush { red 'An uncolorized string' } }
+end
+
+it { is_expected.to eql 'An uncolorized string' }
+```
+
+## Method Invocation Configuration
+
+Pass `colorize: false` to `paintbrush` directly to disable colorization for a single call. This is especially useful when generating a message in two or more contexts. For example, you may want to render the same message to a development log as well as returning that message in a web response, one with colorization and one without:
+
+```rspec:ansi
+def my_message(colorize: true)
+  paintbrush(colorize: colorize) { cyan "A log message with colors in some contexts." }
+end
+
+subject { my_message(colorize: true) }
+
+it { is_expected.to include "\e[36m" }
+```
+
+```rspec:ansi
+def my_message(colorize: true)
+  paintbrush(colorize: colorize) { cyan "A log message with colors in some contexts." }
+end
+
+subject { my_message(colorize: false) }
+
+it { is_expected.not_to include "\e[36m" }
+```

data/rspec-documentation/pages/040-How It Works.md

@@ -0,0 +1,83 @@
+# How It Works
+
+_Paintbrush_ can be broken down into four components:
+
+1. Context manipulation.
+1. String encoding.
+1. Color code tree construction.
+1. Re-encoding into a colorized string.
+
+## Context Manipulation
+
+_Paintbrush_ cares about namespace pollution. It avoids adding methods and constants into a namespace where possible, and it does not overload or extend any other objects. _Paintbrush's_ methods are only available within the block passed to the `#paintbrush` method.
+
+To achieve this, _Paintbrush_ duplicates the binding of the current block (i.e. the namespace that invoked `#paintbrush`), injects a module `PaintbrushSupport::Colors` (which provides the color methods like `#cyan`) into the duplicated context's `self`, and also adds a `@__stack` instance variable which is unique to each invocation of `#paintbrush`.
+
+Each call to `#green`, `#blue`, etc. adds a new `PaintbrushSupport::ColorElement` to the stack, which stores the name of the invoked color method, the string it received, and its index in the current stack.
+
+The `ColorElement` object is then returned so _Ruby_ can interpolate it, calling `ColorElement#to_s` which returns an encoded string.
+
+## String Encoding
+
+Each encoded string includes the following:
+
+* An escape code indicating the beginning of the string.
+* The index of the item in the current stack.
+* The original string received to the color method.
+* An escape code indicating the end of the string.
+
+The index is encoded to both the start end end boundaries of the substring, which allows nested colorized strings. The structure is similar to open and close tags in _XML_, with each tag having a unique identifier attribute.
+
+The raw encoded string looks like this (slightly formatted to allow text wrapping):
+
+```rspec
+subject do
+  PaintbrushSupport::ColorizedString.new(colorize: true) { red "red #{green "green #{blue "blue"}"}" }
+                                    .send(:escaped_output)
+                                    .gsub("CLOSE", "CLOSE ")
+end
+
+it { is_expected.to include "green" }
+```
+This encoded string could be represented in _XML_, for example:
+
+```xml
+<color code="red" id="2">
+  red
+  <color code="green" id="1">
+    green
+    <color code="blue" id="0">
+      blue
+    </color>
+  </color>
+</color>
+```
+However, since the leaf nodes are generated first, and each leaf node does not know where it will appear in the final string, the tree data is built back-to-front and the tree needs to be constructed from the encoded string. Leaves can't attach themselves to parents that don't exist yet, but the resulting string contains information for each node's start/end points and its index in the stack.
+
+## Color Code Tree Construction
+
+Once the encoded string has been generated, a tree structure is built by identifying the start and end points of each substring, finding the largest non-overlapping ranges as 1st-generation children, and then repeating the same algorithm using each parent's boundaries to identify direct descendants, until no direct descendants exist (i.e. we have found a leaf node).
+
+## Re-encoding into a colorized string
+
+Once the final string has been decoded into a tree structure, each leaf node can inspect its parent to identify which color code should be restored. e.g. if a leaf node has color "yellow" and its parent has color "green", the resulting substring will start with the escape code for yellow, then the string's original value, then the escape code for green.
+
+This process is repeated recursively back up the tree until the root is found, at which point the color is reset to the terminal's default.
+
+## Summary
+
+The constraints of using string interpolation to create nested colorized strings made developing _Paintbrush_ quite an interesting challenge. Each invocation of a color method receives only the string passed directly to it, and the return value of each method must be an object that _Ruby_ can interpolate into another string, removing the option to pass around objects with complex state and forcing everything to be encoded into the string.
+
+The strings received to each call can be stored elsewhere, but the final string structure must define all start and end points of each colorization so that the stack can match each substring to a color code. As each string is received, it does not know where in the final string it will appear.
+
+The result is what appears to be a robust model with unlimited nesting. Please [create an issue](https://github.com/bobf/paintbrush/issues) if you are able to break it.
+
+```rspec:ansi
+subject do
+  paintbrush do
+    "nesting with #{blue 'foo'} #{green "bar #{cyan "baz"} with #{cyan 'qux'} and quux"} and #{red "corge"}"
+  end
+end
+
+it { is_expected.to include 'baz' }
+```

data/rspec-documentation/spec_helper.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+RSpec::Documentation.configure do |config|
+  config.context do
+    require 'paintbrush'
+    include Paintbrush
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: paintbrush
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.1.3
 platform: ruby
 authors:
 - Bob Farrell
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2023-05-30 00:00:00.000000000 Z
+date: 2023-06-04 00:00:00.000000000 Z
 dependencies: []
 description: Provides a set of encapsulated methods for nested colorization of strings.
 email:
@@ -28,19 +28,32 @@ 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
+- lib/paintbrush_support/bounded_color_element.rb
+- lib/paintbrush_support/color_element.rb
+- lib/paintbrush_support/colorized_string.rb
+- lib/paintbrush_support/colors.rb
+- lib/paintbrush_support/configuration.rb
+- lib/paintbrush_support/element_tree.rb
+- lib/paintbrush_support/escapes.rb
+- lib/paintbrush_support/hex_color_code.rb
+- lib/paintbrush_support/version.rb
 - paintbrush.gemspec
-- rspec-documentation/pages/Introduction.md
+- rspec-documentation/pages/000-Introduction.md
+- rspec-documentation/pages/010-Colors.md
+- rspec-documentation/pages/020-Examples.md
+- rspec-documentation/pages/020-Examples/010-Basic Usage.md
+- rspec-documentation/pages/020-Examples/020-Bright Colors.md
+- rspec-documentation/pages/020-Examples/030-Nested Colors.md
+- rspec-documentation/pages/020-Examples/040-RGB Colors.md
+- rspec-documentation/pages/020-Examples/050-Dynamic Usage.md
+- rspec-documentation/pages/020-Examples/060-Without Including.md
+- rspec-documentation/pages/030-Configuration.md
+- rspec-documentation/pages/040-How It Works.md
+- rspec-documentation/spec_helper.rb
 - sig/paintbrush.rbs
 homepage: https://github.com/bobf/paintbrush
-licenses: []
+licenses:
+- MIT
 metadata:
   homepage_uri: https://github.com/bobf/paintbrush
   source_code_uri: https://github.com/bobf/paintbrush

data/lib/paintbrush/version.rb

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

data/rspec-documentation/pages/Introduction.md

@@ -1,36 +0,0 @@
-# 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
-```