sashite-cell 2.0.2 → 4.0.0

data/lib/sashite/cell/formatter.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+module Sashite
+  module Cell
+    # Formats index arrays into CELL coordinate strings.
+    #
+    # This module handles the conversion from numeric indices to their
+    # CELL string representation following the cyclic pattern:
+    # - Dimension 1, 4, 7...: lowercase letters (a-z, aa-iv)
+    # - Dimension 2, 5, 8...: positive integers (1-256)
+    # - Dimension 3, 6, 9...: uppercase letters (A-Z, AA-IV)
+    #
+    # @example
+    #   Formatter.indices_to_string([4, 3])    # => "e4"
+    #   Formatter.indices_to_string([0, 0, 0]) # => "a1A"
+    #
+    # @api private
+    module Formatter
+      # Formats an indices array to a CELL string.
+      #
+      # @param indices [Array<Integer>] 0-indexed coordinate values
+      # @return [String] CELL coordinate string
+      #
+      # @example
+      #   Formatter.indices_to_string([4, 3])       # => "e4"
+      #   Formatter.indices_to_string([255, 255, 255]) # => "iv256IV"
+      def self.indices_to_string(indices)
+        result = +""
+
+        indices.each_with_index do |index, i|
+          dimension_type = i % 3
+
+          result << case dimension_type
+                    when 0 then encode_to_lower(index)
+                    when 1 then encode_to_number(index)
+                    when 2 then encode_to_upper(index)
+                    end
+        end
+
+        result.freeze
+      end
+
+      # Encodes an index (0-255) as lowercase letters (a-z, aa-iv).
+      #
+      # @param index [Integer] 0-indexed value (0-255)
+      # @return [String] lowercase letter sequence
+      #
+      # @example
+      #   encode_to_lower(0)   # => "a"
+      #   encode_to_lower(25)  # => "z"
+      #   encode_to_lower(26)  # => "aa"
+      #   encode_to_lower(255) # => "iv"
+      private_class_method def self.encode_to_lower(index)
+        encode_to_letters(index, base: "a")
+      end
+
+      # Encodes an index (0-255) as uppercase letters (A-Z, AA-IV).
+      #
+      # @param index [Integer] 0-indexed value (0-255)
+      # @return [String] uppercase letter sequence
+      #
+      # @example
+      #   encode_to_upper(0)   # => "A"
+      #   encode_to_upper(25)  # => "Z"
+      #   encode_to_upper(26)  # => "AA"
+      #   encode_to_upper(255) # => "IV"
+      private_class_method def self.encode_to_upper(index)
+        encode_to_letters(index, base: "A")
+      end
+
+      # Encodes an index to a letter sequence.
+      #
+      # @param index [Integer] 0-indexed value (0-255)
+      # @param base [String] base character ("a" or "A")
+      # @return [String] letter sequence
+      private_class_method def self.encode_to_letters(index, base:)
+        base_ord = base.ord
+
+        if index < 26
+          (base_ord + index).chr
+        else
+          adjusted = index - 26
+          first = adjusted / 26
+          second = adjusted % 26
+          (base_ord + first).chr + (base_ord + second).chr
+        end
+      end
+
+      # Encodes an index (0-255) as a 1-based positive integer string.
+      #
+      # @param index [Integer] 0-indexed value (0-255)
+      # @return [String] number string (1-indexed)
+      #
+      # @example
+      #   encode_to_number(0)   # => "1"
+      #   encode_to_number(255) # => "256"
+      private_class_method def self.encode_to_number(index)
+        (index + 1).to_s
+      end
+    end
+  end
+end

data/lib/sashite/cell/parser.rb

