sai 0.1.0 → 0.3.0

data/sig/sai/support.rbs

@@ -4,27 +4,38 @@ module Sai
   # Determine the color capabilities of the terminal
   #
   # @author {https://aaronmallen.me Aaron Allen}
-  # @since unreleased
+  # @since 0.1.0
   #
   # @api public
-  class Support
-    # Initialize a new instance of Support
+  module Support
+    # Check if the terminal supports 256 colors (8-bit)
     #
     # @author {https://aaronmallen.me Aaron Allen}
-    # @since unreleased
+    # @since 0.1.0
     #
-    # @api private
+    # @api public
     #
-    # @param color_mode [Integer] the color mode
+    # @example Check if the terminal supports 256 colors
+    #   Sai.advanced? # => true
     #
-    # @return [Support] the new instance of support
-    # @rbs (Integer color_mode) -> void
-    def initialize: (Integer color_mode) -> void
+    # @return [Boolean] `true` if the terminal supports 256 colors (8-bit), otherwise `false`
+    # @rbs () -> bool
+    def self.advanced?: () -> bool
+
+    alias self.color256? self.advanced?
+
+    alias self.colour256? self.advanced?
+
+    alias self.eight_bit? self.advanced?
+
+    alias self.two_hundred_fifty_six_color? self.advanced?
+
+    alias self.two_hundred_fifty_six_colour? self.advanced?
 
     # Check if the terminal supports ANSI colors (4-bit)
     #
     # @author {https://aaronmallen.me Aaron Allen}
-    # @since unreleased
+    # @since 0.1.0
     #
     # @api public
     #
@@ -33,16 +44,22 @@ module Sai
     #
     # @return [Boolean] `true` if the terminal supports ANSI colors (4-bit), otherwise `false`
     # @rbs () -> bool
-    def ansi?: () -> bool
+    def self.ansi?: () -> bool
+
+    alias self.color16? self.ansi?
 
-    alias bit4? ansi?
+    alias self.colour16? self.ansi?
 
-    alias four_bit? ansi?
+    alias self.four_bit? self.ansi?
+
+    alias self.sixteen_color? self.ansi?
+
+    alias self.sixteen_colour? self.ansi?
 
     # Check if the terminal supports basic colors (3-bit)
     #
     # @author {https://aaronmallen.me Aaron Allen}
-    # @since unreleased
+    # @since 0.1.0
     #
     # @api public
     #
@@ -51,32 +68,22 @@ module Sai
     #
     # @return [Boolean] `true` if the terminal supports basic colors (3-bit), otherwise `false`
     # @rbs () -> bool
-    def basic?: () -> bool
+    def self.basic?: () -> bool
 
-    alias bit3? basic?
+    alias self.color8? self.basic?
 
-    alias three_bit? basic?
+    alias self.colour8? self.basic?
 
-    # Check if the terminal supports 256 colors (8-bit)
-    #
-    # @author {https://aaronmallen.me Aaron Allen}
-    # @since unreleased
-    #
-    # @api public
-    #
-    # @example Check if the terminal supports 256 colors
-    #   Sai.bit_8? # => true
-    #
-    # @return [Boolean] `true` if the terminal supports 256 colors (8-bit), otherwise `false`
-    # @rbs () -> bool
-    def bit8?: () -> bool
+    alias self.eight_color? self.basic?
+
+    alias self.eight_colour? self.basic?
 
-    alias eight_bit? bit8?
+    alias self.three_bit? self.basic?
 
     # Check if the terminal supports color output
     #
     # @author {https://aaronmallen.me Aaron Allen}
-    # @since unreleased
+    # @since 0.1.0
     #
     # @api public
     #
@@ -85,12 +92,12 @@ module Sai
     #
     # @return [Boolean] `true` if the terminal supports color output, otherwise `false`
     # @rbs () -> bool
-    def color?: () -> bool
+    def self.color?: () -> bool
 
     # Check if the terminal supports true color (24-bit)
     #
     # @author {https://aaronmallen.me Aaron Allen}
