sashite-gan 2.2.0 → 4.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7ebee55a8937fadf15f9b2a4bcf03e672b96f832cd01482be1c0374a1314fb21
-  data.tar.gz: 3f092d4f12e0b6a2e20d8981c76fad2be914a886a37ca95cb4d3437b9f18e67a
+  metadata.gz: b5469e58632f24a93eea22a4dd6d48c27028f84a2137469164eae9684274a7af
+  data.tar.gz: fa8fe045e1f5ced019b9bdf33369bc457e94187d7703ed13c7189c040e430502
 SHA512:
-  metadata.gz: 472262b63c2401d6392dd65b1e39ca0600515b201cce85fcbbbacf8d245256b978c143d7313c23495cc143cf42c79a6631690a0f0eab51c0a9bf8a78cd64a259
-  data.tar.gz: a5afb55bc54194750b0406646e0074a08f9dd5952f3c743c411a94b1cfa183aa263e7cb7b393fffce542ce5c2adf385f82ac5322e4ddfbfeb843d4a9ae0c063d
+  metadata.gz: 91d7fbc665bce2be60a37921398dea166684efa68ce55e22fd740d7d85907599d8812a491dbd561b73c1bb8aa1c625d453590842adb3edfb86b686e69c1f8ed8
+  data.tar.gz: 7761db8067e89586009fe4c52f06e632e7c153c5a7f370c613abd3066691d3d9b3fe214f71db1de1988a4a0d02df1d841b03a70b9aadb49ad89dcf3b940ef8bd

data/LICENSE.md

@@ -1,4 +1,4 @@
-Copyright (c) 2014-2020 Sashite
+Copyright (c) 2014-2025 Sashite
 
 MIT License
 

data/README.md

@@ -1,181 +1,414 @@
-# GAN.rb
+# Gan.rb
 
