sashite-cell 2.0.0 → 2.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c4fefcdbade2adc694035b6fbff032fb8e03466e35406a67f2a9d1c61b9fd600
-  data.tar.gz: 42c3150a201310805948eaa2e9e6bf05fc9c198925024d7a203f0093d6ee969a
+  metadata.gz: 84228cab7c7155caaec3a2adad475150eb8b272c5c8e67d2dfb1e626b6120e7e
+  data.tar.gz: 318c49ae54afbfec1edaeca7a03c23c7cc5a65cec0658d14973f54a203c15914
 SHA512:
-  metadata.gz: 185910faaa10494b20d39b58ac3f25007d432d63d230de76cf666762a215ab8177283c0fe167efc28fdc24b4abcc55bdb25211fc9d216856b62d889005e57c8c
-  data.tar.gz: 43fe0766f8fe932e2a57dec85c89a07db4f30a543319f035b7e893a8122cfaf30ed90a635515bb9867a1509dc9e374ecf3c0b16c6efb39b419413a4811aebfe2
+  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** (Cell Encoding Location Label) support for the Ruby language.
+> **CELL** (Coordinate Encoding for Layered Locations) support for the Ruby language.
 
 ## What is CELL?
 
-CELL (Cell Encoding Location Label) 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.
+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 multi-dimensional game coordinates through a clean, functional API.
+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
 
@@ -125,14 +125,16 @@ chess_squares.all? { |square| Sashite::Cell.valid?(square) }
 # => true
 ```
 
-### Shogi Board (9x9)
+### Shōgi Board (9x9)
 
 ```ruby
-# Japanese shogi uses 9x9 board
-shogi_position = "5e" # 5th file, e rank
-Sashite::Cell.valid?(shogi_position) # => true
-Sashite::Cell.dimensions(shogi_position) # => 2
-Sashite::Cell.to_indices(shogi_position) # => [4, 4]
+# 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
+
+# Convert to indices for board representation
+Sashite::Cell.to_indices("e5") # => [4, 4] (center of 9x9 board)
 ```
 
 ### 3D Tic-Tac-Toe (3x3x3)
@@ -142,6 +144,11 @@ Sashite::Cell.to_indices(shogi_position) # => [4, 4]
 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]]
 ```
 
 ### Multi-dimensional Coordinates
@@ -179,7 +186,7 @@ Sashite::Cell.parse(coord_5d) # => ["b", "2", "B", "b", "2"]
 
 ### Constants
 
-- `Sashite::Cell::REGEX` - Regular expression for CELL validation: `/\A(?:[a-z]+|[1-9]\d*|[A-Z]+)+\z/`
+- `Sashite::Cell::REGEX` - Regular expression for CELL validation per specification v1.0.0
 
 ## Properties of CELL
 
@@ -188,7 +195,7 @@ Sashite::Cell.parse(coord_5d) # => ["b", "2", "B", "b", "2"]
 * **ASCII-based**: Pure ASCII characters for universal compatibility
 * **Unambiguous**: Each coordinate maps to exactly one location
 * **Scalable**: Extends naturally from 1D to unlimited dimensions
-* **Functional**: Provides a clean, stateless API for coordinate operations
+* **Rule-agnostic**: Independent of specific game mechanics
 
 ## Character Set Details
 
@@ -234,6 +241,9 @@ end_position = "e4"
 
 Sashite::Cell.valid?(start_position) # => true
 Sashite::Cell.valid?(end_position)   # => true
+
+# Convert to array indices for board representation
+Sashite::Cell.to_indices("e4") # => [4, 3]
 ```
 
 ### Go (19x19)
@@ -258,17 +268,80 @@ tesseract_pos = "h8Hh8"
 # Validate high-dimensional coordinates
 Sashite::Cell.valid?(hypercube_4d) # => true
 Sashite::Cell.dimensions(tesseract_pos) # => 5
+
+# Convert for mathematical operations
+Sashite::Cell.to_indices(hypercube_4d) # => [0, 0, 0, 0]
+```
+
+## Specification Compliance
+
+This implementation strictly follows the [CELL Specification v1.0.0](https://sashite.dev/specs/cell/1.0.0/) and includes:
+
+- **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
+
+### Specification Examples
+
+All examples from the CELL specification work correctly:
+
+```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
 ```
 
 ## Documentation
 
-- [Official CELL Specification](https://sashite.dev/documents/cell/1.0.0/)
+- [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/)
+
+## Development
+
+```sh
+# Clone the repository
+git clone https://github.com/sashite/cell.rb.git
+cd cell.rb
+
+# Install dependencies
+bundle install
+
+# Run tests
+ruby test.rb
+
+# Generate documentation
+yard doc
+```
+
+## Contributing
+
+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,17 +1,17 @@
 # frozen_string_literal: true
 
 module Sashite
-  # CELL (Cell Encoding Location Label) implementation for Ruby
+  # CELL (Coordinate Encoding for Layered Locations) implementation for Ruby
   #
   # 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 coordinates according to specification
-    # This is the exact regex from the CELL specification v1.0.0
-    # Using non-capturing groups to avoid Ruby's nested quantifier warning
-    REGEX = /\A[a-z]+(?:[1-9]\d*[A-Z]+[a-z]+)*(?:[1-9]\d*(?:[A-Z]*))?\z/
+    # 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
     #
@@ -27,7 +27,7 @@ module Sashite
       return false unless string.is_a?(String)
       return false if string.empty?
 
-      # Use the formal regex for validation
+      # Use the optimized CELL v1.0.0 regex for validation
       string.match?(REGEX)
     end
 
@@ -104,13 +104,13 @@ module Sashite
 
     # Get the validation regular expression
     #
-    # @return [Regexp] the CELL validation regex
+    # @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 pattern
+    # following the strict CELL specification cyclical pattern
     #
     # @param string [String] the remaining string to parse
     # @param dimension [Integer] the current dimension (1-indexed)
@@ -123,23 +123,21 @@ module Sashite
 
       return [] if component.nil?
 
-      # Invalid format according to CELL specification
-
       # 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: dimension n % 3 determines character set
+    # 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
-      when 2 then :numeric
-      when 0 then :uppercase
+      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
 
@@ -152,13 +150,15 @@ module Sashite
     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
-        # CELL specification requires positive integers only (no zero)
+        # 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
@@ -197,7 +197,7 @@ module Sashite
     end
 
     # Convert letter sequence to 0-indexed position
-    # Extended alphabet: a=0, b=1, ..., z=25, aa=26, ab=27, ..., zz=701, aaa=702, etc.
+    # 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
@@ -219,7 +219,7 @@ module Sashite
     end
 
     # Convert 0-indexed position to letter sequence
-    # Extended alphabet: 0=a, 1=b, ..., 25=z, 26=aa, 27=ab, ..., 701=zz, 702=aaa, etc.
+    # 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

data/lib/sashite-cell.rb

@@ -1,8 +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
-  # @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: 2.0.0
+  version: 2.0.1
 platform: ruby
 authors:
 - Cyril Kato
@@ -10,9 +10,9 @@ cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies: []
 description: CELL defines a standardized format for representing coordinates on multi-dimensional
-  game boards using diverse writing systems from around the world. This gem provides
-  a Ruby interface for working with multi-dimensional game coordinates through a clean,
-  functional API.
+  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: []
@@ -30,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,5 +50,5 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 3.6.9
 specification_version: 4
-summary: CELL (Cell Encoding Location Label) implementation for Ruby
+summary: CELL (Coordinate Encoding for Layered Locations) implementation for Ruby
 test_files: []