-    # @since unreleased
+    # @since 0.1.0
     #
     # @api public
     #
@@ -99,10 +106,16 @@ module Sai
     #
     # @return [Boolean] `true` if the terminal supports true color (24-bit), otherwise `false`
     # @rbs () -> bool
-    def true_color?: () -> bool
+    def self.true_color?: () -> bool
+
+    alias self.color16m? self.true_color?
+
+    alias self.colour16m? self.true_color?
+
+    alias self.sixteen_million_color? self.true_color?
 
-    alias bit24? true_color?
+    alias self.sixteen_million_colour? self.true_color?
 
-    alias twenty_four_bit? true_color?
+    alias self.twenty_for_bit? self.true_color?
   end
 end

data/sig/sai/terminal/capabilities.rbs

@@ -5,14 +5,14 @@ module Sai
     # Detect the color capabilities of the terminal
     #
     # @author {https://aaronmallen.me Aaron Allen}
-    # @since unreleased
+    # @since 0.1.0
     #
     # @api private
     module Capabilities
       # Detect the color capabilities of the current terminal
       #
       # @author {https://aaronmallen.me Aaron Allen}
-      # @since unreleased
+      # @since 0.1.0
       #
       # @api private
       #
@@ -20,43 +20,43 @@ module Sai
       # @rbs () -> Integer
       def self.detect_color_support: () -> Integer
 
-      # Check for ANSI color support
+      # Check for 256 color (8-bit) support
       #
       # @author {https://aaronmallen.me Aaron Allen}
-      # @since unreleased
+      # @since 0.1.0
       #
       # @api private
       #
-      # @return [Boolean] `true` if the terminal supports basic ANSI colors, otherwise `false`
+      # @return [Boolean] `true` if the terminal supports 256 colors, otherwise `false`
       # @rbs () -> bool
-      private def self.ansi?: () -> bool
+      private def self.advanced?: () -> bool
 
-      # Check for basic color support
+      # Check for ANSI color support
       #
       # @author {https://aaronmallen.me Aaron Allen}
-      # @since unreleased
+      # @since 0.1.0
       #
       # @api private
       #
-      # @return [Boolean] `true` if the terminal supports basic colors, otherwise `false`
+      # @return [Boolean] `true` if the terminal supports basic ANSI colors, otherwise `false`
       # @rbs () -> bool
-      private def self.basic?: () -> bool
+      private def self.ansi?: () -> bool
 
-      # Check for 256 color (8-bit) support
+      # Check for basic color support
       #
       # @author {https://aaronmallen.me Aaron Allen}
-      # @since unreleased
+      # @since 0.1.0
       #
       # @api private
       #
-      # @return [Boolean] `true` if the terminal supports 256 colors, otherwise `false`
+      # @return [Boolean] `true` if the terminal supports basic colors, otherwise `false`
       # @rbs () -> bool
-      private def self.bit8?: () -> bool
+      private def self.basic?: () -> bool
 
       # Check for NO_COLOR environment variable
       #
       # @author {https://aaronmallen.me Aaron Allen}
-      # @since unreleased
+      # @since 0.1.0
       #
       # @api private
       #
@@ -69,7 +69,7 @@ module Sai
       # Check for true color (24-bit) support
       #
       # @author {https://aaronmallen.me Aaron Allen}
-      # @since unreleased
+      # @since 0.1.0
       #
       # @api private
       #

data/sig/sai/terminal/color_mode.rbs

@@ -5,14 +5,14 @@ module Sai
     # Represents different color support levels for terminal interfaces
     #
     # @author {https://aaronmallen.me Aaron Allen}
-    # @since unreleased
+    # @since 0.1.0
     #
     # @api private
     module ColorMode
       # The terminal does not support color output
       #
       # @author {https://aaronmallen.me Aaron Allen}
-      # @since unreleased
+      # @since 0.1.0
       #
       # @api private
       #
@@ -22,7 +22,7 @@ module Sai
       # The terminal supports 8 colors (3-bit)
       #
       # @author {https://aaronmallen.me Aaron Allen}
