sashite-gan 2.2.0 → 3.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7ebee55a8937fadf15f9b2a4bcf03e672b96f832cd01482be1c0374a1314fb21
-  data.tar.gz: 3f092d4f12e0b6a2e20d8981c76fad2be914a886a37ca95cb4d3437b9f18e67a
+  metadata.gz: 361cb6527615fdfe0c4246c3f5f603598af97a46e6be9ec0cc300d03651dcb4a
+  data.tar.gz: 50fea949d4a759c2a68792085e1457c16c49966adf075533eb2e5cd1da5f852a
 SHA512:
-  metadata.gz: 472262b63c2401d6392dd65b1e39ca0600515b201cce85fcbbbacf8d245256b978c143d7313c23495cc143cf42c79a6631690a0f0eab51c0a9bf8a78cd64a259
-  data.tar.gz: a5afb55bc54194750b0406646e0074a08f9dd5952f3c743c411a94b1cfa183aa263e7cb7b393fffce542ce5c2adf385f82ac5322e4ddfbfeb843d4a9ae0c063d
+  metadata.gz: '0298e95b598a17d558f85072321ee9006470f83e83aa20fd58235ec5550df98e1ec20f594b715962d8a063f0757ba927c0093577eb9c3c98ec9dd9b5180cdb4a'
+  data.tar.gz: 705ad8e30abe365dedbe108d941625d6c06725d0507c2e853f622bfe9da992137109b9fd4c44a09162cfbe1aed5c1f7bb15c1689977b131123095d69897cbebf

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,180 @@
-# 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 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.
+
+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
 
 ## 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 game identifier, followed by a colon, followed by a piece identifier that follows the PNN specification:
+
+```
+<game-id>:<piece-id>
+```
+
+Where:
 
-   ```ruby
-   gem 'sashite-gan'
-   ```
+- `<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>]`.
 
-2. Run `bundle install`
+The casing of the game identifier reflects the player:
 
-## Usage
+- **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.
+
+## Basic Usage
+
+### Parsing GAN Strings
+
+Convert a GAN string into a structured Ruby hash:
 
 ```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"
+
+# Basic actor
+result = Sashite::Gan.parse("CHESS:K")
+# => { game_id: "CHESS", letter: "K" }
+
+# With piece prefix
+result = Sashite::Gan.parse("SHOGI:+P")
+# => { game_id: "SHOGI", letter: "P", prefix: "+" }
+
+# With piece suffix
+result = Sashite::Gan.parse("CHESS:K'")
+# => { game_id: "CHESS", letter: "K", suffix: "'" }
+
+# With both piece prefix and suffix
+result = Sashite::Gan.parse("SHOGI:+R'")
+# => { game_id: "SHOGI", letter: "R", prefix: "+", suffix: "'" }
 ```
 
-## License
+### Safe Parsing
+
+Parse a GAN string without raising exceptions:
+
+```ruby
+require "sashite-gan"
+
+# Valid GAN string
+result = Sashite::Gan.safe_parse("CHESS:K'")
+# => { game_id: "CHESS", letter: "K", suffix: "'" }
+
+# Invalid GAN string
+result = Sashite::Gan.safe_parse("invalid gan string")
+# => nil
+```
 
