sashite-pnn 2.0.0 → 3.1.0

data/lib/sashite/pnn/name.rb

@@ -0,0 +1,223 @@
+# frozen_string_literal: true
+
+module Sashite
+  module Pnn
+    # Represents a piece name in PNN (Piece Name Notation) format.
+    #
+    # PNN provides a canonical naming system for abstract strategy game pieces.
+    # Each name consists of an optional state modifier (+ or -) followed by a
+    # case-consistent alphabetic name and an optional terminal marker (^),
+    # encoding piece identity, player assignment, state, and terminal status
+    # in a human-readable format.
+    #
+    # All instances are immutable.
+    class Name
+      # PNN validation pattern matching the specification
+      PNN_PATTERN = /\A([+-]?)([A-Z]+|[a-z]+)(\^?)\z/
+
+      # Error messages
+      ERROR_INVALID_NAME = "Invalid PNN string: %s"
+
+      # @return [String] the canonical piece name
+      attr_reader :value
+
+      # Create a new piece name instance
+      #
+      # @param name [String, Symbol] the piece name (e.g., "KING", :queen, "+ROOK", "-pawn", "KING^")
+      # @raise [ArgumentError] if the name does not match PNN pattern
+      def initialize(name)
+        string_value = name.to_s
+        self.class.validate_format(string_value)
+
+        @value = string_value.freeze
+        @parsed = parse_components(string_value)
+        freeze
+      end
+
+      # Parse a PNN string into a Name object
+      #
+      # @param string [String] the PNN-formatted piece name
+      # @return [Name] a new Name instance
+      # @raise [ArgumentError] if the string is invalid
+      #
+      # @example
+      #   Sashite::Pnn::Name.parse("KING")    # => #<Pnn::Name value="KING">
+      #   Sashite::Pnn::Name.parse("+queen")  # => #<Pnn::Name value="+queen">
+      #   Sashite::Pnn::Name.parse("KING^")   # => #<Pnn::Name value="KING^">
+      #   Sashite::Pnn::Name.parse("+ROOK^")  # => #<Pnn::Name value="+ROOK^">
+      def self.parse(string)
+        new(string)
+      end
+
+      # Check whether the given string is a valid PNN name
+      #
+      # @param string [String] input string to validate
+      # @return [Boolean] true if valid, false otherwise
+      #
+      # @example
+      #   Sashite::Pnn::Name.valid?("KING")    # => true
+      #   Sashite::Pnn::Name.valid?("King")    # => false (mixed case)
+      #   Sashite::Pnn::Name.valid?("+queen")  # => true
+      #   Sashite::Pnn::Name.valid?("KING^")   # => true
+      #   Sashite::Pnn::Name.valid?("KING1")   # => false (contains digit)
+      def self.valid?(string)
+        string.is_a?(::String) && string.match?(PNN_PATTERN)
+      end
+
+      # Validate that the string is in proper PNN format
+      #
+      # @param str [String]
+      # @raise [ArgumentError] if invalid
+      def self.validate_format(str)
+        raise ::ArgumentError, format(ERROR_INVALID_NAME, str.inspect) unless str.match?(PNN_PATTERN)
+      end
+
+      # Returns the string representation of the name
+      #
+      # @return [String]
+      def to_s
+        value
+      end
+
+      # Returns the base name without state modifier or terminal marker
+      #
+      # @return [String] the piece name without + or - prefix and without ^ suffix
+      #
+      # @example
+      #   Sashite::Pnn::Name.parse("KING").base_name     # => "KING"
+      #   Sashite::Pnn::Name.parse("+queen").base_name   # => "queen"
+      #   Sashite::Pnn::Name.parse("-ROOK").base_name    # => "ROOK"
+      #   Sashite::Pnn::Name.parse("KING^").base_name    # => "KING"
+      #   Sashite::Pnn::Name.parse("+ROOK^").base_name   # => "ROOK"
+      def base_name
+        @parsed[:base_name]
+      end
+
+      # Check if the piece has enhanced state (+)
+      #
+      # @return [Boolean] true if enhanced, false otherwise
+      #
+      # @example
+      #   Sashite::Pnn::Name.parse("+KING").enhanced?    # => true
+      #   Sashite::Pnn::Name.parse("KING").enhanced?     # => false
+      #   Sashite::Pnn::Name.parse("+KING^").enhanced?   # => true
+      def enhanced?
+        @parsed[:state_modifier] == "+"
+      end
+
+      # Check if the piece has diminished state (-)
+      #
+      # @return [Boolean] true if diminished, false otherwise
+      #
+      # @example
+      #   Sashite::Pnn::Name.parse("-pawn").diminished?  # => true
+      #   Sashite::Pnn::Name.parse("pawn").diminished?   # => false
+      #   Sashite::Pnn::Name.parse("-pawn^").diminished? # => true
+      def diminished?
+        @parsed[:state_modifier] == "-"
+      end
+
+      # Check if the piece has normal state (no modifier)
+      #
+      # @return [Boolean] true if normal, false otherwise
+      #
+      # @example
+      #   Sashite::Pnn::Name.parse("KING").normal?       # => true
+      #   Sashite::Pnn::Name.parse("+KING").normal?      # => false
+      #   Sashite::Pnn::Name.parse("KING^").normal?      # => true
+      def normal?
+        @parsed[:state_modifier].empty?
+      end
+
+      # Check if the piece is a terminal piece (has ^ marker)
+      #
+      # @return [Boolean] true if terminal, false otherwise
+      #
+      # @example
+      #   Sashite::Pnn::Name.parse("KING^").terminal?    # => true
+      #   Sashite::Pnn::Name.parse("KING").terminal?     # => false
+      #   Sashite::Pnn::Name.parse("+KING^").terminal?   # => true
+      #   Sashite::Pnn::Name.parse("-pawn^").terminal?   # => true
+      def terminal?
+        @parsed[:terminal_marker] == "^"
+      end
+
+      # Check if the piece belongs to the first player (uppercase)
+      #
+      # @return [Boolean] true if first player, false otherwise
+      #
+      # @example
+      #   Sashite::Pnn::Name.parse("KING").first_player?     # => true
+      #   Sashite::Pnn::Name.parse("queen").first_player?    # => false
+      #   Sashite::Pnn::Name.parse("KING^").first_player?    # => true
+      def first_player?
+        @parsed[:base_name] == @parsed[:base_name].upcase
+      end
+
+      # Check if the piece belongs to the second player (lowercase)
+      #
+      # @return [Boolean] true if second player, false otherwise
+      #
+      # @example
+      #   Sashite::Pnn::Name.parse("king").second_player?    # => true
+      #   Sashite::Pnn::Name.parse("QUEEN").second_player?   # => false
+      #   Sashite::Pnn::Name.parse("king^").second_player?   # => true
+      def second_player?
+        @parsed[:base_name] == @parsed[:base_name].downcase
+      end
+
+      # Check if another piece has the same base name (ignoring case, state, and terminal marker)
+      #
+      # @param other [Name] another piece name to compare
+      # @return [Boolean] true if same base name, false otherwise
+      #
+      # @example
+      #   king = Sashite::Pnn::Name.parse("KING")
+      #   queen = Sashite::Pnn::Name.parse("king")
+      #   enhanced = Sashite::Pnn::Name.parse("+KING")
+      #   terminal = Sashite::Pnn::Name.parse("KING^")
+      #
+      #   king.same_base_name?(queen)     # => true (same piece, different player)
+      #   king.same_base_name?(enhanced)  # => true (same piece, different state)
+      #   king.same_base_name?(terminal)  # => true (same piece, terminal marker)
+      def same_base_name?(other)
+        return false unless other.is_a?(self.class)
+
+        base_name.downcase == other.base_name.downcase
+      end
+
+      # Equality based on normalized string value
+      #
+      # @param other [Object]
+      # @return [Boolean]
+      def ==(other)
+        other.is_a?(self.class) && value == other.value
+      end
+
+      # Required for correct Set/hash behavior
+      alias eql? ==
+
+      # Hash based on class and value
+      #
+      # @return [Integer]
+      def hash
+        [self.class, value].hash
+      end
+
+      private
+
+      # Parse the components of a PNN string
+      #
+      # @param str [String] the PNN string
+      # @return [Hash] parsed components
+      def parse_components(str)
+        match = str.match(PNN_PATTERN)
+        {
+          state_modifier:  match[1],
+          base_name:       match[2],
+          terminal_marker: match[3]
+        }
+      end
+    end
+  end
+end