@@ -0,0 +1,234 @@
+# frozen_string_literal: true
+
+require_relative "constants"
+require_relative "errors"
+
+module Sashite
+  module Cell
+    # Parses CELL coordinate strings into index arrays.
+    #
+    # This module handles the conversion from CELL string representation
+    # to numeric indices, following the cyclic pattern:
+    # - Dimension 1, 4, 7...: lowercase letters (a-z, aa-iv)
+    # - Dimension 2, 5, 8...: positive integers (1-256)
+    # - Dimension 3, 6, 9...: uppercase letters (A-Z, AA-IV)
+    #
+    # Security considerations:
+    # - Character-by-character parsing (no regex, no ReDoS risk)
+    # - Fail-fast on invalid input
+    # - Bounded iteration (max 7 characters)
+    # - Explicit ASCII validation
+    #
+    # @example
+    #   Parser.parse_to_indices("e4")  # => [4, 3]
+    #   Parser.parse_to_indices("a1A") # => [0, 0, 0]
+    #
+    # @api private
+    module Parser
+      # Parses a CELL string into an array of indices.
+      #
+      # @param string [String] CELL coordinate string
+      # @return [Array<Integer>] 0-indexed coordinate values
+      # @raise [Sashite::Cell::Errors::Argument] if parsing fails
+      #
+      # @example
+      #   Parser.parse_to_indices("e4")      # => [4, 3]
+      #   Parser.parse_to_indices("iv256IV") # => [255, 255, 255]
+      def self.parse_to_indices(string)
+        raise Errors::Argument, Errors::Argument::Messages::EMPTY_INPUT if string.empty?
+
+        if string.length > Constants::MAX_STRING_LENGTH
+          raise Errors::Argument, Errors::Argument::Messages::INPUT_TOO_LONG
+        end
+
+        first_byte = string.getbyte(0)
+        unless lowercase?(first_byte)
+          raise Errors::Argument, Errors::Argument::Messages::INVALID_START
+        end
+
+        indices = []
+        pos = 0
+        dimension_type = 0 # 0: lowercase, 1: integer, 2: uppercase
+
+        while pos < string.length
+          if indices.size >= Constants::MAX_DIMENSIONS
+            raise Errors::Argument, Errors::Argument::Messages::TOO_MANY_DIMENSIONS
+          end
+
+          case dimension_type
+          when 0
+            value, consumed = parse_lowercase(string, pos)
+            indices << value
+            pos += consumed
+            dimension_type = 1
+          when 1
+            value, consumed = parse_integer(string, pos)
+            indices << value
+            pos += consumed
+            dimension_type = 2
+          when 2
+            value, consumed = parse_uppercase(string, pos)
+            indices << value
+            pos += consumed
+            dimension_type = 0
+          end
+        end
+
+        indices
+      end
+
+      # Checks if a byte is a lowercase ASCII letter (a-z).
+      #
+      # @param byte [Integer, nil] byte value
+      # @return [Boolean] true if lowercase letter
+      private_class_method def self.lowercase?(byte)
+        byte && byte >= 97 && byte <= 122 # 'a' = 97, 'z' = 122
+      end
+
+      # Checks if a byte is an uppercase ASCII letter (A-Z).
+      #
+      # @param byte [Integer, nil] byte value
+      # @return [Boolean] true if uppercase letter
+      private_class_method def self.uppercase?(byte)
+        byte && byte >= 65 && byte <= 90 # 'A' = 65, 'Z' = 90
+      end
+
+      # Checks if a byte is an ASCII digit (0-9).
+      #
+      # @param byte [Integer, nil] byte value
+      # @return [Boolean] true if digit
+      private_class_method def self.digit?(byte)
+        byte && byte >= 48 && byte <= 57 # '0' = 48, '9' = 57
+      end
+
+      # Parses lowercase letters starting at position.
+      #
+      # @param string [String] input string
+      # @param pos [Integer] starting position
+      # @return [Array(Integer, Integer)] decoded value and characters consumed
+      # @raise [Sashite::Cell::Errors::Argument] if parsing fails
+      private_class_method def self.parse_lowercase(string, pos)
+        byte = string.getbyte(pos)
+        unless lowercase?(byte)
+          raise Errors::Argument, Errors::Argument::Messages::UNEXPECTED_CHARACTER
+        end
+
+        chars = [byte]
+        pos += 1
+
+        while pos < string.length && lowercase?(string.getbyte(pos))
+          chars << string.getbyte(pos)
+          pos += 1
+        end
+
+        value = decode_lowercase(chars)
+        if value > Constants::MAX_INDEX_VALUE
+          raise Errors::Argument, Errors::Argument::Messages::INDEX_OUT_OF_RANGE
+        end
+
+        [value, chars.size]
+      end
+
+      # Parses a positive integer starting at position.
+      #
+      # @param string [String] input string
+      # @param pos [Integer] starting position
+      # @return [Array(Integer, Integer)] decoded value and characters consumed
+      # @raise [Sashite::Cell::Errors::Argument] if parsing fails
+      private_class_method def self.parse_integer(string, pos)
+        byte = string.getbyte(pos)
+        unless digit?(byte)
+          raise Errors::Argument, Errors::Argument::Messages::UNEXPECTED_CHARACTER
+        end
+
+        # Check for leading zero
+        if byte == 48 # '0'
+          raise Errors::Argument, Errors::Argument::Messages::LEADING_ZERO
+        end
+
+        chars = [byte]
+        pos += 1
+
+        while pos < string.length && digit?(string.getbyte(pos))
+          chars << string.getbyte(pos)
+          pos += 1
+        end
+
+        value = decode_integer(chars)
+        if value < 0 || value > Constants::MAX_INDEX_VALUE
+          raise Errors::Argument, Errors::Argument::Messages::INDEX_OUT_OF_RANGE
+        end
+
+        [value, chars.size]
+      end
+
+      # Parses uppercase letters starting at position.
+      #
+      # @param string [String] input string
+      # @param pos [Integer] starting position
+      # @return [Array(Integer, Integer)] decoded value and characters consumed
+      # @raise [Sashite::Cell::Errors::Argument] if parsing fails
+      private_class_method def self.parse_uppercase(string, pos)
+        byte = string.getbyte(pos)
+        unless uppercase?(byte)
+          raise Errors::Argument, Errors::Argument::Messages::UNEXPECTED_CHARACTER
+        end
+
+        chars = [byte]
+        pos += 1
+
+        while pos < string.length && uppercase?(string.getbyte(pos))
+          chars << string.getbyte(pos)
+          pos += 1
+        end
+
+        value = decode_uppercase(chars)
+        if value > Constants::MAX_INDEX_VALUE
+          raise Errors::Argument, Errors::Argument::Messages::INDEX_OUT_OF_RANGE
+        end
+
+        [value, chars.size]
+      end
+
+      # Decodes lowercase letter bytes to an index.
+      #
+      # @param bytes [Array<Integer>] byte values
+      # @return [Integer] decoded index (0-255)
+      private_class_method def self.decode_lowercase(bytes)
+        if bytes.size == 1
+          bytes[0] - 97 # 'a' = 97
+        else
+          first = bytes[0] - 97
+          second = bytes[1] - 97
+          26 + (first * 26) + second
+        end
+      end
+
+      # Decodes uppercase letter bytes to an index.
+      #
+      # @param bytes [Array<Integer>] byte values
+      # @return [Integer] decoded index (0-255)
+      private_class_method def self.decode_uppercase(bytes)
+        if bytes.size == 1
+          bytes[0] - 65 # 'A' = 65
+        else
+          first = bytes[0] - 65
+          second = bytes[1] - 65
+          26 + (first * 26) + second
+        end
+      end
+
+      # Decodes digit bytes to an index (1-based to 0-based).
+      #
+      # @param bytes [Array<Integer>] byte values
+      # @return [Integer] decoded index (0-255)
+      private_class_method def self.decode_integer(bytes)
+        value = 0
+        bytes.each do |byte|
+          value = (value * 10) + (byte - 48) # '0' = 48
+        end
+        value - 1 # Convert from 1-based to 0-based
+      end
+    end
+  end
+end

