sai 0.1.0 → 0.3.0

data/lib/sai.rb

@@ -1,9 +1,15 @@
 # frozen_string_literal: true
 
+require 'sai/ansi'
+require 'sai/ansi/sequence_processor'
+require 'sai/ansi/sequenced_string'
+require 'sai/conversion/color_sequence'
+require 'sai/conversion/rgb'
 require 'sai/decorator'
+require 'sai/mode_selector'
 require 'sai/support'
 require 'sai/terminal/capabilities'
-require 'singleton'
+require 'sai/terminal/color_mode'
 
 # An elegant color management system for crafting sophisticated CLI applications
 #
@@ -16,6 +22,7 @@ require 'singleton'
 # 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
 #
@@ -23,7 +30,7 @@ require 'singleton'
 # 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
 #
@@ -48,100 +55,139 @@ module Sai
     ignored_decorator_methods = %i[apply call decorate encode]
     Decorator.instance_methods(false).reject { |m| ignored_decorator_methods.include?(m) }.each do |method|
       define_method(method) do |*arguments, **keyword_arguments|
-        Decorator.new(send(:color_mode)).public_send(method, *arguments, **keyword_arguments)
+        Decorator.new(mode: Sai.mode.auto).public_send(method, *arguments, **keyword_arguments)
       end
     end
 
+    # 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 mode
+      ModeSelector
+    end
+
     # @rbs!
-    #   def black: () -> self
-    #   def blink: () -> self
-    #   def blue: () -> self
-    #   def bold: () -> self
-    #   def bright_black: () -> self
-    #   def bright_blue: () -> self
-    #   def bright_cyan: () -> self
-    #   def bright_green: () -> self
-    #   def bright_magenta: () -> self
-    #   def bright_red: () -> self
-    #   def bright_white: () -> self
-    #   def bright_yellow: () -> self
-    #   def conceal: () -> self
-    #   def cyan: () -> self
-    #   def dim: () -> self
-    #   def green: () -> self
-    #   def italic: () -> self
-    #   def magenta: () -> self
-    #   def no_blink: () -> self
-    #   def no_conceal: () -> self
-    #   def no_italic: () -> self
-    #   def no_reverse: () -> self
-    #   def no_strike: () -> self
-    #   def no_underline: () -> self
-    #   def normal_intensity: () -> self
-    #   def on_black: () -> self
-    #   def on_blue: () -> self
-    #   def on_bright_black: () -> self
-    #   def on_bright_blue: () -> self
-    #   def on_bright_cyan: () -> self
-    #   def on_bright_green: () -> self
-    #   def on_bright_magenta: () -> self
-    #   def on_bright_red: () -> self
-    #   def on_bright_white: () -> self
-    #   def on_bright_yellow: () -> self
-    #   def on_cyan: () -> self
-    #   def on_green: () -> self
-    #   def on_magenta: () -> self
-    #   def on_red: () -> self
-    #   def on_white: () -> self
-    #   def on_yellow: () -> self
-    #   def rapid_blink: () -> self
-    #   def red: () -> self
-    #   def reverse: () -> self
-    #   def strike: () -> self
-    #   def underline: () -> self
-    #   def white: () -> self
-    #   def yellow: () -> self
+    #   def black: () -> Decorator
+    #   def blink: () -> Decorator
+    #   def blue: () -> Decorator
+    #   def bold: () -> Decorator
+    #   def bright_black: () -> Decorator
+    #   def bright_blue: () -> Decorator
+    #   def bright_cyan: () -> Decorator
+    #   def bright_green: () -> Decorator
+    #   def bright_magenta: () -> Decorator
+    #   def bright_red: () -> Decorator
+    #   def bright_white: () -> Decorator
+    #   def bright_yellow: () -> Decorator
+    #   def conceal: () -> Decorator
+    #   def cyan: () -> Decorator
+    #   def dim: () -> Decorator
+    #   def green: () -> Decorator
+    #   def italic: () -> Decorator
+    #   def magenta: () -> Decorator
+    #   def no_blink: () -> Decorator
+    #   def no_conceal: () -> Decorator
+    #   def no_italic: () -> Decorator
+    #   def no_reverse: () -> Decorator
+    #   def no_strike: () -> Decorator
+    #   def no_underline: () -> Decorator
+    #   def normal_intensity: () -> Decorator
+    #   def on_black: () -> Decorator
+    #   def on_blue: () -> Decorator
+    #   def on_bright_black: () -> Decorator
+    #   def on_bright_blue: () -> Decorator
+    #   def on_bright_cyan: () -> Decorator
+    #   def on_bright_green: () -> Decorator
+    #   def on_bright_magenta: () -> Decorator
+    #   def on_bright_red: () -> Decorator
+    #   def on_bright_white: () -> Decorator
+    #   def on_bright_yellow: () -> Decorator
+    #   def on_cyan: () -> Decorator
+    #   def on_green: () -> Decorator
+    #   def on_magenta: () -> Decorator
+    #   def on_red: () -> Decorator
+    #   def on_white: () -> Decorator
+    #   def on_yellow: () -> Decorator
+    #   def rapid_blink: () -> Decorator
+    #   def red: () -> Decorator
+    #   def reverse: () -> Decorator
+    #   def strike: () -> Decorator
+    #   def underline: () -> Decorator
+    #   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 sequence(text)
+      ANSI::SequencedString.new(text)
+    end
 
     # 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