-      # @since unreleased
+      # @since 0.1.0
       #
       # @api private
       #
@@ -32,7 +32,7 @@ module Sai
       # The terminal supports 16 colors (4-bit)
       #
       # @author {https://aaronmallen.me Aaron Allen}
-      # @since unreleased
+      # @since 0.1.0
       #
       # @api private
       #
@@ -42,17 +42,17 @@ module Sai
       # The terminal supports 256 colors (8-bit)
       #
       # @author {https://aaronmallen.me Aaron Allen}
-      # @since unreleased
+      # @since 0.1.0
       #
       # @api private
       #
       # @return [Integer] the color mode
-      BIT8: Integer
+      ADVANCED: Integer
 
       # The terminal supports 16 million colors (24-bit)
       #
       # @author {https://aaronmallen.me Aaron Allen}
-      # @since unreleased
+      # @since 0.1.0
       #
       # @api private
       #

data/sig/sai.rbs

@@ -11,6 +11,7 @@
 # adaptive color to your terminal interfaces
 #
 # When included in a class or module, Sai provides the following instance methods:
+# * {#color_mode} - Returns an interface to select Sai color modes
 # * {#decorator} - Returns a new instance of {Decorator} for method chaining
 # * {#terminal_color_support} - Returns the color support capabilities of the current terminal
 #
@@ -18,7 +19,7 @@
 # decorations (apply, call, decorate, encode). These methods are directly delegated to a new {Decorator} instance
 #
 # @author {https://aaronmallen.me Aaron Allen}
-# @since unreleased
+# @since 0.1.0
 #
 # @api public
 #
@@ -39,135 +40,172 @@
 #
 #   Sai.support.true_color? # => true
 module Sai
-  def black: () -> self
+  # The Sai {ModeSelector mode selector}
+  #
+  # @author {https://aaronmallen.me Aaron Allen}
+  # @since 0.2.0
+  #
+  # @api public
+  #
+  # @example
+  #   Sai.mode.auto #=> 4
+  #
+  # @return [ModeSelector] the mode selector
+  # @rbs () -> singleton(ModeSelector)
+  def self.mode: () -> singleton(ModeSelector)
 
-  def blink: () -> self
+  def black: () -> Decorator
 
-  def blue: () -> self
+  def blink: () -> Decorator
 
-  def bold: () -> self
+  def blue: () -> Decorator
 
-  def bright_black: () -> self
+  def bold: () -> Decorator
 
-  def bright_blue: () -> self
+  def bright_black: () -> Decorator
 
-  def bright_cyan: () -> self
+  def bright_blue: () -> Decorator
 
-  def bright_green: () -> self
+  def bright_cyan: () -> Decorator
 
-  def bright_magenta: () -> self
+  def bright_green: () -> Decorator
 
-  def bright_red: () -> self
+  def bright_magenta: () -> Decorator
 
-  def bright_white: () -> self
+  def bright_red: () -> Decorator
 
-  def bright_yellow: () -> self
+  def bright_white: () -> Decorator
 
-  def conceal: () -> self
+  def bright_yellow: () -> Decorator
 
-  def cyan: () -> self
+  def conceal: () -> Decorator
 
-  def dim: () -> self
+  def cyan: () -> Decorator
 
-  def green: () -> self
+  def dim: () -> Decorator
 
-  def italic: () -> self
+  def green: () -> Decorator
 
-  def magenta: () -> self
+  def italic: () -> Decorator
 
-  def no_blink: () -> self
+  def magenta: () -> Decorator
 
-  def no_conceal: () -> self
+  def no_blink: () -> Decorator
 
-  def no_italic: () -> self
+  def no_conceal: () -> Decorator
 
-  def no_reverse: () -> self
+  def no_italic: () -> Decorator
 
-  def no_strike: () -> self
+  def no_reverse: () -> Decorator
 
-  def no_underline: () -> self
+  def no_strike: () -> Decorator
 
-  def normal_intensity: () -> self
+  def no_underline: () -> Decorator
 