data/lib/sashite/cell.rb

@@ -1,264 +1,84 @@
 # frozen_string_literal: true
 
+require_relative "cell/errors"
+require_relative "cell/formatter"
+require_relative "cell/coordinate"
+require_relative "cell/parser"
+
 module Sashite
-  # CELL (Coordinate Encoding for Layered Locations) implementation for Ruby
+  # CELL (Coordinate Encoding for Layered Locations) implementation.
+  #
+  # Provides parsing, formatting, and validation of CELL coordinates
+  # for multi-dimensional game boards (up to 3 dimensions).
+  #
+  # @example Parsing a coordinate
+  #   coord = Sashite::Cell.parse("e4")
+  #   coord.indices    # => [4, 3]
+  #   coord.dimensions # => 2
+  #
+  # @example Formatting indices
+  #   Sashite::Cell.format(4, 3) # => "e4"
   #
-  # Provides functionality for working with multi-dimensional game board coordinates
-  # using a cyclical ASCII character system.
+  # @example Validation
+  #   Sashite::Cell.valid?("e4") # => true
+  #   Sashite::Cell.valid?("a0") # => false
   #
-  # This implementation is strictly compliant with CELL Specification v1.0.0
-  # @see https://sashite.dev/specs/cell/1.0.0/ CELL Specification v1.0.0
+  # @see https://sashite.dev/specs/cell/1.0.0/
   module Cell
