lab42_color 0.1.1 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f0b8cb37c77ec6ca8b6f3d8119778886fb61f257be00459d7f3bea5326b775a2
-  data.tar.gz: c19106ec0eae163b6d9dfa7eda10e17767fdc40f2ea061f4d764898c2b75e278
+  metadata.gz: cf53e88057be590f2ca1a63b4d118e089c09ad1651962b34202aa4d62bd37f7f
+  data.tar.gz: 5ed83c3f5546323db78b3150e51dd223b9510b45e12118359872fb7bcf4cbfcf
 SHA512:
-  metadata.gz: 7c406f8f45aef6377f6ccb3c517b68570b18f3358bcdce249403c2abcc0412c077709a923cb7611337c11ca60cdd29f47d81db0730a07edf9af4d79d50c9fca0
-  data.tar.gz: 1e113daaeee941c804ea98a0c427503e396da3a8b0b516285b8dc8bae3681536c97945730b4e63aa834460bab2a0bb0ec87208ff86a655b51c17b92fbc636256
+  metadata.gz: fb2289c336f75f65982e40afa8758f15cc5cb357f22d50b6f1838d3c034dc4e320abecdfa0115193afd4ffde3b7352546548c5a0f3f7dd2a23348af1376beada
+  data.tar.gz: 60cf66004e616872d3d8bb9ab401ada8307db6e768e9239eff9ee80cced0284eda30df9c485895a3674f151757fffb5e9b729f21c97d9b59c4c4f1e06aa23343

data/README.md

@@ -4,7 +4,200 @@
 
 # Lab42::Color
 
