sashite-gan 3.0.0 → 4.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 361cb6527615fdfe0c4246c3f5f603598af97a46e6be9ec0cc300d03651dcb4a
-  data.tar.gz: 50fea949d4a759c2a68792085e1457c16c49966adf075533eb2e5cd1da5f852a
+  metadata.gz: b5469e58632f24a93eea22a4dd6d48c27028f84a2137469164eae9684274a7af
+  data.tar.gz: fa8fe045e1f5ced019b9bdf33369bc457e94187d7703ed13c7189c040e430502
 SHA512:
-  metadata.gz: '0298e95b598a17d558f85072321ee9006470f83e83aa20fd58235ec5550df98e1ec20f594b715962d8a063f0757ba927c0093577eb9c3c98ec9dd9b5180cdb4a'
-  data.tar.gz: 705ad8e30abe365dedbe108d941625d6c06725d0507c2e853f622bfe9da992137109b9fd4c44a09162cfbe1aed5c1f7bb15c1689977b131123095d69897cbebf
+  metadata.gz: 91d7fbc665bce2be60a37921398dea166684efa68ce55e22fd740d7d85907599d8812a491dbd561b73c1bb8aa1c625d453590842adb3edfb86b686e69c1f8ed8
+  data.tar.gz: 7761db8067e89586009fe4c52f06e632e7c153c5a7f370c613abd3066691d3d9b3fe214f71db1de1988a4a0d02df1d841b03a70b9aadb49ad89dcf3b940ef8bd

data/README.md

@@ -9,13 +9,9 @@
 
 ## What is GAN?
 
-GAN (General Actor Notation) defines a consistent and rule-agnostic format for representing game actors in abstract strategy board games. Building upon Piece Name Notation (PNN), GAN eliminates ambiguity by associating each piece with its originating game, allowing for unambiguous gameplay application and cross-game distinctions.
+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:
-
-- Serializing game actors to GAN strings
-- Parsing GAN strings into their component parts
-- Validating GAN strings according to the specification
+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
 
@@ -32,144 +28,382 @@ gem install sashite-gan
 
 ## GAN Format
 
-A GAN record consists of a game identifier, followed by a colon, followed by a piece identifier that follows the PNN specification:
+A GAN record consists of a style identifier (SNN format), followed by a colon separator, followed by a piece identifier (PNN format):
 
 ```
-<game-id>:<piece-id>
+<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
 
-- `<game-id>` is a sequence of alphabetic characters identifying the game variant.
-- `:` is a literal colon character, serving as a separator.
-- `<piece-id>` is a piece representation following the PNN specification: `[<prefix>]<letter>[<suffix>]`.
+## Basic Usage
 
-The casing of the game identifier reflects the player:
+### Creating Actor Objects
 
-- **Uppercase** game identifiers (e.g., `CHESS:`) denote pieces belonging to the first player.
-- **Lowercase** game identifiers (e.g., `chess:`) denote pieces belonging to the second player.
+The primary interface is the `Sashite::Gan::Actor` class, which represents a game actor in GAN format:
 
-## Basic Usage
+```ruby
+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")
+```
+
+### 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
 
-### Parsing GAN Strings
+Access the style and piece components of an actor:
 
-Convert a GAN string into a structured Ruby hash:
+```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
-require "sashite-gan"
+# Original piece owned by first player
+original = Sashite::Gan::Actor.parse("SHOGI:P")
 
-# Basic actor
-result = Sashite::Gan.parse("CHESS:K")
-# => { game_id: "CHESS", letter: "K" }
+# After capture by second player (modifiers preserved by default)
+captured = original.change_piece_ownership
+captured.to_s # => "SHOGI:p"
 
-# With piece prefix
-result = Sashite::Gan.parse("SHOGI:+P")
-# => { game_id: "SHOGI", letter: "P", prefix: "+" }
+# Or create the captured version directly
+captured = Sashite::Gan::Actor.new(original.style, "p")
 
-# With piece suffix
-result = Sashite::Gan.parse("CHESS:K'")
-# => { game_id: "CHESS", letter: "K", suffix: "'" }
+# 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)
 
-# With both piece prefix and suffix
-result = Sashite::Gan.parse("SHOGI:+R'")
-# => { game_id: "SHOGI", letter: "R", prefix: "+", suffix: "'" }
+# 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)
 ```
 
-### Safe Parsing
+## Traditional Same-Style Games
 
-Parse a GAN string without raising exceptions:
+In traditional games where both players use the same piece style:
 
 ```ruby
