sai 0.1.0 → 0.3.0

data/sig/sai/decorator.rbs

@@ -4,135 +4,134 @@ module Sai
   # A decorator for applying ANSI styles and colors to text
   #
   # @author {https://aaronmallen.me Aaron Allen}
-  # @since unreleased
+  # @since 0.1.0
   #
   # @api public
   class Decorator
     # Initialize a new instance of Decorator
     #
     # @author {https://aaronmallen.me Aaron Allen}
-    # @since unreleased
+    # @since 0.1.0
     #
     # @api private
     #
-    # @param color_mode [Integer] the color mode to use
+    # @param mode [Integer] the color mode to use
     #
     # @return [Decorator] the new instance of Decorator
-    # @rbs (Integer color_mode) -> void
-    def initialize: (Integer color_mode) -> void
+    # @rbs (?mode: Integer) -> void
+    def initialize: (?mode: Integer) -> void
 
-    def black: () -> self
+    def black: () -> Decorator
 
-    def blue: () -> self
+    def blue: () -> Decorator
 
-    def bright_black: () -> self
+    def bright_black: () -> Decorator
 
-    def bright_blue: () -> self
+    def bright_blue: () -> Decorator
 
-    def bright_cyan: () -> self
+    def bright_cyan: () -> Decorator
 
-    def bright_green: () -> self
+    def bright_green: () -> Decorator
 
-    def bright_magenta: () -> self
+    def bright_magenta: () -> Decorator
 
-    def bright_red: () -> self
+    def bright_red: () -> Decorator
 
-    def bright_white: () -> self
+    def bright_white: () -> Decorator
 
-    def bright_yellow: () -> self
+    def bright_yellow: () -> Decorator
 
-    def cyan: () -> self
+    def cyan: () -> Decorator
 
-    def green: () -> self
+    def green: () -> Decorator
 
-    def magenta: () -> self
+    def magenta: () -> Decorator
 
-    def on_black: () -> self
+    def on_black: () -> Decorator
 
-    def on_blue: () -> self
+    def on_blue: () -> Decorator
 
-    def on_bright_black: () -> self
+    def on_bright_black: () -> Decorator
 
-    def on_bright_blue: () -> self
+    def on_bright_blue: () -> Decorator
 
-    def on_bright_cyan: () -> self
+    def on_bright_cyan: () -> Decorator
 
-    def on_bright_green: () -> self
+    def on_bright_green: () -> Decorator
 
-    def on_bright_magenta: () -> self
+    def on_bright_magenta: () -> Decorator
 
-    def on_bright_red: () -> self
+    def on_bright_red: () -> Decorator
 
-    def on_bright_white: () -> self
+    def on_bright_white: () -> Decorator
 
-    def on_bright_yellow: () -> self
+    def on_bright_yellow: () -> Decorator
 
-    def on_cyan: () -> self
+    def on_cyan: () -> Decorator
 
-    def on_green: () -> self
+    def on_green: () -> Decorator
 
-    def on_magenta: () -> self
+    def on_magenta: () -> Decorator
 
-    def on_red: () -> self
+    def on_red: () -> Decorator
 
-    def on_white: () -> self
+    def on_white: () -> Decorator
 
-    def on_yellow: () -> self
+    def on_yellow: () -> Decorator
 
-    def red: () -> self
+    def red: () -> Decorator
 
-    def white: () -> self
+    def white: () -> Decorator
 
-    def yellow: () -> self
+    def yellow: () -> Decorator
 
-    def blink: () -> self
+    def blink: () -> Decorator
 
-    def bold: () -> self
+    def bold: () -> Decorator
 
-    def conceal: () -> self
+    def conceal: () -> Decorator
 
-    def dim: () -> self
+    def dim: () -> Decorator
 
-    def italic: () -> self
+    def italic: () -> Decorator
 
-    def no_blink: () -> self
+    def no_blink: () -> Decorator
 
-    def no_conceal: () -> self
+    def no_conceal: () -> Decorator
 
-    def no_italic: () -> self
+    def no_italic: () -> Decorator
 