+    # @rbs () -> singleton(Support)
     def support
-      @support ||= Support.new(color_mode).freeze
+      Support
     end
+  end
 
-    private
-
-    # Detect the color capabilities of the terminal
-    #
-    # @author {https://aaronmallen.me Aaron Allen}
-    # @since unreleased
-    #
-    # @api private
-    #
-    # @return [Integer] the color mode
-    # @rbs () -> Integer
-    def color_mode
-      Thread.current[:sai_color_mode] ||= Terminal::Capabilities.detect_color_support
-    end
+  # A helper method that provides Sai color modes
+  #
+  # @author {https://aaronmallen.me Aaron Allen}
+  # @since 0.2.0
+  #
+  # @api public
+  #
+  # @example
+  #   class MyClass
+  #     include Sai
+  #   end
+  #
+  #   MyClass.new.color_mode.ansi #=> 2
+  #
+  # @return [ModeSelector] the mode selector
+  # @rbs () -> singleton(ModeSelector)
+  def color_mode
+    ModeSelector
   end
 
   # A helper method to initialize an instance of {Decorator}
   #
   # @author {https://aaronmallen.me Aaron Allen}
-  # @since unreleased
+  # @since 0.1.0
   #
   # @api public
   #
@@ -153,16 +199,21 @@ 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.new(Terminal::Capabilities.detect_color_support)
+  # @rbs (?mode: Integer) -> Decorator
+  def decorator(mode: Sai.mode.auto)
+    Decorator.new(mode:)
   end
 
   # The supported color modes for the terminal
   #
   # @author {https://aaronmallen.me Aaron Allen}
-  # @since unreleased
+  # @since 0.1.0
   #
   # @api public
   #
@@ -173,13 +224,13 @@ 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
+  # @rbs () -> singleton(Support)
   def terminal_color_support
-    Sai.support
+    Support
   end
 end

data/sig/manifest.yaml

@@ -0,0 +1,3 @@
+dependencies:
+  - name: forwardable
+  - name: strscan

data/sig/sai/ansi/sequence_processor.rbs

