Skip to content

sashite/hand.rb

Repository files navigation

Hand.rb

Version Yard documentation Ruby License

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

What is HAND?

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).

Installation

# In your Gemfile
gem "sashite-hand"

Or install manually:

gem install sashite-hand

Usage

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 # => "*"

Movement Notation Examples

# 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)

Integration with CELL

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)

API Reference

Methods

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

Constants

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

Properties

  • 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

Protocol Mapping

Following the Game Protocol:

Protocol Attribute HAND Encoding Meaning
Location * Any off-board reserve area

Related Specifications

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

Documentation

License

Available as open source under the MIT License.

About

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

About

Hold And Notation Designator (HAND) specification

Resources

License

Code of conduct

Stars

Watchers

Forks