-    def no_reverse: () -> self
+    def no_reverse: () -> Decorator
 
-    def no_strike: () -> self
+    def no_strike: () -> Decorator
 
-    def no_underline: () -> self
+    def no_underline: () -> Decorator
 
-    def normal_intensity: () -> self
+    def normal_intensity: () -> Decorator
 
-    def rapid_blink: () -> self
+    def rapid_blink: () -> Decorator
 
-    def reverse: () -> self
+    def reverse: () -> Decorator
 
-    def strike: () -> self
+    def strike: () -> Decorator
 
-    def underline: () -> self
+    def underline: () -> Decorator
 
     # Apply the styles and colors to the text
     #
     # @author {https://aaronmallen.me Aaron Allen}
-    # @since unreleased
+    # @since 0.1.0
     #
     # @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
 
@@ -143,104 +142,129 @@ module Sai
     # Apply a hexadecimal color to the foreground
     #
     # @author {https://aaronmallen.me Aaron Allen}
-    # @since unreleased
+    # @since 0.1.0
     #
     # @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
     #
     # @raise [ArgumentError] if the hex code is invalid
-    # @return [self] the instance of Decorator for chaining
-    # @rbs (String code) -> self
-    def hex: (String code) -> self
+    # @return [Decorator] a new instance of Decorator with the hex color applied
+    # @rbs (String code) -> Decorator
+    def hex: (String code) -> Decorator
 
     # Apply a hexadecimal color to the background
     #
     # @author {https://aaronmallen.me Aaron Allen}
-    # @since unreleased
+    # @since 0.1.0
     #
     # @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
     #
     # @raise [ArgumentError] if the hex code is invalid
-    # @return [self] the instance of Decorator for chaining
-    # @rbs (String code) -> self
-    def on_hex: (String code) -> self
+    # @return [Decorator] a new instance of Decorator with the hex color applied
+    # @rbs (String code) -> Decorator
+    def on_hex: (String code) -> Decorator
 
     # Apply an RGB color to the background
     #
     # @author {https://aaronmallen.me Aaron Allen}
-    # @since unreleased
+    # @since 0.1.0
     #
     # @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
     # @param blue [Integer] the blue component
     #
     # @raise [ArgumentError] if the RGB values are out of range
-    # @return [self] the instance of Decorator for chaining
-    # @rbs (Integer red, Integer green, Integer blue) -> self
-    def on_rgb: (Integer red, Integer green, Integer blue) -> self
+    # @return [Decorator] a new instance of Decorator with the RGB color applied
+    # @rbs (Integer red, Integer green, Integer blue) -> Decorator
+    def on_rgb: (Integer red, Integer green, Integer blue) -> Decorator
 
     # Apply an RGB color to the foreground
     #
     # @author {https://aaronmallen.me Aaron Allen}
-    # @since unreleased
+    # @since 0.1.0
     #
     # @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
     # @param blue [Integer] the blue component
     #
     # @raise [ArgumentError] if the RGB values are out of range
-    # @return [self] the instance of Decorator for chaining
-    # @rbs (Integer red, Integer green, Integer blue) -> self
-    def rgb: (Integer red, Integer green, Integer blue) -> self
+    # @return [Decorator] a new instance of Decorator with the RGB color applied
+    # @rbs (Integer red, Integer green, Integer blue) -> Decorator
+    def rgb: (Integer red, Integer green, Integer blue) -> Decorator
+
+    # Apply a specific color mode to the decorator
+    #
+    # @author {https://aaronmallen.me Aaron Allen}
+    # @since 0.2.0
+    #
+    # @api public
+    #
+    # @example
+    #   decorator.with_mode(Sai.mode.basic_auto) #=> => #<Sai::Decorator:0x123 @mode=1>
+    #
+    # @param mode [Integer] the color mode to use
+    #
+    # @return [Decorator] a new instance of Decorator with the applied color mode
+    # @rbs (Integer mode) -> Decorator
+    def with_mode: (Integer mode) -> Decorator
 
     private
 
     # Apply a named color to the specified style type
     #
     # @author {https://aaronmallen.me Aaron Allen}
