sashite-hand 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 0a34e61b9b036899e230483af790988ca1ee15a47d046e75422158062a1f8688
+  data.tar.gz: 2f40ad92442b907e0385ccae4363bfe3c3aad561b2b94264b8456f3623eda193
+SHA512:
+  metadata.gz: f18bec432f3ab88e64957c17400c317e7f1068b247fa04f5b26d682ca3601c4d892e647406a9c0afb90cf04bb60d67cfc72a262323335587b3629e5d7c4b2445
+  data.tar.gz: a3891d91130f6b7fb78767d049b6e543ce4ccc6eb49fb93a4a56ec9a6eea1f4401bf3a2b86e59f7164043fe5d91c763abb7f4dce19e68ee9aa267cf33993c0ef

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,116 @@
+# Hand.rb
+
+[![Version](https://img.shields.io/github/v/tag/sashite/hand.rb?label=Version&logo=github)](https://github.com/sashite/hand.rb/tags)
+[![Yard documentation](https://img.shields.io/badge/Yard-documentation-blue.svg?logo=github)](https://rubydoc.info/github/sashite/hand.rb/main)
+![Ruby](https://github.com/sashite/hand.rb/actions/workflows/main.yml/badge.svg?branch=main)
+[![License](https://img.shields.io/github/license/sashite/hand.rb?label=License&logo=github)](https://github.com/sashite/hand.rb/raw/main/LICENSE.md)
+
+> **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](https://sashite.dev/specs/hand/1.0.0/), providing a minimalist Ruby interface using a single character: `*` (asterisk).
+
+## Installation
+
+```ruby
+# In your Gemfile
+gem "sashite-hand"
+```
+
+Or install manually:
+
+```sh
+gem install sashite-hand
+```
+
+## Usage
+
+```ruby
+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
+
+```ruby
+# 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](https://sashite.dev/specs/cell/) for complete location coverage:
+
+```ruby
+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](https://sashite.dev/game-protocol/):
+
+| Protocol Attribute | HAND Encoding | Meaning |
+|-------------------|---------------|---------|
+| **Location** | `*` | Any off-board reserve area |
+
+## Related Specifications
+
+- [CELL](https://sashite.dev/specs/cell/) - Board position coordinates
+- [GGN](https://sashite.dev/specs/ggn/) - Movement possibility rules
+- [PMN](https://sashite.dev/specs/pmn/) - Portable Move Notation
+
+## Documentation
+
+- [Official HAND Specification v1.0.0](https://sashite.dev/specs/hand/1.0.0/)
+- [Game Protocol Foundation](https://sashite.dev/game-protocol/)
+- [API Documentation](https://rubydoc.info/github/sashite/hand.rb/main)
+
+## License
+
+Available as open source under the [MIT License](https://opensource.org/licenses/MIT).
+
+## About
+
+Maintained by [Sashité](https://sashite.com/) — promoting chess variants and sharing the beauty of board game cultures.

data/lib/sashite/hand.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Sashite
+  # HAND (Hold And Notation Designator) implementation
+  #
+  # HAND defines a simple, standardized notation for piece reserve locations
+  # in board games where pieces can be held off-board and potentially placed.
+  #
+  # @see https://sashite.dev/specs/hand/1.0.0/
+  # @author Sashité
+  #
+  # @example Basic usage
+  #   Sashite::Hand.reserve?("*")     # => true
+  #   Sashite::Hand.reserve?("a1")    # => false
+  #   Sashite::Hand.to_s              # => "*"
+  module Hand
+    # The reserve location character
+    RESERVE = "*"
+
+    # Check if a string represents the reserve location
+    #
+    # @param string [String] the string to check
+    # @return [Boolean] true if the string is the reserve location
+    #
+    # @example
+    #   Sashite::Hand.reserve?("*")   # => true
+    #   Sashite::Hand.reserve?("a1")  # => false
+    #   Sashite::Hand.reserve?("**")  # => false
+    #   Sashite::Hand.reserve?("")    # => false
+    def self.reserve?(string)
+      RESERVE.eql?(string)
+    end
+
+    # Get the canonical HAND representation
+    #
+    # @return [String] the reserve location character
+    #
+    # @example
+    #   Sashite::Hand.to_s            # => "*"
+    def self.to_s
+      RESERVE
+    end
+  end
+end

data/lib/sashite-hand.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+# Sashité namespace
+module Sashite
+  # @see https://sashite.dev/documents/hand/1.0.0/ HAND Specification v1.0.0
+  # @author Sashité
+end
+
+require_relative "sashite/hand"

metadata

@@ -0,0 +1,51 @@
+--- !ruby/object:Gem::Specification
+name: sashite-hand
+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: Hold And Notation Designator (HAND) provides a standardized notation
+  for piece reserve locations in board games where pieces can be held off-board and
+  potentially placed. Implements HAND Specification v1.0.0.
+email: contact@cyril.email
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.md
+- README.md
+- lib/sashite-hand.rb
+- lib/sashite/hand.rb
+homepage: https://github.com/sashite/hand.rb
+licenses:
+- MIT
+metadata:
+  bug_tracker_uri: https://github.com/sashite/hand.rb/issues
+  documentation_uri: https://rubydoc.info/github/sashite/hand.rb/main
+  homepage_uri: https://github.com/sashite/hand.rb
+  source_code_uri: https://github.com/sashite/hand.rb
+  specification_uri: https://sashite.dev/specs/hand/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.9
+specification_version: 4
+summary: HAND (Hold And Notation Designator) implementation for Ruby
+test_files: []