data/lib/sashite/pnn.rb

@@ -1,69 +1,66 @@
 # frozen_string_literal: true
 
-require_relative "pnn/piece"
+require_relative "pnn/name"
 
 module Sashite
   # PNN (Piece Name Notation) implementation for Ruby
   #
-  # Provides style-aware ASCII-based format for representing pieces in abstract strategy board games.
-  # PNN extends PIN by adding derivation markers that distinguish pieces by their style origin,
-  # enabling cross-style game scenarios and piece origin tracking.
+  # Provides a formal naming system for identifying pieces in abstract strategy board games.
+  # PNN uses canonical, human-readable ASCII names with optional state modifiers and case
+  # encoding for player assignment. It supports unlimited unique piece identifiers with
+  # consistent, rule-agnostic semantics.
   #
-  # Format: [<state>]<letter>[<derivation>]
-  # - State modifier: "+" (enhanced), "-" (diminished), or none (normal)
-  # - Letter: A-Z (first player), a-z (second player)
-  # - Derivation marker: "'" (foreign style), or none (native style)
+  # Format: [<state-modifier>]<case-consistent-name>
   #
   # Examples:
-  #   "K"   - First player king (native style, normal state)
-  #   "k'"  - Second player king (foreign style, normal state)
-  #   "+R'" - First player rook (foreign style, enhanced state)
-  #   "-p"  - Second player pawn (native style, diminished state)
+  #   "KING"        - First player king (normal state)
+  #   "queen"       - Second player queen (normal state)
+  #   "+ROOK"       - First player rook (enhanced state)
+  #   "-pawn"       - Second player pawn (diminished state)
+  #   "BISHOP"      - First player bishop (normal state)
   #
   # See: https://sashite.dev/specs/pnn/1.0.0/
   module Pnn
