sashite-gan 4.0.0 → 5.0.0

data/lib/sashite/gan.rb

@@ -1,88 +1,76 @@
 # frozen_string_literal: true
 
-require "sashite/snn"
-require "pnn"
 require_relative "gan/actor"
 
 module Sashite
-  # General Actor Notation (GAN) module
+  # GAN (General Actor Notation) implementation for Ruby
   #
-  # 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.
+  # Provides a rule-agnostic format for identifying game actors in abstract strategy board games
+  # by combining Style Name Notation (SNN) and Piece Identifier Notation (PIN) with a colon separator
+  # and consistent case encoding.
   #
-  # @see https://sashite.dev/documents/gan/1.0.0/ GAN Specification v1.0.0
+  # GAN represents all four fundamental piece attributes from the Game Protocol:
+  # - Type → PIN component (ASCII letter choice)
+  # - Side → Consistent case encoding across both SNN and PIN components
+  # - State → PIN component (optional prefix modifier)
+  # - Style → SNN component (explicit style identifier)
+  #
+  # Format: <snn>:<pin>
+  # - SNN component: Style identifier with case-based side encoding
+  # - Colon separator: Literal ":"
+  # - PIN component: Piece with optional state and case-based ownership
+  # - Case consistency: SNN and PIN components must have matching case
+  #
+  # Examples:
+  #   "CHESS:K"    - First player chess king
+  #   "chess:k"    - Second player chess king
+  #   "SHOGI:+P"   - First player enhanced shōgi pawn
+  #   "xiangqi:-g" - Second player diminished xiangqi general
+  #
+  # See: https://sashite.dev/specs/gan/1.0.0/
   module Gan
-    # 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/
-
     # 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
+    # @return [Boolean] true if valid GAN, false otherwise
     #
-    # @example
+    # @example Validate various GAN formats
     #   Sashite::Gan.valid?("CHESS:K")      # => true
-    #   Sashite::Gan.valid?("shogi:+p'")    # => true
+    #   Sashite::Gan.valid?("shogi:+p")     # => true
     #   Sashite::Gan.valid?("Chess:K")      # => false (mixed case in style)
+    #   Sashite::Gan.valid?("CHESS:k")      # => false (case mismatch)
     #   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)
+      Actor.valid?(gan_string)
     end
 
-    # 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
+    # Parse a GAN string into an Actor object
     #
-    # @example
-    #   actor = Sashite::Gan.actor("CHESS", "K")
-    #   # => #<Sashite::Gan::Actor:0x... style="CHESS" piece="K">
-    #
-    #   # 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)
+    # @param gan_string [String] GAN notation string
+    # @return [Gan::Actor] new actor instance
+    # @raise [ArgumentError] if the GAN string is invalid
+    # @example Parse different GAN formats
+    #   Sashite::Gan.parse("CHESS:K")     # => #<Gan::Actor name=:Chess type=:K side=:first state=:normal>
+    #   Sashite::Gan.parse("shogi:+p")    # => #<Gan::Actor name=:Shogi type=:P side=:second state=:enhanced>
+    #   Sashite::Gan.parse("XIANGQI:-G")  # => #<Gan::Actor name=:Xiangqi type=:G side=:first state=:diminished>
+    def self.parse(gan_string)
+      Actor.parse(gan_string)
     end
 
-    # 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
+    # Create a new actor instance
     #
-    # @example
-    #   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)
+    # @param name [Symbol] style name (with proper capitalization)
+    # @param type [Symbol] piece type (:A to :Z)
+    # @param side [Symbol] player side (:first or :second)
+    # @param state [Symbol] piece state (:normal, :enhanced, or :diminished)
+    # @return [Gan::Actor] new actor instance
+    # @raise [ArgumentError] if parameters are invalid
+    # @example Create actors directly
+    #   Sashite::Gan.actor(:Chess, :K, :first, :normal)     # => #<Gan::Actor name=:Chess type=:K side=:first state=:normal>
+    #   Sashite::Gan.actor(:Shogi, :P, :second, :enhanced)  # => #<Gan::Actor name=:Shogi type=:P side=:second state=:enhanced>
+    def self.actor(name, type, side, state = :normal)
+      Actor.new(name, type, side, state)
     end
   end
 end

data/lib/sashite-gan.rb

@@ -1,18 +1,14 @@
 # frozen_string_literal: true
 
+require_relative "sashite/gan"
+
 # Sashité namespace for board game notation libraries
+#
+# Sashité provides a collection of libraries for representing and manipulating
+# board game concepts according to the Game Protocol specifications.
+#
+# @see https://sashite.dev/game-protocol/ Game Protocol Foundation
+# @see https://sashite.dev/specs/ Sashité Specifications
+# @author Sashité
 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: 4.0.0
+  version: 5.0.0
 platform: ruby
 authors:
 - Cyril Kato
@@ -10,37 +10,40 @@ cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
-  name: pnn
+  name: sashite-pin
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 2.0.0
+        version: 2.0.2
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 2.0.0
+        version: 2.0.2
 - !ruby/object:Gem::Dependency
   name: sashite-snn
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.0.0
+        version: 1.1.1
   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
-  pieces with their originating game.
+        version: 1.1.1
+description: 'A Ruby implementation of GAN (General Actor Notation) v1.0.0 specification
+  for identifying game actors in abstract strategy board games. GAN combines Style
+  Name Notation (SNN) and Piece Identifier Notation (PIN) with a colon separator to
+  provide complete, unambiguous piece identification. Represents all four fundamental
+  piece attributes: Type, Side, State, and Style. Enables cross-style gaming, immutable
+  transformations, and component extraction with to_pin/to_snn methods. Built on sashite-snn
+  and sashite-pin gems.'
 email: contact@cyril.email
 executables: []
 extensions: []
@@ -59,7 +62,7 @@ metadata:
   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
-  specification_uri: https://sashite.dev/documents/gan/1.0.0/
+  specification_uri: https://sashite.dev/specs/gan/1.0.0/
   rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths:
@@ -75,7 +78,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.7
+rubygems_version: 3.6.9
 specification_version: 4
-summary: GAN (General Actor Notation) support for the Ruby language.
+summary: GAN (General Actor Notation) implementation for Ruby - board game piece identification
 test_files: []