sai 0.2.0 → 0.3.1

data/lib/sai/ansi/sequenced_string.rb

@@ -0,0 +1,475 @@
+# frozen_string_literal: true
+
+require 'forwardable'
+require 'sai/ansi'
+require 'sai/ansi/sequence_processor'
+
+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
+      # @rbs skip
+      extend Forwardable
+      include Enumerable #[Segment]
+
+      # @!method each
+      #   Iterate over each segment
+      #
+      #   @author {https://aaronmallen.me Aaron Allen}
+      #   @since 0.3.0
+      #
+      #   @api public
+      #   @return [Enumerator] the Enumerator
+      #
+      # @!method map
+      #   Map over segments
+      #
+      #   @author {https://aaronmallen.me Aaron Allen}
+      #   @since 0.3.0
+      #
+      #   @api public
+      #   @return [Array] the segments to map over
+      #
+      # @!method size
+      #   Number of segments
+      #
+      #   @author {https://aaronmallen.me Aaron Allen}
+      #   @since 0.3.0
+      #
+      #   @api public
+      #
+      #   @return [Integer] the number of segments
+      def_delegators :@segments, :each, :empty?, :map, :size # steep:ignore NoMethod
+
+      # @rbs!
+      #   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)
+        @segments = ANSI::SequenceProcessor.process(string).map do |segment_options|
+          Segment.new(**segment_options) # steep:ignore InsufficientKeywordArguments
+        end
+      end
+
+      # 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 [](index)
+        @segments[index]
+      end
+
+      # 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 ==(other)
+        (other.is_a?(self.class) && to_s == other.to_s) ||
+          (other.is_a?(String) && to_s == self.class.new(other).to_s)
+      end
+
+      # 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 +(other)
+        string = to_s + other.to_s
+        self.class.new(string)
+      end
+
+      # 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
+        map(&:text).join
+      end
+
+      # 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
+        build_string
+      end
+      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
+        self.class.new(build_string(skip_background: true))
+      end
+
+      # 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
+        self.class.new(build_string(skip_background: true, skip_foreground: true))
+      end
+
+      # 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
+        self.class.new(build_string(skip_foreground: true))
+      end
+
+      # 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(*styles)
+        skipped_styles = styles.empty? ? ANSI::STYLES.keys : styles.map(&:to_sym)
+        self.class.new(build_string(skip_styles: skipped_styles))
+      end
+
+      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, skip_background: false, skip_foreground: false)
+        [
+          (skip_foreground ? nil : segment.foreground),
+          (skip_background ? nil : segment.background)
+        ].compact
+      end
+
+      # 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: false, skip_foreground: false, skip_styles: [])
+        map do |segment|
+          color_sequences = build_color_sequences(segment, skip_background:, skip_foreground:)
+          style_sequences = build_style_sequences(segment, skip_styles: skip_styles)
+          sequences = color_sequences + style_sequences
+
+          out = sequences.empty? ? +'' : "\e[#{sequences.compact.join(';')}m"
+          out << segment.text
+          out << ANSI::RESET unless sequences.empty?
+          out
+        end.join
+      end
+
+      # 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, skip_styles: [])
+        return [] if skip_styles.include?(:all)
+
+        segment.styles.filter_map do |style_code|
+          style_name = ANSI::STYLES.key(style_code.to_i)
+          style_code unless skip_styles.include?(style_name)
+        end
+      end
+
+      # 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(**options)
+          @background = options.fetch(:background, nil)
+          @foreground = options.fetch(:foreground, nil)
+          @encoded_location = Location.new(
+            end_position: options.fetch(:encoded_end), #: Integer
+            start_position: options.fetch(:encoded_start) #: Integer
+          )
+          @stripped_location = Location.new(
+            end_position: options.fetch(:stripped_end), #: Integer
+            start_position: options.fetch(:stripped_start) #: Integer
+          )
+          @styles = options.fetch(:styles, [])
+          @text = options.fetch(:text)
+
+          freeze
+        end
+
+        # 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:, start_position:)
+            @end_position = end_position
+            @start_position = start_position
+            freeze
+          end
+        end
+      end
+    end
+  end
+end

