sashite-ggn 0.2.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 8fc9192ea7b3a42e4f8a039bec43da970ee3e4aa
-  data.tar.gz: 7edd6351985e71da38ab7b8dd0d057bae17aa2ec
+SHA256:
+  metadata.gz: 1af50f2e0d1bcc29f645560a6889184b953b18cc5a10096e2fd5042b61adac22
+  data.tar.gz: d01e4f3b4dfe6d34dd68d6155c541dd5fd17488e4b86e08710e9872ccd901cba
 SHA512:
-  metadata.gz: fe4aa42eac809ad5a93154b3a686c812adb98491c3d8a86ec91ed63403e0bea3b0463017f431cf9bb7942071b88e7244c991648c22928e18096ad15c430d2683
-  data.tar.gz: a251832c03b303ea0011e87088945f64453b64a1cc19900666beddde7d5cd9043f90dcafe175499f6f983925835a649b6085de9ef8f428e42e28404a2714ea4e
+  metadata.gz: 8565e8a83cac905bf9cfd368c136964c83e26f81b8e0fbd0c11c28c4c9da358511cda025688304cb37a16a21b79e07965209dd1027aab478b1fd49e976f00a80
+  data.tar.gz: 4bc9121f894dc379b85c4440a1844946f88cd5c9aa3cf25c8036845fc76060072e7d66579efed704b20f4b8ef851ded94e09b267c8249c231a09ae777d9ebf2e

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,135 @@
-# Sashite::GGN
+# Ggn.rb
 
