sai 0.2.0 → 0.3.0

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

data/sig/sai/ansi/sequenced_string.rbs

@@ -0,0 +1,380 @@
+# Generated from lib/sai/ansi/sequenced_string.rb with RBS::Inline
+
+module Sai
+  module ANSI
+    # A representation of a ANSI encoded string and its individual {SequencedString::Segment segments}
+    #
+    # @author {https://aaronmallen.me Aaron Allen}
+    # @since 0.3.0
+    #
+    # @api public
+    class SequencedString
+      include Enumerable[Segment]
+
+      def each: () { (Segment) -> void } -> SequencedString
+
+      def empty?: () -> bool
+
+      def map: () { (Segment) -> untyped } -> Array[untyped]
+
+      def size: () -> Integer
+
+      # Initialize a new instance of SequencedString
+      #
+      # @author {https://aaronmallen.me Aaron Allen}
+      # @since 0.3.0
+      #
+      # @api private
+      #
+      # @param string [String] the sequenced string to Segment
+      #
+      # @return [SequencedString] the new instance of SequencedString
+      # @rbs (String string) -> void
+      def initialize: (String string) -> void
+
+      # Fetch a segment by index
+      #
+      # @author {https://aaronmallen.me Aaron Allen}
+      # @since 0.3.0
+      #
+      # @api public
+      #
+      # @example
+      #   string = SequencedString.new("\e[31mred\e[0m")
+      #   string[0] #=> #<SequencedString::Segment:0x00007f9b3b8b3e10>
+      #
+      # @param index [Integer] the index of the segment to fetch
+      #
+      # @return [Segment, nil] the segment at the index
+      # @rbs (Integer index) -> Segment?
+      def []: (Integer index) -> Segment?
+
+      # Compare the SequencedString to another object
+      #
+      # @author {https://aaronmallen.me Aaron Allen}
+      # @since 0.3.0
+      #
+      # @api public
+      #
+      # @example
+      #   string = "\e[31mred\e[0m"
+      #   SequencedString.new(string) == string #=> true
+      #
+      # @param other [Object] the object to compare to
+      #
+      # @return [Boolean] `true` if the SequencedString is equal to the other object, `false` otherwise
+      # @rbs (untyped other) -> bool
+      def ==: (untyped other) -> bool
+
+      # Combine a sequenced string with another object
+      #
+      # @author {https://aaronmallen.me Aaron Allen}
+      # @since 0.3.0
+      #
+      # @api public
+      #
+      # @example
+      #   sequenced_string = SequencedString.new("\e[31mred\e[0m")
+      #   sequenced_string + " is a color" #=> "\e[31mred\e[0m is a color"
+      #
+      # @param other [Object] the object to combine with
+      #
+      # @return [SequencedString] the combined string
+      # @rbs (untyped other) -> SequencedString
+      def +: (untyped other) -> SequencedString
+
+      # Return just the raw text content with **no ANSI sequences**
+      #
+      # @author {https://aaronmallen.me Aaron Allen}
+      # @since 0.3.0
+      #
+      # @api public
+      #
+      # @example
+      #   string = SequencedString.new("Normal \e[31mred\e[0m")
+      #   string.stripped #=> "Normal red"
+      #
+      # @return [String] the concatenation of all segment text without color or style
+      def stripped: () -> untyped
+
+      # Return the fully reconstructed string with **all ANSI sequences** (foreground, background, style)
+      #
+      # @author {https://aaronmallen.me Aaron Allen}
+      # @since 0.3.0
+      #
+      # @api public
+      #
+      # @example
+      #   string = SequencedString.new("\e[31mred\e[0m")
+      #   string.to_s #=> "\e[31mred\e[0m"
+      #
+      # @return [String]
+      def to_s: () -> untyped
+
+      alias to_str to_s
+
+      # Return a string with everything except **background** color sequences removed
+      #
+      # @author {https://aaronmallen.me Aaron Allen}
+      # @since 0.3.0
+      #
+      # @api public
+      #
+      # @example Remove all background colors
+      #   string = SequencedString.new("\e[41mBack\e[0m \e[1mBold\e[0m")
+      #   string.without_background #=> "\e[1mBold\e[0m"
+      #
+      # @return [SequencedString] new instance with background colors removed
+      # @rbs () -> SequencedString
+      def without_background: () -> SequencedString
+
+      # Return a string containing *style* sequences but **no foreground or background colors**
+      #
+      # @author {https://aaronmallen.me Aaron Allen}
+      # @since 0.3.0
+      #
+      # @api public
+      #
+      # @example Remove all colors
+      #   string = SequencedString.new("\e[31mred\e[0m \e[1mbold\e[0m")
+      #   string.without_color #=> "\e[1mbold\e[0m"
+      #
+      # @return [SequencedString] new instance with all colors removed
+      # @rbs () -> SequencedString
+      def without_color: () -> SequencedString
+
+      # Return a string with everything except **foreground** color sequences removed
+      #
+      # @author {https://aaronmallen.me Aaron Allen}
+      # @since 0.3.0
+      #
+      # @api public
+      #
+      # @example Remove all foreground colors
+      #   string = SequencedString.new("\e[41mBack\e[0m \e[1mBold\e[0m")
+      #   string.without_foreground #=> "\e[41mBack\e[0m \e[1mBold\e[0m"
+      #
+      # @return [SequencedString] new instance with foreground colors removed
+      # @rbs () -> SequencedString
+      def without_foreground: () -> SequencedString
+
+      # Return a string with specified styles removed
+      #
+      # @author {https://aaronmallen.me Aaron Allen}
+      # @since 0.3.0
+      #
+      # @api public
+      #
+      # @example Remove all styles
+      #   string = SequencedString.new("\e[31mred\e[0m \e[1mbold\e[0m")
+      #   string.without_style #=> "\e[31mred\e[0m"
+      #
+      # @example Remove specific style
+      #   string = SequencedString.new("\e[1;4mBold and Underlined\e[0m")
+      #   string.without_style(:bold) #=> "\e[4mUnderlined\e[0m"
+      #
+      # @param styles [Array<Symbol>] specific styles to remove (default: all)
+      #
+      # @return [SequencedString] new instance with specified styles removed
+      def without_style: (*untyped styles) -> untyped
+
+      private
+
+      # Build the color sequences for a segment
+      #
+      # @author {https://aaronmallen.me Aaron Allen}
+      # @since 0.3.0
+      #
+      # @api private
+      #
+      # @param segment [Segment] the segment to build color sequences for
+      # @param skip_background [Boolean] whether to skip background colors
+      # @param skip_foreground [Boolean] whether to skip foreground colors
+      #
+      # @return [Array<String>] the color sequences
+      # @rbs (Segment segment, ?skip_background: bool, ?skip_foreground: bool) -> Array[String]
+      def build_color_sequences: (Segment segment, ?skip_background: bool, ?skip_foreground: bool) -> Array[String]
+
+      # Build a string with specified parts skipped
+      #
+      # @author {https://aaronmallen.me Aaron Allen}
+      # @since 0.3.0
+      #
+      # @api private
+      #
+      # @param skip_background [Boolean] whether to skip background colors
+      # @param skip_foreground [Boolean] whether to skip foreground colors
+      # @param skip_styles [Array<Symbol>] styles to skip
+      #
+      # @return [String] the built string
+      # @rbs (?skip_background: bool, ?skip_foreground: bool, ?skip_styles: Array[Symbol]) -> String
+      def build_string: (?skip_background: bool, ?skip_foreground: bool, ?skip_styles: Array[Symbol]) -> String
+
+      # Build the style sequences for a segment
+      #
+      # @author {https://aaronmallen.me Aaron Allen}
+      # @since 0.3.0
+      #
+      # @api private
+      #
+      # @param segment [Segment] the segment to build style sequences for
+      # @param skip_styles [Array<Symbol>] styles to skip
+      #
+      # @return [Array<String>] the style sequences
+      # @rbs (Segment segment, ?skip_styles: Array[Symbol]) -> Array[String]
+      def build_style_sequences: (Segment segment, ?skip_styles: Array[Symbol]) -> Array[String]
+
+      # A segment of an ANSI encoded string
+      #
+      # @author {https://aaronmallen.me Aaron Allen}
+      # @since 0.3.0
+      #
+      # @api public
+      class Segment
+        # The background color sequences for the Segment
+        #
+        # @author {https://aaronmallen.me Aaron Allen}
+        # @since 0.3.0
+        #
+        # @api public
+        #
+        # @return [String, nil] the background color sequences
+        attr_reader background: String?
+
+        # The foreground color sequences for the Segment
+        #
+        # @author {https://aaronmallen.me Aaron Allen}
+        # @since 0.3.0
+        #
+        # @api public
+        #
+        # @return [String, nil] the foreground color sequences
+        attr_reader foreground: String?
+
+        # The {Location} of the encoded string within the {SequencedString}
+        #
+        # @author {https://aaronmallen.me Aaron Allen}
+        # @since 0.3.0
+        #
+        # @api public
+        #
+        # @return [Location] the {Location}
+        attr_reader encoded_location: Location
+
+        alias encoded_loc encoded_location
+
+        # The {Location} of the encoded string without it's encoding within the {SequencedString}
+        #
+        # @author {https://aaronmallen.me Aaron Allen}
+        # @since 0.3.0
+        #
+        # @api public
+        #
+        # @return [Location] the {Location}
+        attr_reader stripped_location: Location
+
+        alias stripped_loc stripped_location
+
+        # The style sequences (bold, underline, etc...) for the segment
+        #
+        # @author {https://aaronmallen.me Aaron Allen}
+        # @since 0.3.0
+        #
+        # @api public
+        #
+        # @return [Array<String>] the style sequences
+        attr_reader styles: Array[String]
+
+        # The raw text of the Segment without any of its ANSI sequences
+        #
+        # @author {https://aaronmallen.me Aaron Allen}
+        # @since 0.3.0
+        #
+        # @api public
+        #
+        # @return [String]
+        attr_reader text: String
+
+        # Initialize a new instance of Segment
+        #
+        # @author {https://aaronmallen.me Aaron Allen}
+        # @since 0.3.0
+        #
+        # @api private
+        #
+        # @param options [Hash{Symbol => Object}] the options to initialize the Segment with
+        # @option options background [String, nil] the Segment {#background}
+        # @option options foreground [String, nil] the Segment {#foreground}
+        # @option options encoded_end [Integer] the {Location#end_position end_position} of the Segment
+        #   {#encoded_location}
+        # @option options encoded_start [Integer] the {Location#start_position start_position} of the Segment
+        #   {#encoded_location}
+        # @option options stripped_end [Integer] the {Location#end_position end_position} of the Segment
+        #   {#stripped_location}
+        # @option options stripped_start [Integer] the {Location#start_position start_position} of the Segment
+        #   {#stripped_location}
+        # @option options styles [Array<String>] the Segment {#styles}
+        # @option options text [String] the Segment {#text}
+        #
+        # @return [Segment] the new instance of Segment
+        # @rbs (
+        #   ?background: String?,
+        #   ?foreground: String?,
+        #   encoded_end: Integer,
+        #   encoded_start: Integer,
+        #   stripped_end: Integer,
+        #   stripped_start: Integer,
+        #   ?styles: Array[String],
+        #   text: String
+        #   ) -> void
+        def initialize: (encoded_end: Integer, encoded_start: Integer, stripped_end: Integer, stripped_start: Integer, text: String, ?background: String?, ?foreground: String?, ?styles: Array[String]) -> void
+
+        # The location of the {Segment} within a {SequencedString}
+        #
+        # @author {https://aaronmallen.me Aaron Allen}
+        # @since 0.3.0
+        #
+        # @api public
+        class Location
+          # The ending position of the Location
+          #
+          # @author {https://aaronmallen.me Aaron Allen}
+          # @since 0.3.0
+          #
+          # @api public
+          #
+          # @return [Integer] the end position
+          attr_reader end_position: Integer
+
+          alias end_pos end_position
+
+          # The starting position of the Location
+          #
+          # @author {https://aaronmallen.me Aaron Allen}
+          # @since 0.3.0
+          #
+          # @api public
+          #
+          # @return [Integer] the start position
+          attr_reader start_position: Integer
+
+          alias start_pos start_position
+
+          # Initialize a new instance of Location
+          #
+          # @author {https://aaronmallen.me Aaron Allen}
+          # @since 0.3.0
+          #
+          # @api private
+          #
+          # @param end_position [Integer] the {#end_position} of the location
+          # @param start_position [Integer] the {#start_position} of the location
+          #
+          # @return [Location] the new instance of Location
+          # @rbs (end_position: Integer, start_position: Integer) -> void
+          def initialize: (end_position: Integer, start_position: Integer) -> void
+        end
+      end
+    end
+  end
+end