-require "sashite-gan"
+# Chess pieces
+white_king = Sashite::Gan::Actor.parse("CHESS:K")
+black_king = Sashite::Gan::Actor.parse("chess:k")
 
-# Valid GAN string
-result = Sashite::Gan.safe_parse("CHESS:K'")
-# => { game_id: "CHESS", letter: "K", suffix: "'" }
+white_queen = Sashite::Gan::Actor.parse("CHESS:Q")
+black_queen = Sashite::Gan::Actor.parse("chess:q")
 
-# Invalid GAN string
-result = Sashite::Gan.safe_parse("invalid gan string")
-# => nil
+# 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")
 ```
 
-### Creating GAN Strings
+## Cross-Style Games
 
-Convert actor components into a GAN string:
+In games where players use different piece styles:
 
 ```ruby
-require "sashite-gan"
+# Chess vs Makruk
+chess_king = Sashite::Gan::Actor.parse("CHESS:K")
+makruk_king = Sashite::Gan::Actor.parse("makruk:k")
 
-# Basic actor
-Sashite::Gan.dump(game_id: "CHESS", letter: "K")
-# => "CHESS: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
 
-# With piece prefix
-Sashite::Gan.dump(game_id: "SHOGI", letter: "P", prefix: "+")
-# => "SHOGI:+P"
+```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'"
 
-# With piece suffix
-Sashite::Gan.dump(game_id: "CHESS", letter: "K", suffix: "'")
-# => "CHESS:K'"
+# Chain operations
+complex = actor.enhance_piece.set_piece_intermediate
+complex.to_s # => "SHOGI:+P'"
 
-# With both piece prefix and suffix
-Sashite::Gan.dump(game_id: "SHOGI", letter: "R", prefix: "+", suffix: "'")
-# => "SHOGI:+R'"
+# Remove all modifiers
+bare = complex.bare_piece
+bare.to_s # => "SHOGI:P"
 ```
 
 ### Validation
 
-Check if a string is valid GAN notation:
+All parsing automatically validates input according to the GAN specification:
 
 ```ruby
-require "sashite-gan"
+# 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)
+```
 
-Sashite::Gan.valid?("CHESS:K")      # => true
-Sashite::Gan.valid?("SHOGI:+P")     # => true
-Sashite::Gan.valid?("CHESS:K'")     # => true
-Sashite::Gan.valid?("chess:k")      # => true
+### Inspection and Debugging
 
-Sashite::Gan.valid?("")             # => false
-Sashite::Gan.valid?("CHESS:k")      # => false (mismatched casing)
-Sashite::Gan.valid?("CHESS::K")     # => false
-Sashite::Gan.valid?("CHESS-K")      # => false
+```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
 ```
 
-## Casing Rules
+## 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
+
+## 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
 
-The casing of the game identifier must match the piece letter casing:
+* 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
 
-- **Uppercase** game IDs must have **uppercase** piece letters for the first player
-- **Lowercase** game IDs must have **lowercase** piece letters for the second player
+## Use Cases
 
-This ensures consistency with the FEEN specification's third field.
+GAN is particularly useful in the following scenarios:
 
-## Examples
+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
 
-### Chess Pieces
+## Dependencies
 
-| PNN   | GAN (First Player) | GAN (Second Player) |
-|-------|--------------------|--------------------|
-| `K'`  | `CHESS:K'`         | `chess:k'`         |
-| `Q`   | `CHESS:Q`          | `chess:q`          |
-| `R`   | `CHESS:R`          | `chess:r`          |
-| `B`   | `CHESS:B`          | `chess:b`          |
-| `N`   | `CHESS:N`          | `chess:n`          |
-| `P`   | `CHESS:P`          | `chess:p`          |
+This gem depends on:
 