-    # Check if a string is a valid PNN notation
+    # Check if a string is valid PNN notation
     #
-    # @param pnn_string [String] The string to validate
+    # @param pnn_string [String] the string to validate
     # @return [Boolean] true if valid PNN, false otherwise
     #
-    # @example
-    #   Sashite::Pnn.valid?("K")     # => true
-    #   Sashite::Pnn.valid?("+R'")   # => true
-    #   Sashite::Pnn.valid?("-p")    # => true
-    #   Sashite::Pnn.valid?("KK")    # => false
-    #   Sashite::Pnn.valid?("++K")   # => false
+    # @example Validate PNN strings
+    #   Sashite::Pnn.valid?("KING")     # => true
+    #   Sashite::Pnn.valid?("queen")    # => true
+    #   Sashite::Pnn.valid?("+ROOK")    # => true
+    #   Sashite::Pnn.valid?("-pawn")    # => true
+    #   Sashite::Pnn.valid?("King")     # => false (mixed case)
+    #   Sashite::Pnn.valid?("KING1")    # => false (contains digit)
     def self.valid?(pnn_string)
-      Piece.valid?(pnn_string)
+      Name.valid?(pnn_string)
     end
 
-    # Parse a PNN string into a Piece object
+    # Parse a PNN string into a Name object
     #
-    # @param pnn_string [String] PNN notation string
-    # @return [Pnn::Piece] new piece instance
-    # @raise [ArgumentError] if the PNN string is invalid
-    # @example
-    #   Sashite::Pnn.parse("K")     # => #<Pnn::Piece type=:K side=:first state=:normal native=true>
-    #   Sashite::Pnn.parse("+R'")   # => #<Pnn::Piece type=:R side=:first state=:enhanced native=false>
-    #   Sashite::Pnn.parse("-p")    # => #<Pnn::Piece type=:P side=:second state=:diminished native=true>
+    # @param pnn_string [String] the piece name string
+    # @return [Pnn::Name] a parsed name object
+    # @raise [ArgumentError] if the name is invalid
+    #
+    # @example Parse valid PNN names
+    #   Sashite::Pnn.parse("KING")    # => #<Pnn::Name value="KING">
+    #   Sashite::Pnn.parse("+queen")  # => #<Pnn::Name value="+queen">
     def self.parse(pnn_string)