data/sig/sai/decorator.rbs

@@ -125,14 +125,13 @@ module Sai
     # @api public
     #
     # @example
-    #   decorator.red.on_blue.bold.decorate('Hello, world!')
-    #   #=> "\e[38;2;205;0;0m\e[48;2;0;0;238m\e[1mHello, world!\e[0m"
+    #   decorator.red.on_blue.bold.decorate('Hello, world!').to_s #=> "\e[38;5;160;48;5;21;1mHello, world!\e[0m"
     #
     # @param text [String] the text to decorate
     #
-    # @return [String] the decorated text
-    # @rbs (String text) -> String
-    def decorate: (String text) -> String
+    # @return [ANSI::SequencedString] the decorated text
+    # @rbs (String text) -> ANSI::SequencedString
+    def decorate: (String text) -> ANSI::SequencedString
 
     alias apply decorate
 
@@ -148,7 +147,7 @@ module Sai
     # @api public
     #
     # @example
-    #   decorator.hex("#EB4133").decorate('Hello, world!') #=> "\e[38;2;235;65;51mHello, world!\e[0m"
+    #   decorator.hex("#EB4133").decorate('Hello, world!').to_s #=> "\e[38;2;235;65;51mHello, world!\e[0m"
     #
     # @param code [String] the hex color code
     #