@@ -0,0 +1,253 @@
+# Generated from lib/sai/ansi/sequence_processor.rb with RBS::Inline
+
+module Sai
+  module ANSI
+    # Extract ANSI sequence information from a string
+    #
+    # @author {https://aaronmallen.me Aaron Allen}
+    # @since 0.3.0
+    #
+    # @api private
+    class SequenceProcessor
+      # The pattern to extract ANSI sequences from a string
+      #
+      # @author {https://aaronmallen.me Aaron Allen}
+      # @since 0.3.0
+      #
+      # @api private
+      #
+      # @return [Regexp] the pattern
+      SEQUENCE_PATTERN: Regexp
+
+      # Matches the code portion of style sequences
+      #
+      # @author {https://aaronmallen.me Aaron Allen}
+      # @since 0.3.0
+      #
+      # @api private
+      #
+      # @return [Regexp] the pattern
+      STYLE_CODE_PATTERN: Regexp
+
+      # Initialize a new instance of SequenceProcessor and parse the provided string
+      #
+      # @author {https://aaronmallen.me Aaron Allen}
+      # @since 0.3.0
+      #
+      # @api private
+      #
+      # @param string [String] the string to parse
+      #
+      # @return [Array<Hash{Symbol => Object}>] the segments
+      # @rbs (String string) -> Array[Hash[Symbol, untyped]]
+      def self.process: (String string) -> Array[Hash[Symbol, untyped]]
+
+      # Initialize a new instance of SequenceProcessor
+      #
+      # @author {https://aaronmallen.me Aaron Allen}
+      # @since 0.3.0
+      #
+      # @api private
+      #
+      # @param string [String] the string to parse
+      #
+      # @return [SequenceProcessor] the new instance of SequenceProcessor
+      # @rbs (String string) -> void
+      def initialize: (String string) -> void
+
+      # Parse a string and return a hash of segments
+      #
+      # @author {https://aaronmallen.me Aaron Allen}
+      # @since 0.3.0
+      #
+      # @api private
+      #
+      # @return [Array<Hash{Symbol => Object}>] the segments
+      # @rbs () -> Array[Hash[Symbol, untyped]]
+      def process: () -> Array[Hash[Symbol, untyped]]
+
+      private
+
+      # Applies 24-bit truecolor (e.g., 38;2;R;G;B or 48;2;R;G;B)
+      #
+      # @author {https://aaronmallen.me Aaron Allen}
+      # @since 0.3.0
+      #
+      # @api private
+      #
+      # @param codes_array [Array<Integer>]
+      # @param index [Integer]
+      #
+      # @return [Integer] the updated index (consumed 5 codes)
+      # @rbs (Array[Integer] codes_array, Integer index) -> Integer
+      def apply_24bit_color: (Array[Integer] codes_array, Integer index) -> Integer
+
+      # Applies 256-color mode (e.g., 38;5;160 or 48;5;21)
+      #
+      # @author {https://aaronmallen.me Aaron Allen}
+      # @since 0.3.0
+      #
+      # @api private
+      #
+      # @param codes_array [Array<Integer>]
+      # @param index [Integer]
+      #
+      # @return [Integer] the updated index (consumed 3 codes)
+      # @rbs (Array[Integer] codes_array, Integer index) -> Integer
+      def apply_256_color: (Array[Integer] codes_array, Integer index) -> Integer
+
+      # Applies the appropriate action for the provided ANSI sequence
+      #
+      # @author {https://aaronmallen.me Aaron Allen}
+      # @since 0.3.0
+      #
+      # @api private
+      #
+      # @param sequence [String] an ANSI sequence (e.g. "\e[31m", "\e[0m")
+      #
+      # @return [void]
+      # @rbs (String sequence) -> void
+      def apply_ansi_sequence: (String sequence) -> void
+
+      # Applies a basic color (FG or BG) in the range 30..37 (FG) or 40..47 (BG)
+      #
+      # @author {https://aaronmallen.me Aaron Allen}
+      # @since 0.3.0
+      #
+      # @api private
+      #
+      # @param code [Integer] the numeric color code
+      #
+      # @return [void]
+      # @rbs (Integer code) -> void
+      def apply_basic_color: (Integer code) -> void
+
+      # Parse all numeric codes in the provided string, applying them in order (just like a real ANSI terminal)
+      #
+      # @author {https://aaronmallen.me Aaron Allen}
+      # @since 0.3.0
+      #
+      # @api private
+      #
+      # @param codes_string [String] e.g. "38;5;160;48;5;21;1"
+      #
+      # @return [void]
+      # @rbs (String codes_string) -> void
+      def apply_codes: (String codes_string) -> void
+
+      # Applies a single code (or group) from the array. This might be:
+      #  - 0 => reset
+      #  - 30..37 => basic FG color
+      #  - 40..47 => basic BG color
+      #  - 38 or 48 => extended color sequence
+      #  - otherwise => style code (bold, underline, etc.)
+      #
+      # @author {https://aaronmallen.me Aaron Allen}
+      # @since 0.3.0
+      #
+      # @api private
+      #
+      # @param codes_array [Array<Integer>] the list of numeric codes
+      # @param index [Integer] the current index
+      #
+      # @return [Integer] the updated index after consuming needed codes
+      # @rbs (Array[Integer] codes_array, Integer index) -> Integer
+      def apply_single_code: (Array[Integer] codes_array, Integer index) -> Integer
+
+      # Applies a single style code (e.g. 1=bold, 2=dim, 4=underline, etc.) if it matches
+      #
+      # @author {https://aaronmallen.me Aaron Allen}
+      # @since 0.3.0
+      #
+      # @api private
+      #
+      # @param code [Integer] the numeric code to check
+      #
+      # @return [void]
+      # @rbs (Integer code) -> void
+      def apply_style_code: (Integer code) -> void
+
+      # Creates and returns a fresh, blank segment
+      #
+      # @author {https://aaronmallen.me Aaron Allen}
+      # @since 0.3.0
+      #
+      # @api private
+      #
+      # @return [Hash{Symbol => Object}] a new, empty segment
+      # @rbs () -> Hash[Symbol, untyped]
+      def blank_segment: () -> Hash[Symbol, untyped]
+
+      # Scans the string for ANSI sequences or individual characters
+      #
+      # @author {https://aaronmallen.me Aaron Allen}
+      # @since 0.3.0
+      #
+      # @api private
+      #
+      # @return [void]
+      # @rbs () -> void
+      def consume_tokens: () -> void
+
+      # Finalizes the current segment if any text is present, then resets it
+      #
+      # @author {https://aaronmallen.me Aaron Allen}
+      # @since 0.3.0
+      #
+      # @api private
+      #
+      # @return [void]
+      # @rbs () -> void
+      def finalize_segment_if_text!: () -> void
+
+      # Attempts to capture an ANSI sequence from the scanner If found, finalizes
+      # the current text segment and applies the sequence
+      #
+      # @author {https://aaronmallen.me Aaron Allen}
+      # @since 0.3.0
+      #
+      # @api private
+      #
+      # @return [Boolean] `true` if a sequence was found, `false` if otherwise
+      # @rbs () -> bool
+      def handle_ansi_sequence: () -> bool
+
+      # Reads a single character from the scanner and appends it to the current segment
+      #
+      # @author {https://aaronmallen.me Aaron Allen}
+      # @since 0.3.0
+      #
+      # @api private
+      #
+      # @return [void]
+      # @rbs () -> void
+      def handle_character: () -> void
+
+      # Parse extended color codes from the array, e.g. 38;5;160 (256-color) or 38;2;R;G;B (24-bit),
+      # and apply them to foreground or background
+      #
+      # @author {https://aaronmallen.me Aaron Allen}
+      # @since 0.3.0
+      #
+      # @api private
+      #
+      # @param codes_array [Array<Integer>] the array of codes
+      # @param index [Integer] the current position (where we saw 38 or 48)
+      #
+      # @return [Integer] the updated position in the codes array
+      # @rbs (Array[Integer] codes_array, Integer index) -> Integer
+      def parse_extended_color: (Array[Integer] codes_array, Integer index) -> Integer
+
+      # Resets the current segment to a fresh, blank state
+      #
+      # @author {https://aaronmallen.me Aaron Allen}
+      # @since 0.3.0
+      #
+      # @api private
+      #
+      # @return [void]
+      # @rbs () -> void
+      def reset_segment!: () -> void
+    end
+  end
+end