sai 0.3.1 → 0.3.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0c45105e60b5f7a3a93d837080975996e96a340aef0ad3fd86cd4b5a1be17e8f
-  data.tar.gz: baf93c18ef40221c86c329deeeaabbe7a3619744d3a80a9349314624a4af3995
+  metadata.gz: '091a65a91b7e31cfea072bfad910f4af966edf3370301aa1bfbad8e6292d8e25'
+  data.tar.gz: 2296a5bb8b8b8d4c713b91afdbd777d7e69b16dd3550683d8a799dc6ac9c434d
 SHA512:
-  metadata.gz: c1540fe3fd55f0a338ff04ff6f9794e831b831c040637f4cdd4f0de0ab0a689a55f95d5c1a744f3ae25b0bc7452983044568e83b6e665439672142cd2abd811b
-  data.tar.gz: 4244b0401b7fd0af26665a0a5b5622dd09bd364e4166bc8d12a6c69f94a52b09511d56afe2cd8eaedf1401c402b3ba63845aa900c147e408312221dcc243e21d
+  metadata.gz: 548ca06d57fe14768900f6d04191b52d876c38a9c5cca96b26da9d2c8afc3b7dffdd44b9d075b92bda97d1d80e2b6b75d3d8782c3e592d1a4547dfc72dceba1f
+  data.tar.gz: 48d9f58551111cd95a61c7c11ba2e83506239bf7e4805c93a3c38c653f28dfb94680637f35cf4a0325702ad4fe320f32060d794b26be2c308dd0b216f9cfbf64

data/CHANGELOG.md