@@ -165,7 +164,7 @@ module Sai
     # @api public
     #
     # @example
-    #   decorator.on_hex("#EB4133").decorate('Hello, world!') #=> "\e[48;2;235;65;51mHello, world!\e[0m"
+    #   decorator.on_hex("#EB4133").decorate('Hello, world!').to_s #=> "\e[48;2;235;65;51mHello, world!\e[0m"
     #
     # @param code [String] the hex color code
     #
@@ -182,7 +181,7 @@ module Sai
     # @api public
     #
     # @example
-    #   decorator.on_rgb(235, 65, 51).decorate('Hello, world!') #=> "\e[48;2;235;65;51mHello, world!\e[0m"
+    #   decorator.on_rgb(235, 65, 51).decorate('Hello, world!').to_s #=> "\e[48;2;235;65;51mHello, world!\e[0m"
     #
     # @param red [Integer] the red component
     # @param green [Integer] the green component
@@ -201,7 +200,7 @@ module Sai
     # @api public
     #
     # @example
-    #   decorator.rgb(235, 65, 51).decorate('Hello, world!') #=> "\e[38;2;235;65;51mHello, world!\e[0m"
+    #   decorator.rgb(235, 65, 51).decorate('Hello, world!').to_s #=> "\e[38;2;235;65;51mHello, world!\e[0m"
     #
     # @param red [Integer] the red component
     # @param green [Integer] the green component
@@ -240,7 +239,6 @@ module Sai
     # @param style_type [Symbol] the style type to apply the color to
     # @param color [Symbol] the color to apply
     #
-    # @raise [ArgumentError] if the color is invalid
     # @return [Decorator] a new instance of Decorator with the color applied
     # @rbs (Conversion::ColorSequence::style_type style_type, Symbol color) -> Decorator
     def apply_named_color: (Conversion::ColorSequence::style_type style_type, Symbol color) -> Decorator
@@ -254,7 +252,6 @@ module Sai
     #
     # @param style [String, Symbol] the style to apply
     #
-    # @raise [ArgumentError] if the style is invalid
     # @return [Decorator] a new instance of Decorator with the style applied
     # @rbs (String | Symbol style) -> self
     def apply_style: (String | Symbol style) -> self