-    # Regular expression from CELL Specification v1.0.0
-    # Note: Line breaks must be rejected separately (see valid?)
-    REGEX = /^[a-z]+(?:[1-9][0-9]*[A-Z]+[a-z]+)*(?:[1-9][0-9]*[A-Z]*)?$/
-
-    # Check if a string represents a valid CELL coordinate
-    #
-    # Implements full-string matching as required by the CELL specification.
-    # Rejects any input containing line breaks (\r or \n).
+    # Parses a CELL string into a Coordinate.
     #
-    # @param string [String] the string to validate
-    # @return [Boolean] true if the string is a valid CELL coordinate
+    # @param string [String] CELL coordinate string
+    # @return [Coordinate] parsed coordinate
+    # @raise [Sashite::Cell::Errors::Argument] if the string is not a valid CELL coordinate
     #
     # @example
-    #   Sashite::Cell.valid?("a1")     # => true
-    #   Sashite::Cell.valid?("a1A")    # => true
-    #   Sashite::Cell.valid?("*")      # => false
-    #   Sashite::Cell.valid?("a0")     # => false
-    #   Sashite::Cell.valid?("a1\n")   # => false
-    def self.valid?(string)
-      return false unless string.is_a?(String)
-      return false if string.empty?
-      return false if string.include?("\r") || string.include?("\n")
-
-      string.match?(REGEX)
-    end
-
-    # Get the number of dimensions in a coordinate
-    #
-    # @param string [String] the coordinate string
-    # @return [Integer] the number of dimensions
-    #
-    # @example
-    #   Sashite::Cell.dimensions("a1")     # => 2
-    #   Sashite::Cell.dimensions("a1A")    # => 3
-    #   Sashite::Cell.dimensions("foobar") # => 1
-    def self.dimensions(string)
-      return 0 unless valid?(string)
-
-      parse(string).length
-    end
-
-    # Parse a coordinate string into dimensional components
-    #
-    # @param string [String] the coordinate string to parse
-    # @return [Array<String>] array of dimensional components
-    #
-    # @example
-    #   Sashite::Cell.parse("a1A")      # => ["a", "1", "A"]
-    #   Sashite::Cell.parse("h8Hh8")    # => ["h", "8", "H", "h", "8"]
-    #   Sashite::Cell.parse("foobar")   # => ["foobar"] (if valid single dimension)
+    #   Sashite::Cell.parse("e4")  # => #<Sashite::Cell::Coordinate e4>
+    #   Sashite::Cell.parse("a1A") # => #<Sashite::Cell::Coordinate a1A>
+    #   Sashite::Cell.parse("a0")  # => raises Sashite::Cell::Errors::Argument
     def self.parse(string)
-      return [] unless string.is_a?(::String)
-      return [] if string.empty?
-      return [] unless valid?(string)
-
-      parse_recursive(string, 1)
+      Coordinate.new(*Parser.parse_to_indices(string))
     end
 
-    # Convert a CELL coordinate to an array of 0-indexed integers
+    # Formats indices into a CELL string.
     #