-[![Build Status](https://travis-ci.org/sashite/gan.rb.svg?branch=master)](https://travis-ci.org/sashite/gan.rb)
+[![Version](https://img.shields.io/github/v/tag/sashite/gan.rb?label=Version&logo=github)](https://github.com/sashite/gan.rb/tags)
+[![Yard documentation](https://img.shields.io/badge/Yard-documentation-blue.svg?logo=github)](https://rubydoc.info/github/sashite/gan.rb/main)
+![Ruby](https://github.com/sashite/gan.rb/actions/workflows/main.yml/badge.svg?branch=main)
+[![License](https://img.shields.io/github/license/sashite/gan.rb?label=License&logo=github)](https://github.com/sashite/gan.rb/raw/main/LICENSE.md)
 
-> A Ruby interface for data serialization in [General Actor Notation](https://developer.sashite.com/specs/general-actor-notation) format ♟️
+> **GAN** (General Actor Notation) support for the Ruby language.
+
+## What is GAN?
+
+GAN (General Actor Notation) defines a consistent and rule-agnostic format for identifying game actors in abstract strategy board games. GAN provides unambiguous identification of pieces by combining Style Name Notation (SNN) with Piece Name Notation (PNN), eliminating collision problems when multiple piece styles are present in the same context.
+
+This gem implements the [GAN Specification v1.0.0](https://sashite.dev/documents/gan/1.0.0/), providing a Ruby interface for working with game actors through a clean and modular API that builds upon the existing [sashite-snn](https://rubygems.org/gems/sashite-snn) and [pnn](https://rubygems.org/gems/pnn) gems.
 
 ## Installation
 
-1. Add the dependency to your `Gemfile`:
+```ruby
+# In your Gemfile
+gem "sashite-gan"
+```
+
+Or install manually:
+
+```sh
+gem install sashite-gan
+```
+
+## GAN Format
+
+A GAN record consists of a style identifier (SNN format), followed by a colon separator, followed by a piece identifier (PNN format):
+
+```
+<style-id>:<piece-id>
+```
+
+Where:
+- `<style-id>` is a Style Name Notation (SNN) identifier conforming to SNN specification
+- `:` is a literal colon character serving as a separator
+- `<piece-id>` is a Piece Name Notation (PNN) identifier conforming to PNN specification
 
-   ```ruby
-   gem 'sashite-gan'
-   ```
+## Basic Usage
 
-2. Run `bundle install`
+### Creating Actor Objects
 
-## Usage
+The primary interface is the `Sashite::Gan::Actor` class, which represents a game actor in GAN format:
 
 ```ruby
-require 'sashite-gan'
-
-
-# Chess (Western chess)'s Rook, White
-piece = Sashite::GAN.parse("C:R")
-
-piece.abbr.to_s # => "R"
-piece.style # => "C"
-piece.topside? # => false
-piece.bottomside? # => true
-piece.to_s # => "C:R"
-piece.topside.to_s # => "c:r"
-piece.bottomside.to_s # => "C:R"
-piece.oppositeside.to_s # => "c:r"
-piece.promote.to_s # => "C:+R"
-piece.unpromote.to_s # => "C:R"
-
-
-# Chess (Western chess)'s King, Black
-piece = Sashite::GAN.parse("c:-k")
-
-piece.abbr.to_s # => "-k"
-piece.style # => "c"
-piece.topside? # => true
-piece.bottomside? # => false
-piece.to_s # => "c:-k"
-piece.topside.to_s # => "c:-k"
-piece.bottomside.to_s # => "C:-K"
-piece.oppositeside.to_s # => "C:-K"
-piece.promote.to_s # => "c:+-k"
-piece.unpromote.to_s # => "c:-k"
-
-
-# Makruk (Thai chess)'s Bishop, White
-piece = Sashite::GAN.parse("M:B")
-
-piece.abbr.to_s # => "B"
-piece.style # => "M"
-piece.topside? # => false
-piece.bottomside? # => true
-piece.to_s # => "M:B"
-piece.topside.to_s # => "m:b"
-piece.bottomside.to_s # => "M:B"
-piece.oppositeside.to_s # => "m:b"
-piece.promote.to_s # => "M:+B"
-piece.unpromote.to_s # => "M:B"
-
-
-# Shogi (Japanese chess)'s King, Gote
-piece = Sashite::GAN.parse("s:-k")
-
-piece.abbr.to_s # => "-k"
-piece.style # => "s"
-piece.topside? # => true
-piece.bottomside? # => false
-piece.to_s # => "s:-k"
-piece.topside.to_s # => "s:-k"
-piece.bottomside.to_s # => "S:-K"
-piece.oppositeside.to_s # => "S:-K"
-piece.promote.to_s # => "s:+-k"
-piece.unpromote.to_s # => "s:-k"
-
-
-# Shogi (Japanese chess)'s King, Sente
-piece = Sashite::GAN.parse("S:-K")
-
-piece.abbr.to_s # => "-K"
-piece.style # => "S"
-piece.topside? # => false
-piece.bottomside? # => true
-piece.to_s # => "S:-K"
-piece.topside.to_s # => "s:-k"
-piece.bottomside.to_s # => "S:-K"
-piece.oppositeside.to_s # => "s:-k"
-piece.promote.to_s # => "S:+-K"
-piece.unpromote.to_s # => "S:-K"
-
-
-# Shogi (Japanese chess)'s promoted Pawn, Sente
-piece = Sashite::GAN.parse("S:+P")
-
-piece.abbr.to_s # => "+P"
-piece.style # => "S"
-piece.topside? # => false
-piece.bottomside? # => true
-piece.to_s # => "S:+P"
-piece.topside.to_s # => "s:+p"
-piece.bottomside.to_s # => "S:+P"
-piece.oppositeside.to_s # => "s:+p"
-piece.promote.to_s # => "S:+P"
-piece.unpromote.to_s # => "S:P"
-
-
-# Xiangqi (Chinese chess)'s General, Red
-piece = Sashite::GAN.parse("X:-G")
-
-piece.abbr.to_s # => "-G"
-piece.style # => "X"
-piece.topside? # => false
-piece.bottomside? # => true
-piece.to_s # => "X:-G"
-piece.topside.to_s # => "x:-g"
-piece.bottomside.to_s # => "X:-G"
-piece.oppositeside.to_s # => "x:-g"
-piece.promote.to_s # => "X:+-G"
-piece.unpromote.to_s # => "X:-G"
-
-
-# Xiangqi (Chinese chess)'s Flying General, Red
-piece = Sashite::GAN.parse("X:+-G")
-
-piece.abbr.to_s # => "+-G"
-piece.style # => "X"
-piece.topside? # => false
-piece.bottomside? # => true
-piece.to_s # => "X:+-G"
-piece.topside.to_s # => "x:+-g"
-piece.bottomside.to_s # => "X:+-G"
-piece.oppositeside.to_s # => "x:+-g"
-piece.promote.to_s # => "X:+-G"
-piece.unpromote.to_s # => "X:-G"
-
-
-# Dai Dai Shogi (huge Japanese chess)'s Phoenix, Sente
-piece = Sashite::GAN.parse("DAI_DAI_SHOGI:PH")
-
-piece.abbr.to_s # => "PH"
-piece.style # => "DAI_DAI_SHOGI"
-piece.topside? # => false
-piece.bottomside? # => true
-piece.to_s # => "DAI_DAI_SHOGI:PH"
-piece.topside.to_s # => "dai_dai_shogi:ph"
-piece.bottomside.to_s # => "DAI_DAI_SHOGI:PH"
-piece.oppositeside.to_s # => "dai_dai_shogi:ph"
-piece.promote.to_s # => "DAI_DAI_SHOGI:+PH"
-piece.unpromote.to_s # => "DAI_DAI_SHOGI:PH"
-
-
-# A random FOO chess variant's promoted Z piece, Bottom-side
-piece = Sashite::GAN.parse("FOO:+Z")
-
-piece.abbr.to_s # => "+Z"
-piece.style # => "FOO"
-piece.topside? # => false
-piece.bottomside? # => true
-piece.to_s # => "FOO:+Z"
-piece.topside.to_s # => "foo:+z"
-piece.bottomside.to_s # => "FOO:+Z"
-piece.oppositeside.to_s # => "foo:+z"
-piece.promote.to_s # => "FOO:+Z"
-piece.unpromote.to_s # => "FOO:Z"
+require "sashite/gan"
+
+# Parse a GAN string into an actor object
+actor = Sashite::Gan::Actor.parse("CHESS:K")
+# => #<Sashite::Gan::Actor:0x... @style="CHESS" @piece="K">
+
+# With piece modifiers
+enhanced_actor = Sashite::Gan::Actor.parse("SHOGI:+P")
+# => #<Sashite::Gan::Actor:0x... @style="SHOGI" @piece="+P">
+
+# Create directly with constructor
+actor = Sashite::Gan::Actor.new("CHESS", "K")
+enhanced_actor = Sashite::Gan::Actor.new("SHOGI", "+P")
+
+# Create with style and piece objects
+style = Sashite::Snn::Style.new("CHESS")
+piece = Pnn::Piece.new("K")
+actor = Sashite::Gan::Actor.new(style, piece)
+
+# Convenience method
+actor = Sashite::Gan.actor("CHESS", "K")
 ```
 
-## License
+### Converting to GAN String
+
+Convert an actor object back to its GAN string representation:
+
+```ruby
+actor = Sashite::Gan::Actor.parse("CHESS:K")
+actor.to_s
+# => "CHESS:K"
+
+enhanced_actor = Sashite::Gan::Actor.parse("SHOGI:+p'")
+enhanced_actor.to_s
+# => "SHOGI:+p'"
+```
+
+### Accessing Components
+
+Access the style and piece components of an actor:
+
+```ruby
+actor = Sashite::Gan::Actor.parse("CHESS:K")
+
+# Access as strings
+actor.style_name    # => "CHESS"
+actor.piece_name    # => "K"
+
+# Access as objects
+actor.style         # => #<Sashite::Snn::Style:0x... @identifier="CHESS">
+actor.piece         # => #<Pnn::Piece:0x... @letter="K">
+
+# Check player associations
+actor.style.first_player?   # => true
+actor.piece.uppercase?      # => true
+```
+
+## Casing Combinations and Player Association
+
+GAN allows all four combinations of case between style and piece identifiers to support dynamic ownership changes:
+
+```ruby
+# First player's style, first player's piece
+actor1 = Sashite::Gan::Actor.parse("CHESS:K")
+actor1.style.first_player?   # => true
+actor1.piece.uppercase?      # => true
+
+# First player's style, second player's piece (piece was captured and converted)
+actor2 = Sashite::Gan::Actor.parse("CHESS:k")
+actor2.style.first_player?   # => true
+actor2.piece.lowercase?      # => true
+
+# Second player's style, first player's piece (piece was captured and converted)
+actor3 = Sashite::Gan::Actor.parse("chess:K")
+actor3.style.second_player?  # => true
+actor3.piece.uppercase?      # => true
+
+# Second player's style, second player's piece
+actor4 = Sashite::Gan::Actor.parse("chess:k")
+actor4.style.second_player?  # => true
+actor4.piece.lowercase?      # => true
+```
+
+## Dynamic Ownership Changes
+
+While style assignment remains fixed throughout a game, piece ownership may change during gameplay:
+
+```ruby
+# Original piece owned by first player
+original = Sashite::Gan::Actor.parse("SHOGI:P")
+
+# After capture by second player (modifiers preserved by default)
+captured = original.change_piece_ownership
+captured.to_s # => "SHOGI:p"
+
+# Or create the captured version directly
+captured = Sashite::Gan::Actor.new(original.style, "p")
+
+# Example with enhanced piece - modifiers are preserved
+enhanced = Sashite::Gan::Actor.parse("SHOGI:+P")
+captured_enhanced = enhanced.change_piece_ownership
+captured_enhanced.to_s # => "SHOGI:+p" (modifiers preserved)
+
+# To remove modifiers explicitly (if game rules require it):
+bare_captured = enhanced.bare_piece.change_piece_ownership
+bare_captured.to_s # => "SHOGI:p" (modifiers removed)
+```
+
+## Traditional Same-Style Games
+
+In traditional games where both players use the same piece style:
+
+```ruby
+# Chess pieces
+white_king = Sashite::Gan::Actor.parse("CHESS:K")
+black_king = Sashite::Gan::Actor.parse("chess:k")
+
+white_queen = Sashite::Gan::Actor.parse("CHESS:Q")
+black_queen = Sashite::Gan::Actor.parse("chess:q")
+
+# Shogi pieces
+first_king = Sashite::Gan::Actor.parse("SHOGI:K")
+second_king = Sashite::Gan::Actor.parse("shogi:k")
+
+first_gold = Sashite::Gan::Actor.parse("SHOGI:G")
+second_gold = Sashite::Gan::Actor.parse("shogi:g")
+```
+
+## Cross-Style Games
+
+In games where players use different piece styles:
+
+```ruby
+# Chess vs Makruk
+chess_king = Sashite::Gan::Actor.parse("CHESS:K")
+makruk_king = Sashite::Gan::Actor.parse("makruk:k")
+
+chess_queen = Sashite::Gan::Actor.parse("CHESS:Q")
+makruk_queen = Sashite::Gan::Actor.parse("makruk:q")
+
+# Shogi vs Xiangqi
+shogi_king = Sashite::Gan::Actor.parse("SHOGI:K")
+xiangqi_general = Sashite::Gan::Actor.parse("xiangqi:g")
+
+shogi_gold = Sashite::Gan::Actor.parse("SHOGI:G")
+xiangqi_advisor = Sashite::Gan::Actor.parse("xiangqi:a")
+```
+
+## Pieces with States and Ownership Changes
+
+```ruby
+# Original enhanced piece
+original = Sashite::Gan::Actor.parse("CHESS:R'")
+
+# After capture (modifiers preserved by default)
+captured = original.change_piece_ownership
+captured.to_s # => "chess:R'"
+
+# If game rules require modifier removal during capture:
+captured_bare = original.bare_piece.change_piece_ownership
+captured_bare.to_s # => "chess:R"
+
+# Promoted shogi piece captured
+promoted_pawn = Sashite::Gan::Actor.parse("shogi:+p")
+captured_promoted = promoted_pawn.change_piece_ownership
+captured_promoted.to_s # => "SHOGI:+p" (modifiers preserved)
+
+# With explicit modifier removal:
+captured_demoted = promoted_pawn.bare_piece.change_piece_ownership
+captured_demoted.to_s # => "SHOGI:p"
+```
+
+## Collision Resolution
+
+GAN resolves naming conflicts between different styles:
+
+```ruby
+# All different actors despite similar piece types
+chess_rook = Sashite::Gan::Actor.parse("CHESS:R")
+shogi_rook = Sashite::Gan::Actor.parse("SHOGI:R")
+makruk_rook = Sashite::Gan::Actor.parse("MAKRUK:R")
+xiangqi_chariot = Sashite::Gan::Actor.parse("xiangqi:r")
+
+# They can all coexist in the same context
+pieces = [chess_rook, shogi_rook, makruk_rook, xiangqi_chariot]
+puts pieces.map(&:to_s)
+# => ["CHESS:R", "SHOGI:R", "MAKRUK:R", "xiangqi:r"]
+```
+
+## Advanced Usage
+
+### Working with Collections
+
+```ruby
+# Group actors by style
+actors = [
+  Sashite::Gan::Actor.parse("CHESS:K"),
+  Sashite::Gan::Actor.parse("CHESS:Q"),
+  Sashite::Gan::Actor.parse("shogi:k"),
+  Sashite::Gan::Actor.parse("shogi:g")
+]
+
+grouped = actors.group_by { |actor| actor.style_name.downcase }
+# => {"chess" => [...], "shogi" => [...]}
+
+# Filter by player
+first_player_actors = actors.select { |actor| actor.style.first_player? }
+second_player_actors = actors.select { |actor| actor.style.second_player? }
+
+# Find actors by piece type
+kings = actors.select { |actor| actor.piece_name.downcase == "k" }
+```
+
+### State Manipulation
+
+```ruby
+actor = Sashite::Gan::Actor.parse("SHOGI:P")
+
+# Enhance the piece
+enhanced = actor.enhance_piece
+enhanced.to_s # => "SHOGI:+P"
+
+# Add intermediate state
+intermediate = actor.set_piece_intermediate
+intermediate.to_s # => "SHOGI:P'"
+
+# Chain operations
+complex = actor.enhance_piece.set_piece_intermediate
+complex.to_s # => "SHOGI:+P'"
+
+# Remove all modifiers
+bare = complex.bare_piece
+bare.to_s # => "SHOGI:P"
+```
+
+### Validation
+
+All parsing automatically validates input according to the GAN specification:
+
+```ruby
+# Valid GAN strings
+Sashite::Gan::Actor.parse("CHESS:K")      # ✓
+Sashite::Gan::Actor.parse("shogi:+p")     # ✓
+Sashite::Gan::Actor.parse("XIANGQI:r'")   # ✓
+
+# Valid constructor calls
+Sashite::Gan::Actor.new("CHESS", "K")     # ✓
+Sashite::Gan::Actor.new("shogi", "+p")    # ✓
+
+# Convenience method
+Sashite::Gan.actor("MAKRUK", "Q") # ✓
+
+# Check validity
+Sashite::Gan.valid?("CHESS:K")            # => true
+Sashite::Gan.valid?("Chess:K")            # => false (mixed case in style)
+Sashite::Gan.valid?("CHESS")              # => false (missing piece)
+Sashite::Gan.valid?("")                   # => false (empty string)
+
+# Invalid GAN strings raise ArgumentError
+Sashite::Gan::Actor.parse("")             # ✗ ArgumentError
+Sashite::Gan::Actor.parse("Chess:K")      # ✗ ArgumentError (mixed case)
+Sashite::Gan::Actor.parse("CHESS")        # ✗ ArgumentError (missing piece)
+Sashite::Gan::Actor.parse("CHESS:++K")    # ✗ ArgumentError (invalid piece)
+```
+
+### Inspection and Debugging
+
+```ruby
+actor = Sashite::Gan::Actor.parse("SHOGI:+p'")
+
+# Get detailed information
+actor.inspect
+# => "#<Sashite::Gan::Actor:0x... style=\"SHOGI\" piece=\"+p'\">"
+
+# Check components
+actor.style_name     # => "SHOGI"
+actor.piece_name     # => "+p'"
+actor.piece.enhanced?     # => true
+actor.piece.intermediate? # => true
+```
+
+## API Reference
+
+### Module Methods
+
+- `Sashite::Gan.valid?(gan_string)` - Check if a string is valid GAN notation
+- `Sashite::Gan.actor(style, piece)` - Convenience method to create actors
+
+### Sashite::Gan::Actor Class Methods
+
+- `Sashite::Gan::Actor.parse(gan_string)` - Parse a GAN string into an actor object
+- `Sashite::Gan::Actor.new(style, piece)` - Create a new actor instance
+
+### Instance Methods
+
+#### Component Access
+- `#style` - Get the style object (Sashite::Snn::Style)
+- `#piece` - Get the piece object (Pnn::Piece)
+- `#style_name` - Get the style name as string
+- `#piece_name` - Get the piece name as string
+
+#### Piece State Manipulation
+- `#enhance_piece` - Create actor with enhanced piece
+- `#diminish_piece` - Create actor with diminished piece
+- `#set_piece_intermediate` - Create actor with intermediate piece state
+- `#bare_piece` - Create actor with piece without modifiers
+- `#change_piece_ownership` - Create actor with piece ownership flipped
+
+#### Conversion
+- `#to_s` - Convert to GAN string representation
+- `#inspect` - Detailed string representation for debugging
 
-The code is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+## Properties of GAN
+
+* **Rule-agnostic**: GAN does not encode game states, legality, validity, or game-specific conditions
+* **Unambiguous identification**: Different piece styles can coexist without naming conflicts
+* **Canonical representation**: Equivalent actors yield identical strings
+* **Cross-style support**: Enables games where pieces from multiple traditions may be present
+* **Dynamic ownership**: Supports games where piece ownership can change during gameplay
+* **Compositional architecture**: Built on independent SNN and PNN specifications
+
+## Constraints
+
+* GAN supports exactly **two players**
+* Players are distinguished through the combination of SNN and PNN casing
+* Style assignment to players remains **fixed throughout a game**
+* Piece ownership may change during gameplay through casing changes
+* Both style and piece identifiers must conform to their respective specifications
+
+## Use Cases
+
+GAN is particularly useful in the following scenarios:
+
+1. **Multi-style environments**: When positions or analyses involve pieces from multiple style traditions
+2. **Game engine development**: When implementing engines that need to distinguish between similar pieces from different styles while tracking ownership changes
+3. **Hybrid games**: When creating or analyzing positions from games that combine elements from different piece traditions
+4. **Database systems**: When storing game data that must avoid naming conflicts between similar pieces from different styles
+5. **Cross-style analysis**: When comparing or analyzing strategic elements across different piece traditions
+6. **Capture-conversion games**: When implementing games like shōgi where pieces change ownership and require clear ownership tracking
+
+## Dependencies
+
+This gem depends on:
+
+- [sashite-snn](https://github.com/sashite/snn.rb) (~> 1.0.0) - Style Name Notation implementation
+- [pnn](https://github.com/sashite/pnn.rb) (~> 2.0.0) - Piece Name Notation implementation
+
+## Specification
+
+- [GAN Specification](https://sashite.dev/documents/gan/1.0.0/)
+- [SNN Specification](https://sashite.dev/documents/snn/1.0.0/)
+- [PNN Specification](https://sashite.dev/documents/pnn/1.0.0/)
+
+## Documentation
+
+- [GAN Documentation](https://rubydoc.info/github/sashite/gan.rb/main)
+- [SNN Documentation](https://rubydoc.info/github/sashite/snn.rb/main)
+- [PNN Documentation](https://rubydoc.info/github/sashite/pnn.rb/main)
+
+## License
 
-## About Sashite
+The [gem](https://rubygems.org/gems/sashite-gan) is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
 
-This [gem](https://rubygems.org/gems/sashite-gan) is maintained by [Sashite](https://sashite.com/).
+## About Sashité
 
-With some [lines of code](https://github.com/sashite/), let's share the beauty of Chinese, Japanese and Western cultures through the game of chess!
+This project is maintained by [Sashité](https://sashite.com/) — promoting chess variants and sharing the beauty of Chinese, Japanese, and Western chess cultures.