-A collection of mappers for [GGN](http://sashite.wiki/General_Gameplay_Notation) objects.
+A Ruby implementation of the General Gameplay Notation (GGN) specification for describing pseudo-legal moves in abstract strategy board games.
 
-## Status
+[![Gem Version](https://badge.fury.io/rb/sashite-ggn.svg)](https://badge.fury.io/rb/sashite-ggn)
+[![Ruby](https://github.com/sashite/ggn.rb/workflows/Ruby/badge.svg)](https://github.com/sashite/ggn.rb/actions)
 
-* [![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 representing pseudo-legal moves in abstract strategy board games. This gem implements the [GGN Specification v1.0.0](https://sashite.dev/documents/ggn/1.0.0/).
+
+GGN focuses on basic movement constraints rather than game-specific legality rules, making it suitable for:
+
+- Cross-game move analysis and engine development
+- Hybrid games combining elements from different chess variants
+- Database systems requiring piece disambiguation across game types
+- Performance-critical applications with pre-computed move libraries
 
 ## Installation
 
-Add this line to your application's Gemfile:
+```ruby
+gem 'sashite-ggn'
+```
+
+## Basic Usage
 
-    gem 'sashite-ggn'
+### Loading GGN Data
 
-And then execute:
+```ruby
+require "sashite-ggn"
 
-    $ bundle
+# Load from file
+ruleset = Sashite::Ggn.load_file("chess_moves.json")
 
-Or install it yourself as:
+# Load from string
+json = '{"CHESS:P": {"e2": {"e4": [{"perform": {"e2": null, "e4": "CHESS:P"}}]}}}'
+ruleset = Sashite::Ggn.load_string(json)
+```
 
-    $ gem install sashite-ggn
+### Evaluating Moves
 
-## Usage
+```ruby
+# Query specific move
+engine = ruleset.select("CHESS:P").from("e2").to("e4")
 
-Working with GGN can be very simple, for example:
+# Define board state
+board_state = { "e2" => "CHESS:P", "e3" => nil, "e4" => nil }
+
+# Evaluate move
+transitions = engine.where(board_state, {}, "CHESS")
+# => [#<Transition diff={"e2"=>nil, "e4"=>"CHESS:P"}>]
+```
+
+### Generating All Moves
 
 ```ruby
-require 'sashite-ggn'
+# Get all pseudo-legal moves for current position
+all_moves = ruleset.pseudo_legal_transitions(board_state, captures, "CHESS")
+
+# Each move is represented as [actor, origin, target, transitions]
+all_moves.each do |actor, origin, target, transitions|
+  puts "#{actor}: #{origin} → #{target} (#{transitions.size} variants)"
+end
+```
+
+## Move Variants
 
-state = Sashite::GGN::State.new
-state.last_moved_actor       = nil
-state.previous_moves_counter = nil
+GGN supports multiple outcomes for a single move (e.g., promotion choices):
 
-subject = Sashite::GGN::Subject.new
-subject.ally  = true
-subject.actor = :self
-subject.state = state
+```ruby
+# Chess pawn promotion
+engine = ruleset.select("CHESS:P").from("e7").to("e8")
+transitions = engine.where({"e7" => "CHESS:P", "e8" => nil}, {}, "CHESS")
+
+transitions.each do |transition|
+  promoted_piece = transition.diff["e8"]
+  puts "Promote to #{promoted_piece}"
+end
+# Output: CHESS:Q, CHESS:R, CHESS:B, CHESS:N
 ```
 
-## Contributing
+## Piece Drops
+
+For games supporting piece drops (e.g., Shogi):
+
+```ruby
+# Drop from hand (origin "*")
+engine = ruleset.select("SHOGI:P").from("*").to("5e")
+
+captures = { "SHOGI:P" => 1 }  # One pawn in hand
+board_state = { "5e" => nil }   # Empty target square
+
+transitions = engine.where(board_state, captures, "SHOGI")
+# => [#<Transition diff={"5e"=>"SHOGI:P"} drop="SHOGI:P">]
+```
+
+## Validation
+
+```ruby
+# Validate GGN data
+Sashite::Ggn.validate!(data)  # Raises exception on failure
+Sashite::Ggn.valid?(data)     # Returns boolean
+```
+
+## API Reference
+
+### Core Classes
+
+- `Sashite::Ggn::Ruleset` - Main entry point for querying moves
+- `Sashite::Ggn::Ruleset::Source` - Piece type with source positions
+- `Sashite::Ggn::Ruleset::Source::Destination` - Available destinations
+- `Sashite::Ggn::Ruleset::Source::Destination::Engine` - Move evaluator
+- `Sashite::Ggn::Ruleset::Source::Destination::Engine::Transition` - Move result
+
+### Key Methods
+
+- `#pseudo_legal_transitions(board_state, captures, turn)` - Generate all moves
+- `#select(actor).from(origin).to(target)` - Query specific move
+- `#where(board_state, captures, turn)` - Evaluate move validity
+
+## Related Specifications
+
+GGN works alongside other Sashité specifications:
+
+- [GAN](https://sashite.dev/documents/gan/1.0.0/) - General Actor Notation for piece identifiers
+- [FEEN](https://sashite.dev/documents/feen/1.0.0/) - Board position representation
+- [PMN](https://sashite.dev/documents/pmn/1.0.0/) - Move sequence representation
+
+## 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/move_validator.rb

@@ -0,0 +1,180 @@
+# frozen_string_literal: true
+
+module Sashite
+  module Ggn
+    # Centralized module for move condition validation.
+    # Contains shared logic between Engine and performance optimizations.
+    module MoveValidator
+      # Reserved for drops from hand
+      DROP_ORIGIN = "*"
+
+      # Separator in GAN (General Actor Notation) identifiers
+      GAN_SEPARATOR = ":"
+
+      private_constant :DROP_ORIGIN, :GAN_SEPARATOR
+
+      private
+
+      # Checks if the piece is available in hand for a drop move.
+      #
+      # @param actor [String] GAN identifier of the piece
+      # @param captures [Hash] Pieces available in hand
+      #
+      # @return [Boolean] true if the piece can be dropped
+      def piece_available_in_hand?(actor, captures)
+        return false unless valid_gan_format?(actor)
+
+        base_piece = extract_base_piece(actor)
+        return false if base_piece.nil?
+
+        (captures[base_piece] || 0) > 0
+      end
+
+      # Checks if the correct piece is present at the origin square on the board.
+      #
+      # @param actor [String] GAN identifier of the piece
+      # @param origin [String] Origin square
+      # @param board_state [Hash] Current board state
+      #
+      # @return [Boolean] true if the piece is at the correct position
+      def piece_on_board_at_origin?(actor, origin, board_state)
+        return false unless valid_gan_format?(actor)
+        return false unless origin.is_a?(String) && !origin.empty?
+        return false unless board_state.is_a?(Hash)
+
+        board_state[origin] == actor
+      end
+
+      # Checks if the piece belongs to the current player.
+      # Fixed version that verifies both the game name AND the case.
+      #
+      # This method now performs strict validation by ensuring:
+      # - The game identifier matches exactly with the turn parameter
+      # - The case convention is consistent (uppercase/lowercase players)
+      # - The piece part follows the same case convention as the game part
+      #
+      # @param actor [String] GAN identifier of the piece
+      # @param turn [String] Current player's game identifier
+      #
+      # @return [Boolean] true if the piece belongs to the current player
+      def piece_belongs_to_current_player?(actor, turn)
+        return false unless valid_gan_format?(actor)
+        return false unless valid_game_identifier?(turn)
+
+        game_part, piece_part = actor.split(GAN_SEPARATOR, 2)
+
+        # Strict verification: the game name must match exactly
+        # while considering case to determine the player
+        case turn
+        when turn.upcase
+          # Current player is the uppercase one
+          game_part == turn && game_part == game_part.upcase && piece_part.match?(/\A[-+]?[A-Z][']?\z/)
+        when turn.downcase
+          # Current player is the lowercase one
+          game_part == turn && game_part == game_part.downcase && piece_part.match?(/\A[-+]?[a-z][']?\z/)
+        else
+          # Turn is neither entirely uppercase nor lowercase
+          false
+        end
+      end
+
+      # Extracts the base form of a piece (removes modifiers).
+      #
+      # According to FEEN specification, pieces in hand are always stored
+      # in their base form without any state modifiers (prefixes/suffixes).
+      #
+      # @param actor [String] Complete GAN identifier
+      #
+      # @return [String, nil] Base form for hand storage, nil if invalid format
+      def extract_base_piece(actor)
+        return nil unless valid_gan_format?(actor)
+
+        game_part, piece_part = actor.split(GAN_SEPARATOR, 2)
+
+        # Safe extraction of the base character
+        match = piece_part.match(/\A[-+]?([A-Za-z])[']?\z/)
+        return nil unless match
+
+        clean_piece = match[1]
+
+        # Case consistency verification
+        game_is_upper = game_part == game_part.upcase
+        piece_is_upper = clean_piece == clean_piece.upcase
+
+        return nil unless game_is_upper == piece_is_upper
+
+        "#{game_part}#{GAN_SEPARATOR}#{clean_piece}"
+      end
+
+      # Validates the GAN format of an identifier.
+      #
+      # A valid GAN identifier must:
+      # - Be a string containing exactly one colon separator
+      # - Have a valid game identifier before the colon
+      # - Have a valid piece identifier after the colon
+      # - Maintain case consistency between game and piece parts
+      #
+      # @param actor [String] Identifier to validate
+      #
+      # @return [Boolean] true if the format is valid
+      def valid_gan_format?(actor)
+        return false unless actor.is_a?(String)
+        return false unless actor.include?(GAN_SEPARATOR)
+
+        parts = actor.split(GAN_SEPARATOR, 2)
+        return false unless parts.length == 2
+
+        game_part, piece_part = parts
+
+        return false unless valid_game_identifier?(game_part)
+        return false unless valid_piece_identifier?(piece_part)
+
+        # Case consistency verification between game and piece
+        game_is_upper = game_part == game_part.upcase
+        piece_match = piece_part.match(/\A[-+]?([A-Za-z])[']?\z/)
+        return false unless piece_match
+
+        piece_char = piece_match[1]
+        piece_is_upper = piece_char == piece_char.upcase
+
+        game_is_upper == piece_is_upper
+      end
+
+      # Validates a game identifier.
+      #
+      # Game identifiers must be non-empty strings containing only
+      # alphabetic characters, either all uppercase or all lowercase.
+      # Mixed case is not allowed as it breaks the player distinction.
+      #
+      # @param game_id [String] Game identifier to validate
+      #
+      # @return [Boolean] true if the identifier is valid
+      def valid_game_identifier?(game_id)
+        return false unless game_id.is_a?(String)
+        return false if game_id.empty?
+
+        # Must be either entirely uppercase or entirely lowercase
+        game_id.match?(/\A[A-Z]+\z/) || game_id.match?(/\A[a-z]+\z/)
+      end
+
+      # Validates a piece identifier (part after the colon).
+      #
+      # Piece identifiers follow the pattern: [optional prefix][letter][optional suffix]
+      # Where:
+      # - Optional prefix: + or -
+      # - Letter: A-Z or a-z (must match game part case)
+      # - Optional suffix: ' (apostrophe)
+      #
+      # @param piece_id [String] Piece identifier to validate
+      #
+      # @return [Boolean] true if the identifier is valid
+      def valid_piece_identifier?(piece_id)
+        return false unless piece_id.is_a?(String)
+        return false if piece_id.empty?
+
+        # Format: [optional prefix][letter][optional suffix]
+        piece_id.match?(/\A[-+]?[A-Za-z][']?\z/)
+      end
+    end
+  end
+end

data/lib/sashite/ggn/ruleset/source/destination/engine/transition.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module Sashite
+  module Ggn
+    class Ruleset
+      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