sashite-ggn 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 8fc9192ea7b3a42e4f8a039bec43da970ee3e4aa
-  data.tar.gz: 7edd6351985e71da38ab7b8dd0d057bae17aa2ec
+SHA256:
+  metadata.gz: 3841392373c865dd1e96e3cd8321cb8720767585d815fc16449f05a00c8d0900
+  data.tar.gz: a00ebca510e8af7ff2e77ea8056009ca2198a43d79885a61fd8ea682f6c9aaf3
 SHA512:
-  metadata.gz: fe4aa42eac809ad5a93154b3a686c812adb98491c3d8a86ec91ed63403e0bea3b0463017f431cf9bb7942071b88e7244c991648c22928e18096ad15c430d2683
-  data.tar.gz: a251832c03b303ea0011e87088945f64453b64a1cc19900666beddde7d5cd9043f90dcafe175499f6f983925835a649b6085de9ef8f428e42e28404a2714ea4e
+  metadata.gz: 9cc52a786d043b1e2ed437d58f9c939268d23f97df82211732dacf955964bbc27fbc24a3ac280c5cb63a84e6aeaf7fb22aa88e659832020802ac1e78e949f6b5
+  data.tar.gz: 35a6f1b1d9d0f5878ebef7c443f675a0c15027d0895ca96c92c69c1f9a6864c152b7c58fb25e57cbb5ff50223a007003eb994ddb265d1e0e67707fa5b692a6b3

data/LICENSE.md

@@ -1,22 +1,21 @@
-Copyright (c) 2014 Cyril Wack
+# The MIT License
 
-MIT License
+Copyright (c) 2014-2025 Sashité
 
-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:
+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 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.
+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

@@ -1,48 +1,418 @@
-# Sashite::GGN
+# Ggn.rb
 
