sashite-cell 1.0.0 → 2.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1071f1a4bf4e1d9f6893185fe61fc25a361ca97ba8e9d74e3e72f2fba1300362
-  data.tar.gz: 2b723da1c614caed08b87bbb8eb382d484a5cc0e915ab6ed7c87949196322ded
+  metadata.gz: 84228cab7c7155caaec3a2adad475150eb8b272c5c8e67d2dfb1e626b6120e7e
+  data.tar.gz: 318c49ae54afbfec1edaeca7a03c23c7cc5a65cec0658d14973f54a203c15914
 SHA512:
-  metadata.gz: 86c6f48a5c77440ddfe886b6c7da0e8871149af862164b7fc060dd07002afa18e69bffc0f897f1de392ecbf7bcc2507786903b326513b6241251f3be20638c81
-  data.tar.gz: 37dd7540c541a6aaee7d8a29ff8e6eb03119dabdc6c0c0f21cd63fdcb8ed59ff2d80d74b479a9b9a8e6cbb84cb8dbd981ed2492cd48c2c07e3fe383a917a5a8f
+  metadata.gz: afe40400d123291deed966e92943ac01b18195cb1a1d191473ff0c719721288c4bae5c1032b6a524f194c722779818c81d02c4709e115bb7f29916eb3ed1828f
+  data.tar.gz: be17bfa93a1db05ddaecc938db407a3788ab565d1254e3f61ff9cdd714a09298c5137d3131e11d374d0c9c2d51725a0720f8e8dac7375b614ad3909e26e8687c

data/README.md