-    # @param string [String] the CELL coordinate
-    # @return [Array<Integer>] array of 0-indexed positions
+    # @param indices [Array<Integer>] 0-indexed coordinate values (0-255)
+    # @return [String] CELL coordinate string
+    # @raise [Sashite::Cell::Errors::Argument] if indices are invalid
     #
     # @example
-    #   Sashite::Cell.to_indices("a1")   # => [0, 0]
-    #   Sashite::Cell.to_indices("e4")   # => [4, 3]
-    #   Sashite::Cell.to_indices("a1A")  # => [0, 0, 0]
-    def self.to_indices(string)
-      return [] unless valid?(string)
-
-      parse(string).map.with_index do |component, index|
-        dimension_type = dimension_type(index + 1)
-        component_to_index(component, dimension_type)
-      end
+    #   Sashite::Cell.format(4, 3)    # => "e4"
+    #   Sashite::Cell.format(0, 0, 0) # => "a1A"
+    def self.format(*indices)
+      Coordinate.new(*indices).to_s
     end
 
-    # Convert an array of 0-indexed integers to a CELL coordinate
+    # Validates a CELL string.
     #
-    # @param indices [Array<Integer>] splat arguments of 0-indexed positions
-    # @return [String] the CELL coordinate
+    # @param string [String] CELL coordinate string
+    # @return [nil]
+    # @raise [Sashite::Cell::Errors::Argument] if the string is not a valid CELL coordinate
     #
     # @example
-    #   Sashite::Cell.from_indices(0, 0)     # => "a1"
-    #   Sashite::Cell.from_indices(4, 3)     # => "e4"
-    #   Sashite::Cell.from_indices(0, 0, 0)  # => "a1A"
-    def self.from_indices(*indices)
-      return "" if indices.empty?
-
-      result = indices.map.with_index do |index, dimension|
-        dimension_type = dimension_type(dimension + 1)
-        index_to_component(index, dimension_type)
-      end.join
-
-      # Verify the result is valid according to CELL specification
-      valid?(result) ? result : ""
-    end
-
-    # Get the validation regular expression
-    #
-    # Note: This regex alone does not guarantee full compliance. The valid?
-    # method additionally rejects strings containing line breaks, as required
-    # by the specification's anchoring requirements.
-    #
-    # @return [Regexp] the CELL validation regex from specification v1.0.0
-    def self.regex
-      REGEX
-    end
-
-    # Recursively parse a coordinate string into components
-    # following the strict CELL specification cyclical pattern
-    #
-    # @param string [String] the remaining string to parse
-    # @param dimension [Integer] the current dimension (1-indexed)
-    # @return [Array<String>] array of dimensional components
-    def self.parse_recursive(string, dimension)
-      return [] if string.empty?
-
-      expected_type = dimension_type(dimension)
-      component = extract_component(string, expected_type)
-
-      return [] if component.nil?
-
-      # Extract component and recursively parse the rest
-      remaining = string[component.length..]
-      [component] + parse_recursive(remaining, dimension + 1)
+    #   Sashite::Cell.validate("e4")  # => nil
+    #   Sashite::Cell.validate("a0")  # => raises Sashite::Cell::Errors::Argument
+    def self.validate(string)
+      Parser.parse_to_indices(string)
+      nil
     end
 
-    # Determine the character set type for a given dimension
-    # Following CELL specification cyclical system: dimension n % 3 determines character set
+    # Reports whether string is a valid CELL coordinate.
     #