-A collection of mappers for [GGN](http://sashite.wiki/General_Gameplay_Notation) objects.
+[![Version](https://img.shields.io/github/v/tag/sashite/ggn.rb?label=Version&logo=github)](https://github.com/sashite/ggn.rb/tags)
+[![Yard documentation](https://img.shields.io/badge/Yard-documentation-blue.svg?logo=github)](https://rubydoc.info/github/sashite/ggn.rb/main)
+![Ruby](https://github.com/sashite/ggn.rb/actions/workflows/main.yml/badge.svg?branch=main)
+[![License](https://img.shields.io/github/license/sashite/ggn.rb?label=License&logo=github)](https://github.com/sashite/ggn.rb/raw/main/LICENSE.md)
 
-## Status
+> **GGN** (General Gameplay Notation) support for the Ruby language.
 
-* [![Gem Version](https://badge.fury.io/rb/sashite-ggn.svg)](//badge.fury.io/rb/sashite-ggn)
-* [![Build Status](https://secure.travis-ci.org/sashite/ggn.rb.svg?branch=master)](//travis-ci.org/sashite/ggn.rb?branch=master)
-* [![Dependency Status](https://gemnasium.com/sashite/ggn.rb.svg)](//gemnasium.com/sashite/ggn.rb)
+## What is GGN?
+
+GGN (General Gameplay Notation) is a rule-agnostic, JSON-based format for describing **pseudo-legal moves** in abstract strategy board games. Unlike move notations that express *what* a move does, GGN expresses *whether* that move is **possible** under basic movement constraints.
+
+GGN is deliberately silent about higher-level, game-specific legality questions (e.g., check, ko, repetition, castling paths). This neutrality makes the format universal: any engine can pre-compute and share a library of pseudo-legal moves for any mix of games.
+
+This gem implements the [GGN Specification v1.0.0](https://sashite.dev/documents/ggn/1.0.0/), providing a Ruby interface for:
+
+- Loading and validating GGN JSON documents
+- Querying pseudo-legal moves for specific pieces and positions
+- Evaluating move validity under current board conditions
+- Processing complex move conditions including captures, drops, and promotions
 
 ## Installation
 
-Add this line to your application's Gemfile:
+```ruby
+# In your Gemfile
+gem "sashite-ggn"
+```
+
+Or install manually:
+
+```sh
+gem install sashite-ggn
+```
+
+## GGN Format
+
+A single GGN **entry** answers the question:
+
+> Can this piece, currently on this square, reach that square?
+
+It encodes:
+
+1. **Which piece** (via GAN identifier)
+2. **From where** (source square label, or "`*`" for off-board)
+3. **To where** (destination square label)
+4. **Which pre-conditions** must hold (`require`)
+5. **Which pre-conditions** must not hold (`prevent`)
+6. **Which post-conditions** result (`perform`, plus optional `gain` or `drop`)
+
+### JSON Structure
+
+```json
+{
+  "<Source piece GAN>": {
+    "<Source square>": {
+      "<Destination square>": [
+        {
+          "require":  { "<square>": "<required state>", … },
+          "prevent":  { "<square>": "<forbidden state>", … },
+          "perform":  { "<square>": "<new state | null>", … },
+          "gain":     "<piece GAN>" | null,
+          "drop":     "<piece GAN>" | null
+        }
+      ]
+    }
+  }
+}
+```
+
+## Basic Usage
+
+### Loading GGN Data
+
+Load GGN data from various sources:
+
+```ruby
+require "sashite-ggn"
+
+# From file
+piece_data = Sashite::Ggn.load_file("chess_moves.json")
+
+# From JSON string
+json_string = '{"CHESS:P": {"e2": {"e4": [{"require": {"e3": "empty", "e4": "empty"}, "perform": {"e2": null, "e4": "CHESS:P"}}]}}}'
+piece_data = Sashite::Ggn.load_string(json_string)
+
+# From Hash
+ggn_hash = { "CHESS:P" => { "e2" => { "e4" => [{ "require" => { "e3" => "empty", "e4" => "empty" }, "perform" => { "e2" => nil, "e4" => "CHESS:P" } }] } } }
+piece_data = Sashite::Ggn.load_hash(ggn_hash)
+```
+
+### Querying Moves
 
-    gem 'sashite-ggn'
+Navigate through the GGN structure to find specific moves:
 
-And then execute:
+```ruby
+require "sashite-ggn"
+
+piece_data = Sashite::Ggn.load_file("chess_moves.json")
+
+# Select a piece type
+source = piece_data.select("CHESS:P")
+
+# Get destinations from a specific source square
+destinations = source.from("e2")
+
+# Get the engine for a specific target square
+engine = destinations.to("e4")
+```
+
+### Evaluating Move Validity
 
-    $ bundle
+Check if a move is valid under current board conditions:
 
-Or install it yourself as:
+```ruby
+require "sashite-ggn"
+
+# Load piece data and get the movement engine
+piece_data = Sashite::Ggn.load_file("chess_moves.json")
+engine = piece_data.select("CHESS:P").from("e2").to("e4")
 
-    $ gem install sashite-ggn
+# Define current board state
+board_state = {
+  "e2" => "CHESS:P",  # White pawn on e2
+  "e3" => nil,        # Empty square
+  "e4" => nil         # Empty square
+}
 
-## Usage
+# Evaluate the move
+result = engine.where(board_state, {}, "CHESS")
+
+if result
+  puts "Move is valid!"
+  puts "Board changes: #{result.diff}"
+  # => { "e2" => nil, "e4" => "CHESS:P" }
+  puts "Piece gained: #{result.gain}"  # => nil (no capture)
+  puts "Piece dropped: #{result.drop}" # => nil (not a drop move)
+else
+  puts "Move is not valid under current conditions"
+end
+```
 
-Working with GGN can be very simple, for example:
+### Handling Captures
+
+Process moves that capture enemy pieces:
 
 ```ruby
-require 'sashite-ggn'
+require "sashite-ggn"
+
+# Load piece data for a capture move
+piece_data = Sashite::Ggn.load_file("chess_moves.json")
+engine = piece_data.select("CHESS:P").from("e5").to("d6")
+
+# Board state with enemy piece to capture
+board_state = {
+  "e5" => "CHESS:P",  # Our pawn
+  "d6" => "chess:p"   # Enemy pawn (lowercase = opponent)
+}
 
-state = Sashite::GGN::State.new
-state.last_moved_actor       = nil
-state.previous_moves_counter = nil
+result = engine.where(board_state, {}, "CHESS")
 
-subject = Sashite::GGN::Subject.new
-subject.ally  = true
-subject.actor = :self
-subject.state = state
+if result
+  puts "Capture is valid!"
+  puts "Board changes: #{result.diff}"
+  # => { "e5" => nil, "d6" => "CHESS:P" }
+  puts "Captured piece: #{result.gain}"  # => "CHESS:P" (gained in hand)
+end
 ```
 
-## Contributing
+### Piece Drops (Shogi-style)
+
+Handle dropping pieces from hand onto the board:
+
+```ruby
+require "sashite-ggn"
+
+# Load Shogi piece data
+piece_data = Sashite::Ggn.load_file("shogi_moves.json")
+engine = piece_data.select("SHOGI:P").from("*").to("5e")
+
+# Player has captured pawns available
+captures = { "SHOGI:P" => 2 }
+
+# Current board state (5th file is clear of unpromoted pawns)
+board_state = {
+  "5e" => nil,  # Target square is empty
+  "5a" => nil, "5b" => nil, "5c" => nil, "5d" => nil,
+  "5f" => nil, "5g" => nil, "5h" => nil, "5i" => nil
+}
+
+result = engine.where(board_state, captures, "SHOGI")
+
+if result
+  puts "Pawn drop is valid!"
+  puts "Board changes: #{result.diff}"  # => { "5e" => "SHOGI:P" }
+  puts "Piece dropped from hand: #{result.drop}"  # => "SHOGI:P"
+end
+```
+
+## Validation
+
+### Schema Validation
+
+Validate GGN data against the official JSON Schema:
+
+```ruby
+require "sashite-ggn"
+
+# Validate during loading (default behavior)
+begin
+  piece_data = Sashite::Ggn.load_file("moves.json")
+  puts "GGN data is valid!"
+rescue Sashite::Ggn::ValidationError => e
+  puts "Validation failed: #{e.message}"
+end
+
+# Skip validation for performance (large files)
+piece_data = Sashite::Ggn.load_file("large_moves.json", validate: false)
+
+# Validate manually
+begin
+  Sashite::Ggn.validate!(my_data)
+  puts "Data is valid"
+rescue Sashite::Ggn::ValidationError => e
+  puts "Invalid: #{e.message}"
+end
+
+# Check validity without exceptions
+if Sashite::Ggn.valid?(my_data)
+  puts "Data is valid"
+else
+  errors = Sashite::Ggn.validation_errors(my_data)
+  puts "Validation errors: #{errors.join(', ')}"
+end
+```
+
+## Occupation States
+
+GGN recognizes several occupation states for move conditions:
+
+| State            | Meaning                                                                      |
+| ---------------- | ---------------------------------------------------------------------------- |
+| `"empty"`        | Square must be empty                                                         |
+| `"enemy"`        | Square must contain a standard opposing piece                                |
+| *GAN identifier* | Square must contain **exactly** the specified piece                          |
+
+### Implicit States
+
+Through the `prevent` field, additional states can be expressed:
+
+| Implicit State   | Expression                   | Meaning                                                  |
+| ---------------- | ---------------------------- | -------------------------------------------------------- |
+| `"occupied"`     | `"prevent": { "a1": "empty" }` | Square must be occupied by any piece                     |
+| `"ally"`         | `"prevent": { "a1": "enemy" }` | Square must contain a friendly piece                     |
+
+## Examples
+
+### Simple Move
+
+A piece moving from one square to another without conditions:
+
+```json
+{
+  "CHESS:K": {
+    "e1": {
+      "e2": [
+        {
+          "perform": { "e1": null, "e2": "CHESS:K" }
+        }
+      ]
+    }
+  }
+}
+```
+
+### Sliding Move
+
+A piece that slides along empty squares:
+
+```json
+{
+  "CHESS:R": {
+    "a1": {
+      "a3": [
+        {
+          "require": { "a2": "empty", "a3": "empty" },
+          "perform": { "a1": null, "a3": "CHESS:R" }
+        }
+      ]
+    }
+  }
+}
+```
+
+### Capture with Gain
+
+A piece capturing an enemy and gaining it in hand:
+
+```json
+{
+  "SHOGI:P": {
+    "5f": {
+      "5e": [
+        {
+          "require": { "5e": "enemy" },
+          "perform": { "5f": null, "5e": "SHOGI:P" },
+          "gain": "SHOGI:P"
+        }
+      ]
+    }
+  }
+}
+```
+
+### Piece Drop
+
+Dropping a piece from hand onto the board:
+
+```json
+{
+  "SHOGI:P": {
+    "*": {
+      "5e": [
+        {
+          "require": { "5e": "empty" },
+          "prevent": {
+            "5a": "SHOGI:P", "5b": "SHOGI:P", "5c": "SHOGI:P",
+            "5d": "SHOGI:P", "5f": "SHOGI:P", "5g": "SHOGI:P",
+            "5h": "SHOGI:P", "5i": "SHOGI:P"
+          },
+          "perform": { "5e": "SHOGI:P" },
+          "drop": "SHOGI:P"
+        }
+      ]
+    }
+  }
+}
+```
+
+### Promotion
+
+A piece moving and changing to a different piece type:
+
+```json
+{
+  "CHESS:P": {
+    "g7": {
+      "g8": [
+        {
+          "require": { "g8": "empty" },
+          "perform": { "g7": null, "g8": "CHESS:Q" }
+        }
+      ]
+    }
+  }
+}
+```
+
+## Error Handling
+
+The library provides comprehensive error handling:
+
+```ruby
+require "sashite-ggn"
+
+begin
+  # Various operations that might fail
+  piece_data = Sashite::Ggn.load_file("nonexistent.json")
+  source = piece_data.select("INVALID:PIECE")
+  destinations = source.from("invalid_square")
+  engine = destinations.to("another_invalid")
+  result = engine.where({}, {}, "")
+rescue Sashite::Ggn::ValidationError => e
+  puts "GGN validation error: #{e.message}"
+rescue KeyError => e
+  puts "Key not found: #{e.message}"
+rescue ArgumentError => e
+  puts "Invalid argument: #{e.message}"
+end
+```
+
+## Performance Considerations
+
+For large GGN files or high-frequency operations:
+
+```ruby
+# Skip validation for better performance
+piece_data = Sashite::Ggn.load_file("large_dataset.json", validate: false)
+
+# Cache frequently used engines
+@engines = {}
+def get_engine(piece, from, to)
+  key = "#{piece}:#{from}:#{to}"
+  @engines[key] ||= piece_data.select(piece).from(from).to(to)
+end
+```
+
+## Related Specifications
+
+GGN works alongside other Sashité specifications:
+
+- **[GAN](https://sashite.dev/documents/gan/1.0.0/)** (General Actor Notation): Unique piece identifiers
+- **[FEEN](https://sashite.dev/documents/feen/1.0.0/)** (Forsyth-Edwards Enhanced Notation): Board position representation
+- **[PMN](https://sashite.dev/documents/pmn/1.0.0/)** (Portable Move Notation): Move sequence representation
+
+## Documentation
+
+- [Official GGN Specification](https://sashite.dev/documents/ggn/1.0.0/)
+- [JSON Schema](https://sashite.dev/schemas/ggn/1.0.0/schema.json)
+- [API Documentation](https://rubydoc.info/github/sashite/ggn.rb/main)
+
+## License
+
+The [gem](https://rubygems.org/gems/sashite-ggn) is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## About Sashité
 
-1. Fork it
-2. Create your feature branch (`git checkout -b my-new-feature`)
-3. Commit your changes (`git commit -am 'Add some feature'`)
-4. Push to the branch (`git push origin my-new-feature`)
-5. Create a new Pull Request
+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/ggn/piece/source/destination/engine/transition.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module Sashite
+  module Ggn
+    class Piece
+      class Source
+        class Destination
+          class Engine
+            # Represents the result of a valid pseudo-legal move evaluation.
+            #
+            # A Transition encapsulates the changes that occur when a move is executed:
+            # - Board state changes (pieces moving, appearing, or disappearing)
+            # - Pieces gained in hand (from captures)
+            # - Pieces dropped from hand (for drop moves)
+            #
+            # @example Basic move (pawn advance)
+            #   transition = Transition.new(nil, nil, "e2" => nil, "e4" => "CHESS:P")
+            #   transition.diff  # => { "e2" => nil, "e4" => "CHESS:P" }
+            #   transition.gain  # => nil
+            #   transition.drop  # => nil
+            #
+            # @example Capture with piece gain
+            #   transition = Transition.new("CHESS:R", nil, "g7" => nil, "h8" => "CHESS:Q")
+            #   transition.gain  # => "CHESS:R" (captured rook goes to hand)
+            #
+            # @example Piece drop from hand
+            #   transition = Transition.new(nil, "SHOGI:P", "5e" => "SHOGI:P")
+            #   transition.drop  # => "SHOGI:P" (pawn removed from hand)
+            class Transition
+              # @return [Hash<String, String|nil>] Board state changes after the move.
+              #   Keys are square labels, values are piece identifiers or nil for empty squares.
+              attr_reader :diff
+
+              # @return [String, nil] Piece identifier added to the current player's hand,
+              #   typically from a capture. Nil if no piece is gained.
+              attr_reader :gain
+
+              # @return [String, nil] Piece identifier removed from the current player's hand
+              #   for drop moves. Nil if no piece is dropped.
+              attr_reader :drop
+
+              # Creates a new Transition with the specified changes.
+              #
+              # @param gain [String, nil] Piece gained in hand (usually from capture)
+              # @param drop [String, nil] Piece dropped from hand (for drop moves)
+              # @param diff [Hash] Board state changes as keyword arguments.
+              #   Keys should be square labels, values should be piece identifiers or nil.
+              #
+              # @example Creating a simple move transition
+              #   Transition.new(nil, nil, "e2" => nil, "e4" => "CHESS:P")
+              #
+              # @example Creating a capture transition
+              #   Transition.new("CHESS:R", nil, "d4" => nil, "e5" => "CHESS:P")
+              #
+              # @example Creating a drop transition
+              #   Transition.new(nil, "SHOGI:P", "3c" => "SHOGI:P")
+              def initialize(gain, drop, **diff)
+                @gain = gain
+                @drop = drop
+                @diff = diff
+
+                freeze
+              end
+
+              # Checks if this transition involves gaining a piece.
+              #
+              # @return [Boolean] true if a piece is gained (typically from capture)
+              #
+              # @example
+              #   transition.gain?  # => true if @gain is not nil
+              def gain?
+                !@gain.nil?
+              end
+
+              # Checks if this transition involves dropping a piece from hand.
+              #
+              # @return [Boolean] true if a piece is dropped from hand
+              #
+              # @example
+              #   transition.drop?  # => true if @drop is not nil
+              def drop?
+                !@drop.nil?
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end