sashite-cell 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 1071f1a4bf4e1d9f6893185fe61fc25a361ca97ba8e9d74e3e72f2fba1300362
+  data.tar.gz: 2b723da1c614caed08b87bbb8eb382d484a5cc0e915ab6ed7c87949196322ded
+SHA512:
+  metadata.gz: 86c6f48a5c77440ddfe886b6c7da0e8871149af862164b7fc060dd07002afa18e69bffc0f897f1de392ecbf7bcc2507786903b326513b6241251f3be20638c81
+  data.tar.gz: 37dd7540c541a6aaee7d8a29ff8e6eb03119dabdc6c0c0f21cd63fdcb8ed59ff2d80d74b479a9b9a8e6cbb84cb8dbd981ed2492cd48c2c07e3fe383a917a5a8f

data/LICENSE.md

@@ -0,0 +1,22 @@
+Copyright (c) 2025 Sashite
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,351 @@
+# Cell.rb
+
+[![Version](https://img.shields.io/github/v/tag/sashite/cell.rb?label=Version&logo=github)](https://github.com/sashite/cell.rb/tags)
+[![Yard documentation](https://img.shields.io/badge/Yard-documentation-blue.svg?logo=github)](https://rubydoc.info/github/sashite/cell.rb/main)
+![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.
+
+## 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.
+
+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.
+
+## Installation
+
+```ruby
+# In your Gemfile
+gem "sashite-cell"
+```
+
+Or install manually:
+
+```sh
+gem install sashite-cell
+```
+
+## CELL Format
+
+A CELL location is represented by a single string following one of two patterns:
+
+### Board Coordinates
+
+Any non-empty string containing only alphanumeric characters (`a-z`, `A-Z`, `0-9`):
+
+```
+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
+```
+
+## Basic Usage
+
+### Creating Location Objects
+
+The primary interface is the `Sashite::Cell::Location` class, which represents a game location in CELL format:
+
+```ruby
+require "sashite/cell"
+
+# Parse CELL strings into location objects
+board_pos = Sashite::Cell::Location.parse("e4")
+# => #<Sashite::Cell::Location:0x... @coordinate="e4">
+
+hand_pos = Sashite::Cell::Location.parse("*")
+# => #<Sashite::Cell::Location:0x... @coordinate="*">
+
+# Create directly with constructor
+location = Sashite::Cell::Location.new("e4")
+hand = Sashite::Cell::Location.new("*")
+
+# Convenience method
+location = Sashite::Cell.location("e4")
+```
+
+### Converting to CELL String
+
+Convert a location object back to its CELL string representation:
+
+```ruby
+location = Sashite::Cell::Location.parse("e4")
+location.to_s
+# => "e4"
+
+hand = Sashite::Cell::Location.parse("*")
+hand.to_s
+# => "*"
+```
+
+### Checking Location Types
+
+Distinguish between board coordinates and hand/reserve locations:
+
+```ruby
+board_loc = Sashite::Cell::Location.parse("e4")
+hand_loc = Sashite::Cell::Location.parse("*")
+
+board_loc.board?     # => true
+board_loc.hand?      # => false
+
+hand_loc.board?      # => false
+hand_loc.hand?       # => true
+```
+
+## Game-Specific Examples
+
+### Chess
+
+```ruby
+# Standard chess coordinates
+locations = %w[a1 e4 h8].map { |coord| Sashite::Cell::Location.parse(coord) }
+
+# Check if valid chess square
+def valid_chess_square?(location)
+  return false unless location.board?
+
+  coord = location.to_s
+  coord.length == 2 &&
+    coord[0].between?("a", "h") &&
+    coord[1].between?("1", "8")
+end
+
+valid_chess_square?(Sashite::Cell::Location.parse("e4"))  # => true
+valid_chess_square?(Sashite::Cell::Location.parse("z9"))  # => false
+```
+
+### Shōgi
+
+```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]}
+```
+
+### Go
+
+```ruby
+# Go coordinates (traditional notation)
+go_positions = %w[A1 T19 K10].map { |coord| Sashite::Cell::Location.parse(coord) }
+
+# Custom validation for Go board
+def valid_go_position?(location, board_size = 19)
+  return false unless location.board?
+
+  coord = location.to_s
+  return false unless [2, 3].include?(coord.length)
+
+  letter = coord[0]
+  number = coord[1..].to_i
+
+  letter.between?("A", ("A".ord + board_size - 1).chr) &&
+    number.between?(1, board_size)
+end
+```
+
+### Custom Coordinate Systems
+
+```ruby
+# 3D chess coordinates
+location_3d = Sashite::Cell::Location.parse("A3a")
+
+# Named locations
+center = Sashite::Cell::Location.parse("center")
+corner = Sashite::Cell::Location.parse("NE")
+
+# Hexagonal coordinates
+hex_coord = Sashite::Cell::Location.parse("Q3R7")
+```
+
+## Advanced Usage
+
+### Working with Collections
+
+```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"]
+```
+
+### Game State Representation
+
+```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
+
+e_file_pieces = pieces_on_file(piece_locations, "e")
+```
+
+### Validation and Error Handling
+
+```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
+end
+
+# Invalid coordinates raise ArgumentError
+begin
+  Sashite::Cell::Location.parse("")
+rescue ArgumentError => e
+  puts "Invalid coordinate: #{e.message}"
+end
+```
+
+### Integration with Other Notations
+
+```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
+
+# Usage
+move = SimpleMove.new("e4", "e5")    # Normal move
+drop = SimpleMove.new("*", "e4")     # Drop from hand
+```
+
+## API Reference
+
+### Module Methods
+
+- `Sashite::Cell.valid?(cell_string)` - Check if a string is valid CELL notation
+- `Sashite::Cell.location(coordinate)` - Convenience method to create locations
+
+### Sashite::Cell::Location Class Methods
+
+- `Sashite::Cell::Location.parse(cell_string)` - Parse a CELL string into a location object
+- `Sashite::Cell::Location.new(coordinate)` - Create a new location instance
+
+### Instance Methods
+
+#### Type Checking
+- `#board?` - Check if location represents a board coordinate
+- `#hand?` - Check if location represents hand/reserve
+
+#### Conversion
+- `#to_s` - Convert to CELL string representation
+- `#inspect` - Detailed string representation for debugging
+
+#### Comparison
+- `#==` - Compare locations for equality
+- `#eql?` - Strict equality comparison
+- `#hash` - Hash value for use in collections
+
+## Properties of CELL
+
+* **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
+
+## Constraints
+
+* 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
+
+## Use Cases
+
+CELL is particularly useful in the following scenarios:
+
+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
+
+## Dependencies
+
+This gem has no external dependencies beyond Ruby standard library.
+
+## Specification
+
+- [CELL Specification](https://sashite.dev/documents/cell/1.0.0/)
+
+## Documentation
+
+- [CELL Documentation](https://rubydoc.info/github/sashite/cell.rb/main)
+
+## 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).
+
+## About Sashité
+
+This project is maintained by [Sashité](https://sashite.com/) — promoting chess variants and sharing the beauty of Chinese, Japanese, and Western chess cultures.

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

@@ -0,0 +1,16 @@
+# 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

@@ -0,0 +1,136 @@
+# 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

data/lib/sashite/cell.rb

@@ -0,0 +1,61 @@
+# 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 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.
+  #
+  # @see https://sashite.dev/documents/cell/1.0.0/ CELL Specification v1.0.0
+  module Cell
+    # Regular expression for validating CELL notation
+    #
+    # Matches either:
+    # - Hand/reserve location: exactly "*"
+    # - Board coordinate: one or more alphanumeric characters [a-zA-Z0-9]
+    #
+    # @return [Regexp] the validation pattern
+    CELL_PATTERN = /\A(#{::Regexp.escape(Location::HAND_CHAR)}|[a-zA-Z0-9]+)\z/
+
+    # Check if a string is valid CELL notation
+    #
+    # @param cell_string [String] the string to validate
+    # @return [Boolean] true if valid CELL notation, false otherwise
+    #
+    # @example Valid CELL strings
+    #   Sashite::Cell.valid?("e4")      # => true
+    #   Sashite::Cell.valid?("*")       # => true
+    #   Sashite::Cell.valid?("A3a")     # => true
+    #   Sashite::Cell.valid?("center")  # => true
+    #
+    # @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)
+
+      CELL_PATTERN.match?(cell_string)
+    end
+
+    # Convenience method to create a Location object
+    #
+    # @param coordinate [String] the coordinate string in CELL format
+    # @return [Location] a new Location object
+    # @raise [ArgumentError] if the coordinate is invalid
+    #
+    # @example
+    #   location = Sashite::Cell.location("e4")
+    #   hand = Sashite::Cell.location("*")
+    def self.location(coordinate)
+      Location.new(coordinate)
+    end
+  end
+end

data/lib/sashite-cell.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+# Sashité namespace for board game notation libraries
+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

@@ -0,0 +1,54 @@
+--- !ruby/object:Gem::Specification
+name: sashite-cell
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Cyril Kato
+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.
+email: contact@cyril.email
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.md
+- 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
+metadata:
+  bug_tracker_uri: https://github.com/sashite/cell.rb/issues
+  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/
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.7
+specification_version: 4
+summary: CELL (Coordinate Expression Location Label) implementation for Ruby
+test_files: []