-    # @param dimension [Integer] the dimension number (1-indexed)
-    # @return [Symbol] :lowercase, :numeric, or :uppercase
-    def self.dimension_type(dimension)
-      case dimension % 3
-      when 1 then :lowercase  # n % 3 = 1: Latin lowercase letters
-      when 2 then :numeric    # n % 3 = 2: Arabic numerals
-      when 0 then :uppercase  # n % 3 = 0: Latin uppercase letters
-      end
-    end
-
-    # Extract the next component from a string based on expected type
-    # Strictly follows CELL specification patterns
-    #
-    # @param string [String] the string to extract from
-    # @param type [Symbol] the expected component type
-    # @return [String, nil] the extracted component or nil if invalid
-    def self.extract_component(string, type)
-      case type
-      when :lowercase
-        # Latin lowercase letters: [a-z]+
-        match = string.match(/^([a-z]+)/)
-        match ? match[1] : nil
-      when :numeric
-        # Arabic numerals: [1-9][0-9]* (CELL specification requires positive integers only)
-        match = string.match(/^([1-9][0-9]*)/)
-        match ? match[1] : nil
-      when :uppercase
-        # Latin uppercase letters: [A-Z]+
-        match = string.match(/^([A-Z]+)/)
-        match ? match[1] : nil
-      end
-    end
-
-    # Convert a component to its 0-indexed position
-    #
-    # @param component [String] the component
-    # @param type [Symbol] the component type
-    # @return [Integer] the 0-indexed position
-    def self.component_to_index(component, type)
-      case type
-      when :lowercase
-        letters_to_index(component)
-      when :numeric
-        component.to_i - 1
-      when :uppercase
-        letters_to_index(component.downcase)
-      end
-    end
-
-    # Convert a 0-indexed position to a component
-    #
-    # @param index [Integer] the 0-indexed position
-    # @param type [Symbol] the component type
-    # @return [String] the component
-    def self.index_to_component(index, type)
-      case type
-      when :lowercase
-        index_to_letters(index)
-      when :numeric
-        (index + 1).to_s
-      when :uppercase
-        index_to_letters(index).upcase
-      end
-    end
-
-    # Convert letter sequence to 0-indexed position
-    # Extended alphabet per CELL specification: a=0, b=1, ..., z=25, aa=26, ab=27, ..., zz=701, aaa=702, etc.
+    # @param string [String] CELL coordinate string
+    # @return [Boolean] true if valid, false otherwise
     #
-    # @param letters [String] the letter sequence
-    # @return [Integer] the 0-indexed position
-    def self.letters_to_index(letters)
-      length = letters.length
-      index = 0
-
-      # Add positions from shorter sequences
-      (1...length).each do |len|
-        index += 26**len
-      end
-
-      # Add position within current length
-      letters.each_char.with_index do |char, pos|
-        index += (char.ord - 97) * (26**(length - pos - 1))
-      end
-
-      index
-    end
-
-    # Convert 0-indexed position to letter sequence
-    # Extended alphabet per CELL specification: 0=a, 1=b, ..., 25=z, 26=aa, 27=ab, ..., 701=zz, 702=aaa, etc.
-    #
-    # @param index [Integer] the 0-indexed position
-    # @return [String] the letter sequence
-    def self.index_to_letters(index)
-      # Find the length of the result
-      length = 1
-      base = 0
-
-      loop do
-        range_size = 26**length
-        break if index < base + range_size
-
-        base += range_size
-        length += 1
-      end
-
-      # Convert within the found length
-      adjusted_index = index - base
-      result = ""
-
-      length.times do |pos|
-        char_index = adjusted_index / (26**(length - pos - 1))
-        result += (char_index + 97).chr
-        adjusted_index %= (26**(length - pos - 1))
-      end
-
-      result
+    # @example
+    #   Sashite::Cell.valid?("e4")  # => true
+    #   Sashite::Cell.valid?("a0")  # => false
+    def self.valid?(string)
+      validate(string)
+      true
+    rescue Errors::Argument
+      false
     end
-
-    private_class_method :parse_recursive, :dimension_type, :extract_component
-    private_class_method :component_to_index, :index_to_component
-    private_class_method :letters_to_index, :index_to_letters
   end
 end

data/lib/sashite-cell.rb

@@ -1,14 +1,3 @@
 # frozen_string_literal: true
 
 require_relative "sashite/cell"
-
-# Sashité namespace for board game notation libraries
-#
-# Sashité provides a collection of libraries for representing and manipulating
-# board game concepts according to the Sashité Protocol specifications.
-#
-# @see https://sashite.dev/protocol/ Sashité Protocol
-# @see https://sashite.dev/specs/ Sashité Specifications
-# @author Sashité
-module Sashite
-end