-Describing how this gem works with some [speculations](https://github.com/RobertDober/speculate_about)...
+## Usage
+
+```sh
+  gem install lab42_color
+```
+
+With bundler
+
+```ruby
+  gem 'lab42_color'
+```
+
+In your code
+
+```ruby
+require 'lab42/color'
+```
+
+## Synopsis
+
+The `lab42_color` gem exposes the `Lab42::Color` module.
+
+It can be uses as a receiver or to extend a module or
+to be included.
+
+## Speculations (literate specs)
+
+The following specs are executed with the [speculate about](https://github.com/RobertDober/speculate_about) gem.
+
+These specs assume the following setup code
+
+```ruby
+    require 'lab42/color'
+    Color = Lab42::Color
+```
+
+### Context: using `Color` as receiver
+
+Then we can get a color code, with or without the reset
+```ruby
+    expect(Color.color(:red, "hello")).to eq("\e[31mhello\e[0m")
+    expect(Color.color(:color253, "hello", reset: false)).to eq("\e[38;5;253mhello")
+```
+
+And we can combine different colors, fg and bg, as well as bold, dim, etc.
+```ruby
+    expect(Color.color(:bg_red, :bold, :dark_sea_green, "text", reset: false))
+      .to eq("\e[41m\e[1m\e[38;2;135;175;135mtext")
+```
+
+And we are also protected against typos
+```ruby
+    expect {
+     Color.color(:bg_red, :bold, :dark_see_green, "text", reset: false)
+    }.to raise_error(Color::BadColorSpecification, "bad color specification: dark_see_green")
+```
+
+Or just the ANSI SGC code
+```ruby
+    expect(Color.sgc(31)).to eq("\e[31m")
+    
+```
+
+And we can observe that the NO_COLOR environnement variable is respected
+```ruby
+    original = ENV['NO_COLOR']
+    ENV['NO_COLOR'] = 'true'
+    # ENV['NO_COLOR'] is cached though
+    Lab42::Color.instance_variable_set("@___no_color__", true)
+
+    expect(Color.color(:red, "hello")).to eq("hello")
+    expect(Color.sgc(31)).to eq("")
+
+ensure
+    ENV['NO_COLOR'] = original
+    Lab42::Color.instance_variable_set("@___no_color__", false)
+```
+
+And we can also output directly
+```ruby
+   expect { Color.putc(:yellow, 'yellow') }.to output("\e[33myellow").to_stdout
+   expect { Color.putcs(:green, 'green', device: $stderr) }.to output("\e[32mgreen\e[0m\n").to_stderr
+```
+
+And we can override the default `reset:` argument of the two output methods
+```ruby
+   expect { Color.putcs(:green, 'green', device: $stderr, reset: false) }.to output("\e[32mgreen\n").to_stderr
+```
+
+And we can write to any IO device
+```ruby
+   out = StringIO.new
+   Color.putc(:magenta, 'magenta', device: out, reset: true)
+   out.rewind
+   expect(out.string).to eq("\e[35mmagenta\e[0m")
+```
+
+### Context: Including `Color`
+
+Given a class including `Color`
+```ruby
+    class IncludingColor
+      include Color
+    end
+
+    let(:colorizer) { IncludingColor.new }
+```
+
+Then we can use the included methods
+```ruby
+    expect(colorizer.color(:aquamarine1, "hello")).to eq("\e[38;2;95;255;215mhello\e[0m")
+    expect(colorizer.color(:light_coral, "hello", reset: false)).to eq("\e[38;2;255;135;135mhello")
+    
+```
+
+### Context: Selective Inclusion
+
+Given two classes with different selective inclusion
+```ruby
+    class OnlyOutput
+      include Color::Output
+    end
+
+    class OnlyEncode
+      include Color::Encode
+    end
+
+    let(:oo) { OnlyOutput.new }
+    let(:oe) { OnlyEncode.new }
+```
+
+Then we can use the representivly included methods
+```ruby
+    expect { oo.putc('something') }.to output('something').to_stdout
+    expect { oo.putcs(:red, 'red', device: $stderr) }.to output("\e[31mred\e[0m\n").to_stderr
+```
+
+And also
+```ruby
+    expect(oe.color(:dim)).to eq("\e[2m\e[0m")
+    expect(oe.sgc(45)).to eq("\e[45m")
+```
+
+But we will see that
+```ruby
+    expect {
+      oo.color(:bold)
+    }.to raise_error(NoMethodError, "undefined method 'color' for an instance of OnlyOutput")
+    expect {
+      oo.sgc(0)
+    }.to raise_error(NoMethodError, "undefined method 'sgc' for an instance of OnlyOutput")
+```
+
+And about the same for `OnlyEncode` instances
+```ruby
+    # Yeah this might need a name change because of possible interfearence with the private method
+    expect {
+      oe.putc("hello")
+    }.to raise_error(NoMethodError, "private method 'putc' called for an instance of OnlyEncode")
+    expect {
+      oe.putcs("hello", reset: false)
+    }.to raise_error(NoMethodError, "undefined method 'putcs' for an instance of OnlyEncode")
+```
+
+### Context: But all I need is `#putcs`
+
+Well that is easy, use `Forwardable`
+
+Given a class only using `#putcs`
+```ruby
+    class OnlyPutcs
+      extend Forwardable
+      def_delegators Color::Output, :putcs
+    end
+
+    let(:op) { OnlyPutcs.new } 
+```
+
+Then we can call `#putcs` from an instance, of course
+```ruby
+  expect {
+    op.putcs(:bold, "Greetings", reset: false)
+  }.to output("\e[1mGreetings\n").to_stdout
+    
+```
+
+But we cannot use `#putc` 
+```ruby
+    # Yeah this might need a name change because of possible interfearence with the private method
+    expect {
+      op.putc("hello")
+    }.to raise_error(NoMethodError, "private method 'putc' called for an instance of OnlyPutcs")
+    
+```
 
 ## Author
 

data/lib/lab42/color/color_definitions.rb

@@ -257,7 +257,7 @@ module Lab42
         in [:color, col]
           sgc("38;5;#{col}")
         in nil
-          raise ArgumentError, "bad color definition #{color}"
+          raise BadColorSpecification, "bad color specification: #{color}"
         in value
           sgc(value)
         end

data/lib/lab42/color/encode.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Lab42
+  module Color
+    module Encode extend self
+
+      def color(*chunks, reset: true)
+        _colors(chunks.flatten) => {needs_reset:, colorized:}
+        colorized << _color_code(:reset) if needs_reset && reset
+
+        colorized.join
+      end
+
+      def sgc(value)
+        return '' if _no_color
+
+        ColorDefinitions.sgc(value)
+      end
+
+      private
+      def _colors(chunks) =
+        # need the [""] to get the correct encoding (WTH?)
+        chunks.inject(OpenStruct.new(needs_reset: false, colorized: [""])) do |acc, chunk|
+          _color(acc, chunk)
+        end
+
+      def _color(acc, chunk)
+        case chunk
+        when Symbol
+          acc.colorized << _color_code(chunk)
+          acc.update(needs_reset: chunk != :reset)
+        when String
+          acc.colorized << chunk
+        when 0
+          acc.colorized << _color_code(:reset)
+          acc.update(needs_reset: false)
+        else
+          raise ArgumentError, "need a colorspec by symbol, a string or 0 (short for :reset), but got #{chunk.inspect}"
+        end
+        acc
+      end
+
+      def _color_code(color) = ColorDefinitions.color_code(color, _no_color)
+
+      def _no_color
+        @___no_color__ ||= ENV['NO_COLOR']
+      end
+
+    end
+  end
+end
+# SPDX-License-Identifier: AGPL-3.0-or-later

data/lib/lab42/color/output.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require_relative 'encode'
+module Lab42
+  module Color
+    module Output extend self
+
+      def putc(*chunks, reset: false, device: $stdout)
+        output = Encode.color(*chunks, reset:)
+        device.print(output)
+      end
+
+      def putcs(*chunks, reset: true, device: $stdout)
+        output = Encode.color(*chunks, reset:)
+        device.puts(output)
+      end
+
+    end
+  end
+end
+# SPDX-License-Identifier: AGPL-3.0-or-later

data/lib/lab42/color/version.rb

@@ -2,7 +2,7 @@
 
 module Lab42
   module Color
-    VERSION = '0.1.1'
+    VERSION = '0.1.2'
   end
 end
 # SPDX-License-Identifier: AGPL-3.0-or-later

data/lib/lab42/color.rb

@@ -1,62 +1,21 @@
 # frozen_string_literal: true
 
 require_relative 'color/color_definitions'
+require_relative 'color/output'
 require 'forwardable'
 require_relative 'ostruct'
 
 module Lab42
   module Color extend self
-    extend Forwardable
+    BadColorSpecification = Class.new(RuntimeError)
+    extend Encode
+    extend Output
 
-    def color(*chunks, reset: true)
-      _colors(chunks.flatten) => {needs_reset:, colorized:}
-      colorized << _color_code(:reset) if needs_reset && reset
-
-      colorized.join
-    end
-
-    def putc(*chunks, reset: false, device: $stdout)
-      device.print(color(*chunks, reset:))
+    def self.included(into)
+      into.send(:include, Encode)
+      into.send(:include, Output)
     end
-    
-    def putcs(*chunks, reset: false, device: $stdout)
-      device.puts(color(*chunks, reset:))
-    end
-
-    def sgc(value)
-      return '' if _no_color
 
-      ColorDefinitions.sgc(value)
-    end
-
-    private
-    def _colors(chunks) =
-      # need the [""] to get the correct encoding (WTH?)
-      chunks.inject(OpenStruct.new(needs_reset: false, colorized: [""])) do |acc, chunk|
-        _color(acc, chunk)
-      end
-    
-    def _color(acc, chunk)
-      case chunk
-      when Symbol
-        acc.colorized << _color_code(chunk)
-        acc.update(needs_reset: chunk != :reset)
-      when String
-        acc.colorized << chunk
-      when 0
-        acc.colorized << _color_code(:reset)
-        acc.update(needs_reset: false)
-      else
-        raise ArgumentError, "need a colorspec by symbol, a string or 0 (short for :reset), but got #{chunk.inspect}"
-      end
-      acc
-    end
-
-    def _color_code(color) = ColorDefinitions.color_code(color, _no_color)
-
-    def _no_color
-      @___no_color__ ||= ENV['NO_COLOR']
-    end
   end
 end
 # SPDX-License-Identifier: AGPL-3.0-or-later

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: lab42_color
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.1.2
 platform: ruby
 authors:
 - Robert Dober
@@ -34,6 +34,8 @@ files:
 - lib/lab42.rb
 - lib/lab42/color.rb
 - lib/lab42/color/color_definitions.rb
+- lib/lab42/color/encode.rb
+- lib/lab42/color/output.rb
 - lib/lab42/color/version.rb
 - lib/lab42/ostruct.rb
 homepage: https://codeberg.org/lab419/lab42_color.git