@@ -6,6 +6,13 @@ The format is based on [Keep a Changelog], and this project adheres to [Break Ve
 
 ## [Unreleased]
 
+## [0.3.2] - 2025-01-22
+
+### Added
+
+* [#15](https://github.com/aaronmallen/sai/pull/15) - Add support for registering custom named colors by
+  [@aaronmallen](https://github.com/aaronmallen)
+
 ## [0.3.1] - 2025-01-22
 
 ### Added 
@@ -64,7 +71,8 @@ The format is based on [Keep a Changelog], and this project adheres to [Break Ve
 
 <!-- versions -->
 
-[Unreleased]: https://github.com/aaronmallen/sai/compare/0.3.1..HEAD
+[Unreleased]: https://github.com/aaronmallen/sai/compare/0.3.2..HEAD
+[0.3.2]: https://github.com/aaronmallen/sai/compare/0.3.1..0.3.2
 [0.3.1]: https://github.com/aaronmallen/sai/compare/0.3.0..0.3.1
 [0.3.0]: https://github.com/aaronmallen/sai/compare/0.2.0..0.3.0
 [0.2.0]: https://github.com/aaronmallen/sai/compare/0.1.0..0.2.0

data/README.md

@@ -4,7 +4,7 @@
 [![Sai Codacy grade](https://img.shields.io/codacy/grade/0f9a91b573ed4768a773867b95ed4894/main?style=for-the-badge&logo=codacy&logoColor=white&logoSize=auto)](https://app.codacy.com/gh/aaronmallen/sai)
 [![Sai Codacy coverage](https://img.shields.io/codacy/coverage/0f9a91b573ed4768a773867b95ed4894/main?style=for-the-badge&logo=codacy&logoColor=white&logoSize=auto)](https://app.codacy.com/gh/aaronmallen/sai/coverage)
 [![Sai License](https://img.shields.io/github/license/aaronmallen/sai?style=for-the-badge&logo=opensourceinitiative&logoColor=white&logoSize=auto)](./LICENSE)
-[![Sai Docs](https://img.shields.io/badge/rubydoc-blue?style=for-the-badge&logo=readthedocs&logoColor=white&logoSize=auto&label=docs)](https://rubydoc.info/gems/sai/0.3.1)
+[![Sai Docs](https://img.shields.io/badge/rubydoc-blue?style=for-the-badge&logo=readthedocs&logoColor=white&logoSize=auto&label=docs)](https://rubydoc.info/gems/sai/0.3.2)
 [![Sai Open Issues](https://img.shields.io/github/issues-search/aaronmallen/sai?query=state%3Aopen&style=for-the-badge&logo=github&logoColor=white&logoSize=auto&label=issues&color=red)](https://github.com/aaronmallen/sai/issues?q=state%3Aopen%20)
 
 An elegant color management system for crafting sophisticated CLI applications
@@ -88,7 +88,7 @@ puts text.stripped        # Get plain text
 ## Documentation
 
 * [Complete Usage Guide](docs/USAGE.md) - Comprehensive documentation of all features
-* [API Documentation](https://rubydoc.info/gems/sai/0.3.1) - Detailed API reference
+* [API Documentation](https://rubydoc.info/gems/sai/0.3.2) - Detailed API reference
 
 ## Contributing
 

data/docs/USAGE.md

@@ -107,6 +107,20 @@ For a complete list of available colors, see:
 * [Online Color Reference](https://github.com/aaronmallen/sai/blob/main/docs/AVAILABLE_NAMED_COLORS.md)
 * `Sai::NamedColors.names` in your code
 
+#### Registering Custom Named Colors
+
+Sai allows you to register custom named colors for easy reuse with `Sai.register`:
+
+```ruby
+# Register custom colors
+Sai.register(:my_color, '#CF4C5F')
+
+# or alternatively 
+Sai.register(:my_color, [207, 76, 95])
+
+Sai.my_color.decorate('Hello, world!')
+```
+
 ### Color Manipulation
 
 Adjust the brightness of colors:

data/lib/sai/decorator/delegation.rb

@@ -52,6 +52,7 @@ module Sai
           methods = collect_delegatable_methods.reject { |m| ignored_methods.include?(m) }
 
           methods.each do |method|
+            klass.undef_method(method) if klass.method_defined?(method)
             klass.define_method(method) do |*args, **kwargs|
               Decorator.new(mode: Sai.mode.auto).public_send(method, *args, **kwargs)
             end

data/lib/sai/decorator/named_colors.rb

@@ -749,15 +749,27 @@ module Sai
       #   def yellow_green: () -> Decorator
       #   def yellow_system: () -> Decorator
 
-      Sai::NamedColors.names.each do |color|
-        define_method(color) do
-          apply_named_color(:foreground, color)
-        end
-        define_method(:"on_#{color}") do
-          apply_named_color(:background, color)
+      # Install a color method on the {Decorator} class
+      #
+      # @author {https://aaronmallen.me Aaron Allen}
+      # @since 0.3.2
+      #
+      # @api private
+      #
+      # @param color_name [Symbol] the name of the color to install
+      #
+      # @return [void]
+      # @rbs (Symbol color_name) -> void
+      def self.install(color_name)
+        { color_name => :foreground, :"on_#{color_name}" => :background }.each do |method_name, style_type|
+          # @type var style_type: Sai::Conversion::ColorSequence::style_type
+          Sai::Decorator.undef_method(method_name) if Sai::Decorator.method_defined?(method_name)
+          Sai::Decorator.define_method(method_name) { apply_named_color(style_type, color_name) }
         end
       end
 
+      Sai::NamedColors.names.each { |color| Sai::Decorator::NamedColors.install(color) }
+
       private
 
       # Apply a named color to the specified style type

data/lib/sai/named_colors.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'sai/conversion/rgb'
+
 module Sai
   # A collection of named colors and their RGB values
   #
@@ -406,32 +408,115 @@ module Sai
     }.freeze #: Hash[Symbol, Array[Integer]]
     # rubocop:enable Naming/VariableNumber
 
-    # Look up an RGB value by color name
-    #
-    # @author {https://aaronmallen.me Aaron Allen}
-    # @since 0.3.1
-    #
-    # @api private
-    #
-    # @param name [String, Symbol] the color name
-    #
-    # @return [Array<Integer>] the RGB value
-    # @rbs (String | Symbol name) -> Array[Integer]?
-    def self.[](name)
-      key = name.to_sym
-      ANSI.fetch(key, XTERM.fetch(key, CSS.fetch(key, nil)))
-    end
+    class << self
+      # Look up an RGB value by color name
+      #
+      # @author {https://aaronmallen.me Aaron Allen}
+      # @since 0.3.1
+      #
+      # @api private
+      #
+      # @param name [String, Symbol] the color name
+      #
+      # @return [Array<Integer>] the RGB value
+      # @rbs (String | Symbol name) -> Array[Integer]?
+      def [](name)
+        registry[name.to_sym]
+      end
 
-    # Get a list of all color names
-    #
-    # @author {https://aaronmallen.me Aaron Allen}
-    # @since 0.3.1
-    #
-    # @api private
-    #
-    # @return [Array<Symbol>] the color names
-    def self.names
-      (ANSI.keys + CSS.keys + XTERM.keys).uniq.sort
+      # Get a list of all color names
+      #
+      # @author {https://aaronmallen.me Aaron Allen}
+      # @since 0.3.1
+      #
+      # @api private
+      #
+      # @return [Array<Symbol>] the color names
+      def names
+        @names ||= registry.keys.uniq.sort
+      end
+
+      # Register a named color with an RGB or Hexadecimal value
+      #
+      # @author {https://aaronmallen.me Aaron Allen}
+      # @since 0.3.2
+      #
+      # @api private
+      #
+      # @param name [String, Symbol] the name of the color being registered
+      # @param rgb_or_hex [Array<Integer>, String] the RGB or Hexadecimal value of the color
+      #
+      # @return [Boolean] `true` if the color was registered
+      # @rbs (String | Symbol name, Array[Integer] | String rgb_or_hex) -> void
+      def register(name, rgb_or_hex)
+        key = name.to_s.downcase.to_sym
+        provision_color(key, rgb_or_hex)
+        install_color(key)
+        true
+      end
+
+      private
+
+      # Install the color methods onto {Sai} and {Sai::Decorator}
+      #
+      # @author {https://aaronmallen.me Aaron Allen}
+      # @since 0.3.2
+      #
+      # @api private
+      #
+      # @param name [Symbol] the name of the color to install
+      #
+      # @return [void]
+      # @rbs (Symbol name) -> void
+      def install_color(name)
+        Sai::Decorator::NamedColors.install(name)
+        Sai::Decorator::Delegation.install(Sai)
+      end
+
+      # Provision a color for the registry
+      #
+      # @author {https://aaronmallen.me Aaron Allen}
+      # @since 0.3.2
+      #
+      # @api private
+      #
+      # @param name [Symbol] the name of the color to register
+      # @param rgb_or_hex [Array<Integer>, String] the RGB or Hexadecimal value of the color
+      #
+      # @return [void]
+      # @rbs (Symbol name, Array[Integer] | String rgb_or_hex) -> void
+      def provision_color(name, rgb_or_hex)
+        rgb = Conversion::RGB.resolve(rgb_or_hex)
+        registry[name] = rgb
+        @names = nil
+      end
+
+      # The Sai named colors registry
+      #
+      # @author {https://aaronmallen.me Aaron Allen}
+      # @since 0.3.2
+      #
+      # @api private
+      #
+      # @return [Hash{Symbol => Array<Integer>}] the named colors registry
+      def registry
+        thread_lock.synchronize do
+          @registry ||= CSS.merge(XTERM).merge(ANSI)
+        end
+      end
+
+      # A Mutex for thread safety
+      #
+      # @author {https://aaronmallen.me Aaron Allen}
+      # @since 0.3.2
+      #
+      # @api private
+      #
+      # @return [Mutex] the thread lock
+      # @rbs () -> Mutex
+      def thread_lock
+        @thread_lock ||= Mutex.new
+      end
     end
   end
 end

data/lib/sai.rb

@@ -833,6 +833,28 @@ module Sai
       ModeSelector
     end
 
+    # Register a custom name and color
+    #
+    # @author {https://aaronmallen.me Aaron Allen}
+    # @since 0.3.2
+    #
+    # @api public
+    #
+    # @example Register a color
+    #   Sai.register(:my_color, '#CF4C5F')
+    #   Sai.register(:my_color, [207, 76, 95])
+    #
+    #   Sai.my_color.decorate('Hello, world!').to_s #=> "\e[38;2;207;76;95mHello, world!\e[0m"
+    #
+    # @param name [String, Symbol] the name of the color to register
+    # @param rgb_or_hex [Array<Integer>, String] the RGB values or hex code to register
+    #
+    # @return [void]
+    # @rbs (String | Symbol name, Array[Integer] | String rgb_or_hex) -> void
+    def register(name, rgb_or_hex)
+      NamedColors.register(name, rgb_or_hex)
+    end
+
     # Sequence a string with ANSI escape codes
     #
     # @author {https://aaronmallen.me Aaron Allen}

data/sig/sai/decorator/named_colors.rbs

@@ -1471,6 +1471,19 @@ module Sai
 
       def yellow_system: () -> Decorator
 
+      # Install a color method on the {Decorator} class
+      #
+      # @author {https://aaronmallen.me Aaron Allen}
+      # @since 0.3.2
+      #
+      # @api private
+      #
+      # @param color_name [Symbol] the name of the color to install
+      #
+      # @return [void]
+      # @rbs (Symbol color_name) -> void
+      def self.install: (Symbol color_name) -> void
+
       private
 
       # Apply a named color to the specified style type

data/sig/sai/named_colors.rbs

@@ -61,5 +61,67 @@ module Sai
     #
     # @return [Array<Symbol>] the color names
     def self.names: () -> untyped
+
+    # Register a named color with an RGB or Hexadecimal value
+    #
+    # @author {https://aaronmallen.me Aaron Allen}
+    # @since 0.3.2
+    #
+    # @api private
+    #
+    # @param name [String, Symbol] the name of the color being registered
+    # @param rgb_or_hex [Array<Integer>, String] the RGB or Hexadecimal value of the color
+    #
+    # @return [Boolean] `true` if the color was registered
+    # @rbs (String | Symbol name, Array[Integer] | String rgb_or_hex) -> void
+    def self.register: (String | Symbol name, Array[Integer] | String rgb_or_hex) -> void
+
+    # Install the color methods onto {Sai} and {Sai::Decorator}
+    #
+    # @author {https://aaronmallen.me Aaron Allen}
+    # @since 0.3.2
+    #
+    # @api private
+    #
+    # @param name [Symbol] the name of the color to install
+    #
+    # @return [void]
+    # @rbs (Symbol name) -> void
+    private def self.install_color: (Symbol name) -> void
+
+    # Provision a color for the registry
+    #
+    # @author {https://aaronmallen.me Aaron Allen}
+    # @since 0.3.2
+    #
+    # @api private
+    #
+    # @param name [Symbol] the name of the color to register
+    # @param rgb_or_hex [Array<Integer>, String] the RGB or Hexadecimal value of the color
+    #
+    # @return [void]
+    # @rbs (Symbol name, Array[Integer] | String rgb_or_hex) -> void
+    private def self.provision_color: (Symbol name, Array[Integer] | String rgb_or_hex) -> void
+
+    # The Sai named colors registry
+    #
+    # @author {https://aaronmallen.me Aaron Allen}
+    # @since 0.3.2
+    #
+    # @api private
+    #
+    # @return [Hash{Symbol => Array<Integer>}] the named colors registry
+    private def self.registry: () -> untyped
+
+    # A Mutex for thread safety
+    #
+    # @author {https://aaronmallen.me Aaron Allen}
+    # @since 0.3.2
+    #
+    # @api private
+    #
+    # @return [Mutex] the thread lock
+    # @rbs () -> Mutex
+    private def self.thread_lock: () -> Mutex
   end
 end

data/sig/sai.rbs

@@ -1574,6 +1574,26 @@ module Sai
   # @rbs () -> singleton(ModeSelector)
   def self.mode: () -> singleton(ModeSelector)
 
+  # Register a custom name and color
+  #
+  # @author {https://aaronmallen.me Aaron Allen}
+  # @since 0.3.2
+  #
+  # @api public
+  #
+  # @example Register a color
+  #   Sai.register(:my_color, '#CF4C5F')
+  #   Sai.register(:my_color, [207, 76, 95])
+  #
+  #   Sai.my_color.decorate('Hello, world!').to_s #=> "\e[38;2;207;76;95mHello, world!\e[0m"
+  #
+  # @param name [String, Symbol] the name of the color to register
+  # @param rgb_or_hex [Array<Integer>, String] the RGB values or hex code to register
+  #
+  # @return [void]
+  # @rbs (String | Symbol name, Array[Integer] | String rgb_or_hex) -> void
+  def self.register: (String | Symbol name, Array[Integer] | String rgb_or_hex) -> void
+
   # Sequence a string with ANSI escape codes
   #
   # @author {https://aaronmallen.me Aaron Allen}

metadata

@@ -1,10 +1,11 @@
 --- !ruby/object:Gem::Specification
 name: sai
 version: !ruby/object:Gem::Version
-  version: 0.3.1
+  version: 0.3.2
 platform: ruby
 authors:
 - Aaron Allen
+autorequire:
 bindir: bin
 cert_chain: []
 date: 2025-01-22 00:00:00.000000000 Z
@@ -79,10 +80,11 @@ licenses:
 - MIT
 metadata:
   bug_tracker_uri: https://github.com/aaronmallen/sai/issues
-  changelog_uri: https://github.com/aaronmallen/sai/releases/tag/0.3.1
+  changelog_uri: https://github.com/aaronmallen/sai/releases/tag/0.3.2
   homepage_uri: https://github.com/aaronmallen/sai
   rubygems_mfa_required: 'true'
-  source_code_uri: https://github.com/aaronmallen/sai/tree/0.3.1
+  source_code_uri: https://github.com/aaronmallen/sai/tree/0.3.2
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -97,7 +99,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.2
+rubygems_version: 3.3.27
+signing_key:
 specification_version: 4
 summary: An elegant color management system for crafting sophisticated CLI applications
 test_files: []