@@ -5,13 +5,13 @@
 ![Ruby](https://github.com/sashite/cell.rb/actions/workflows/main.yml/badge.svg?branch=main)
 [![License](https://img.shields.io/github/license/sashite/cell.rb?label=License&logo=github)](https://github.com/sashite/cell.rb/raw/main/LICENSE.md)
 
-> **CELL** (Coordinate Expression Location Label) support for the Ruby language.
+> **CELL** (Coordinate Encoding for Layered Locations) support for the Ruby language.
 
 ## What is CELL?
 
-CELL (Coordinate Expression Location Label) defines a consistent and rule-agnostic format for representing locations in abstract strategy board games. CELL provides a standardized way to identify positions on game boards and pieces held in hand/reserve, establishing a common foundation for location reference across the Sashité notation ecosystem.
+CELL (Coordinate Encoding for Layered Locations) is a standardized format for representing coordinates on multi-dimensional game boards using a cyclical ASCII character system. CELL supports unlimited dimensional coordinate systems through the systematic repetition of three distinct character sets.
 
-This gem implements the [CELL Specification v1.0.0](https://sashite.dev/documents/cell/1.0.0/), providing a Ruby interface for working with game locations through a clean and simple API that serves as a foundational building block for other Sashité specifications.
+This gem implements the [CELL Specification v1.0.0](https://sashite.dev/specs/cell/1.0.0/), providing a Ruby interface for working with multi-dimensional game coordinates through a clean, functional API.
 
 ## Installation
 
@@ -28,324 +28,320 @@ gem install sashite-cell
 
 ## CELL Format
 
-A CELL location is represented by a single string following one of two patterns:
+CELL uses a cyclical three-character-set system that repeats indefinitely based on dimensional position:
 
-### Board Coordinates
+**Dimension (n % 3 = 1)**: Latin Lowercase Letters
+- `a`, `b`, `c`, ..., `z`, `aa`, `ab`, ..., `zz`, `aaa`, ...
 
-Any non-empty string containing only alphanumeric characters (`a-z`, `A-Z`, `0-9`):
+**Dimension (n % 3 = 2)**: Arabic Numerals
+- `1`, `2`, `3`, ..., `25`, `26`, ...
 
-```
-e4        # Chess notation
-5c        # Shōgi notation
-A3a       # 3D coordinate
-center    # Custom coordinate
-```
-
-### Hand/Reserve Location
-
-The reserved character `*` represents pieces held off-board:
-```
-*         # Hand/reserve location
-```
+**Dimension (n % 3 = 0)**: Latin Uppercase Letters
+- `A`, `B`, `C`, ..., `Z`, `AA`, `AB`, ..., `ZZ`, `AAA`, ...
 
 ## Basic Usage
 
-### Creating Location Objects
+### Validation
 
-The primary interface is the `Sashite::Cell::Location` class, which represents a game location in CELL format:
+The primary functionality is validating CELL coordinates:
 
 ```ruby
 require "sashite/cell"
 
-# Parse CELL strings into location objects
-board_pos = Sashite::Cell::Location.parse("e4")
-# => #<Sashite::Cell::Location:0x... @coordinate="e4">
+# Check if a string represents a valid CELL coordinate
+Sashite::Cell.valid?("a1")     # => true (2D coordinate)
+Sashite::Cell.valid?("a1A")    # => true (3D coordinate)
+Sashite::Cell.valid?("e4")     # => true (2D coordinate)
+Sashite::Cell.valid?("h8Hh8")  # => true (5D coordinate)
+Sashite::Cell.valid?("*")      # => false (not a CELL coordinate)
+Sashite::Cell.valid?("a0")     # => false (invalid numeral)
+Sashite::Cell.valid?("")       # => false (empty string)
+
+# Alias for convenience
+Cell = Sashite::Cell
+Cell.valid?("a1") # => true
+```
+
+### Dimensional Analysis
+
+```ruby
+# Get the number of dimensions in a coordinate
+Sashite::Cell.dimensions("a1")     # => 2
+Sashite::Cell.dimensions("a1A")    # => 3
+Sashite::Cell.dimensions("h8Hh8")  # => 5
+Sashite::Cell.dimensions("foobar") # => 1
 
-hand_pos = Sashite::Cell::Location.parse("*")
-# => #<Sashite::Cell::Location:0x... @coordinate="*">
+# Parse coordinate into dimensional components
+Sashite::Cell.parse("a1A")
+# => ["a", "1", "A"]
 
-# Create directly with constructor
-location = Sashite::Cell::Location.new("e4")
-hand = Sashite::Cell::Location.new("*")
+Sashite::Cell.parse("h8Hh8")
+# => ["h", "8", "H", "h", "8"]
 
-# Convenience method
-location = Sashite::Cell.location("e4")
+Sashite::Cell.parse("foobar")
+# => ["foobar"]
 ```
 
-### Converting to CELL String
-
-Convert a location object back to its CELL string representation:
+### Coordinate Conversion
 
 ```ruby
-location = Sashite::Cell::Location.parse("e4")
-location.to_s
-# => "e4"
-
-hand = Sashite::Cell::Location.parse("*")
-hand.to_s
-# => "*"
-```
+# Convert coordinates to arrays of integers (0-indexed)
+Sashite::Cell.to_indices("a1")
+# => [0, 0]
 
-### Checking Location Types
+Sashite::Cell.to_indices("e4")
+# => [4, 3]
 
-Distinguish between board coordinates and hand/reserve locations:
+Sashite::Cell.to_indices("a1A")
+# => [0, 0, 0]
 
-```ruby
-board_loc = Sashite::Cell::Location.parse("e4")
-hand_loc = Sashite::Cell::Location.parse("*")
+# Convert arrays of integers back to CELL coordinates
+Sashite::Cell.from_indices(0, 0)
+# => "a1"
 
-board_loc.board?     # => true
-board_loc.hand?      # => false
+Sashite::Cell.from_indices(4, 3)
+# => "e4"
 
-hand_loc.board?      # => false
-hand_loc.hand?       # => true
+Sashite::Cell.from_indices(0, 0, 0)
+# => "a1A"
 ```
 
-## Game-Specific Examples
+## Usage Examples
 
-### Chess
+### Chess Board (8x8)
 
 ```ruby
-# Standard chess coordinates
-locations = %w[a1 e4 h8].map { |coord| Sashite::Cell::Location.parse(coord) }
+# Standard chess notation mapping
+chess_squares = %w[a1 b1 c1 d1 e1 f1 g1 h1
+                   a2 b2 c2 d2 e2 f2 g2 h2
+                   a3 b3 c3 d3 e3 f3 g3 h3
+                   a4 b4 c4 d4 e4 f4 g4 h4
+                   a5 b5 c5 d5 e5 f5 g5 h5
+                   a6 b6 c6 d6 e6 f6 g6 h6
+                   a7 b7 c7 d7 e7 f7 g7 h7
+                   a8 b8 c8 d8 e8 f8 g8 h8]
+
+chess_squares.all? { |square| Sashite::Cell.valid?(square) }
+# => true
+```
 
-# Check if valid chess square
-def valid_chess_square?(location)
-  return false unless location.board?
+### Shōgi Board (9x9)
 
-  coord = location.to_s
-  coord.length == 2 &&
-    coord[0].between?("a", "h") &&
-    coord[1].between?("1", "8")
-end
+```ruby
+# CELL coordinates for shōgi positions
+shogi_positions = %w[a1 e5 i9] # Left corner, center, right corner
+shogi_positions.all? { |pos| Sashite::Cell.valid?(pos) }
+# => true
 
-valid_chess_square?(Sashite::Cell::Location.parse("e4"))  # => true
-valid_chess_square?(Sashite::Cell::Location.parse("z9"))  # => false
+# Convert to indices for board representation
+Sashite::Cell.to_indices("e5") # => [4, 4] (center of 9x9 board)
 ```
 
-### Shōgi
+### 3D Tic-Tac-Toe (3x3x3)
 
 ```ruby
-# Shōgi board coordinates and hand
-board_positions = %w[9a 5e 1i].map { |coord| Sashite::Cell::Location.parse(coord) }
-hand_position = Sashite::Cell::Location.parse("*")
-
-# Group by location type
-positions = board_positions + [hand_position]
-grouped = positions.group_by(&:hand?)
-# => {false => [board positions], true => [hand position]}
+# Three-dimensional game coordinates
+positions_3d = %w[a1A b2B c3C a2B b3C c1A]
+positions_3d.all? { |pos| Sashite::Cell.valid?(pos) && Sashite::Cell.dimensions(pos) == 3 }
+# => true
+
+# Winning diagonal across all three dimensions
+diagonal_win = %w[a1A b2B c3C]
+diagonal_win.map { |pos| Sashite::Cell.to_indices(pos) }
+# => [[0,0,0], [1,1,1], [2,2,2]]
 ```
 
-### Go
+### Multi-dimensional Coordinates
 
 ```ruby
-# Go coordinates (traditional notation)
-go_positions = %w[A1 T19 K10].map { |coord| Sashite::Cell::Location.parse(coord) }
+# Higher dimensional coordinates
+coord_4d = "a1Aa"
+coord_5d = "b2Bb2"
 
-# Custom validation for Go board
-def valid_go_position?(location, board_size = 19)
-  return false unless location.board?
+Sashite::Cell.dimensions(coord_4d) # => 4
+Sashite::Cell.dimensions(coord_5d) # => 5
 
-  coord = location.to_s
-  return false unless [2, 3].include?(coord.length)
+# Parse into components
+Sashite::Cell.parse(coord_4d) # => ["a", "1", "A", "a"]
+Sashite::Cell.parse(coord_5d) # => ["b", "2", "B", "b", "2"]
+```
 
-  letter = coord[0]
-  number = coord[1..].to_i
+## API Reference
 
-  letter.between?("A", ("A".ord + board_size - 1).chr) &&
-    number.between?(1, board_size)
-end
-```
+### Module Methods
 
-### Custom Coordinate Systems
+#### Validation
+- `Sashite::Cell.valid?(string)` - Check if string represents a valid CELL coordinate
 
-```ruby
-# 3D chess coordinates
-location_3d = Sashite::Cell::Location.parse("A3a")
+#### Analysis
+- `Sashite::Cell.dimensions(string)` - Get number of dimensions
+- `Sashite::Cell.parse(string)` - Parse coordinate into dimensional components array
 
-# Named locations
-center = Sashite::Cell::Location.parse("center")
-corner = Sashite::Cell::Location.parse("NE")
+#### Conversion
+- `Sashite::Cell.to_indices(string)` - Convert CELL coordinate to 0-indexed integer array
+- `Sashite::Cell.from_indices(*indices)` - Convert splat indices to CELL coordinate
 
-# Hexagonal coordinates
-hex_coord = Sashite::Cell::Location.parse("Q3R7")
-```
+#### Utilities
+- `Sashite::Cell.regex` - Get the validation regular expression
 
-## Advanced Usage
+### Constants
 
-### Working with Collections
+- `Sashite::Cell::REGEX` - Regular expression for CELL validation per specification v1.0.0
 
-```ruby
-# Mix of board and hand locations
-locations = [
-  Sashite::Cell::Location.parse("e4"),
-  Sashite::Cell::Location.parse("d5"),
-  Sashite::Cell::Location.parse("*"),
-  Sashite::Cell::Location.parse("a1")
-]
-
-# Separate board from hand locations
-board_locations = locations.select(&:board?)
-hand_locations = locations.select(&:hand?)
-
-# Convert collection to strings
-coordinates = locations.map(&:to_s)
-# => ["e4", "d5", "*", "a1"]
-```
+## Properties of CELL
 
-### Game State Representation
+* **Multi-dimensional**: Supports unlimited dimensional coordinate systems
+* **Cyclical**: Uses systematic three-character-set repetition
+* **ASCII-based**: Pure ASCII characters for universal compatibility
+* **Unambiguous**: Each coordinate maps to exactly one location
+* **Scalable**: Extends naturally from 1D to unlimited dimensions
+* **Rule-agnostic**: Independent of specific game mechanics
 
-```ruby
-# Represent piece positions
-piece_locations = {
-  "white_king"      => Sashite::Cell::Location.parse("e1"),
-  "black_king"      => Sashite::Cell::Location.parse("e8"),
-  "white_rook"      => Sashite::Cell::Location.parse("a1"),
-  "captured_pieces" => Sashite::Cell::Location.parse("*")
-}
-
-# Find pieces on specific ranks/files
-def pieces_on_file(locations, file)
-  locations.select do |piece, location|
-    location.board? && location.to_s.start_with?(file)
-  end
-end
+## Character Set Details
 
-e_file_pieces = pieces_on_file(piece_locations, "e")
-```
+### Latin Lowercase (Dimensions 1, 4, 7, ...)
+Single letters: `a` through `z` (positions 0-25)
+Double letters: `aa` through `zz` (positions 26-701)
+Triple letters: `aaa` through `zzz` (positions 702-18277)
+And so on...
+
+### Arabic Numerals (Dimensions 2, 5, 8, ...)
+Standard decimal notation: `1`, `2`, `3`, ... (1-indexed)
+No leading zeros, unlimited range
 
-### Validation and Error Handling
+### Latin Uppercase (Dimensions 3, 6, 9, ...)
+Single letters: `A` through `Z` (positions 0-25)
+Double letters: `AA` through `ZZ` (positions 26-701)
+Triple letters: `AAA` through `ZZZ` (positions 702-18277)
+And so on...
+
+## Integration with DROP
+
+CELL complements the DROP specification for complete location coverage:
 
 ```ruby
-# Check validity before parsing
-Sashite::Cell.valid?("e4")      # => true
-Sashite::Cell.valid?("*")       # => true
-Sashite::Cell.valid?("")        # => false
-Sashite::Cell.valid?("e-4")     # => false
-Sashite::Cell.valid?("@")       # => false
-
-# Safe parsing
-def safe_parse(coord_string)
-  return nil unless Sashite::Cell.valid?(coord_string)
-
-  Sashite::Cell::Location.parse(coord_string)
-rescue ArgumentError
-  nil
+# Combined location validation
+def valid_game_location?(location)
+  Sashite::Cell.valid?(location) || Sashite::Drop.reserve?(location)
 end
 
-# Invalid coordinates raise ArgumentError
-begin
-  Sashite::Cell::Location.parse("")
-rescue ArgumentError => e
-  puts "Invalid coordinate: #{e.message}"
-end
+valid_game_location?("a1")  # => true (board position)
+valid_game_location?("*")   # => true (reserve position)
+valid_game_location?("$")   # => false (invalid)
 ```
 
-### Integration with Other Notations
+## Examples in Different Games
+
+### Chess
 
 ```ruby
-# CELL serves as foundation for move notation
-class SimpleMove
-  def initialize(from, to)
-    @from = Sashite::Cell::Location.parse(from)
-    @to = Sashite::Cell::Location.parse(to)
-  end
-
-  def from_board?
-    @from.board?
-  end
-
-  def to_board?
-    @to.board?
-  end
-
-  def drop_move?
-    @from.hand? && @to.board?
-  end
-
-  def capture_move?
-    @from.board? && @to.board?
-  end
-
-  def to_s
-    "#{@from}→#{@to}"
-  end
-end
+# Standard algebraic notation positions
+start_position = "e2"
+end_position = "e4"
+
+Sashite::Cell.valid?(start_position) # => true
+Sashite::Cell.valid?(end_position)   # => true
 
-# Usage
-move = SimpleMove.new("e4", "e5")    # Normal move
-drop = SimpleMove.new("*", "e4")     # Drop from hand
+# Convert to array indices for board representation
+Sashite::Cell.to_indices("e4") # => [4, 3]
 ```
 
-## API Reference
+### Go (19x19)
 
-### Module Methods
+```ruby
+# Go board positions
+corner = "a1"       # Corner position
+edge = "j1"         # Edge position
+tengen = "j10"      # Center point (tengen) on 19x19 board
 
-- `Sashite::Cell.valid?(cell_string)` - Check if a string is valid CELL notation
-- `Sashite::Cell.location(coordinate)` - Convenience method to create locations
+[corner, edge, tengen].all? { |pos| Sashite::Cell.valid?(pos) }
+# => true
+```
 
-### Sashite::Cell::Location Class Methods
+### Abstract Strategy Games
 
-- `Sashite::Cell::Location.parse(cell_string)` - Parse a CELL string into a location object
-- `Sashite::Cell::Location.new(coordinate)` - Create a new location instance
+```ruby
+# Multi-dimensional abstract games
+hypercube_4d = "a1Aa"
+tesseract_pos = "h8Hh8"
 
-### Instance Methods
+# Validate high-dimensional coordinates
+Sashite::Cell.valid?(hypercube_4d) # => true
+Sashite::Cell.dimensions(tesseract_pos) # => 5
 
-#### Type Checking
-- `#board?` - Check if location represents a board coordinate
-- `#hand?` - Check if location represents hand/reserve
+# Convert for mathematical operations
+Sashite::Cell.to_indices(hypercube_4d) # => [0, 0, 0, 0]
+```
 
-#### Conversion
-- `#to_s` - Convert to CELL string representation
-- `#inspect` - Detailed string representation for debugging
+## Specification Compliance
 
-#### Comparison
-- `#==` - Compare locations for equality
-- `#eql?` - Strict equality comparison
-- `#hash` - Hash value for use in collections
+This implementation strictly follows the [CELL Specification v1.0.0](https://sashite.dev/specs/cell/1.0.0/) and includes:
 
-## Properties of CELL
+- **Exact regex**: Uses the official validation pattern from the specification
+- **Complete API**: All methods and behaviors defined in the specification
+- **Full test coverage**: Validates against all specification examples
+- **Round-trip safety**: Guaranteed coordinate ↔ indices conversion integrity
 
-* **Rule-agnostic**: CELL does not encode game states, movement rules, or game-specific conditions
-* **Universal location identification**: Supports both board positions and hand/reserve areas
-* **Canonical representation**: Equivalent locations yield identical strings
-* **Arbitrary coordinate systems**: Flexible format supports any alphanumeric coordinate system
-* **Foundational specification**: Serves as building block for other Sashité notations
+### Specification Examples
 
-## Constraints
+All examples from the CELL specification work correctly:
 
-* Board coordinates must contain only alphanumeric characters (`a-z`, `A-Z`, `0-9`)
-* Board coordinates must be non-empty strings
-* Hand/reserve locations must be exactly the character `*`
-* No other characters or formats are permitted
+```ruby
+# Basic Examples from spec
+Sashite::Cell.valid?("a")        # => true (1D)
+Sashite::Cell.valid?("a1")       # => true (2D)
+Sashite::Cell.valid?("a1A")      # => true (3D)
+Sashite::Cell.valid?("a1Aa1A")   # => true (6D)
+
+# Extended Alphabet Examples from spec
+Sashite::Cell.valid?("aa1AA")    # => true
+Sashite::Cell.valid?("z26Z")     # => true
+Sashite::Cell.valid?("abc123XYZ") # => true
+
+# Invalid Examples from spec
+Sashite::Cell.valid?("")         # => false
+Sashite::Cell.valid?("a0")       # => false
+Sashite::Cell.valid?("1a")       # => false
+Sashite::Cell.valid?("a1a")      # => false
+```
 
-## Use Cases
+## Documentation
 
-CELL is particularly useful in the following scenarios:
+- [Official CELL Specification v1.0.0](https://sashite.dev/specs/cell/1.0.0/)
+- [API Documentation](https://rubydoc.info/github/sashite/cell.rb/main)
+- [CELL Examples](https://sashite.dev/specs/cell/1.0.0/examples/)
 
-1. **Move notation systems**: As coordinate foundation for MIN, PMN, and GGN specifications
-2. **Game engine development**: When implementing position tracking across different board layouts
-3. **Board representation**: When storing piece positions in databases or memory structures
-4. **Cross-game compatibility**: When building systems that work with multiple game types
-5. **Position analysis**: When comparing locations across different coordinate systems
-6. **User interface development**: When translating between display coordinates and logical positions
+## Development
 
-## Dependencies
+```sh
+# Clone the repository
+git clone https://github.com/sashite/cell.rb.git
+cd cell.rb
 
-This gem has no external dependencies beyond Ruby standard library.
+# Install dependencies
+bundle install
 
-## Specification
+# Run tests
+ruby test.rb
 
-- [CELL Specification](https://sashite.dev/documents/cell/1.0.0/)
+# Generate documentation
+yard doc
+```
 
-## Documentation
+## Contributing
 
-- [CELL Documentation](https://rubydoc.info/github/sashite/cell.rb/main)
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/new-feature`)
+3. Add tests for your changes
+4. Ensure all tests pass (`ruby test.rb`)
+5. Commit your changes (`git commit -am 'Add new feature'`)
+6. Push to the branch (`git push origin feature/new-feature`)
+7. Create a Pull Request
 
 ## License
 
-The [gem](https://rubygems.org/gems/sashite-cell) is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+Available as open source under the [MIT License](https://opensource.org/licenses/MIT).
 
-## About Sashité
+## About
 
-This project is maintained by [Sashité](https://sashite.com/) — promoting chess variants and sharing the beauty of Chinese, Japanese, and Western chess cultures.
+Maintained by [Sashité](https://sashite.com/) — promoting chess variants and sharing the beauty of board game cultures.

data/lib/sashite/cell.rb

@@ -1,61 +1,252 @@
 # frozen_string_literal: true
 
-require_relative "cell/location"
-
-# Sashité module providing implementations of various game notation specifications
-#
-# @see https://sashite.com/ Sashité
 module Sashite
-  # CELL (Coordinate Expression Location Label) implementation
+  # CELL (Coordinate Encoding for Layered Locations) implementation for Ruby
   #
-  # CELL defines a consistent and rule-agnostic format for representing locations
-  # in abstract strategy board games. CELL provides a standardized way to identify
-  # positions on game boards and pieces held in hand/reserve.
+  # Provides functionality for working with multi-dimensional game board coordinates
+  # using a cyclical ASCII character system.
   #
-  # @see https://sashite.dev/documents/cell/1.0.0/ CELL Specification v1.0.0
+  # 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
   module Cell
-    # Regular expression for validating CELL notation
+    # Regular expression for validating CELL coordinates according to specification v1.0.0
+    # Optimized version with redundant nested repeat operator removed for clean Ruby execution
+    REGEX = /\A[a-z]+(?:[1-9]\d*[A-Z]+[a-z]+)*(?:[1-9]\d*[A-Z]*)?\z/
+
+    # Check if a string represents a valid CELL coordinate
     #
-    # Matches either:
-    # - Hand/reserve location: exactly "*"
-    # - Board coordinate: one or more alphanumeric characters [a-zA-Z0-9]
+    # @param string [String] the string to validate
+    # @return [Boolean] true if the string is a valid CELL coordinate
     #
-    # @return [Regexp] the validation pattern
-    CELL_PATTERN = /\A(#{::Regexp.escape(Location::HAND_CHAR)}|[a-zA-Z0-9]+)\z/
+    # @example
+    #   Sashite::Cell.valid?("a1")     # => true
+    #   Sashite::Cell.valid?("a1A")    # => true
+    #   Sashite::Cell.valid?("*")      # => false
+    #   Sashite::Cell.valid?("a0")     # => false
+    def self.valid?(string)
+      return false unless string.is_a?(String)
+      return false if string.empty?
 
-    # Check if a string is valid CELL notation
+      # Use the optimized CELL v1.0.0 regex for validation
+      string.match?(REGEX)
+    end
+
+    # Get the number of dimensions in a coordinate
+    #
+    # @param string [String] the coordinate string
+    # @return [Integer] the number of dimensions
     #
-    # @param cell_string [String] the string to validate
-    # @return [Boolean] true if valid CELL notation, false otherwise
+    # @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
     #
-    # @example Valid CELL strings
-    #   Sashite::Cell.valid?("e4")      # => true
-    #   Sashite::Cell.valid?("*")       # => true
-    #   Sashite::Cell.valid?("A3a")     # => true
-    #   Sashite::Cell.valid?("center")  # => true
+    # @param string [String] the coordinate string to parse
+    # @return [Array<String>] array of dimensional components
     #
-    # @example Invalid CELL strings
-    #   Sashite::Cell.valid?("")        # => false
-    #   Sashite::Cell.valid?("e-4")     # => false
-    #   Sashite::Cell.valid?("@")       # => false
-    #   Sashite::Cell.valid?("e4!")     # => false
-    def self.valid?(cell_string)
-      return false unless cell_string.is_a?(::String)
+    # @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)
+    def self.parse(string)
+      return [] unless string.is_a?(::String)
+      return [] if string.empty?
+      return [] unless valid?(string)
 
-      CELL_PATTERN.match?(cell_string)
+      parse_recursive(string, 1)
     end
 
-    # Convenience method to create a Location object
+    # Convert a CELL coordinate to an array of 0-indexed integers
     #
-    # @param coordinate [String] the coordinate string in CELL format
-    # @return [Location] a new Location object
-    # @raise [ArgumentError] if the coordinate is invalid
+    # @param string [String] the CELL coordinate
+    # @return [Array<Integer>] array of 0-indexed positions
     #
     # @example
-    #   location = Sashite::Cell.location("e4")
-    #   hand = Sashite::Cell.location("*")
-    def self.location(coordinate)
-      Location.new(coordinate)
+    #   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
+    end
+
+    # Convert an array of 0-indexed integers to a CELL coordinate
+    #
+    # @param indices [Array<Integer>] splat arguments of 0-indexed positions
+    # @return [String] the 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
+    #
+    # @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)
+    end
+
+    # Determine the character set type for a given dimension
+    # Following CELL specification cyclical system: dimension n % 3 determines character set
+    #
+    # @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([a-z]+)/)
+        match ? match[1] : nil
+      when :numeric
+        # Arabic numerals: [1-9]\d* (CELL specification requires positive integers only)
+        match = string.match(/\A([1-9]\d*)/)
+        match ? match[1] : nil
+      when :uppercase
+        # Latin uppercase letters: [A-Z]+
+        match = string.match(/\A([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 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
     end
   end
 end

data/lib/sashite-cell.rb

@@ -1,15 +1,14 @@
 # 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
-  # Coordinate Expression Location Label (CELL) implementation for Ruby
-  #
-  # CELL defines a consistent and rule-agnostic format for representing locations
-  # in abstract strategy board games. CELL provides a standardized way to identify
-  # positions on game boards and pieces held in hand/reserve, establishing a
-  # common foundation for location reference across the Sashité notation ecosystem.
-  #
-  # @see https://sashite.dev/documents/cell/1.0.0/ CELL Specification v1.0.0
 end
-
-require_relative "sashite/cell"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: sashite-cell
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 2.0.1
 platform: ruby
 authors:
 - Cyril Kato
@@ -9,10 +9,10 @@ bindir: bin
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies: []
-description: CELL defines a consistent and rule-agnostic format for representing locations
-  in abstract strategy board games. This gem provides a Ruby interface for working
-  with game locations, serving as a foundational building block for the Sashité notation
-  ecosystem.
+description: CELL defines a standardized format for representing coordinates on multi-dimensional
+  game boards using a cyclical ASCII character system. This gem provides a Ruby interface
+  for working with unlimited dimensional game coordinates through a clean, functional
+  API that strictly follows the CELL Specification v1.0.0.
 email: contact@cyril.email
 executables: []
 extensions: []
@@ -22,8 +22,6 @@ files:
 - README.md
 - lib/sashite-cell.rb
 - lib/sashite/cell.rb
-- lib/sashite/cell/location.rb
-- lib/sashite/cell/location/hand_char.rb
 homepage: https://github.com/sashite/cell.rb
 licenses:
 - MIT
@@ -32,7 +30,9 @@ metadata:
   documentation_uri: https://rubydoc.info/github/sashite/cell.rb/main
   homepage_uri: https://github.com/sashite/cell.rb
   source_code_uri: https://github.com/sashite/cell.rb
-  specification_uri: https://sashite.dev/documents/cell/1.0.0/
+  specification_uri: https://sashite.dev/specs/cell/1.0.0/
+  wiki_uri: https://sashite.dev/specs/cell/1.0.0/examples/
+  funding_uri: https://github.com/sponsors/sashite
   rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths:
@@ -48,7 +48,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.7
+rubygems_version: 3.6.9
 specification_version: 4
-summary: CELL (Coordinate Expression Location Label) implementation for Ruby
+summary: CELL (Coordinate Encoding for Layered Locations) implementation for Ruby
 test_files: []

data/lib/sashite/cell/location/hand_char.rb

@@ -1,16 +0,0 @@
-# frozen_string_literal: true
-
-module Sashite
-  module Cell
-    class Location
-      # Character representing hand/reserve location in CELL notation
-      #
-      # This character is used to identify pieces held off-board in a player's
-      # hand or reserve, as opposed to pieces positioned on the game board.
-      #
-      # @return [String] the hand/reserve character
-      # @see https://sashite.dev/documents/cell/1.0.0/ CELL Specification v1.0.0
-      HAND_CHAR = "*"
-    end
-  end
-end

data/lib/sashite/cell/location.rb

@@ -1,136 +0,0 @@
-# frozen_string_literal: true
-
-require_relative "location/hand_char"
-
-module Sashite
-  module Cell
-    # Represents a game location in CELL format
-    #
-    # A Location object encapsulates either a board coordinate (alphanumeric string)
-    # or a hand/reserve location (the "*" character). This class provides methods
-    # to distinguish between location types and convert to string representation.
-    #
-    # @see https://sashite.dev/documents/cell/1.0.0/ CELL Specification v1.0.0
-    class Location
-      # The coordinate string for this location
-      # @return [String] the coordinate in CELL format
-      attr_reader :coordinate
-
-      # Create a new Location object
-      #
-      # @param coordinate [String] the coordinate string in CELL format
-      # @raise [ArgumentError] if the coordinate is not valid CELL notation
-      #
-      # @example Create board locations
-      #   Location.new("e4")      # Chess square
-      #   Location.new("5c")      # Shōgi square
-      #   Location.new("A3a")     # 3D coordinate
-      #   Location.new("center")  # Custom coordinate
-      #
-      # @example Create hand/reserve location
-      #   Location.new("*")       # Hand/reserve
-      def initialize(coordinate)
-        raise ::ArgumentError, "Invalid CELL coordinate: #{coordinate.inspect}" unless Sashite::Cell.valid?(coordinate)
-
-        @coordinate = coordinate.freeze
-
-        freeze
-      end
-
-      # Parse a CELL string into a Location object
-      #
-      # @param cell_string [String] the CELL string to parse
-      # @return [Location] a new Location object
-      # @raise [ArgumentError] if the string is not valid CELL notation
-      #
-      # @example
-      #   location = Location.parse("e4")
-      #   hand = Location.parse("*")
-      def self.parse(cell_string)
-        new(cell_string)
-      end
-
-      # Check if this location represents a board coordinate
-      #
-      # @return [Boolean] true if this is a board coordinate, false if hand/reserve
-      #
-      # @example
-      #   Location.new("e4").board?  # => true
-      #   Location.new("*").board?   # => false
-      def board?
-        @coordinate != HAND_CHAR
-      end
-
-      # Check if this location represents a hand/reserve location
-      #
-      # @return [Boolean] true if this is hand/reserve, false if board coordinate
-      #
-      # @example
-      #   Location.new("e4").hand?  # => false
-      #   Location.new("*").hand?   # => true
-      def hand?
-        @coordinate == HAND_CHAR
-      end
-
-      # Convert to CELL string representation
-      #
-      # @return [String] the coordinate in CELL format
-      #
-      # @example
-      #   Location.new("e4").to_s  # => "e4"
-      #   Location.new("*").to_s   # => "*"
-      def to_s
-        @coordinate
-      end
-
-      # Detailed string representation for debugging
-      #
-      # @return [String] detailed representation showing class and coordinate
-      #
-      # @example
-      #   Location.new("e4").inspect
-      #   # => "#<Sashite::Cell::Location:0x... @coordinate=\"e4\">"
-      def inspect
-        "#<#{self.class}:0x#{object_id.to_s(16)} @coordinate=#{@coordinate.inspect}>"
-      end
-
-      # Compare locations for equality
-      #
-      # Two locations are equal if they have the same coordinate string.
-      #
-      # @param other [Object] the object to compare with
-      # @return [Boolean] true if locations are equal
-      #
-      # @example
-      #   loc1 = Location.new("e4")
-      #   loc2 = Location.new("e4")
-      #   loc1 == loc2  # => true
-      def ==(other)
-        other.is_a?(Location) && @coordinate == other.coordinate
-      end
-
-      # Strict equality comparison
-      #
-      # @param other [Object] the object to compare with
-      # @return [Boolean] true if objects are equal
-      def eql?(other)
-        self == other
-      end
-
-      # Hash value for use in collections
-      #
-      # Ensures that equal locations have the same hash value.
-      #
-      # @return [Integer] hash value based on coordinate
-      #
-      # @example
-      #   locations = Set.new
-      #   locations << Location.new("e4")
-      #   locations << Location.new("e4")  # Won't be added (same hash)
-      #   locations.size  # => 1
-      def hash
-        [self.class, @coordinate].hash
-      end
-    end
-  end
-end