data/lib/sai/ansi/style_parser.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Sai
+  module ANSI
+    # Handles parsing of ANSI style codes
+    #
+    # @author {https://aaronmallen.me Aaron Allen}
+    # @since 0.3.1
+    #
+    # @api private
+    class StyleParser
+      # Matches the code portion of style sequences
+      #
+      # @author {https://aaronmallen.me Aaron Allen}
+      # @since 0.3.1
+      #
+      # @api private
+      #
+      # @return [Regexp] the pattern
+      STYLE_CODE_PATTERN = /^(?:[1-9]|2[1-9])$/ #: Regexp
+      private_constant :STYLE_CODE_PATTERN
+
+      # The current segment being processed
+      #
+      # @author {https://aaronmallen.me Aaron Allen}
+      # @since 0.3.1
+      #
+      # @api private
+      #
+      # @return [Hash] the current segment being processed
+      attr_reader :segment #: Hash[Symbol, untyped]
+
+      # Initialize a new instance of StyleParser
+      #
+      # @author {https://aaronmallen.me Aaron Allen}
+      # @since 0.3.1
+      #
+      # @api private
+      #
+      # @param segment [Hash] the segment to update
+      #
+      # @return [StyleParser] the new instance of StyleParser
+      # @rbs (Hash[Symbol, untyped] segment) -> void
+      def initialize(segment)
+        @segment = segment
+      end
+
+      # Parse a style code
+      #
+      # @author {https://aaronmallen.me Aaron Allen}
+      # @since 0.3.1
+      #
+      # @api private
+      #
+      # @param code [Integer] the style code
+      #
+      # @return [void]
+      # @rbs (Integer code) -> void
+      def parse(code)
+        return unless code.to_s.match?(STYLE_CODE_PATTERN)
+
+        segment[:styles] << code.to_s
+      end
+    end
+  end
+end

data/lib/sai/ansi.rb

@@ -27,33 +27,6 @@ module Sai
       white: 7
     }.freeze # Hash[Symbol, Integer]
 
-    # Standard ANSI color names and their RGB values
-    #
-    # @author {https://aaronmallen.me Aaron Allen}
-    # @since 0.1.0
-    #
-    # @api private
-    #
-    # @return [Hash{Symbol => Array<Integer>}] the color names and RGB values
-    COLOR_NAMES = {
-      black: [0, 0, 0],
-      red: [205, 0, 0],
-      green: [0, 205, 0],
-      yellow: [205, 205, 0],
-      blue: [0, 0, 238],
-      magenta: [205, 0, 205],
-      cyan: [0, 205, 205],
-      white: [229, 229, 229],
-      bright_black: [127, 127, 127],
-      bright_red: [255, 0, 0],
-      bright_green: [0, 255, 0],
-      bright_yellow: [255, 255, 0],
-      bright_blue: [92, 92, 255],
-      bright_magenta: [255, 0, 255],
-      bright_cyan: [0, 255, 255],
-      bright_white: [255, 255, 255]
-    }.freeze # Hash[Symbol, Array[Integer]]
-
     # ANSI escape sequence for resetting text formatting
     #
     # @author {https://aaronmallen.me Aaron Allen}

data/lib/sai/conversion/color_sequence.rb

@@ -61,9 +61,9 @@ module Sai
         def advanced(rgb, style_type)
           code = style_type == :background ? 48 : 38
           color_code = if rgb.uniq.size == 1
-                         RGB.to_grayscale_index(rgb)
+                         RGB.index.grayscale(rgb)
                        else
-                         RGB.to_color_cube_index(rgb)
+                         RGB.index.color_cube(rgb)
                        end
 
           "\e[#{code};5;#{color_code}m"
@@ -86,7 +86,7 @@ module Sai
           brightness = (r + g + b) / 3.0
           is_bright = brightness > 0.5
 
-          color = RGB.closest_ansi_color(r, g, b)
+          color = RGB.classify.closest_ansi_color(r, g, b)
           code = base_color_for_style_type(ANSI::COLOR_CODES[color], style_type)
           code += 60 if is_bright
           "\e[#{code}m"
@@ -122,7 +122,7 @@ module Sai
         # @rbs (Array[Integer] rgb, style_type style_type) -> String
         def basic(rgb, style_type)
           r, g, b = rgb.map { |c| c / 255.0 } #: [Float, Float, Float]
-          color = RGB.closest_ansi_color(r, g, b)
+          color = RGB.classify.closest_ansi_color(r, g, b)
           code = base_color_for_style_type(ANSI::COLOR_CODES[color], style_type)
           "\e[#{code}m"
         end