-  def on_black: () -> self
+  def normal_intensity: () -> Decorator
 
-  def on_blue: () -> self
+  def on_black: () -> Decorator
 
-  def on_bright_black: () -> self
+  def on_blue: () -> Decorator
 
-  def on_bright_blue: () -> self
+  def on_bright_black: () -> Decorator
 
-  def on_bright_cyan: () -> self
+  def on_bright_blue: () -> Decorator
 
-  def on_bright_green: () -> self
+  def on_bright_cyan: () -> Decorator
 
-  def on_bright_magenta: () -> self
+  def on_bright_green: () -> Decorator
 
-  def on_bright_red: () -> self
+  def on_bright_magenta: () -> Decorator
 
-  def on_bright_white: () -> self
+  def on_bright_red: () -> Decorator
 
-  def on_bright_yellow: () -> self
+  def on_bright_white: () -> Decorator
 
-  def on_cyan: () -> self
+  def on_bright_yellow: () -> Decorator
 
-  def on_green: () -> self
+  def on_cyan: () -> Decorator
 
-  def on_magenta: () -> self
+  def on_green: () -> Decorator
 
-  def on_red: () -> self
+  def on_magenta: () -> Decorator
 
-  def on_white: () -> self
+  def on_red: () -> Decorator
 
-  def on_yellow: () -> self
+  def on_white: () -> Decorator
 
-  def rapid_blink: () -> self
+  def on_yellow: () -> Decorator
 
-  def red: () -> self
+  def rapid_blink: () -> Decorator
 
-  def reverse: () -> self
+  def red: () -> Decorator
 
-  def strike: () -> self
+  def reverse: () -> Decorator
 
-  def underline: () -> self
+  def strike: () -> Decorator
 
-  def white: () -> self
+  def underline: () -> Decorator
 
-  def yellow: () -> self
+  def white: () -> Decorator
+
+  def yellow: () -> Decorator
+
+  # Sequence a string with ANSI escape codes
+  #
+  # @author {https://aaronmallen.me Aaron Allen}
+  # @since 0.3.0
+  #
+  # @api public
+  #
+  # @example Sequence a string with ANSI escape codes
+  #   Sai.sequence("\e[38;2;205;0;0mHello, World!\e[0m") #=> #<Sai::ANSI::SequencedString:0x123>
+  #
+  # @param text [String] the text to sequence
+  #
+  # @return [ANSI::SequencedString] the sequenced string
+  # @rbs (String text) -> ANSI::SequencedString
+  def self.sequence: (String text) -> ANSI::SequencedString
 
   # The supported color modes for the terminal
   #
   # @author {https://aaronmallen.me Aaron Allen}
-  # @since unreleased
+  # @since 0.1.0
   #
   # @api public
   #
   # @example Check the color support of the terminal
   #   Sai.support.ansi? # => true
   #   Sai.support.basic? # => true
-  #   Sai.support.bit8? # => true
+  #   Sai.support.advanced? # => true
   #   Sai.support.no_color? # => false
   #   Sai.support.true_color? # => true
   #
   # @return [Support] the color support
-  # @rbs () -> Support
-  def self.support: () -> Support
+  # @rbs () -> singleton(Support)
+  def self.support: () -> singleton(Support)
 
-  # Detect the color capabilities of the terminal
+  # A helper method that provides Sai color modes
   #
   # @author {https://aaronmallen.me Aaron Allen}
-  # @since unreleased
+  # @since 0.2.0
   #
-  # @api private
+  # @api public
   #
-  # @return [Integer] the color mode
-  # @rbs () -> Integer
-  private def self.color_mode: () -> Integer
+  # @example
+  #   class MyClass
+  #     include Sai
+  #   end
+  #
+  #   MyClass.new.color_mode.ansi #=> 2
+  #
+  # @return [ModeSelector] the mode selector
+  # @rbs () -> singleton(ModeSelector)
+  def color_mode: () -> singleton(ModeSelector)
 
   # A helper method to initialize an instance of {Decorator}
   #
   # @author {https://aaronmallen.me Aaron Allen}
