sai 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0d27e2e0d0202e3dc41887be8cfa58f3d862fdee0c9fc3dbd0db792bac1d8f91
-  data.tar.gz: c1a6cd0918fd89b72fe1bd22479192354293a270803297fe901df818032fbfb5
+  metadata.gz: 77b862fa47bb8861e21f03dc023a4b411b22b40e345a7e74895eab4c2d7e416b
+  data.tar.gz: b579615c7b59bc268ac222ec678b3d4656a886f892229c794429f82d400c3d68
 SHA512:
-  metadata.gz: 958aae38da9095a09347a97dd5eddca62a2ac2b4f2eddf51ee4e5b11f4ffdeed26918dad6f00bd85129f82de8eafbde5eb1ed6e3c6a8136d6d5ad6cf3b3765fe
-  data.tar.gz: cce26cf788ae60731b58cf2460cea923bda925db36a75f009ec4846046edf47afbd10a81990c7651a0cde21d1090c725dbc7b5e290f412968b83c0dc5f61e1db
+  metadata.gz: 131c38f0d73c9899fe2b7baf6a98af00bb1afdbfd26141d630362ba08da157430ad3cd5cd89a3cf0b2e5c786630f29a06cdd087704807c882db0ba96ccbbaedd
+  data.tar.gz: 8ea163a5901b333aa06589434b553a3655225b222341ad542ffdb078e96916f89b8feee995c2efb7058fae882871c2f35e891c3186fd1d488ad7fcdc3f1ca15a

data/.yardopts

@@ -8,4 +8,4 @@ lib/**/*.rb
 --embed-mixins
 --tag rbs
 --hide-tag rbs
---files LICENSE
+--files LICENSE,docs/USAGE.md

data/CHANGELOG.md

