Hand.rb

HAND (Hold And Notation Designator) implementation for the Ruby language.

HAND (Hold And Notation Designator) is a standardized notation for representing piece reserve locations in board games where pieces can be held off-board and potentially placed. This applies to games like Shōgi, Crazyhouse, Go, and other games featuring reserve mechanics.

This gem implements the HAND Specification v1.0.0, providing a minimalist Ruby interface using a single character: * (asterisk).

# In your Gemfile
gem "sashite-hand"

Or install manually:

gem install sashite-hand

require "sashite/hand"

# Check if a location represents the reserve
Sashite::Hand.reserve?("*")    # => true
Sashite::Hand.reserve?("a1")   # => false
Sashite::Hand.reserve?("**")   # => false

# Get the canonical representation
Sashite::Hand.to_s # => "*"

# From reserve to board
source = "*"
destination = "e4"
puts "#{source} → #{destination}" # => "* → e4"

# Shōgi piece drop
puts "Dropping piece from reserve to 5e" if Sashite::Hand.reserve?("*")

# Go stone placement
supply = "*"
puts "Placing stone from supply to dd" if Sashite::Hand.reserve?(supply)

HAND complements the CELL specification for complete location coverage:

def valid_location?(location)
  Sashite::Cell.valid?(location) || Sashite::Hand.reserve?(location)
end

valid_location?("*")  # => true (reserve)
valid_location?("a1") # => true (board position)

• Sashite::Hand.reserve?(location) - Check if location represents the reserve
• Sashite::Hand.to_s - Get the canonical HAND representation ("*")

• Sashite::Hand::RESERVE - The reserve location character ("*")

• Minimalist: Single character (*) for all reserve operations
• Universal: Works across different board game systems
• Rule-agnostic: Independent of specific reserve mechanics
• Complementary: Designed to work with CELL coordinates

Following the Game Protocol:

• CELL - Board position coordinates
• GGN - Movement possibility rules
• PMN - Portable Move Notation

• Official HAND Specification v1.0.0
• Game Protocol Foundation
• API Documentation

Available as open source under the MIT License.

Maintained by Sashité — promoting chess variants and sharing the beauty of board game cultures.