cell.rb

CELL (Coordinate Encoding for Layered Locations) implementation for Ruby.

Overview

This library implements the CELL Specification v1.0.0.

Implementation Constraints

Constraint	Value	Rationale
Max dimensions	3	Sufficient for 1D, 2D, 3D boards
Max index value	255	Fits in 8-bit integer, covers 256×256×256 boards
Max string length	7	"iv256IV" (max for all dimensions at 255)

These constraints enable bounded memory usage and safe parsing.

Installation

# In your Gemfile
gem "sashite-cell"

Or install manually:

gem install sashite-cell

Usage

Parsing (String → Coordinate)

Convert a CELL string into a Coordinate object.

require "sashite/cell"

# Standard parsing (returns Coordinate or raises)
coord = Sashite::Cell.parse("e4")
coord.indices    # => [4, 3]
coord.dimensions # => 2

# 3D coordinate
coord = Sashite::Cell.parse("a1A")
coord.indices # => [0, 0, 0]

# Invalid input raises Sashite::Cell::Errors::Argument
Sashite::Cell.parse("a0") # => raises Sashite::Cell::Errors::Argument

Formatting (Coordinate → String)

Convert a Coordinate back to a CELL string.

# From Coordinate object
coord = Sashite::Cell::Coordinate.new(4, 3)
coord.to_s # => "e4"

# Direct formatting (convenience)
Sashite::Cell.format(2, 2, 2) # => "c3C"

Validation

# Boolean check
Sashite::Cell.valid?("e4") # => true

# Detailed error
Sashite::Cell.validate("a0") # => raises Sashite::Cell::Errors::Argument, "leading zero"

Accessing Coordinate Data

coord = Sashite::Cell.parse("e4")

# Get dimensions count
coord.dimensions # => 2

# Get indices as array
coord.indices # => [4, 3]

# Access individual index
coord.indices[0] # => 4
coord.indices[1] # => 3

API Reference

Types

# Coordinate represents a parsed CELL coordinate with up to 3 dimensions.
class Sashite::Cell::Coordinate
  # Creates a Coordinate from 1 to 3 indices.
  # Raises Sashite::Cell::Errors::Argument if no indices provided or more than 3.
  #
  # @param indices [Array<Integer>] 0-indexed coordinate values (0-255)
  # @return [Coordinate]
  def initialize(*indices)

  # Returns the number of dimensions (1, 2, or 3).
  #
  # @return [Integer]
  def dimensions

  # Returns the coordinate indices as a frozen array.
  #
  # @return [Array<Integer>]
  def indices

  # Returns the CELL string representation.
  #
  # @return [String]
  def to_s
end

Constants

Sashite::Cell::Constants::MAX_DIMENSIONS   # => 3
Sashite::Cell::Constants::MAX_INDEX_VALUE  # => 255
Sashite::Cell::Constants::MAX_STRING_LENGTH # => 7

Parsing

# Parses a CELL string into a Coordinate.
# Raises Sashite::Cell::Errors::Argument if the string is not valid.
#
# @param string [String] CELL coordinate string
# @return [Coordinate]
# @raise [Sashite::Cell::Errors::Argument] if invalid
def Sashite::Cell.parse(string)

Formatting

# Formats indices into a CELL string.
# Convenience method equivalent to Coordinate.new(*indices).to_s.
#
# @param indices [Array<Integer>] 0-indexed coordinate values
# @return [String]
def Sashite::Cell.format(*indices)

Validation

# Validates a CELL string.
# Raises Sashite::Cell::Errors::Argument with descriptive message if invalid.
#
# @param string [String] CELL coordinate string
# @return [nil]
# @raise [Sashite::Cell::Errors::Argument] if invalid
def Sashite::Cell.validate(string)

# Reports whether string is a valid CELL coordinate.
#
# @param string [String] CELL coordinate string
# @return [Boolean]
def Sashite::Cell.valid?(string)

Errors

All parsing and validation errors raise Sashite::Cell::Errors::Argument (a subclass of ArgumentError) with descriptive messages:

Message	Cause
"empty input"	String length is 0
"input exceeds 7 characters"	String too long
"must start with lowercase letter"	Invalid first character
"unexpected character"	Character violates the cyclic sequence
"leading zero"	Numeric part starts with '0'
"exceeds 3 dimensions"	More than 3 dimensions
"index exceeds 255"	Decoded value out of range

begin
  Sashite::Cell.parse("a0")
rescue Sashite::Cell::Errors::Argument => e
  puts e.message # => "leading zero"
end

# Also catchable as ArgumentError for compatibility
begin
  Sashite::Cell.parse("a0")
rescue ArgumentError => e
  puts e.message # => "leading zero"
end

Design Principles

• Bounded values: Index validation prevents overflow
• Object-oriented: Coordinate class enables methods and encapsulation
• Ruby idioms: valid? predicate, to_s conversion
• Custom error class: Errors::Argument inherits from ArgumentError for precise error handling
• Immutable coordinates: Frozen indices array prevents mutation
• No dependencies: Pure Ruby standard library only

Related Specifications

• Game Protocol — Conceptual foundation
• CELL Specification — Official specification
• CELL Examples — Usage examples

License

Available as open source under the Apache License 2.0.