-  # @since unreleased
+  # @since 0.1.0
   #
   # @api public
   #
@@ -179,14 +217,19 @@ module Sai
   #   MyClass.new.decorator.blue.on_red.bold.decorate('Hello, world!')
   #   #=> "\e[38;5;21m\e[48;5;160m\e[1mHello, world!\e[0m"
   #
+  #   MyClass.new.decorator(mode: Sai.mode.no_color)
+  #   #=> "Hello, world!"
+  #
+  # @param mode [Integer] the color mode to use
+  #
   # @return [Decorator] the Decorator instance
-  # @rbs () -> Decorator
-  def decorator: () -> Decorator
+  # @rbs (?mode: Integer) -> Decorator
+  def decorator: (?mode: Integer) -> Decorator
 
   # The supported color modes for the terminal
   #
   # @author {https://aaronmallen.me Aaron Allen}
-  # @since unreleased
+  # @since 0.1.0
   #
   # @api public
   #
@@ -197,11 +240,11 @@ module Sai
   #
   #   MyClass.new.terminal_color_support.ansi? # => true
   #   MyClass.new.terminal_color_support.basic? # => true
-  #   MyClass.new.terminal_color_support.bit8? # => true
+  #   MyClass.new.terminal_color_support.advanced? # => true
   #   MyClass.new.terminal_color_support.no_color? # => false
   #   MyClass.new.terminal_color_support.true_color? # => true
   #
   # @return [Support] the color support
-  # @rbs () -> Support
-  def terminal_color_support: () -> Support
+  # @rbs () -> singleton(Support)
+  def terminal_color_support: () -> singleton(Support)
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: sai
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Aaron Allen
 bindir: bin
 cert_chain: []
-date: 2025-01-19 00:00:00.000000000 Z
+date: 2025-01-20 00:00:00.000000000 Z
 dependencies: []
 description: |-
   Sai (彩) - meaning 'coloring' or 'paint' in Japanese - is a powerful and intuitive system for managing color output in command-line applications. Drawing inspiration from traditional Japanese artistic techniques, Sai brings vibrancy and harmony to terminal interfaces through its sophisticated color management.
@@ -22,19 +22,27 @@ files:
 - CHANGELOG.md
 - LICENSE
 - README.md
+- docs/USAGE.md
 - lib/sai.rb
 - lib/sai/ansi.rb
+- lib/sai/ansi/sequence_processor.rb
+- lib/sai/ansi/sequenced_string.rb
 - lib/sai/conversion/color_sequence.rb
 - lib/sai/conversion/rgb.rb
 - lib/sai/decorator.rb
+- lib/sai/mode_selector.rb
 - lib/sai/support.rb
 - lib/sai/terminal/capabilities.rb
 - lib/sai/terminal/color_mode.rb
+- sig/manifest.yaml
 - sig/sai.rbs
 - sig/sai/ansi.rbs
+- sig/sai/ansi/sequence_processor.rbs
+- sig/sai/ansi/sequenced_string.rbs
 - sig/sai/conversion/color_sequence.rbs
 - sig/sai/conversion/rgb.rbs
 - sig/sai/decorator.rbs
+- sig/sai/mode_selector.rbs
 - sig/sai/support.rbs
 - sig/sai/terminal/capabilities.rbs
 - sig/sai/terminal/color_mode.rbs
@@ -43,10 +51,10 @@ licenses:
 - MIT
 metadata:
   bug_tracker_uri: https://github.com/aaronmallen/sai/issues
-  changelog_uri: https://github.com/aaronmallen/sai/releases/tag/0.1.0
+  changelog_uri: https://github.com/aaronmallen/sai/releases/tag/0.3.0
   homepage_uri: https://github.com/aaronmallen/sai
   rubygems_mfa_required: 'true'
-  source_code_uri: https://github.com/aaronmallen/sai/tree/0.1.0
+  source_code_uri: https://github.com/aaronmallen/sai/tree/0.3.0
 rdoc_options: []
 require_paths:
 - lib