attributed-string 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 82923e8039feb4f88aed1efcddc7df11bf2a620c2320d602f8d105c57b510a8a
+  data.tar.gz: 0aa653c860bd4329d28464fd2513df2ce3c733cda59f77739c4c6f9eb45cc809
+SHA512:
+  metadata.gz: 15758243087810b97934ddc122f4bb60e473ece3a338d5a642e272b08adad982701d2791c71acf46e42a20422a7ff7411e31d748875faa243a5e508eec8a136d
+  data.tar.gz: d6c2f8655e93f1536724a321e17fd90da6f82cca842eecfdaa82b20630cafd243e7d5a40ec60a890ae8c3f973359252742e90568347746c355b04ff5d9fc53ce

data/LICENSE

@@ -0,0 +1,202 @@
+Copyright 2024-, Andrew Mackross
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

data/README.md

@@ -0,0 +1,45 @@
+# AttributedString
+
+An attributed string implementation for Ruby.
+
+An attributed string contains key-value pairs known as attributes that specify additional information related to ranges of characters within the string. Attributed strings support any key-value pair, but are often used for: 
+
+- Rendering attributes such as font, color,  and other details.
+- Attributes for inline-attachments such as images, videos, files, etc. 
+- Semantic attributes such as link URLs or tool-tip information
+- Language attributes to support automatic gender agreement or verb agreement. 
+- Accessibility attributes that provide information for assistive technologies
+- Custom attributes you define
+
+You will typically need to create a presenter for an attributed string, as the default shows no attribute information and inspect shows all attributes. 
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+  gem 'attributed-string', github: 'instruct-rb/attributed-string', branch: 'main'
+```
+
+
+## Usage
+
+🚧 This gem is a work in progress and the API may change before 1.0.
+
+```ruby
+  using AttributedString::Refinements
+  hello_world1 = AttributedString.new('Hello, World!',  color: :red, font: 'Helvetica' )
+  hello_world2 = 'Hello, World!'.to_attr_s(color: :red, font: 'Helvetica')
+  puts hello_world1 == hello_world2 # true
+```
+
+## Attachments
+
+```ruby
+  hello_world = AttributedString.new('Hello, World!')
+  hello_world.add_attachment("any ruby object", position: string.length)
+  puts hello_world # => "Hello, World! "
+  puts hello_world.attachments # => ["any ruby object"]
+  hello_world[-1..-1] = ''
+  puts hello_world.attachments # => []
+```

data/lib/attributed-string.rb

@@ -0,0 +1,9 @@
+require_relative "attributed_string/filter_result"
+require_relative "attributed_string/inspect"
+require_relative "attributed_string/klass"
+require_relative "attributed_string/attachment"
+require_relative "attributed_string/unsupported"
+require_relative "attributed_string/needs_testing"
+require_relative "attributed_string/refine"
+require_relative "attributed_string/string_ops"
+require_relative "attributed_string/version"

data/lib/attributed_string/attachment.rb

@@ -0,0 +1,66 @@
+class AttributedString < String
+  # This character Object Replacement Character is used to represent an attachment in the string.
+  ATTACHMENT_CHARACTER = "\u{FFFC}".freeze
+
+  # Adds an attachment to the given position.
+  # @param attachment [Object] The attachment to add.
+  # @param position [Integer] The position to add the attachment to.
+  # @return [AttributedString] self for chaining
+  def add_attachment(attachment, position: self.length)
+    self.insert(position, ATTACHMENT_CHARACTER)
+
+    range = normalize_range(position..position)
+    raise ArgumentError, "Position out of bounds" if range.nil?
+    @store << { range:, attachment: }
+    self
+  end
+
+  # Deletes the attachment at a specific position.
+  # @param position [Integer] The index in the string.
+  # @return [Object] The attachment that was removed.
+  def delete_attachment(position)
+    attachment = attachment_at(position)
+    self[position] = ''
+    attachment
+  end
+
+  # Check if the string has an attachment
+  # @param range [Range] The range to check for attachments.
+  # @return [Boolean] Whether the string has an attachment at the given position.
+  def has_attachment?(range: 0...self.length)
+    range = normalize_range(range)
+    return false if range.nil?
+    (self.to_s[range]||'').include?(ATTACHMENT_CHARACTER)
+  end
+
+  # Returns the attachments at a specific position.
+  # @param position [Integer] The index in the string.
+  # @return <Object> The attachments at the given position.
+  def attachment_at(position)
+    result = nil
+    @store.each do |stored_val|
+      if stored_val[:range].begin == position && stored_val[:attachment]
+        result = stored_val[:attachment]
+      end
+    end
+    result
+  end
+
+  # Returns an array of attachments in the given range.
+  # @param range [Range] The range to check for attachments.
+  # @return [Array<Object>] The attachments in the given range.
+  def attachments(range: 0...self.length)
+    attachments_with_positions(range: range).map { |attachment| attachment[:attachment] }
+  end
+
+  # TODO: needs a test
+  def attachments_with_positions(range: 0...self.length)
+    range = normalize_range(range)
+    return [] if range.nil?
+    attachments = []
+    self.chars[range].map.with_index do |char, i|
+      attachments << { attachment: attachment_at(range.begin + i), position: range.begin + i } if char == ATTACHMENT_CHARACTER
+    end
+    attachments
+  end
+end

data/lib/attributed_string/filter_result.rb

@@ -0,0 +1,108 @@
+class AttributedString < String
+
+  # Returns a filtered string the block will be called with each attribute,
+  # value pair. It's an inclusive filter, so if the block returns true, any
+  # character with that attribute will be included.
+  #
+  # This method has been slightly optimized to minimize allocations.
+  # @see AttributedString#filter
+  # @param attr_string [AttributedString]
+  # @param block [Proc] the block to filter the attributes.
+  # @return [AttributedString::FilterResult] a filtered string.
+  def filter(&block)
+    AttributedString::FilterResult.new(self, &block)
+  end
+
+  class FilterResult < String
+    # @see AttributedString#filter
+    def initialize(attr_string, &block)
+      filtered_positions = []
+      cached_block_calls = {}
+
+      # TODO: this can be optimized to use the same method that inspect uses which doesn't go through
+      # every character (it goes through each substring span with different ranges)
+      # A presenter type architecture that inspect, rainbow print, and filter can share would be ideal
+      attr_string.each_char.with_index do |char, index|
+        attrs = attr_string.attrs_at(index)
+        # Use the attrs object ID as the cache key to handle different attribute hashes
+        cache_key = attrs.hash
+        cached_result = cached_block_calls.fetch(cache_key) do
+          result = block.call(attrs)
+          cached_block_calls[cache_key] = result
+          result
+        end
+        if cached_result
+          filtered_positions << index
+        end
+      end
+
+      # Group adjacent positions into ranges to minimize allocations
+      ranges = []
+      unless filtered_positions.empty?
+        start_pos = filtered_positions.first
+        prev_pos = start_pos
+        filtered_positions.each_with_index do |pos, idx|
+          next if idx == 0
+          if pos == prev_pos + 1
+            # Continue the current range
+            prev_pos = pos
+          else
+            # End the current range and start a new one
+            ranges << (start_pos..prev_pos)
+            start_pos = pos
+            prev_pos = pos
+          end
+        end
+        # Add the final range
+        ranges << (start_pos..prev_pos)
+      end
+
+      # Concatenate substrings from the original string based on the ranges
+      result_string = ranges.map { |range| attr_string.send(:original_slice,range) }.join
+
+      # Build the list of original positions
+      original_positions = ranges.flat_map { |range| range.to_a }
+
+      super(result_string)
+      @original_positions = original_positions
+      freeze
+    end
+
+    def original_position_at(index)
+      @original_positions.fetch(index)
+    end
+
+    def original_ranges_for(filtered_range)
+      # TODO: this doesn't work for excluded end range
+      raise ArgumentError, "Invalid range" unless filtered_range.is_a?(Range)
+      raise ArgumentError, "Range out of bounds" if filtered_range.end >= length
+      if filtered_range.begin > filtered_range.end
+        raise ArgumentError, "Reverse range is not allowed"
+      end
+      if filtered_range.begin == filtered_range.end && filtered_range.exclude_end?
+        return []
+      end
+
+      original_positions = @original_positions[filtered_range]
+      ranges = []
+      start_pos = original_positions.first
+      prev_pos = start_pos
+
+      original_positions.each_with_index do |pos, idx|
+        next if idx == 0
+        if pos == prev_pos + 1
+          # Continue the current range
+          prev_pos = pos
+        else
+          # End the current range and start a new one
+          ranges << (start_pos..prev_pos)
+          start_pos = pos
+          prev_pos = pos
+        end
+      end
+      # Add the final range
+      ranges << (start_pos..prev_pos)
+      ranges
+    end
+  end
+end

data/lib/attributed_string/inspect.rb

@@ -0,0 +1,95 @@
+class AttributedString
+# Inspect prints the attributed string in an easily readable way.
+# An example inspect output "{ k1: 1 }these have the attributes k1: 1 { k1: 2, k2: true }these have 2 attrs k1: 2, and k2: true { -k2 }and these have k1: 2 { -k1 }and these have none"
+# could be constructed as:
+#
+#   ("these have the attributes k1: 1 ".to_attr_s(k1: 1) +
+#   "these have 2 attrs k1: 2, and k2: true ".to_attr_s(k1: 2, k2: true) +
+#   "and these have k1: 2 ".to_attr_s(k1: 2) +
+#   "and these have none").inspect
+#
+  def inspect(color: false)
+    # Collect all positions where attributes change
+    positions = Set.new
+
+    @store.each do |attr|
+      range = attr[:range]
+      positions << range.begin
+      positions << range.begin + range.size
+    end
+
+    # Include the start and end positions of the string
+    positions << 0
+    positions << self.length
+
+    # Sort all positions
+    positions = positions.to_a.sort
+
+    result = ""
+    last_attrs = {}  # Initialize as empty hash
+
+    positions.each_cons(2) do |start_pos, end_pos|
+      next if start_pos >= end_pos  # Skip invalid ranges
+
+      substring = self.to_s[start_pos...end_pos]
+      attrs_before = last_attrs
+      attachment = attachment_at(start_pos)
+      attrs_after = attrs_at(start_pos)
+
+      # Determine attribute changes
+      ended_attrs = {}
+      started_attrs = {}
+
+      # Attributes that have ended or changed
+      attrs_before.each do |key, value|
+        if !attrs_after.key?(key)
+          # Attribute has ended
+          ended_attrs[key] = value
+        elsif attrs_after[key] != value
+          # Attribute value has changed; treat as ending old and starting new
+          ended_attrs[key] = value
+          started_attrs[key] = attrs_after[key]
+        end
+      end
+
+      # Attributes that have started
+      attrs_after.each do |key, value|
+        if !attrs_before.key?(key)
+          started_attrs[key] = value
+        end
+      end
+
+      # Remove attributes that both ended and started (value change)
+      ended_attrs.delete_if { |k, _| started_attrs.key?(k) }
+
+      unless ended_attrs.empty? && started_attrs.empty?
+        attrs_str = ended_attrs.keys.sort.map{ |k| "-#{k}" }
+        attrs_str += started_attrs.to_a.sort{ |a,b| a[0] <=> b[0] }.map{ |a| "#{a[0]}: #{a[1]}" }
+        attrs_str = "{ #{attrs_str.join(', ')} }"
+        result += dim(attrs_str, color: color)
+      end
+
+      if attachment
+        substring = dim("[#{attachment}]", color: color)
+      end
+
+      # Append the substring
+      result += substring
+
+      last_attrs = attrs_after
+    end
+
+    # Close any remaining attributes
+    unless last_attrs.empty?
+      result += dim("{ #{last_attrs.keys.sort.map{ |k| "-#{k}" }.join(", ")} }", color: color)
+    end
+
+    result
+  end
+
+
+  def dim(string, color: true)
+    color ? "\e[2m#{string}\e[22m" : string
+  end
+
+end

data/lib/attributed_string/klass.rb

@@ -0,0 +1,113 @@
+class AttributedString < String
+
+  alias_method :original_slice, :slice
+  private :original_slice
+
+  # Returns a new instance of AttributedString with the kwargs passed in as
+  # attributes for the whole string.
+  # @param string [String]
+  def initialize(string = "", **attrs)
+    super(string)
+    @store = []
+    if string.is_a?(AttributedString)
+      string.instance_variable_get(:@store).each do |entry|
+        @store << entry.dup
+      end
+    end
+    add_attrs(**attrs)
+  end
+
+  def dup
+    super.tap do |copy|
+      new_store = @store.map do |entry|
+        entry[:range] = entry[:range].dup
+        entry.dup
+      end
+      copy.instance_variable_set(:@store, new_store)
+    end
+  end
+
+  # Adds the given attributes in the hash to the range.
+  # @param range [Range] The range to apply the attributes to.
+  # @param attributes [Hash<Symbol, Object>] The attributes to apply to the range.
+  # @return [AttributedString] self for chaining
+  def add_attrs(range = 0..self.length - 1, **attributes)
+    range = normalize_range(range)
+    return self if attributes.empty? || self.empty? || range.nil? || range.size.zero?
+    @store << { range: range, attributes: attributes }
+    self
+  end
+
+  # Adds the given attributes in the hash to the range.
+  #
+  # If the attribute is already set, it will be converted to an array and the new value will be appended.
+  #
+  # @param range [Range] The range to apply the attributes to.
+  # @param attributes [Hash<Symbol, Object>] The attributes to apply to the range.
+  # @return [AttributedString] self for chaining
+  def add_arr_attrs(range = 0..self.length - 1, **attributes)
+    range = normalize_range(range)
+    return self if attributes.empty? || self.empty? || range.nil? || range.size.zero?
+    @store << { range: range, arr_attributes: attributes }
+    self
+  end
+
+
+
+  # Need to think about how this works as the attachment store is an array
+  # def remove_attachment(position)
+  #   raise Todo
+  # end
+
+
+  # Removes the given attributes from a range.
+  # @param range_or_key [Range] The range to remove the attributes from, if its not a range, it will be treated as a key to remove.
+  # @param attribute_keys [Array<Symbol>] The keys of the attributes to remove.
+  # @return [AttributedString] self for chaining
+  def remove_attrs(range_or_key, *attribute_keys)
+    if !range_or_key.is_a?(Range)
+      attribute_keys << range_or_key
+      range_or_key = 0..self.length - 1
+    end
+    @store << { range: range_or_key, delete: attribute_keys }
+    self
+  end
+
+  # Returns the attributes at a specific position.
+  # @param position [Integer] The index in the string.
+  # @return [Hash] The attributes at the given position.
+  def attrs_at(position)
+    result = {}
+    @store.each do |stored_val|
+      if stored_val[:range].include?(position)
+        if stored_val[:delete]
+          stored_val[:delete].each do |key|
+            result.delete(key)
+          end
+        elsif stored_val[:arr_attributes]
+          stored_val[:arr_attributes].each do |key, value|
+            result[key] = [result[key]] if result.key?(key) && !result[key].is_a?(Array)
+            if value.is_a?(Array)
+              (result[key] ||= []).concat(value)
+            else
+              (result[key] ||= []).push(value)
+            end
+          end
+        elsif stored_val[:attributes]
+          result.merge!(stored_val[:attributes])
+        end
+      end
+    end
+    result
+  end
+
+  def ==(other)
+    return false unless other.is_a?(AttributedString)
+    # not super efficient, but it works for now
+    (0...length).all? { |i| attrs_at(i) == other.attrs_at(i) && attachment_at(i) == other.attachment_at(i) } && super
+  end
+
+
+
+
+end

data/lib/attributed_string/needs_testing.rb

@@ -0,0 +1,8 @@
+class AttributedString < String
+
+  def clear
+    @store.clear
+    super
+  end
+
+end

data/lib/attributed_string/refine.rb

@@ -0,0 +1,42 @@
+class AttributedString
+  module Refinements
+    refine String do
+      unless self.class == AttributedString
+      # @param attrs [Hash] A hash of attributes to apply to the string.
+      # @return [Instruct::AttributedString] A new AttributedString with the given attributes.
+      def to_attr_s(**attrs)
+        AttributedString.new(self, **attrs)
+      end
+
+      alias_method :original_eq, :==
+      private :original_eq
+      def ==(other)
+        return false if other.is_a?(AttributedString)
+        original_eq(other)
+      end
+
+        alias_method :original_plus, :+
+        private :original_plus
+        def +(other)
+          if other.is_a?(AttributedString)
+            other.class.new(self) + other
+          else
+            original_plus(other)
+          end
+        end
+
+        alias_method :original_concat, :concat
+        private :original_concat
+        def concat(*args)
+          args.each do |arg|
+            if arg.is_a?(AttributedString)
+              raise ArgumentError, "Cannot concatenate AttributedString to String"
+            end
+          end
+          original_concat(*args)
+          self
+        end
+      end
+    end
+  end
+end

data/lib/attributed_string/string_ops.rb

@@ -0,0 +1,270 @@
+class AttributedString < String
+
+  def insert(index, other)
+    return super if other.empty?
+    other = AttributedString.new(other) unless other.is_a?(AttributedString)
+    index = normalize_index(index, len: self.length + 1)
+    split_ranges(@store, index, other.length, self.length + other.length)
+    store = other.instance_variable_get(:@store).map { |obj| obj.dup }
+    translate_ranges(store, distance: index)
+    @store.concat(store)
+    super
+  end
+
+  def slice(arg, *args)
+    result = super
+    raise Todo, "Regular expression not implemented for slice, consider raising a pull request" if arg.is_a?(Regexp)
+
+    range = arg.is_a?(Range) ? normalize_range(arg) : normalize_integer_slice_args(arg, *args)
+
+    return range if range.nil?
+    raise RuntimeError if range.size != result.length
+    store = @store.map do |obj|
+      clamped = clamp_range(obj[:range], range)
+      next nil if clamped.nil?
+      obj.dup.tap do |obj|
+        obj[:range] = translate_range(clamped, distance: -range.begin)
+      end
+    end.compact
+
+    new_string = self.class.new(result)
+    new_string.instance_variable_set(:@store, store)
+    new_string
+  end
+  alias_method :[], :slice
+
+  def slice!(arg, *args)
+    result = slice(arg, *args)
+    return result if result.nil?
+
+    range = arg.is_a?(Range) ? normalize_range(arg) : normalize_integer_slice_args(arg, *args)
+    return result if range.nil?
+
+    super(range)
+
+    split_ranges(@store, range.begin, -range.size, self.length)
+
+    result
+  end
+
+  # TODO: this should take args not other
+  # can be implemented as (other, *args)
+  def concat(other)
+    if other.is_a?(AttributedString)
+      store = other.instance_variable_get(:@store).map { |obj| obj.dup }
+      translate_ranges(store, distance: self.length)
+      @store.concat(store)
+    end
+    super
+  end
+  alias_method :<<, :concat
+
+  def prepend(other)
+    if other.is_a?(AttributedString)
+      store = other.instance_variable_get(:@store).map { |obj| obj.dup }
+      translate_ranges(@store, distance: other.length)
+      @store.concat(store)
+    end
+    super
+  end
+
+
+  # modifies the string or returns a modified string
+  def replace(other)
+    super
+    other_store = other.instance_variable_get(:@store) || []
+    @store = other_store.map { |obj| obj.dup }
+  end
+
+  def +(other)
+    self.dup.concat(other)
+  end
+
+  def []=(arg, *args, value)
+      if arg.is_a?(Regexp)
+        raise Todo, "Regular expression assignment not implemented for []=, consider raising a pull request"
+      end
+      value ||= ""
+      value = value.is_a?(AttributedString) ? value : self.class.new(value)
+
+      range = arg.is_a?(Range) ? normalize_range(arg) : normalize_integer_slice_args(arg, *args)
+      return nil if range.nil?
+      slice!(range)
+      insert(range.begin, value)
+      value
+  end
+
+  private
+
+  def normalize_range(range, len: self.length)
+    return nil unless range
+
+     b = range.begin
+     e = range.end
+     exclude_end = range.exclude_end?
+
+     # Handle nil for begin and end
+     b = b.nil? ? 0 : b
+     e = e.nil? ? len : e
+
+     # Convert negative indices to positive
+     b += len if b < 0
+     e += len if e < 0
+
+     # Return nil if adjusted begin index is out of bounds
+     return nil if b < 0 || b > len
+
+     # Adjust indices to be within bounds
+     b = b.clamp(0, len)
+     e = e.clamp(-1, len)
+
+     # Adjust end for exclusive ranges unless both begin and end are nil
+     unless range.begin.nil? && range.end.nil?
+       e -= 1 if exclude_end
+     end
+
+     # Ensure the end index does not exceed len - 1
+     e = [e, len - 1].min
+
+     # Return nil if begin index is outside the string
+     return nil if b >= len
+
+     # Return empty range if begin > end
+     return b...b if b > e
+
+     # Return the normalized range
+     b..e
+  end
+
+  def normalize_index(index, len: self.length)
+    # Convert negative index to positive equivalent
+    normalized_index = index < 0 ? len + index : index
+
+    # Clamp the index within string bounds
+    [[normalized_index, 0].max, len].min
+  end
+
+  def normalize_integer_slice_args(start, *args, len: self.length)
+    length_set = args.length == 1
+    length = length_set ? args[0] : 1
+    # Return nil if start is nil or length is nil or negative
+    return nil if !length_set && start >= len
+
+    # Adjust negative start index
+    start += len if start < 0
+
+    # Return nil if start is still negative
+    return nil if start < 0
+
+    # Adjust length if it extends beyond the string
+    max_length = len - start
+    length = [length, max_length].min
+
+    # Return nil if length is negative
+    return nil if length < 0
+
+    # Return the normalized arguments
+    start...(start + length)
+  end
+
+  # @api private
+  # splits the ranges in the store at the given index
+  # if the index is negative, it will be counted from the end of the string
+  # @param index [Integer] the index to split the ranges at
+  # @param gap [Integer] the gap to insert at the index, if its negative, it will delete
+  # @param new_length [Integer] the new length of the string, used to remove ranges that are out of bounds
+  def split_ranges(store, index, gap, new_length)
+    new_ranges = []
+    store.each_with_index do |obj, idx|
+      range = obj[:range]
+
+      if gap > 0
+        if index <= range.begin
+          # Shift the range
+          obj[:range] = translate_range(range, distance: gap)
+        elsif index > range.begin && index <= range.end
+          # Attribute spans over the insertion point; split into two
+          original_end = range.end
+          obj[:range] = range.begin..(index - 1)
+          new_range = (index + gap)..(original_end + gap)
+          new_obj = obj.dup
+          new_obj[:range] = new_range
+          new_ranges << new_obj
+        end
+      else
+        # Deletion logic
+        deletion_end = index - gap - 1  # Since gap is negative
+        if range.end < index
+          # Case 1: Attribute entirely before deletion; no change needed
+          next
+        elsif range.begin > deletion_end
+          # Case 2: Attribute entirely after deletion; shift it
+          obj[:range] = translate_range(range, distance: gap)
+        elsif range.begin >= index && range.end <= deletion_end
+          # Case 5: Attribute entirely within deletion; remove it
+          store[idx] = nil
+        elsif range.begin >= index && range.end > deletion_end
+          # Case 3: Attribute starts within deletion, ends after deletion
+          obj[:range] = (index)..(range.end + gap)
+        elsif range.begin < index && range.end >= index && range.end <= deletion_end
+          # Case 4: Attribute starts before deletion, ends within deletion
+          obj[:range] = range.begin..(index - 1)
+        elsif range.begin < index && range.end > deletion_end
+          # Case 6: Attribute spans over deletion
+          obj[:range] = range.begin..(range.end + gap)
+        end
+
+        # Remove ranges that are now invalid
+        if obj[:range].end < obj[:range].begin || obj[:range].end < 0 || obj[:range].begin >= new_length
+          store[idx] = nil
+        end
+      end
+    end
+    store.concat(new_ranges)
+    store.compact!
+  end
+
+  def translate_ranges(store, distance:)
+    store.each do |obj|
+      obj[:range] = translate_range(obj[:range], distance:)
+    end
+  end
+
+  def translate_range(range, distance:)
+    range.exclude_end? ? (range.begin + distance)...(range.end + distance) : (range.begin + distance)..(range.end + distance)
+  end
+
+  def clamp_range(range, clamp_range)
+    # Determine the new start index
+    new_start = [range.begin, clamp_range.begin].max
+
+    # Adjust ends based on exclude_end?
+    range_end_adj = range.exclude_end? ? range.end - 1 : range.end
+    clamp_end_adj = clamp_range.exclude_end? ? clamp_range.end - 1 : clamp_range.end
+
+    # Determine the new adjusted end index
+    new_end_adj = [range_end_adj, clamp_end_adj].min
+
+    # Check if ranges do not overlap
+    if new_start > new_end_adj
+      return nil
+    end
+
+    # Check if each range includes new_end_adj
+    range_includes_new_end = range.cover?(new_end_adj)
+    clamp_includes_new_end = clamp_range.cover?(new_end_adj)
+
+    # Determine if the new range should exclude the end
+    new_exclude_end = !(range_includes_new_end && clamp_includes_new_end)
+
+    # Construct the new range
+    if new_exclude_end
+      # For exclusive ranges, the end index is one beyond the last included index
+      new_range = new_start... (new_end_adj + 1)
+    else
+      new_range = new_start..new_end_adj
+    end
+
+    new_range
+  end
+end

data/lib/attributed_string/unsupported.rb

@@ -0,0 +1,221 @@
+class AttributedString < String
+  class Todo < NotImplementedError
+    def message = "Not implemented, consider adding a pull request"
+  end
+
+  # Unsupported.
+  # Consider opening pull request
+  def gsub(*args, **kwargs, &block) = raise Todo
+
+  # Unsupported.
+  # Consider opening pull request
+  def gsub!(*args, **kwargs, &block) = raise Todo
+
+  # Unsupported.
+  # Consider opening pull request
+  def sub(*args, **kwargs, &block) = raise Todo
+
+  # Unsupported.
+  # Consider opening pull request
+  def sub!(*args, **kwargs, &block) = raise Todo
+
+  # Unsupported.
+  # Consider opening pull request
+  def succ(*args, **kwargs, &block) = raise Todo
+
+  # Unsupported.
+  # Consider opening pull request
+  def succ!(*args, **kwargs, &block) = raise Todo
+
+  # Unsupported.
+  # Consider opening pull request
+  def reverse(*args, **kwargs, &block) = raise Todo
+
+  # Unsupported.
+  # Consider opening pull request
+  def reverse!(*args, **kwargs, &block) = raise Todo
+
+  # Unsupported.
+  # Consider opening pull request
+  def setbyte(*args, **kwargs, &block) = raise Todo
+
+  # Unsupported.
+  # Consider opening pull request
+  def tr(*args, **kwargs, &block) = raise Todo
+
+  # Unsupported.
+  # Consider opening pull request
+  def tr!(*args, **kwargs, &block) = raise Todo
+
+  # Unsupported.
+  # Consider opening pull request
+  def tr_s(*args, **kwargs, &block) = raise Todo
+
+  # Unsupported.
+  # Consider opening pull request
+  def tr_s!(*args, **kwargs, &block) = raise Todo
+
+  # Unsupported.
+  # Consider opening pull request
+  def squeeze(*args, **kwargs, &block) = raise Todo
+
+  # Unsupported.
+  # Consider opening pull request
+  def squeeze!(*args, **kwargs, &block) = raise Todo
+
+  # Unsupported.
+  # Consider opening pull request
+  def lstrip(*args, **kwargs, &block) = raise Todo
+
+  # Unsupported.
+  # Consider opening pull request
+  def lstrip!(*args, **kwargs, &block) = raise Todo
+
+  # Unsupported.
+  # Consider opening pull request
+  def rstrip(*args, **kwargs, &block) = raise Todo
+
+  # Unsupported.
+  # Consider opening pull request
+  def rstrip!(*args, **kwargs, &block) = raise Todo
+
+  # Unsupported.
+  # Consider opening pull request
+  def strip(*args, **kwargs, &block) = raise Todo
+
+  # Unsupported.
+  # Consider opening pull request
+  def strip!(*args, **kwargs, &block) = raise Todo
+
+  # Unsupported.
+  # Consider opening pull request
+  def chomp(*args, **kwargs, &block) = raise Todo
+
+  # Unsupported.
+  # Consider opening pull request
+  def chomp!(*args, **kwargs, &block) = raise Todo
+
+  # Unsupported.
+  # Consider opening pull request
+  def chop(*args, **kwargs, &block) = raise Todo
+
+  # Unsupported.
+  # Consider opening pull request
+  def chop!(*args, **kwargs, &block) = raise Todo
+
+  # converts string
+
+  # Unsupported.
+  # Consider opening pull request
+  def center(*args, **kwargs, &block) = raise Todo
+
+  # Unsupported.
+  # Consider opening pull request
+  def ljust(*args, **kwargs, &block) = raise Todo
+
+  # Unsupported.
+  # Consider opening pull request
+  def rjust(*args, **kwargs, &block) = raise Todo
+
+  # Unsupported.
+  # Consider opening pull request
+  def b(*args, **kwargs, &block) = raise Todo
+
+  # Unsupported.
+  # Consider opening pull request
+  def scrub(*args, **kwargs, &block) = raise Todo
+
+  # Unsupported.
+  # Consider opening pull request
+  def unicode_normalize(*args, **kwargs, &block) = raise Todo
+
+  # Unsupported.
+  # Consider opening pull request
+  def encode(*args, **kwargs, &block) = raise Todo
+
+  # substitutions
+
+  # Unsupported.
+  # Consider opening pull request
+  def dump(*args, **kwargs, &block) = raise Todo
+
+  # Unsupported.
+  # Consider opening pull request
+  def undump(*args, **kwargs, &block) = raise Todo
+
+  # Unsupported.
+  # Consider opening pull request
+  def %(*args, **kwargs, &block) = raise Todo
+
+  # more deletes
+
+  # Unsupported.
+  # Consider opening pull request
+  def delete(*args, **kwargs, &block) = raise Todo
+
+  # Unsupported.
+  # Consider opening pull request
+  def delete!(*args, **kwargs, &block) = raise Todo
+
+  # Unsupported.
+  # Consider opening pull request
+  def delete_prefix(*args, **kwargs, &block) = raise Todo
+
+  # Unsupported.
+  # Consider opening pull request
+  def delete_prefix!(*args, **kwargs, &block) = raise Todo
+
+  # Unsupported.
+  # Consider opening pull request
+  def delete_suffix(*args, **kwargs, &block) = raise Todo
+
+  # Unsupported.
+  # Consider opening pull request
+  def delete_suffix!(*args, **kwargs, &block) = raise Todo
+
+  # Unsupported.
+  # Consider opening pull request
+  def byteslice(*args, **kwargs, &block) = raise Todo
+
+  # Unsupported.
+  # Consider opening pull request
+  def chr(*args, **kwargs, &block) = raise Todo
+
+  # Unsupported.
+  # Consider opening pull request
+  def *(*args, **kwargs, &block) = raise Todo
+
+
+  # Unsupported.
+  # Consider opening pull request
+  def lines(*args, **kwargs, &block) = raise Todo
+
+  # Unsupported.
+  # Consider opening pull request
+  def partition(*args, **kwargs, &block) = raise Todo
+
+  # Unsupported.
+  # Consider opening pull request
+  def rpartition(*args, **kwargs, &block) = raise Todo
+
+  # Unsupported.
+  # Consider opening pull request
+  def split(*args, **kwargs, &block) = raise Todo
+
+  # Unsupported.
+  # Consider opening pull request
+  def scan(*args, **kwargs, &block) = raise Todo
+
+  # Unsupported.
+  # Consider opening pull request
+  def unpack(*args, **kwargs, &block) = raise Todo
+
+  # Unsupported.
+  # Consider opening pull request
+  def unpack1(*args, **kwargs, &block) = raise Todo
+
+  # Unsupported.
+  # Consider opening pull request
+  def upto(*args, **kwargs, &block) = raise Todo
+
+end

data/lib/attributed_string/version.rb

@@ -0,0 +1,3 @@
+class AttributedString < String
+  VERSION = "0.1.0"
+end

metadata

@@ -0,0 +1,56 @@
+--- !ruby/object:Gem::Specification
+name: attributed-string
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Andrew Mackross
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2024-12-20 00:00:00.000000000 Z
+dependencies: []
+description:
+email: andrew@mackross.net
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/attributed-string.rb
+- lib/attributed_string/attachment.rb
+- lib/attributed_string/filter_result.rb
+- lib/attributed_string/inspect.rb
+- lib/attributed_string/klass.rb
+- lib/attributed_string/needs_testing.rb
+- lib/attributed_string/refine.rb
+- lib/attributed_string/string_ops.rb
+- lib/attributed_string/unsupported.rb
+- lib/attributed_string/version.rb
+homepage: https://github.com/instruct-rb/attributed-string
+licenses:
+- Apache-2.0
+metadata:
+  source_code_uri: https://github.com/instruct-rb/attributed-string
+  homepage_uri: https://github.com/instruct-rb/attributed-string
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.3
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.16
+signing_key:
+specification_version: 4
+summary: An attributed string implementation for Ruby.
+test_files: []