@@ -6,6 +6,21 @@ The format is based on [Keep a Changelog], and this project adheres to [Break Ve
 
 ## [Unreleased]
 
+## [0.3.0] - 2025-01-20
+
+### Added
+
+* [#6](https://github.com/aaronmallen/sai/pull/6) - Add `Sai::ANSI::SequencedString` for ANSI string manipulation by
+  [@aaronmallen](https://github.com/aaronmallen)
+
+### Changed
+
+* [#5](https://github.com/aaronmallen/sai/pull/5) - Remove unnecessary error handling in `Sai::Decorator` by
+  [@aaronmallen](https://github.com/aaronmallen)
+
+* [#6](https://github.com/aaronmallen/sai/pull/6) - Changed `Sai::Decorator#decorate` now returns a
+  `Sai::ANSI::SequencedString` by [@aaronmallen](https://github.com/aaronmallen)
+
 ## [0.2.0] - 2025-01-20
 
 ### Added
@@ -29,5 +44,6 @@ The format is based on [Keep a Changelog], and this project adheres to [Break Ve
 
 <!-- versions -->
 
-[Unreleased]: https://github.com/aaronmallen/sai/compare/0.2.0..HEAD
+[Unreleased]: https://github.com/aaronmallen/sai/compare/0.3.0..HEAD
+[0.3.0]: https://github.com/aaronmallen/sai/compare/0.2.0..0.3.0
 [0.2.0]: https://github.com/aaronmallen/sai/compare/0.1.0..0.2.0

data/README.md

@@ -1,36 +1,39 @@
 # Sai
 
 [![Sai Version](https://img.shields.io/gem/v/sai?style=for-the-badge&logo=rubygems&logoColor=white&logoSize=auto&label=Gem%20Version)](https://rubygems.org/gems/sai)
+[![Sai Codacy grade](https://img.shields.io/codacy/grade/0f9a91b573ed4768a773867b95ed4894/main?style=for-the-badge&logo=codacy&logoColor=white&logoSize=auto)](https://app.codacy.com/gh/aaronmallen/sai)
+[![Sai Codacy coverage](https://img.shields.io/codacy/coverage/0f9a91b573ed4768a773867b95ed4894/main?style=for-the-badge&logo=codacy&logoColor=white&logoSize=auto)](https://app.codacy.com/gh/aaronmallen/sai/coverage)
 [![Sai License](https://img.shields.io/github/license/aaronmallen/sai?style=for-the-badge&logo=opensourceinitiative&logoColor=white&logoSize=auto)](./LICENSE)
-[![Sai Docs](https://img.shields.io/badge/rubydoc-blue?style=for-the-badge&logo=readthedocs&logoColor=white&logoSize=auto&label=docs)](https://rubydoc.info/gems/sai/0.2.0)
+[![Sai Docs](https://img.shields.io/badge/rubydoc-blue?style=for-the-badge&logo=readthedocs&logoColor=white&logoSize=auto&label=docs)](https://rubydoc.info/gems/sai/0.3.0)
 [![Sai Open Issues](https://img.shields.io/github/issues-search/aaronmallen/sai?query=state%3Aopen&style=for-the-badge&logo=github&logoColor=white&logoSize=auto&label=issues&color=red)](https://github.com/aaronmallen/sai/issues?q=state%3Aopen%20)
 
 An elegant color management system for crafting sophisticated CLI applications
 
 ```ruby
-puts Sai.rgb(255, 128, 0).bold.decorate('Create beautiful CLI applications')
-puts Sai.hex('#4834d4').italic.decorate('with intuitive color management')
-puts Sai.bright_cyan.on_blue.underline.decorate('that adapts to any terminal')
+# Create beautiful CLI applications with intuitive color management
+puts Sai.rgb(255, 128, 0).bold.decorate('Warning: Battery Low')
+puts Sai.hex('#4834d4').italic.decorate('Processing request...')
+puts Sai.bright_cyan.on_blue.underline.decorate('Download Complete!')
+
+# Analyze and manipulate ANSI-encoded text
+text = Sai.sequence("\e[31mError:\e[0m Connection failed")
+puts text.without_color  # Keep formatting, remove colors
+puts text.stripped      # Get plain text without any formatting
 ```
 
 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.
 
-Sai empowers developers to create beautiful, colorful CLI applications that maintain visual consistency across different
-terminal capabilities. Like its artistic namesake, it combines simplicity and sophistication to bring rich, adaptive
-color to your terminal interfaces.
-
 ## Features
 
-* Automatic color mode detection and downgrading
-* Support for True Color (24-bit), 256 colors (8-bit), ANSI colors (4-bit), and basic colors (3-bit)
-* Rich set of ANSI text styles
-* Named color support with bright variants
-* RGB and Hex color support
-* Foreground and background colors
+* Rich color support (True Color, 256 colors, ANSI, and basic modes)
+* Automatic terminal capability detection and color mode adaptation
+* RGB, Hex, and named color support with bright variants
+* Comprehensive text styling (bold, italic, underline, etc.)
+* Advanced ANSI sequence parsing and manipulation
+* Intelligent color downgrading for compatibility
 * Respects NO_COLOR environment variable
-* Can be used directly or included in classes/modules
 
 ## Installation
 
@@ -42,20 +45,20 @@ gem 'sai'
 
 Or install it yourself as:
 
-```bash
+```ruby
 gem install sai
 ```
 
-## Usage
-
-Sai can be used directly or included in your own classes and modules.
+> [!IMPORTANT]  
+> If you're upgrading from version 0.2.0, please see our [Migration Guide](docs/migrations/0.2.0-0.3.0.md) for
+> important changes.
 
-### Direct Usage
+## Quick Start
 
 ```ruby
 require 'sai'
 
-# Using named colors
+# Basic usage
 puts Sai.red.decorate('Error!')
 puts Sai.bright_blue.on_white.decorate('Info')
 
@@ -63,234 +66,21 @@ puts Sai.bright_blue.on_white.decorate('Info')
 puts Sai.rgb(255, 128, 0).decorate('Custom color')
 puts Sai.on_rgb(0, 255, 128).decorate('Custom background')
 
-# Using hex colors
-puts Sai.hex('#FF8000').decorate('Hex color')
-puts Sai.on_hex('#00FF80').decorate('Hex background')
-
 # Applying styles
 puts Sai.bold.underline.decorate('Important')
 puts Sai.red.bold.italic.decorate('Error!')
 
-# Complex combinations
-puts Sai.bright_cyan
-        .on_blue
-        .bold
-        .italic
-        .decorate('Styled text')
-```
-
-### Module Inclusion
-
-```ruby
-class CLI
-  include Sai
-
-  def error(message)
-    puts decorator.red.bold.decorate(message)
-  end
-
-  def info(message)
-    puts decorator.bright_blue.decorate(message)
-  end
-
-  def success(message)
-    puts decorator.with_mode(color_mode.ansi_auto).green.decorate(message)
-  end
-end
-
-cli = CLI.new
-cli.error('Something went wrong!')
-cli.info('Processing...')
-cli.success('Done!')
+# Working with ANSI sequences
+text = Sai.sequence("\e[31mError:\e[0m Details here")
+puts text.without_color    # Remove colors but keep formatting
+puts text.without_style    # Remove formatting but keep colors
+puts text.stripped        # Get plain text
 ```
 
-### Defining Reusable Styles
-
-Sai decorators can be assigned to constants to create reusable styles throughout your application:
-
-```ruby
-module Style
-  ERROR = Sai.bold.bright_white.on_red
-  WARNING = Sai.black.on_yellow
-  SUCCESS = Sai.bright_green
-  INFO = Sai.bright_blue
-  HEADER = Sai.bold.bright_cyan.underline
-end
-
-# Use your defined styles
-puts Style::ERROR.decorate('Something went wrong!')
-puts Style::SUCCESS.decorate('Operation completed successfully')
-
-# Styles can be further customized when needed
-puts Style::ERROR.italic.decorate('Critical error!')
-```
+## Documentation
 
-> [!TIP]
-> This pattern is particularly useful for maintaining consistent styling across your application and creating theme
-> systems. You can even build on existing styles:
->
-> ```ruby
-> module Theme
->   PRIMARY = Sai.rgb(63, 81, 181)
->   SECONDARY = Sai.rgb(255, 87, 34)
->
->   BUTTON = PRIMARY.bold
->   LINK = SECONDARY.underline
->   HEADER = PRIMARY.bold.underline
-> end
-> ```
-
-## Features
-
-### Color Support
-
-Sai supports up to 16.7 million colors (true color/24-bit) depending on your terminal's capabilities. Colors can be
-specified in several ways:
-
-#### RGB Colors
-
-```ruby
-# Specify any RGB color (0-255 per channel)
-Sai.rgb(255, 128, 0).decorate('Orange text')
-Sai.on_rgb(0, 255, 128).decorate('Custom green background')
-```
-
-#### Hex Colors
-
-```ruby
-# Use any hex color code
-Sai.hex('#FF8000').decorate('Orange text')
-Sai.on_hex('#00FF80').decorate('Custom green background')
-```
-
-#### Named Color Shortcuts
-
-For convenience, Sai provides shortcuts for common ANSI colors:
-
-Standard colors:
-
-```ruby
-Sai.red.decorate('Red text')
-Sai.blue.decorate('Blue text')
-Sai.on_green.decorate('Green background')
-```
-
-Bright variants:
-
-```ruby
-Sai.bright_red.decorate('Bright red text')
-Sai.bright_blue.decorate('Bright blue text')
-Sai.on_bright_green.decorate('Bright green background')
-```
-
-Available named colors:
-
-* black/bright_black
-* red/bright_red
-* green/bright_green
-* yellow/bright_yellow
-* blue/bright_blue
-* magenta/bright_magenta
-* cyan/bright_cyan
-* white/bright_white
-
-> [!TIP]
-> While named colors provide convenient shortcuts, remember that Sai supports the full RGB color space. Don't feel
-> limited to just these predefined colors!
-
-### Text Styles
-
-Available styles:
-
-* bold
-* dim
-* italic
-* underline
-* blink
-* rapid_blink
-* reverse
-* conceal
-* strike
-
-Style removal:
-
-* no_blink
-* no_italic
-* no_underline
-* no_reverse
-* no_conceal
-* no_strike
-* normal_intensity
-
-### Color Mode Detection & Downgrading
-
-Sai automatically detects your terminal's color capabilities and adapts the output appropriately:
-
-* True Color terminals (24-bit): Full access to all 16.7 million colors
-* 256-color terminals (8-bit): Colors are mapped to the closest available color in the 256-color palette
-* ANSI terminals (4-bit): Colors are mapped to the 16 standard ANSI colors
-* Basic terminals (3-bit): Colors are mapped to the 8 basic ANSI colors
-* NO_COLOR: All color sequences are stripped when the NO_COLOR environment variable is set
-
-> [!NOTE]
-> This automatic downgrading ensures your application looks great across all terminal types without any extra code!
-
-### Color Mode Selection
-
-Sai provides flexible color mode selection through its `mode` interface:
-
-```ruby
-# Use automatic mode detection (default)
-Sai.with_mode(Sai.mode.auto)
-
-# Force specific color modes
-puts Sai.with_mode(Sai.mode.true_color).red.decorate('24-bit color')
-puts Sai.with_mode(Sai.mode.advanced).red.decorate('256 colors')
-puts Sai.with_mode(Sai.mode.ansi).red.decorate('16 colors')
-puts Sai.with_mode(Sai.mode.basic).red.decorate('8 colors')
-puts Sai.with_mode(Sai.mode.no_color).red.decorate('No color')
-
-# Use automatic downgrading
-puts Sai.with_mode(Sai.mode.advanced_auto).red.decorate('256 colors or less')
-puts Sai.with_mode(Sai.mode.ansi_auto).red.decorate('16 colors or less')
-puts Sai.with_mode(Sai.mode.basic_auto).red.decorate('8 colors or less')
-```
-
-> [!WARNING]
-> When using fixed color modes (like `true_color` or `advanced`), Sai will not automatically downgrade colors for
-> terminals with lower color support. For automatic color mode adjustment, use modes ending in `_auto`
-> (like `advanced_auto` or `ansi_auto`).
-
-This allows you to:
-
-* Explicitly set specific color modes
-* Use automatic mode detection (default)
-* Set maximum color modes with automatic downgrading
-* Disable colors entirely
-
-### Terminal Support Detection
-
-You can check the terminal's capabilities:
-
-```ruby
-# Using directly
-Sai.support.true_color? # => true/false
-Sai.support.advanced?   # => true/false
-Sai.support.ansi?      # => true/false
-Sai.support.basic?     # => true/false
-Sai.support.color?     # => true/false
-
-# Using included module
-class CLI
-  include Sai
-
-  def check_support
-    if terminal_color_support.true_color?
-      puts "Terminal supports true color!"
-    end
-  end
-end
-```
+* [Complete Usage Guide](docs/USAGE.md) - Comprehensive documentation of all features
+* [API Documentation](https://rubydoc.info/gems/sai/0.3.0) - Detailed API reference
 
 ## Contributing
 

data/docs/USAGE.md

@@ -0,0 +1,303 @@
+# Sai Usage Guide
+
+This guide provides comprehensive documentation for using Sai in your applications.
+
+## Table of Contents
+
+* [Basic Usage](#basic-usage)
+* [Color Support](#color-support)
+  * [RGB Colors](#rgb-colors)
+  * [Hex Colors](#hex-colors)
+  * [Named Colors](#named-colors)
+* [Text Styles](#text-styles)
+* [ANSI Sequence Manipulation](#ansi-sequence-manipulation)
+* [Color Mode Management](#color-mode-management)
+* [Terminal Capabilities](#terminal-capabilities)
+* [Integration Patterns](#integration-patterns)
+* [Best Practices](#best-practices)
+
+## Basic Usage
+
+Sai can be used directly or included in your own classes and modules:
+
+```ruby
+# Direct usage
+puts Sai.red.decorate('Error!')
+puts Sai.bright_blue.on_white.decorate('Info')
+
+# Include in your own classes
+class CLI
+  include Sai
+
+  def error(message)
+    puts decorator.red.bold.decorate(message)
+  end
+
+  def info(message)
+    puts decorator.bright_blue.decorate(message)
+  end
+end
+```
+
+## Color Support
+
+### RGB Colors
+
+Use any RGB color (0-255 per channel):
+
+```ruby
+# Foreground colors
+Sai.rgb(255, 128, 0).decorate('Orange text')
+Sai.rgb(100, 149, 237).decorate('Cornflower blue')
+
+# Background colors
+Sai.on_rgb(0, 255, 128).decorate('Custom green background')
+```
+
+### Hex Colors
+
+Use any hex color code:
+
+```ruby
+# Foreground colors
+Sai.hex('#FF8000').decorate('Orange text')
+Sai.hex('#6495ED').decorate('Cornflower blue')
+
+# Background colors
+Sai.on_hex('#00FF80').decorate('Custom green background')
+```
+
+### Named Colors
+
+Common ANSI colors have convenient shortcuts:
+
+```ruby
+# Standard colors
+Sai.red.decorate('Red text')
+Sai.blue.decorate('Blue text')
+Sai.on_green.decorate('Green background')
+
+# Bright variants
+Sai.bright_red.decorate('Bright red text')
+Sai.bright_blue.decorate('Bright blue text')
+Sai.on_bright_green.decorate('Bright green background')
+```
+
+Available named colors:
+* black/bright_black
+* red/bright_red
+* green/bright_green
+* yellow/bright_yellow
+* blue/bright_blue
+* magenta/bright_magenta
+* cyan/bright_cyan
+* white/bright_white
+
+> [!TIP]
+> While named colors provide convenient shortcuts, remember that Sai supports the full RGB color space. Don't feel
+> limited to just these predefined colors!
+
+## Text Styles
+
+Sai supports a variety of text styles:
+
+```ruby
+Sai.bold.decorate('Bold text')
+Sai.italic.decorate('Italic text')
+Sai.underline.decorate('Underlined text')
+Sai.strike.decorate('Strikethrough text')
+```
+
+Available styles:
+* bold
+* dim
+* italic
+* underline
+* blink
+* rapid_blink
+* reverse
+* conceal
+* strike
+
+Style removal:
+* no_blink
+* no_italic
+* no_underline
+* no_reverse
+* no_conceal
+* no_strike
+* normal_intensity
+
+## ANSI Sequence Manipulation
+
+Sai provides powerful tools for working with ANSI-encoded strings:
+
+```ruby
+# Create a SequencedString from decorated text
+text = Sai.red.bold.decorate("Warning!")
+
+# Or parse existing ANSI text
+text = Sai.sequence("\e[31mred\e[0m and \e[32mgreen\e[0m")
+
+# Get plain text without formatting
+plain = text.stripped  # => "red and green"
+
+# Remove specific attributes
+text.without_color    # Remove all colors but keep styles
+text.without_style    # Remove all styles but keep colors
+text.without_style(:bold, :italic)  # Remove specific styles
+
+# Access individual segments
+text.each do |segment|
+  puts "Text: #{segment.text}"
+  puts "Foreground: #{segment.foreground}"
+  puts "Background: #{segment.background}"
+  puts "Styles: #{segment.styles}"
+  puts "Position: #{segment.encoded_location.start_position}..#{segment.encoded_location.end_position}"
+end
+```
+
+## Color Mode Management
+
+Sai by default automatically detects your terminal's capabilities and automatically downgrades colors based on those
+capabilities but also allows manual control:
+
+```ruby
+# Use automatic mode detection (default)
+Sai.with_mode(Sai.mode.auto)
+
+# Force specific color modes
+puts Sai.with_mode(Sai.mode.true_color).red.decorate('24-bit color')
+puts Sai.with_mode(Sai.mode.advanced).red.decorate('256 colors')
+puts Sai.with_mode(Sai.mode.ansi).red.decorate('16 colors')
+puts Sai.with_mode(Sai.mode.basic).red.decorate('8 colors')
+puts Sai.with_mode(Sai.mode.no_color).red.decorate('No color')
+
+# Use automatic downgrading
+puts Sai.with_mode(Sai.mode.advanced_auto).red.decorate('256 colors or less')
+puts Sai.with_mode(Sai.mode.ansi_auto).red.decorate('16 colors or less')
+puts Sai.with_mode(Sai.mode.basic_auto).red.decorate('8 colors or less')
+```
+
+> [!WARNING]
+> When using fixed color modes (like `true_color` or `advanced`), Sai will not automatically downgrade colors for
+> terminals with lower color support. For automatic color mode adjustment, use modes ending in `_auto`
+> (like `advanced_auto` or `ansi_auto`).
+
+Color Mode Hierarchy:
+
+1. True Color (24-bit): 16.7 million colors
+2. Advanced (8-bit): 256 colors
+3. ANSI (4-bit): 16 colors
+4. Basic (3-bit): 8 colors
+5. No Color: All formatting stripped
+
+## Terminal Capabilities
+
+Check terminal color support:
+
+```ruby
+# Using directly
+Sai.support.true_color? # => true/false
+Sai.support.advanced?   # => true/false
+Sai.support.ansi?      # => true/false
+Sai.support.basic?     # => true/false
+Sai.support.color?     # => true/false
+
+# Using included module
+class CLI
+  include Sai
+
+  def check_support
+    if terminal_color_support.true_color?
+      puts "Terminal supports true color!"
+    end
+  end
+end
+```
+
+## Integration Patterns
+
+### Defining Reusable Styles
+
+Create consistent styling across your application:
+
+```ruby
+module Style
+  ERROR = Sai.bold.bright_white.on_red
+  WARNING = Sai.black.on_yellow
+  SUCCESS = Sai.bright_green
+  INFO = Sai.bright_blue
+  HEADER = Sai.bold.bright_cyan.underline
+end
+
+# Use your defined styles
+puts Style::ERROR.decorate('Something went wrong!')
+puts Style::SUCCESS.decorate('Operation completed successfully')
+
+# Styles can be further customized
+puts Style::ERROR.italic.decorate('Critical error!')
+```
+
+> [!TIP]
+> This pattern is particularly useful for maintaining consistent styling across your application and creating theme
+> systems. You can even build on existing styles:
+>
+> ```ruby
+> module Theme
+>   PRIMARY = Sai.rgb(63, 81, 181)
+>   SECONDARY = Sai.rgb(255, 87, 34)
+>
+>   BUTTON = PRIMARY.bold
+>   LINK = SECONDARY.underline
+>   HEADER = PRIMARY.bold.underline
+> end
+> ```
+
+### Class Integration
+
+Integrate Sai into your classes:
+
+```ruby
+class Logger
+  include Sai
+
+  def error(message)
+    puts decorator.red.bold.decorate(message)
+  end
+
+  def warn(message)
+    puts decorator.yellow.decorate(message)
+  end
+
+  def info(message)
+    puts decorator.with_mode(color_mode.true_color).bright_blue.decorate(message)
+  end
+end
+```
+
+## Best Practices
+
+1. **Automatic Mode Detection**
+  * Use `Sai.mode.auto` by default to respect terminal capabilities
+  * Only force specific color modes when necessary
+
+2. **Color Usage**
+  * Use named colors for standard indicators (red for errors, etc.)
+  * Use RGB/Hex for brand colors or specific design requirements
+  * Consider color blindness when choosing colors
+
+3. **Style Organization**
+  * Create reusable styles for consistency
+  * Group related styles in modules
+  * Consider creating a theme system for larger applications
+
+4. **Performance**
+  * Cache decorator instances when using repeatedly
+  * Use `SequencedString` parsing for complex manipulations
+  * Consider terminal capabilities when designing output
+
+5. **Accessibility**
+  * Don't rely solely on color for important information
+  * Use styles (bold, underline) to enhance meaning
+  * Respect NO_COLOR environment variable