-      Piece.parse(pnn_string)
+      Name.parse(pnn_string)
     end
 
-    # Create a new piece instance
+    # Create a new Name instance directly
+    #
+    # @param value [String, Symbol] piece name to construct
+    # @return [Pnn::Name] new name instance
+    # @raise [ArgumentError] if name format is invalid
     #
-    # @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)
-    # @param native [Boolean] style derivation (true for native, false for foreign)
-    # @return [Pnn::Piece] new piece instance
-    # @raise [ArgumentError] if parameters are invalid
     # @example
-    #   Sashite::Pnn.piece(:K, :first, :normal, true)      # => #<Pnn::Piece type=:K side=:first state=:normal native=true>
-    #   Sashite::Pnn.piece(:R, :first, :enhanced, false)   # => #<Pnn::Piece type=:R side=:first state=:enhanced native=false>
-    #   Sashite::Pnn.piece(:P, :second, :diminished, true) # => #<Pnn::Piece type=:P side=:second state=:diminished native=true>
-    def self.piece(type, side, state = Sashite::Pin::Piece::NORMAL_STATE, native = Piece::NATIVE)
-      Piece.new(type, side, state, native)
+    #   Sashite::Pnn.name("BISHOP") # => #<Pnn::Name value="BISHOP">
+    #   Sashite::Pnn.name(:queen)   # => #<Pnn::Name value="queen">
+    def self.name(value)
+      Name.new(value)
     end
   end
 end

data/lib/sashite-pnn.rb

@@ -5,9 +5,9 @@ require_relative "sashite/pnn"
 # 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.
+# board game concepts according to the Sashité Protocol specifications.
 #
-# @see https://sashite.dev/game-protocol/ Game Protocol Foundation
+# @see https://sashite.dev/protocol/ Sashité Protocol
 # @see https://sashite.dev/specs/ Sashité Specifications
 # @author Sashité
 module Sashite

metadata

@@ -1,36 +1,22 @@
 --- !ruby/object:Gem::Specification
 name: sashite-pnn
 version: !ruby/object:Gem::Version
-  version: 2.0.0
+  version: 3.1.0
 platform: ruby
 authors:
 - Cyril Kato
 bindir: bin
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
-dependencies:
-- !ruby/object:Gem::Dependency
-  name: sashite-pin
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: 2.0.2
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: 2.0.2
+dependencies: []
 description: |
-  PNN (Piece Name Notation) extends PIN to provide style-aware piece representation
-  in abstract strategy board games. This gem implements the PNN Specification v1.0.0 with
-  a modern Ruby interface featuring immutable piece objects and functional programming
-  principles. PNN adds derivation markers to PIN that distinguish pieces by their style
-  origin, enabling cross-style game scenarios and piece origin tracking. Represents all
-  four Game Protocol piece attributes with full PIN backward compatibility. Perfect for
-  game engines, cross-tradition tournaments, and hybrid board game environments.
+  PNN (Piece Name Notation) provides a rule-agnostic, scalable naming system for identifying
+  abstract strategy board game pieces. This gem implements the PNN Specification v1.0.0 with
+  a modern Ruby interface featuring immutable piece name objects and functional programming
+  principles. PNN uses canonical ASCII names with optional state modifiers and optional terminal
+  markers (e.g., "KING", "queen", "+ROOK", "-pawn", "KING^", "+GENERAL^") to unambiguously
+  refer to game pieces across variants and traditions. Ideal for engines, protocols, and tools
+  that need clear and extensible piece identifiers.
 email: contact@cyril.email
 executables: []
 extensions: []
@@ -40,7 +26,7 @@ files:
 - README.md
 - lib/sashite-pnn.rb
 - lib/sashite/pnn.rb
-- lib/sashite/pnn/piece.rb
+- lib/sashite/pnn/name.rb
 homepage: https://github.com/sashite/pnn.rb
 licenses:
 - MIT
@@ -65,8 +51,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.9
+rubygems_version: 3.7.2
 specification_version: 4
-summary: PNN (Piece Name Notation) implementation for Ruby extending PIN with style
-  derivation markers
+summary: PNN (Piece Name Notation) implementation for Ruby with immutable piece name
+  objects
 test_files: []