sashite-gan 2.2.0 → 4.0.0

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,49 +1,88 @@
 # frozen_string_literal: true
 
-require_relative 'gan/parser'
+require "sashite/snn"
+require "pnn"
+require_relative "gan/actor"
 
 module Sashite
-  # The GAN (General Actor Notation) module.
+  # General Actor Notation (GAN) module
   #
-  # @see https://developer.sashite.com/specs/general-actor-notation
-  module GAN
-    SEPARATOR_CHAR = ':'
+  # 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/ GAN Specification v1.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/
 
-    # 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")
+    # Check if a string is valid GAN notation
     #
-    # @example Makruk (Thai chess)'s Bishop, White
-    #   GAN.parse("M:B")
+    # @param gan_string [String] The string to validate
+    # @return [Boolean] true if the string is valid GAN notation, false otherwise
     #
-    # @example Shogi (Japanese chess)'s King, Gote
-    #   GAN.parse("s:-k")
+    # @example
+    #   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
+
+    # Convenience method to create an actor object
     #
-    # @example Shogi (Japanese chess)'s King, Sente
-    #   GAN.parse("S:-K")
+    # @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
     #
-    # @example Shogi (Japanese chess)'s promoted Pawn, Sente
-    #   GAN.parse("S:+P")
+    # @example
+    #   actor = Sashite::Gan.actor("CHESS", "K")
+    #   # => #<Sashite::Gan::Actor:0x... style="CHESS" piece="K">
     #
-    # @example Xiangqi (Chinese chess)'s General, Red
-    #   GAN.parse("X:-G")
+    #   # 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
+
+    # Parse a GAN string into component parts
     #
-    # @example Xiangqi (Chinese chess)'s Flying General, Red
-    #   GAN.parse("X:+-G")
+    # @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
     #
-    # @example Dai Dai Shogi (huge Japanese chess)'s Phoenix, Sente
-    #   GAN.parse("DAI_DAI_SHOGI:PH")
+    # @example
+    #   Sashite::Gan.parse_components("CHESS:K")
+    #   # => ["CHESS", "K"]
     #
-    # @example Another FOO chess variant's promoted Z piece, Bottom-side
-    #   GAN.parse("FOO:+Z")
+    #   Sashite::Gan.parse_components("shogi:+p'")
+    #   # => ["shogi", "+p'"]
     #
-    # @return [Piece] An instance of the piece.
-    def self.parse(string)
-      Parser.call(string)
+    # @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,6 +1,18 @@
 # frozen_string_literal: true
 
-# Sashite namespace
-module Sashite; end
+# 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'
+require_relative "sashite/gan"

metadata

@@ -1,114 +1,46 @@
 --- !ruby/object:Gem::Specification
 name: sashite-gan
 version: !ruby/object:Gem::Version
-  version: 2.2.0
+  version: 4.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: 2.0.0
+  type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 2.0.0
 - !ruby/object:Gem::Dependency
-  name: bundler
+  name: sashite-snn
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
+        version: 1.0.0
+  type: :runtime
   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.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.
 email: contact@cyril.email
 executables: []
 extensions: []
@@ -118,22 +50,17 @@ 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/parser.rb
-- lib/sashite/gan/piece.rb
-homepage: https://developer.sashite.com/specs/general-actor-notation
+- lib/sashite/gan/actor.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 +68,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/parser.rb

@@ -1,31 +0,0 @@
-# frozen_string_literal: true
-
-require_relative 'error'
-require_relative 'piece'
-
-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
-        )
-      end
-
-      def self.valid?(arg)
-        raise ::TypeError, arg.class.inspect unless arg.is_a?(::String)
-
-        arg.match?(/\A([a-z_]+:\+?-?[a-z]{1,2}|[A-Z_]+:\+?-?[A-Z]{1,2})\z/)
-      end
-    end
-  end
-end