-The code is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+### Creating GAN Strings
+
+Convert actor components into a GAN string:
+
+```ruby
+require "sashite-gan"
+
+# Basic actor
+Sashite::Gan.dump(game_id: "CHESS", letter: "K")
+# => "CHESS:K"
+
+# With piece prefix
+Sashite::Gan.dump(game_id: "SHOGI", letter: "P", prefix: "+")
+# => "SHOGI:+P"
+
+# With piece suffix
+Sashite::Gan.dump(game_id: "CHESS", letter: "K", suffix: "'")
+# => "CHESS:K'"
+
+# With both piece prefix and suffix
+Sashite::Gan.dump(game_id: "SHOGI", letter: "R", prefix: "+", suffix: "'")
+# => "SHOGI:+R'"
+```
+
+### Validation
+
+Check if a string is valid GAN notation:
+
+```ruby
+require "sashite-gan"
+
+Sashite::Gan.valid?("CHESS:K")      # => true
+Sashite::Gan.valid?("SHOGI:+P")     # => true
+Sashite::Gan.valid?("CHESS:K'")     # => true
+Sashite::Gan.valid?("chess:k")      # => true
+
+Sashite::Gan.valid?("")             # => false
+Sashite::Gan.valid?("CHESS:k")      # => false (mismatched casing)
+Sashite::Gan.valid?("CHESS::K")     # => false
+Sashite::Gan.valid?("CHESS-K")      # => false
+```
+
+## Casing Rules
+
+The casing of the game identifier must match the piece letter casing:
+
+- **Uppercase** game IDs must have **uppercase** piece letters for the first player
+- **Lowercase** game IDs must have **lowercase** piece letters for the second player
+
+This ensures consistency with the FEEN specification's third field.
+
+## Examples
+
+### Chess Pieces
+
+| 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`          |
+
+### Disambiguated Collisions
+
+These examples show how GAN resolves ambiguities between pieces that would have identical PNN representation:
+
+| 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`          |
+
+## Documentation
+
+- [Official GAN Specification](https://sashite.dev/documents/gan/1.0.0/)
+- [API Documentation](https://rubydoc.info/github/sashite/gan.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.

data/lib/sashite/gan/dumper.rb

@@ -0,0 +1,94 @@
+# 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,30 +1,57 @@
 # frozen_string_literal: true
 
-require_relative 'error'
-require_relative 'piece'
+require "pnn"
 
 module Sashite
-  module GAN
-    # The notation parser.
-    module Parser
-      def self.call(arg)
-        raise Error::String, "Invalid: #{arg.inspect}" unless valid?(arg)
-
-        style, abbr = arg.split(SEPARATOR_CHAR)
-
-        Piece.new(
-          abbr.delete('-+'),
-          is_king: abbr.include?('-'),
-          is_promoted: abbr.include?('+'),
-          is_topside: style.downcase.eql?(style),
-          style: style
-        )
+  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
 
-      def self.valid?(arg)
-        raise ::TypeError, arg.class.inspect unless arg.is_a?(::String)
+      # 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
 
-        arg.match?(/\A([a-z_]+:\+?-?[a-z]{1,2}|[A-Z_]+:\+?-?[A-Z]{1,2})\z/)
+      # 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

data/lib/sashite/gan/validator.rb

@@ -0,0 +1,23 @@
+# 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

data/lib/sashite/gan.rb

@@ -1,49 +1,76 @@
 # frozen_string_literal: true
 
-require_relative 'gan/parser'
+require_relative File.join("gan", "dumper")
+require_relative File.join("gan", "parser")
+require_relative File.join("gan", "validator")
 
 module Sashite
-  # The GAN (General Actor Notation) module.
+  # This module provides a Ruby interface for serialization and
+  # deserialization of game actors in GAN format.
   #
-  # @see https://developer.sashite.com/specs/general-actor-notation
-  module GAN
-    SEPARATOR_CHAR = ':'
-
-    # Parse the GAN string into a Ruby object structure and return it.
-    #
-    # @example Chess (Western chess)'s Rook, White
-    #   GAN.parse("C:R")
-    #
-    # @example Chess (Western chess)'s King, Black
-    #   GAN.parse("c:-k")
-    #
-    # @example Makruk (Thai chess)'s Bishop, White
-    #   GAN.parse("M:B")
-    #
-    # @example Shogi (Japanese chess)'s King, Gote
-    #   GAN.parse("s:-k")
-    #
-    # @example Shogi (Japanese chess)'s King, Sente
-    #   GAN.parse("S:-K")
-    #
-    # @example Shogi (Japanese chess)'s promoted Pawn, Sente
-    #   GAN.parse("S:+P")
+  # 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).
+  #
+  # @see https://sashite.dev/documents/gan/1.0.0/
+  module Gan
+    # Serializes an actor into a GAN string.
     #
-    # @example Xiangqi (Chinese chess)'s General, Red
-    #   GAN.parse("X:-G")
+    # @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
+
+    # Parses a GAN string into its component parts.
     #
-    # @example Xiangqi (Chinese chess)'s Flying General, Red
-    #   GAN.parse("X:+-G")
+    # @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)
+    end
+
+    # Safely parses a GAN string into its component parts without raising exceptions.
     #
-    # @example Dai Dai Shogi (huge Japanese chess)'s Phoenix, Sente
-    #   GAN.parse("DAI_DAI_SHOGI:PH")
+    # @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: "'" }
     #
-    # @example Another FOO chess variant's promoted Z piece, Bottom-side
-    #   GAN.parse("FOO:+Z")
+    #   # Invalid GAN string
+    #   Sashite::Gan.safe_parse("invalid")
+    #   # => nil
+    def self.safe_parse(gan_string)
+      Parser.safe_parse(gan_string)
+    end
+
+    # Validates if the given string is a valid GAN string
     #
-    # @return [Piece] An instance of the piece.
-    def self.parse(string)
-      Parser.call(string)
+    # @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)
     end
   end
 end

data/lib/sashite-gan.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
-# Sashite namespace
-module Sashite; end
+# Sashité namespace
+module Sashite
+end
 
-require_relative 'sashite/gan'
+require_relative "sashite/gan"

metadata

@@ -1,114 +1,32 @@
 --- !ruby/object:Gem::Specification
 name: sashite-gan
 version: !ruby/object:Gem::Version
-  version: 2.2.0
+  version: 3.0.0
 platform: ruby
 authors:
 - Cyril Kato
-autorequire: 
 bindir: bin
 cert_chain: []
-date: 2020-08-07 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
-  name: brutal
+  name: pnn
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
+        version: 1.1.0
+  type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
-- !ruby/object:Gem::Dependency
-  name: bundler
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-- !ruby/object:Gem::Dependency
-  name: rake
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-- !ruby/object:Gem::Dependency
-  name: rubocop-performance
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-- !ruby/object:Gem::Dependency
-  name: rubocop-thread_safety
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-- !ruby/object:Gem::Dependency
-  name: simplecov
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-- !ruby/object:Gem::Dependency
-  name: yard
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-description: A Ruby interface for data serialization in GAN format ♟️
+        version: 1.1.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
+  pieces with their originating game.
 email: contact@cyril.email
 executables: []
 extensions: []
@@ -118,22 +36,19 @@ files:
 - README.md
 - lib/sashite-gan.rb
 - lib/sashite/gan.rb
-- lib/sashite/gan/abbr.rb
-- lib/sashite/gan/error.rb
-- lib/sashite/gan/error/string.rb
-- lib/sashite/gan/error/style.rb
-- lib/sashite/gan/error/type.rb
+- lib/sashite/gan/dumper.rb
 - lib/sashite/gan/parser.rb
-- lib/sashite/gan/piece.rb
-homepage: https://developer.sashite.com/specs/general-actor-notation
+- lib/sashite/gan/validator.rb
+homepage: https://github.com/sashite/gan.rb
 licenses:
 - MIT
 metadata:
   bug_tracker_uri: https://github.com/sashite/gan.rb/issues
-  documentation_uri: https://rubydoc.info/gems/sashite-gan/index
+  documentation_uri: https://rubydoc.info/github/sashite/gan.rb/main
+  homepage_uri: https://github.com/sashite/gan.rb
   source_code_uri: https://github.com/sashite/gan.rb
-  wiki_uri: https://github.com/sashite/gan.rb/wiki
-post_install_message: 
+  specification_uri: https://sashite.dev/documents/gan/1.0.0/
+  rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths:
 - lib
@@ -141,15 +56,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.3.0
+      version: 3.2.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.1.2
-signing_key: 
+rubygems_version: 3.6.7
 specification_version: 4
-summary: A GAN implementation in Ruby.
+summary: GAN (General Actor Notation) support for the Ruby language.
 test_files: []

data/lib/sashite/gan/abbr.rb

@@ -1,76 +0,0 @@
-# frozen_string_literal: true
-
-module Sashite
-  module GAN
-    # The piece's abbreviation.
-    class Abbr
-      # The piece's type.
-      #
-      # @!attribute [r] type
-      #   @return [String] The type of the piece.
-      attr_reader :type
-
-      def initialize(type, is_promoted:, is_king:)
-        @type = TypeString(type)
-        @is_promoted = Boolean(is_promoted)
-        @is_king = Boolean(is_king)
-
-        freeze
-      end
-
-      # @return [Boolean] Is the piece a king?
-      def king?
-        @is_king
-      end
-
-      # @return [Boolean] Is the piece promoted?
-      def promoted?
-        @is_promoted
-      end
-
-      # @return [String] The abbreviation of the piece.
-      def to_s
-        str = type
-        str = "-#{str}" if king?
-        str = "+#{str}" if promoted?
-        str
-      end
-
-      def inspect
-        to_s
-      end
-
-      def ==(other)
-        other.to_s == to_s
-      end
-
-      def eql?(other)
-        self == other
-      end
-
-      private
-
-      # rubocop:disable Naming/MethodName
-
-      # Ensures `arg` is a boolean, and returns it.  Otherwise, raises a
-      #   `TypeError`.
-      def Boolean(arg)
-        raise ::TypeError, arg.class.inspect unless [false, true].include?(arg)
-
-        arg
-      end
-
-      # Ensures `arg` is a type, and returns it.  Otherwise, raises an error.
-      def TypeString(arg)
-        raise ::TypeError, arg.class.inspect unless arg.is_a?(::String)
-        raise Error::Type, arg.inspect unless arg.match?(/\A[a-z]{1,2}\z/i)
-
-        arg
-      end
-
-      # rubocop:enable Naming/MethodName
-    end
-  end
-end
-
-require_relative 'error'

data/lib/sashite/gan/error/string.rb

@@ -1,10 +0,0 @@
-# frozen_string_literal: true
-
-module Sashite
-  module GAN
-    module Error
-      # `String` is the base class for GAN string errors.
-      class String < ::StandardError; end
-    end
-  end
-end

data/lib/sashite/gan/error/style.rb

@@ -1,12 +0,0 @@
-# frozen_string_literal: true
-
-require_relative 'string'
-
-module Sashite
-  module GAN
-    module Error
-      # Raised when encountering an invalid sequence of characters.
-      class Style < String; end
-    end
-  end
-end

data/lib/sashite/gan/error/type.rb

@@ -1,12 +0,0 @@
-# frozen_string_literal: true
-
-require_relative 'string'
-
-module Sashite
-  module GAN
-    module Error
-      # Raised when encountering an invalid sequence of characters.
-      class Type < String; end
-    end
-  end
-end

data/lib/sashite/gan/error.rb

@@ -1,12 +0,0 @@
-# frozen_string_literal: true
-
-module Sashite
-  module GAN
-    # The error namespace.
-    module Error; end
-  end
-end
-
-Dir[File.join(File.dirname(__FILE__), 'error', '*.rb')].each do |fname|
-  require_relative fname
-end

data/lib/sashite/gan/piece.rb

@@ -1,150 +0,0 @@
-# frozen_string_literal: true
-
-module Sashite
-  module GAN
-    # A piece abstraction.
-    class Piece
-      # The abbreviation of the piece.
-      #
-      # @!attribute [r] abbr
-      #   @return [String] The abbreviation of the piece.
-      attr_reader :abbr
-
-      # The piece's style.
-      #
-      # @!attribute [r] style
-      #   @return [String] The piece's style.
-      attr_reader :style
-
-      # Initialize a piece.
-      #
-      # @param type [String] The type of the piece.
-      # @param is_king [Boolean] Is it a King (or a Xiangqi General),
-      #   so it could be checkmated?
-      # @param is_promoted [Boolean] Is it promoted?
-      # @param is_topside [Boolean] Is it owned by top-side player?
-      # @param style [String] The piece's style.
-      def initialize(type, is_king:, is_promoted:, is_topside:, style:)
-        @abbr = Abbr.new(type, is_king: is_king, is_promoted: is_promoted)
-        @is_topside = Boolean(is_topside)
-        @style = StyleString(style)
-
-        freeze
-      end
-
-      def king?
-        abbr.king?
-      end
-
-      # Is it owned by top-side player?
-      #
-      # @return [Boolean] Returns `true` if the top-side player own the piece,
-      #   `false` otherwise.
-      def topside?
-        @is_topside
-      end
-
-      # Is it owned by bottom-side player?
-      #
-      # @return [Boolean] Returns `true` if the bottom-side player own the
-      #   piece, `false` otherwise.
-      def bottomside?
-        !topside?
-      end
-
-      # @see https://developer.sashite.com/specs/general-actor-notation
-      # @return [String] The notation of the piece.
-      def to_s
-        topside? ? raw.downcase : raw.upcase
-      end
-
-      def inspect
-        to_s
-      end
-
-      # @return [Piece] The top-side side version of the piece.
-      def topside
-        topside? ? self : oppositeside
-      end
-
-      # @return [Piece] The bottom-side side version of the piece.
-      def bottomside
-        topside? ? oppositeside : self
-      end
-
-      # @return [Piece] The opposite side version of the piece.
-      def oppositeside
-        self.class.new(abbr.type,
-          is_king: abbr.king?,
-          is_promoted: abbr.promoted?,
-          is_topside: !topside?,
-          style: style
-        )
-      end
-
-      # @return [Piece] The promoted version of the piece.
-      def promote
-        self.class.new(abbr.type,
-          is_king: abbr.king?,
-          is_promoted: true,
-          is_topside: topside?,
-          style: style
-        )
-      end
-
-      # @return [Piece] The unpromoted version of the piece.
-      def unpromote
-        self.class.new(abbr.type,
-          is_king: abbr.king?,
-          is_promoted: false,
-          is_topside: topside?,
-          style: style
-        )
-      end
-
-      def ==(other)
-        other.to_s == to_s
-      end
-
-      def eql?(other)
-        self == other
-      end
-
-      private
-
-      # @return [String] The style and the abbreviation of the piece (without
-      #   case).
-      def raw
-        params.join(SEPARATOR_CHAR)
-      end
-
-      # @return [Array] The style and the abbreviation of the piece.
-      def params
-        [style, abbr]
-      end
-
-      # rubocop:disable Naming/MethodName
-
-      # Ensures `arg` is a boolean, and returns it.  Otherwise, raises a
-      #   `TypeError`.
-      def Boolean(arg)
-        raise ::TypeError, arg.class.inspect unless [false, true].include?(arg)
-
-        arg
-      end
-
-      # Ensures `arg` is a style, and returns it.  Otherwise, raises an error.
-      def StyleString(arg)
-        raise ::TypeError, arg.class.inspect unless arg.is_a?(::String)
-        raise Error::Style, arg.inspect unless arg.match?(/\A[a-z_]+\z/i)
-
-        arg
-      end
-
-      # rubocop:enable Naming/MethodName
-    end
-  end
-end
-
-require_relative 'abbr'
-require_relative 'error'