-### Disambiguated Collisions
+- [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
 
-These examples show how GAN resolves ambiguities between pieces that would have identical PNN representation:
+## Specification
 
-| Description | PNN   | GAN                 |
-|-------------|-------|---------------------|
-| Chess Rook (white) | `R`   | `CHESS:R`           |
-| Makruk Rook (white) | `R`   | `MAKRUK:R`          |
-| Shogi Rook (sente) | `R`   | `SHOGI:R`           |
-| Promoted Shogi Rook (sente) | `+R`  | `SHOGI:+R`          |
+- [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
 
-- [Official GAN Specification](https://sashite.dev/documents/gan/1.0.0/)
-- [API Documentation](https://rubydoc.info/github/sashite/gan.rb/main)
+- [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
 

data/lib/sashite/gan/actor.rb

@@ -0,0 +1,185 @@
+# frozen_string_literal: true
+
+module Sashite
+  module Gan
+    # Represents a game actor in GAN format
+    #
+    # An actor combines a style identifier (SNN format) with a piece identifier (PNN format)
+    # to create an unambiguous representation of a game piece within its style context.
+    # The casing of both components determines player association and piece ownership:
+    # - Style casing determines which player uses that style tradition (fixed per game)
+    # - Piece casing determines current piece ownership (may change during gameplay)
+    #
+    # @example
+    #   # Traditional same-style game
+    #   white_king = Sashite::Gan::Actor.new("CHESS", "K")  # First player's chess king
+    #   black_king = Sashite::Gan::Actor.new("chess", "k")  # Second player's chess king
+    #
+    #   # Cross-style game
+    #   chess_king = Sashite::Gan::Actor.new("CHESS", "K")   # First player uses chess
+    #   shogi_king = Sashite::Gan::Actor.new("shogi", "k")   # Second player uses shogi
+    #
+    #   # Dynamic ownership (piece captured and converted)
+    #   captured = Sashite::Gan::Actor.new("CHESS", "k")     # Chess piece owned by second player
+    class Actor
+      # @return [Sashite::Snn::Style] The style component
+      attr_reader :style
+
+      # @return [Pnn::Piece] The piece component
+      attr_reader :piece
+
+      # Create a new actor instance
+      #
+      # @param style [String, Sashite::Snn::Style] The style identifier or style object
+      # @param piece [String, Pnn::Piece] The piece identifier or piece object
+      # @raise [ArgumentError] if the parameters are invalid
+      #
+      # @example
+      #   # With strings
+      #   actor = Sashite::Gan::Actor.new("CHESS", "K")
+      #
+      #   # With objects
+      #   style = Sashite::Snn::Style.new("CHESS")
+      #   piece = Pnn::Piece.new("K")
+      #   actor = Sashite::Gan::Actor.new(style, piece)
+      def initialize(style, piece)
+        @style = style.is_a?(Snn::Style) ? style : Snn::Style.new(style.to_s)
+        @piece = piece.is_a?(Pnn::Piece) ? piece : Pnn::Piece.parse(piece.to_s)
+
+        freeze
+      end
+
+      # Parse a GAN string into an actor object
+      #
+      # @param gan_string [String] GAN notation string
+      # @return [Actor] new actor instance
+      # @raise [ArgumentError] if the GAN string is invalid
+      #
+      # @example
+      #   actor = Sashite::Gan::Actor.parse("CHESS:K")
+      #   # => #<Sashite::Gan::Actor:0x... style="CHESS" piece="K">
+      #
+      #   enhanced = Sashite::Gan::Actor.parse("SHOGI:+p'")
+      #   # => #<Sashite::Gan::Actor:0x... style="SHOGI" piece="+p'">
+      def self.parse(gan_string)
+        style_string, piece_string = Gan.parse_components(gan_string)
+        new(style_string, piece_string)
+      end
+
+      # Convert the actor to its GAN string representation
+      #
+      # @return [String] GAN notation string
+      #
+      # @example
+      #   actor.to_s  # => "CHESS:K"
+      def to_s
+        "#{style}:#{piece}"
+      end
+
+      # Get the style name as a string
+      #
+      # @return [String] The style identifier string
+      #
+      # @example
+      #   actor.style_name  # => "CHESS"
+      def style_name
+        style.to_s
+      end
+
+      # Get the piece name as a string
+      #
+      # @return [String] The piece identifier string
+      #
+      # @example
+      #   actor.piece_name  # => "K"
+      def piece_name
+        piece.to_s
+      end
+
+      # Create a new actor with an enhanced piece
+      #
+      # @return [Actor] new actor instance with enhanced piece
+      #
+      # @example
+      #   actor.enhance_piece  # SHOGI:P => SHOGI:+P
+      def enhance_piece
+        self.class.new(style, piece.enhance)
+      end
+
+      # Create a new actor with a diminished piece
+      #
+      # @return [Actor] new actor instance with diminished piece
+      #
+      # @example
+      #   actor.diminish_piece  # CHESS:R => CHESS:-R
+      def diminish_piece
+        self.class.new(style, piece.diminish)
+      end
+
+      # Create a new actor with an intermediate piece state
+      #
+      # @return [Actor] new actor instance with intermediate piece
+      #
+      # @example
+      #   actor.set_piece_intermediate  # CHESS:R => CHESS:R'
+      def set_piece_intermediate
+        self.class.new(style, piece.intermediate)
+      end
+
+      # Create a new actor with a piece without modifiers
+      #
+      # @return [Actor] new actor instance with bare piece
+      #
+      # @example
+      #   actor.bare_piece  # SHOGI:+P' => SHOGI:P
+      def bare_piece
+        self.class.new(style, piece.bare)
+      end
+
+      # Create a new actor with piece ownership flipped
+      #
+      # Changes the piece ownership (case) while keeping the style unchanged.
+      # This method is rule-agnostic and preserves all piece modifiers.
+      # If modifier removal is needed, it should be done explicitly.
+      #
+      # @return [Actor] new actor instance with ownership changed
+      #
+      # @example
+      #   actor.change_piece_ownership  # SHOGI:P => SHOGI:p
+      #   enhanced.change_piece_ownership  # SHOGI:+P => SHOGI:+p (modifiers preserved)
+      #
+      #   # To remove modifiers explicitly:
+      #   actor.bare_piece.change_piece_ownership  # SHOGI:+P => SHOGI:p
+      #   # or
+      #   actor.change_piece_ownership.bare_piece  # SHOGI:+P => SHOGI:p
+      def change_piece_ownership
+        self.class.new(style, piece.flip)
+      end
+
+      # Custom equality comparison
+      #
+      # @param other [Object] The object to compare with
+      # @return [Boolean] true if both objects are Actor instances with the same components
+      def ==(other)
+        other.is_a?(Actor) && style == other.style && piece == other.piece
+      end
+
+      # Alias for equality comparison
+      alias eql? ==
+
+      # Hash code for use in hashes and sets
+      #
+      # @return [Integer] The hash code
+      def hash
+        [self.class, style, piece].hash
+      end
+
+      # String representation for debugging
+      #
+      # @return [String] A detailed string representation
+      def inspect
+        "#<#{self.class}:0x#{object_id.to_s(16)} style=#{style_name.inspect} piece=#{piece_name.inspect}>"
+      end
+    end
+  end
+end

data/lib/sashite/gan.rb

@@ -1,76 +1,88 @@
 # frozen_string_literal: true
 
-require_relative File.join("gan", "dumper")
-require_relative File.join("gan", "parser")
-require_relative File.join("gan", "validator")
+require "sashite/snn"
+require "pnn"
+require_relative "gan/actor"
 
 module Sashite
-  # This module provides a Ruby interface for serialization and
-  # deserialization of game actors in GAN format.
+  # General Actor Notation (GAN) module
   #
-  # GAN (General Actor Notation) defines a consistent and rule-agnostic
-  # format for representing game actors in abstract strategy board games,
-  # building upon Piece Name Notation (PNN).
+  # GAN provides a consistent and rule-agnostic format for identifying game actors
+  # in abstract strategy board games. It combines Style Name Notation (SNN) with
+  # Piece Name Notation (PNN) to create unambiguous actor identification that
+  # eliminates collision problems when multiple piece styles are present.
   #
-  # @see https://sashite.dev/documents/gan/1.0.0/
+  # @see https://sashite.dev/documents/gan/1.0.0/ GAN Specification v1.0.0
   module Gan
-    # Serializes an actor into a GAN string.
-    #
-    # @param game_id [String] The game identifier
-    # @param piece_params [Hash] Piece parameters as accepted by Pnn.dump
-    # @option piece_params [String] :letter The single ASCII letter identifier (required)
-    # @option piece_params [String, nil] :prefix Optional prefix modifier for the piece ("+", "-")
-    # @option piece_params [String, nil] :suffix Optional suffix modifier for the piece ("'")
-    # @return [String] GAN notation string
-    # @raise [ArgumentError] If any parameter is invalid
-    # @example
-    #   Sashite::Gan.dump(game_id: "CHESS", letter: "K", suffix: "'")
-    #   # => "CHESS:K'"
-    def self.dump(game_id:, **piece_params)
-      Dumper.dump(game_id:, **piece_params)
-    end
+    # GAN validation regular expression
+    # Matches: <snn>:<pnn> where snn and pnn follow their respective specifications
+    VALIDATION_REGEX = /\A([A-Z][A-Z0-9]*|[a-z][a-z0-9]*):[-+]?[a-zA-Z]'?\z/
 
-    # Parses a GAN string into its component parts.
+    # Check if a string is valid GAN notation
+    #
+    # @param gan_string [String] The string to validate
+    # @return [Boolean] true if the string is valid GAN notation, false otherwise
     #
-    # @param gan_string [String] GAN notation string
-    # @return [Hash] Hash containing the parsed actor data with the following keys:
-    #   - :game_id [String] - The game identifier
-    #   - :letter [String] - The base letter identifier
-    #   - :prefix [String, nil] - The prefix modifier if present
-    #   - :suffix [String, nil] - The suffix modifier if present
-    # @raise [ArgumentError] If the GAN string is invalid
     # @example
-    #   Sashite::Gan.parse("CHESS:K'")
-    #   # => { game_id: "CHESS", letter: "K", suffix: "'" }
-    def self.parse(gan_string)
-      Parser.parse(gan_string)
+    #   Sashite::Gan.valid?("CHESS:K")      # => true
+    #   Sashite::Gan.valid?("shogi:+p'")    # => true
+    #   Sashite::Gan.valid?("Chess:K")      # => false (mixed case in style)
+    #   Sashite::Gan.valid?("CHESS")        # => false (missing piece)
+    #   Sashite::Gan.valid?("")             # => false (empty string)
+    def self.valid?(gan_string)
+      return false unless gan_string.is_a?(String)
+      return false if gan_string.empty?
+
+      # Quick regex check first
+      return false unless VALIDATION_REGEX.match?(gan_string)
+
+      # Split and validate components individually for more precise validation
+      parts = gan_string.split(":", 2)
+      return false unless parts.length == 2
+
+      style_part, piece_part = parts
+
+      # Validate SNN and PNN components using their respective libraries
+      Snn.valid?(style_part) && Pnn.valid?(piece_part)
     end
 
-    # Safely parses a GAN string into its component parts without raising exceptions.
+    # Convenience method to create an actor object
+    #
+    # @param style [String, Sashite::Snn::Style] The style identifier or style object
+    # @param piece [String, Pnn::Piece] The piece identifier or piece object
+    # @return [Sashite::Gan::Actor] A new actor object
+    # @raise [ArgumentError] if the parameters are invalid
     #
-    # @param gan_string [String] GAN notation string
-    # @return [Hash, nil] Hash containing the parsed actor data or nil if parsing fails
     # @example
-    #   # Valid GAN string
-    #   Sashite::Gan.safe_parse("CHESS:K'")
-    #   # => { game_id: "CHESS", letter: "K", suffix: "'" }
+    #   actor = Sashite::Gan.actor("CHESS", "K")
+    #   # => #<Sashite::Gan::Actor:0x... style="CHESS" piece="K">
     #
-    #   # Invalid GAN string
-    #   Sashite::Gan.safe_parse("invalid")
-    #   # => nil
-    def self.safe_parse(gan_string)
-      Parser.safe_parse(gan_string)
+    #   # With objects
+    #   style = Sashite::Snn::Style.new("CHESS")
+    #   piece = Pnn::Piece.new("K")
+    #   actor = Sashite::Gan.actor(style, piece)
+    def self.actor(style, piece)
+      Actor.new(style, piece)
     end
 
-    # Validates if the given string is a valid GAN string
+    # Parse a GAN string into component parts
+    #
+    # @param gan_string [String] The GAN string to parse
+    # @return [Array<String>] An array containing [style_string, piece_string]
+    # @raise [ArgumentError] if the string is invalid GAN notation
     #
-    # @param gan_string [String] GAN string to validate
-    # @return [Boolean] True if the string is a valid GAN string
     # @example
-    #   Sashite::Gan.valid?("CHESS:K'") # => true
-    #   Sashite::Gan.valid?("invalid") # => false
-    def self.valid?(gan_string)
-      Validator.valid?(gan_string)
+    #   Sashite::Gan.parse_components("CHESS:K")
+    #   # => ["CHESS", "K"]
+    #
+    #   Sashite::Gan.parse_components("shogi:+p'")
+    #   # => ["shogi", "+p'"]
+    #
+    # @api private
+    def self.parse_components(gan_string)
+      raise ArgumentError, "Invalid GAN format: #{gan_string.inspect}" unless valid?(gan_string)
+
+      gan_string.split(":", 2)
     end
   end
 end

data/lib/sashite-gan.rb

@@ -1,7 +1,18 @@
 # frozen_string_literal: true
 
-# Sashité namespace
+# Sashité namespace for board game notation libraries
 module Sashite
+  # General Actor Notation (GAN) implementation for Ruby
+  #
+  # GAN 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.
+  #
+  # @see https://sashite.dev/documents/gan/1.0.0/ GAN Specification v1.0.0
+  # @author Sashité
+  # @since 1.0.0
 end
 
 require_relative "sashite/gan"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: sashite-gan
 version: !ruby/object:Gem::Version
-  version: 3.0.0
+  version: 4.0.0
 platform: ruby
 authors:
 - Cyril Kato
@@ -15,14 +15,28 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.1.0
+        version: 2.0.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.1.0
+        version: 2.0.0
+- !ruby/object:Gem::Dependency
+  name: sashite-snn
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.0.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.0.0
 description: A Ruby interface for serialization and deserialization of game actors
   in GAN format. GAN is a consistent and rule-agnostic format for representing game
   actors in abstract strategy board games, providing a standardized way to identify
@@ -36,9 +50,7 @@ files:
 - README.md
 - lib/sashite-gan.rb
 - lib/sashite/gan.rb
-- lib/sashite/gan/dumper.rb
-- lib/sashite/gan/parser.rb
-- lib/sashite/gan/validator.rb
+- lib/sashite/gan/actor.rb
 homepage: https://github.com/sashite/gan.rb
 licenses:
 - MIT

data/lib/sashite/gan/dumper.rb

@@ -1,94 +0,0 @@
-# frozen_string_literal: true
-
-require "pnn"
-
-module Sashite
-  module Gan
-    # Serializes actor components into GAN (General Actor Notation) strings.
-    #
-    # The dumper transforms piece data and game identifiers into properly
-    # formatted GAN strings, ensuring consistency between game ID casing
-    # and piece letter casing according to the GAN specification.
-    #
-    # According to the specification, game IDs must be either all uppercase
-    # or all lowercase, and their casing must match the casing of the piece letter.
-    class Dumper
-      # Pattern for validating game identifiers - must be all uppercase OR all lowercase
-      GAME_ID_PATTERN = /\A([A-Z]+|[a-z]+)\z/
-
-      # Error message templates
-      INVALID_GAME_ID_ERROR = "Game ID must be a non-empty string containing only ASCII letters and must be either all uppercase or all lowercase: %s"
-      CASING_MISMATCH_ERROR = "Game ID casing (%s) must match piece letter casing (%s)"
-
-      # Serializes actor components into a GAN string
-      #
-      # @param game_id [String] The game identifier (e.g., "CHESS", "shogi")
-      # @param piece_params [Hash] Piece parameters as accepted by Pnn.dump:
-      #   @option piece_params [String] :letter The single ASCII letter identifier (required)
-      #   @option piece_params [String, nil] :prefix Optional prefix modifier for the piece ("+", "-")
-      #   @option piece_params [String, nil] :suffix Optional suffix modifier for the piece ("'")
-      # @return [String] A properly formatted GAN notation string (e.g., "CHESS:K'")
-      # @raise [ArgumentError] If game_id is invalid or casing is inconsistent with piece letter
-      # @example Create a GAN string for a white chess king with castling rights
-      #   Dumper.dump(game_id: "CHESS", letter: "K", suffix: "'")
-      #   # => "CHESS:K'"
-      # @example Create a GAN string for a promoted shogi pawn
-      #   Dumper.dump(game_id: "SHOGI", letter: "P", prefix: "+")
-      #   # => "SHOGI:+P"
-      def self.dump(game_id:, **piece_params)
-        game_id = String(game_id)
-        validate_game_id!(game_id)
-
-        # Build the piece string using the PNN gem
-        pnn_string = ::Pnn.dump(**piece_params)
-
-        # Verify casing consistency
-        validate_casing_consistency!(game_id, pnn_string)
-
-        "#{game_id}:#{pnn_string}"
-      end
-
-      # @api private
-      # Validates that the game_id contains only ASCII letters
-      #
-      # @param game_id [String] The game identifier to validate
-      # @return [void]
-      # @raise [ArgumentError] If game_id contains non-letter characters
-      def self.validate_game_id!(game_id)
-        return if game_id.match?(GAME_ID_PATTERN)
-
-        raise ::ArgumentError, format(INVALID_GAME_ID_ERROR, game_id)
-      end
-      private_class_method :validate_game_id!
-
-      # @api private
-      # Validates that the casing of the game_id is consistent with the piece letter
-      #
-      # According to GAN specification, if game_id is uppercase, piece letter must be uppercase,
-      # and if game_id is lowercase, piece letter must be lowercase.
-      #
-      # @param game_id [String] The game identifier
-      # @param pnn_string [String] The PNN string
-      # @return [void]
-      # @raise [ArgumentError] If casing is inconsistent
-      def self.validate_casing_consistency!(game_id, pnn_string)
-        return if casing_consistent?(game_id, pnn_string)
-
-        raise ::ArgumentError, format(CASING_MISMATCH_ERROR, game_id, pnn_string)
-      end
-      private_class_method :validate_casing_consistency!
-
-      # @api private
-      # Verifies that the casing of the game_id matches the casing of the piece letter
-      #
-      # @param game_id [String] The game identifier
-      # @param pnn_string [String] The PNN string
-      # @return [Boolean] True if casing is consistent
-      def self.casing_consistent?(game_id, pnn_string)
-        # Both must be uppercase or both must be lowercase
-        (game_id == game_id.upcase) == (pnn_string == pnn_string.upcase)
-      end
-      private_class_method :casing_consistent?
-    end
-  end
-end

data/lib/sashite/gan/parser.rb

@@ -1,58 +0,0 @@
-# frozen_string_literal: true
-
-require "pnn"
-
-module Sashite
-  module Gan
-    # Parses GAN strings into their component parts
-    class Parser
-      # GAN regex pattern for parsing
-      PATTERN = /\A(?<game_id>[a-zA-Z]+):(?<pnn_part>[-+]?[a-zA-Z][']?)\z/
-
-      # Parse a GAN string into its components
-      #
-      # @param gan_string [String] The GAN string to parse
-      # @return [Hash] Hash containing the parsed components
-      # @raise [ArgumentError] If the GAN string is invalid
-      def self.parse(gan_string)
-        gan_string = String(gan_string)
-
-        matches = PATTERN.match(gan_string)
-        raise ArgumentError, "Invalid GAN string: #{gan_string}" if matches.nil?
-
-        game_id = matches[:game_id]
-        pnn_part = matches[:pnn_part]
-
-        # Parse the PNN part using the PNN gem
-        pnn_result = Pnn.parse(pnn_part)
-
-        # Verify casing consistency
-        unless casing_consistent?(game_id, pnn_result[:letter])
-          raise ArgumentError, "Game ID casing (#{game_id}) must match piece letter casing (#{pnn_result[:letter]})"
-        end
-
-        # Merge the game_id with the piece parameters for a flatter structure
-        { game_id: game_id }.merge(pnn_result)
-      end
-
-      # Safely parse a GAN string without raising exceptions
-      #
-      # @param gan_string [String] The GAN string to parse
-      # @return [Hash, nil] Hash containing the parsed components or nil if invalid
-      def self.safe_parse(gan_string)
-        parse(gan_string)
-      rescue ArgumentError
-        nil
-      end
-
-      # Verifies that the casing of the game_id matches the casing of the piece letter
-      #
-      # @param game_id [String] The game identifier
-      # @param letter [String] The piece letter
-      # @return [Boolean] True if casing is consistent
-      def self.casing_consistent?(game_id, letter)
-        (game_id == game_id.upcase) == (letter == letter.upcase)
-      end
-    end
-  end
-end

data/lib/sashite/gan/validator.rb

@@ -1,23 +0,0 @@
-# frozen_string_literal: true
-
-require "pnn"
-
-module Sashite
-  module Gan
-    # Validates GAN strings
-    class Validator
-      # GAN regex pattern for validation
-      PATTERN = /\A([A-Z]+:[-+]?[A-Z][']?|[a-z]+:[-+]?[a-z][']?)\z/
-
-      # Validates if the given string is a valid GAN string
-      #
-      # @param gan_string [String] The GAN string to validate
-      # @return [Boolean] True if the string is a valid GAN string
-      def self.valid?(gan_string)
-        return false unless gan_string.is_a?(String)
-
-        PATTERN.match?(gan_string)
-      end
-    end
-  end
-end