-    # @since unreleased
+    # @since 0.1.0
     #
     # @api private
     #
     # @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 [self] the instance of Decorator for chaining
-    # @rbs (Conversion::ColorSequence::style_type style_type, Symbol color) -> self
-    def apply_named_color: (Conversion::ColorSequence::style_type style_type, Symbol color) -> self
+    # @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
 
     # Apply a style to the text
     #
     # @author {https://aaronmallen.me Aaron Allen}
-    # @since unreleased
+    # @since 0.1.0
     #
     # @api private
     #
     # @param style [String, Symbol] the style to apply
     #
-    # @raise [ArgumentError] if the style is invalid
-    # @return [self] the instance of Decorator for chaining
+    # @return [Decorator] a new instance of Decorator with the style applied
     # @rbs (String | Symbol style) -> self
     def apply_style: (String | Symbol style) -> self
+
+    # Check if text should be decorated
+    #
+    # @author {https://aaronmallen.me Aaron Allen}
+    # @since 0.2.0
+    #
+    # @api private
+    #
+    # @return [Boolean] `true` if text should be decorated, `false` otherwise
+    # @rbs () -> bool
+    def should_decorate?: () -> bool
   end
 end

data/sig/sai/mode_selector.rbs

@@ -0,0 +1,319 @@
+# Generated from lib/sai/mode_selector.rb with RBS::Inline
+
+module Sai
+  # Color mode selection methods
+  #
+  # @author {https://aaronmallen.me Aaron Allen}
+  # @since 0.2.0
+  #
+  # @api public
+  module ModeSelector
+    # Set the color mode to 256 color (8-bit) mode
+    #
+    # @author {https://aaronmallen.me Aaron Allen}
+    # @since 0.2.0
+    #
+    # @api public
+    #
+    # @example
+    #   Sai.mode.advanced  #=> 3
+    #   Sai.mode.eight_bit #=> 3
+    #   Sai.mode.color256  #=> 3
+    #
+    # @return [Integer] the color mode
+    # @rbs () -> Integer
+    def self.advanced: () -> Integer
+
+    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
+
+    # Automatically set the color mode to advanced (8-bit) or lower
+    #
+    # Sets the terminal color mode to advanced (8-bit) support, which provides 256 colors
+    # The mode will automatically downgrade to 4-bit, 3-bit, or NO_COLOR if the terminal doesn't support
+    # advanced colors
+    #
+    # @author {https://aaronmallen.me Aaron Allen}
+    # @since 0.2.0
+    #
+    # @api public
+    #
+    # @example With color support enabled
+    #   ENV['COLORTERM']        #=> nil
+    #   ENV['TERM']             #=> 'xterm-256color'
+    #   Sai.mode.advanced_auto  #=> 3
+    #   Sai.mode.eight_bit_auto #=> 3
+    #   Sai.mode.color256_auto  #=> 3
+    #
+    # @example With only 4-bit color support
+    #   ENV['NO_COLOR']         #=> nil
+    #   ENV['TERM']             #=> 'ansi'
+    #   Sai.mode.advanced_auto  #=> 2
+    #   Sai.mode.eight_bit_auto #=> 2
+    #   Sai.mode.color256_auto  #=> 2
+    #
+    # @example With only 3-bit color support
+    #   ENV['TERM']             #=> nil
+    #   ENV['NO_COLOR']         #=> nil
+    #   Sai.mode.advanced_auto  #=> 1
+    #   Sai.mode.eight_bit_auto #=> 1
+    #   Sai.mode.color256_auto  #=> 1
+    #
+    # @example With color support disabled
+    #   ENV['NO_COLOR']         #=> 'true'
+    #   Sai.mode.advanced_auto  #=> 0
+    #   Sai.mode.eight_bit_auto #=> 0
+    #   Sai.mode.color256_auto  #=> 0
+    #
+    # @return [Integer] the color mode
+    # @rbs () -> Integer
+    def self.advanced_auto: () -> Integer
+
+    alias self.color256_auto self.advanced_auto
+
+    alias self.colour256_auto self.advanced_auto
+
+    alias self.eight_bit_auto self.advanced_auto
+
+    alias self.two_hundred_fifty_six_color_auto self.advanced_auto
+
+    alias self.two_hundred_fifty_six_colour_auto self.advanced_auto
+
+    # Set the color mode to 16 color (4-bit) mode
+    #
+    # @author {https://aaronmallen.me Aaron Allen}
+    # @since 0.2.0
+    #
+    # @api public
+    #
+    # @example
+    #   Sai.mode.ansi     #=> 2
+    #   Sai.mode.color16 #=> 2
+    #   Sai.mode.four_bit #=> 2
+    #
+    # @return [Integer] the color mode
+    # @rbs () -> Integer
+    def self.ansi: () -> Integer
+
+    alias self.color16 self.ansi
+
+    alias self.colour16 self.ansi
+
+    alias self.four_bit self.ansi
+
+    alias self.sixteen_color self.ansi
+
+    alias self.sixteen_colour self.ansi
+
+    # Automatically set the color mode to ansi (4-bit) or lower
+    #
+    # Sets the terminal color mode to ansi (4-bit) support, which provides 8 colors
+    # The mode will automatically downgrade to 3-bit or NO_COLOR if the terminal doesn't support
+    # ansi colors
+    #
+    # @author {https://aaronmallen.me Aaron Allen}
+    # @since 0.2.0
+    #
+    # @api public
+    #
+    # @example With color support enabled
+    #   ENV['NO_COLOR'] #=> nil
+    #   ENV['TERM'] #=> 'ansi'
+    #   Sai.mode.ansi_auto     #=> 2
+    #   Sai.mode.four_bit_auto #=> 2
+    #   Sai.mode.color16_auto  #=> 2
+    #
+    # @example With only 3-bit color support
+    #   ENV['TERM']             #=> nil
+    #   ENV['NO_COLOR']         #=> nil
+    #   Sai.mode.ansi_auto      #=> 1
+    #   Sai.mode.four_bit_auto  #=> 1
+    #   Sai.mode.color16_auto   #=> 1
+    #
+    # @example With color support disabled
+    #   ENV['NO_COLOR']         #=> 'true'
+    #   Sai.mode.ansi_auto      #=> 0
+    #   Sai.mode.four_bit_auto  #=> 0
+    #   Sai.mode.color16_auto   #=> 0
+    #
+    # @return [Integer] the color mode
+    # @rbs () -> Integer
+    def self.ansi_auto: () -> Integer
+
+    alias self.color16_auto self.ansi_auto
+
+    alias self.colour16_auto self.ansi_auto
+
+    alias self.four_bit_auto self.ansi_auto
+
+    alias self.sixteen_color_auto self.ansi_auto
+
+    alias self.sixteen_colour_auto self.ansi_auto
+
+    # Set the color mode based on the current Terminal's capabilities
+    #
+    # This is the default color mode for {Sai}
+    #
+    # @author {https://aaronmallen.me Aaron Allen}
+    # @since 0.2.0
+    #
+    # @api public
+    #
+    # @example With 24-bit color support enabled
+    #   ENV['COLORTERM'] #=> 'truecolor'
+    #   Sai.node.auto    #=> 4
+    #
+    # @example With only 8-bit color support enabled
+    #   ENV['COLORTERM'] #=> nil
+    #   ENV['TERM']      #=> 'xterm-256color'
+    #   Sai.mode.auto    #=> 3
+    #
+    # @example With only 4-bit color support
+    #   ENV['NO_COLOR'] #=> nil
+    #   ENV['TERM']     #=> 'ansi'
+    #   Sai.mode.auto   #=> 2
+    #
+    # @example With only 3-bit color support
+    #   ENV['TERM']     #=> nil
+    #   ENV['NO_COLOR'] #=> nil
+    #   Sai.mode.auto   #=> 1
+    #
+    # @example With color support disabled
+    #   ENV['NO_COLOR'] #=> 'true'
+    #   Sai.mode.auto   #=> 0
+    #
+    # @return [Integer] the color mode
+    # @rbs () -> Integer
+    def self.auto: () -> Integer
+
+    alias self.color16m_auto self.auto
+
+    alias self.colour16m_auto self.auto
+
+    alias self.enabled self.auto
+
+    alias self.sixteen_million_color_auto self.auto
+
+    alias self.sixteen_million_colour_auto self.auto
+
+    alias self.twenty_for_bit_auto self.auto
+
+    # Set the color mode to 8 color (3-bit) mode
+    #
+    # @author {https://aaronmallen.me Aaron Allen}
+    # @since 0.2.0
+    #
+    # @api public
+    #
+    # @example
+    #   Sai.mode.basic     #=> 1
+    #   Sai.mode.color8    #=> 1
+    #   Sai.mode.three_bit #=> 1
+    #
+    # @return [Integer] the 4 color (3-bit) mode
+    # @rbs () -> Integer
+    def self.basic: () -> Integer
+
+    alias self.color8 self.basic
+
+    alias self.colour8 self.basic
+
+    alias self.eight_color self.basic
+
+    alias self.eight_colour self.basic
+
+    alias self.three_bit self.basic
+
+    # Automatically set the color mode to basic (3-bit) or lower
+    #
+    # Sets the terminal color mode to basic (3-bit) support, which provides 8 colors
+    # The mode will automatically downgrade to NO_COLOR if the terminal doesn't support
+    # basic colors
+    #
+    # @author {https://aaronmallen.me Aaron Allen}
+    # @since 0.2.0
+    #
+    # @api public
+    #
+    # @example With color support enabled
+    #   ENV['NO_COLOR']         #=> nil
+    #   Sai.mode.basic_auto     #=> 1
+    #   Sai.mode.three_bit_auto #=> 1
+    #   Sai.mode.color8_auto    #=> 1
+    #
+    # @example With color support disabled
+    #   ENV['NO_COLOR']         #=> 'true'
+    #   Sai.mode.basic_auto     #=> 0
+    #   Sai.mode.three_bit_auto #=> 0
+    #   Sai.mode.color8_auto    #=> 0
+    #
+    # @return [Integer] the color mode
+    # @rbs () -> Integer
+    def self.basic_auto: () -> Integer
+
+    alias self.color8_auto self.basic_auto
+
+    alias self.colour8_auto self.basic_auto
+
+    alias self.eight_color_auto self.basic_auto
+
+    alias self.eight_colour_auto self.basic_auto
+
+    alias self.three_bit_auto self.basic_auto
+
+    # Set the color mode to disable all color and styling
+    #
+    # @author {https://aaronmallen.me Aaron Allen}
+    # @since 0.2.0
+    #
+    # @api public
+    #
+    # @example
+    #   Sai.mode.no_color #=> 0
+    #   Sai.mode.disabled #=> 0
+    #   Sai.mode.mono     #=> 0
+    #
+    # @return [Integer] the color mode
+    # @rbs () -> Integer
+    def self.no_color: () -> Integer
+
+    alias self.disabled self.no_color
+
+    alias self.mono self.no_color
+
+    alias self.no_colour self.no_color
+
+    # Set the color mode to 16-million color (24-bit) mode
+    #
+    # @author {https://aaronmallen.me Aaron Allen}
+    # @since 0.2.0
+    #
+    # @api public
+    #
+    # @example
+    #   Sai.mode.true_color      #=> 4
+    #   Sai.mode.twenty_four_bit #=> 4
+    #   Sai.mode.color_16m       #=> 4
+    #
+    # @return [Integer] the color mode
+    # @rbs () -> Integer
+    def self.true_color: () -> Integer
+
+    alias self.color16m self.true_color
+
+    alias self.colour16m self.true_color
+
+    alias self.sixteen_million_color self.true_color
+
+    alias self.sixteen_million_colour self.true_color
+
+    alias self.twenty_for_bit self.true_color
+  end
+end