sashite-pnn 3.0.0 → 3.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4d74e4979082abf26a0ec1d7e871f9d3a31834cbbca683e73952f789f88b50c8
-  data.tar.gz: 5587bdfc31daba336a8c50be37ee8f342ab90c10b4f1d61b8b73426f1a9c071e
+  metadata.gz: 85b86d223876b87d9bdcf29bc1484a32b667038bc378b1b9188aea72f4f2f66d
+  data.tar.gz: 27793a4f9a79241ffedbcf69f3ed4c3f6dc0293928318c308331d21eafb7df0c
 SHA512:
-  metadata.gz: '04313675987fd9ec5b2262ce3aeea7263e0a0cbd863a4a894def608a6b6b716c8991447227c9194260e248a0bde325958459eea80e1480117435f0b3ff903ea4'
-  data.tar.gz: 618b5df20b597a34228458430f88b9cf4134b8997348e7f2691a3411534001ea74358b62cd914b66338c6bd6a6e047ec43077775d9af6d3971ed227696e804f8
+  metadata.gz: 13c0726586676a5ecf632126879761198c9ca7be438aaf58720c5e469b3283c3782bc51a4e8315ee91f14fc57501c705860d7fc225de175b43526014d1464239
+  data.tar.gz: d654455e116883dfed83ac75ca22906ae42480eafa656f1f39f908ee0d5a79da7974ac2b421c0e8bdcaa8615650666fa1de1c39c9e149a7da079a7c127931be8

data/README.md

@@ -9,19 +9,17 @@
 
 ## What is PNN?
 
-PNN (Piece Name Notation) is a formal, rule-agnostic naming system for identifying **pieces** in abstract strategy board games such as chess, shÅgi, xiangqi, and their many variants. Each piece is represented by a canonical, human-readable ASCII name with optional state modifiers (e.g., `"KING"`, `"queen"`, `"+ROOK"`, `"-pawn"`).
+PNN (Piece Name Notation) is a formal, rule-agnostic naming system for identifying **pieces** in abstract strategy board games such as chess, shōgi, xiangqi, and their many variants. Each piece is represented by a canonical, human-readable ASCII name with optional state modifiers and optional terminal markers (e.g., `"KING"`, `"queen"`, `"+ROOK"`, `"-pawn"`, `"KING^"`).
 
-This gem implements the [PNN Specification v1.0.0](https://sashite.dev/specs/pnn/1.0.0/), supporting validation, parsing, and comparison of piece names with integrated state management.
+This gem implements the [PNN Specification v1.0.0](https://sashite.dev/specs/pnn/1.0.0/), supporting validation, parsing, and comparison of piece names with integrated state management and terminal piece identification.
 
 ## Installation
-
 ```ruby
 # In your Gemfile
 gem "sashite-pnn"
 ```
 
 Or install manually:
-
 ```sh
 gem install sashite-pnn
 ```
@@ -29,7 +27,6 @@ gem install sashite-pnn
 ## Usage
 
 ### Basic Operations
-
 ```ruby
 require "sashite/pnn"
 
@@ -47,10 +44,11 @@ Sashite::Pnn.valid?("BISHOP")                 # => true
 Sashite::Pnn.valid?("King")                   # => false (mixed case not allowed)
 Sashite::Pnn.valid?("+ROOK")                  # => true (enhanced state)
 Sashite::Pnn.valid?("-pawn")                  # => true (diminished state)
+Sashite::Pnn.valid?("KING^")                  # => true (terminal piece)
+Sashite::Pnn.valid?("+KING^")                 # => true (enhanced terminal piece)
 ```
 
 ### State Modifiers
-
 ```ruby
 # Enhanced pieces (+ prefix)
 enhanced = Sashite::Pnn.parse("+QUEEN")
@@ -70,39 +68,69 @@ normal.enhanced?                              # => false
 normal.diminished?                            # => false
 ```
 
-### Player Assignment
+### Terminal Markers
+```ruby
+# Terminal pieces (^ suffix)
+terminal = Sashite::Pnn.parse("KING^")
+terminal.terminal?                            # => true
+terminal.base_name                            # => "KING"
+
+# Non-terminal pieces (no suffix)
+non_terminal = Sashite::Pnn.parse("PAWN")
+non_terminal.terminal? # => false
+
+# Combined state and terminal marker
+enhanced_terminal = Sashite::Pnn.parse("+ROOK^")
+enhanced_terminal.enhanced?                   # => true
+enhanced_terminal.terminal?                   # => true
+enhanced_terminal.base_name                   # => "ROOK"
+
+diminished_terminal = Sashite::Pnn.parse("-king^")
+diminished_terminal.diminished?               # => true
+diminished_terminal.terminal?                 # => true
+diminished_terminal.base_name                 # => "king"
+```
 
+### Player Assignment
 ```ruby
 # First player pieces (uppercase)
 first_player = Sashite::Pnn.parse("KING")
 first_player.first_player?                    # => true
 first_player.second_player?                   # => false
 
+first_player_terminal = Sashite::Pnn.parse("KING^")
+first_player_terminal.first_player?           # => true
+first_player_terminal.terminal?               # => true
+
 # Second player pieces (lowercase)
 second_player = Sashite::Pnn.parse("king")
 second_player.first_player?                   # => false
 second_player.second_player?                  # => true
+
+second_player_terminal = Sashite::Pnn.parse("king^")
+second_player_terminal.second_player?         # => true
+second_player_terminal.terminal?              # => true
 ```
 
 ### Normalization and Comparison
-
 ```ruby
 a = Sashite::Pnn.parse("ROOK")
 b = Sashite::Pnn.parse("ROOK")
 
 a == b                                        # => true
 a.same_base_name?(Sashite::Pnn.parse("rook")) # => true (same piece, different player)
-a.to_s                                        # => "ROOK"
+a.same_base_name?(Sashite::Pnn.parse("ROOK^")) # => true (same piece, terminal marker)
+a.same_base_name?(Sashite::Pnn.parse("+rook")) # => true (same piece, different state)
+a.to_s # => "ROOK"
 ```
 
 ### Collections and Filtering
-
 ```ruby
-pieces = %w[KING queen +ROOK -pawn BISHOP knight].map { |n| Sashite::Pnn.parse(n) }
+pieces = %w[KING^ queen +ROOK -pawn BISHOP knight^ GENERAL^].map { |n| Sashite::Pnn.parse(n) }
 
 # Filter by player
 first_player_pieces = pieces.select(&:first_player?).map(&:to_s)
-# => ["KING", "+ROOK", "BISHOP"]
+# => ["KING^", "+ROOK", "BISHOP", "GENERAL^"]
 
 # Filter by state
 enhanced_pieces = pieces.select(&:enhanced?).map(&:to_s)
@@ -110,24 +138,33 @@ enhanced_pieces = pieces.select(&:enhanced?).map(&:to_s)
 
 diminished_pieces = pieces.select(&:diminished?).map(&:to_s)
 # => ["-pawn"]
+
+# Filter by terminal status
+terminal_pieces = pieces.select(&:terminal?).map(&:to_s)
+# => ["KING^", "knight^", "GENERAL^"]
+
+# Combine filters
+first_player_terminals = pieces.select { |p| p.first_player? && p.terminal? }.map(&:to_s)
+# => ["KING^", "GENERAL^"]
 ```
 
 ## Format Specification
 
 ### Structure
-
 ```
-<state-modifier>?<piece-name>
+[<state-modifier>]<piece-name>[<terminal-marker>]
 ```
 
 Where:
 - `<state-modifier>` is optional `+` (enhanced) or `-` (diminished)
 - `<piece-name>` is case-consistent alphabetic characters
+- `<terminal-marker>` is optional `^` (terminal piece)
 
 ### Grammar (BNF)
-
 ```bnf
-<pnn> ::= <state-modifier> <name-body>
+<pnn> ::= <state-modifier> <name-body> <terminal-marker>
+       | <state-modifier> <name-body>
+       | <name-body> <terminal-marker>
        | <name-body>
 
 <state-modifier> ::= "+" | "-"
@@ -137,20 +174,22 @@ Where:
 <uppercase-name> ::= <uppercase-letter>+
 <lowercase-name> ::= <lowercase-letter>+
 
+<terminal-marker> ::= "^"
+
 <uppercase-letter> ::= "A" | "B" | "C" | ... | "Z"
 <lowercase-letter> ::= "a" | "b" | "c" | ... | "z"
 ```
 
 ### Regular Expression
-
 ```ruby
-/\A[+-]?([A-Z]+|[a-z]+)\z/
+/\A[+-]?([A-Z]+|[a-z]+)\^?\z/
 ```
 
 ## Design Principles
 
 * **Human-readable**: Names like `"KING"` or `"queen"` are intuitive and descriptive.
 * **State-aware**: Integrated state management through `+` and `-` modifiers.
+* **Terminal-aware**: Explicit identification of terminal pieces through `^` marker.
 * **Rule-agnostic**: Independent of specific game mechanics.
 * **Case-consistent**: Visual distinction between players through case.
 * **Canonical**: One valid name per piece state within a given context.
@@ -160,55 +199,69 @@ Where:
 
 PNN names serve as the formal source for PIN character identifiers. For example:
 
-| PNN       | PIN     | Description |
-| --------- | ------- | ----------- |
-| `KING`    | `K`     | First player king |
-| `king`    | `k`     | Second player king |
-| `+ROOK`   | `+R`    | Enhanced first player rook |
-| `-pawn`   | `-p`    | Diminished second player pawn |
+| PNN        | PIN      | Description |
+| ---------- | -------- | ----------- |
+| `KING`     | `K`      | First player king |
+| `king`     | `k`      | Second player king |
+| `KING^`    | `K^`     | Terminal first player king |
+| `king^`    | `k^`     | Terminal second player king |
+| `+ROOK`    | `+R`     | Enhanced first player rook |
+| `+ROOK^`   | `+R^`    | Enhanced terminal first player rook |
+| `-pawn`    | `-p`     | Diminished second player pawn |
+| `-pawn^`   | `-p^`    | Diminished terminal second player pawn |
 
-Multiple PNN names may map to the same PIN character (e.g., `"KING"` and `"KHAN"` both â†' `K`), but PNN provides unambiguous naming within broader contexts.
+Multiple PNN names may map to the same PIN character (e.g., `"KING"` and `"KHAN"` both → `K`), but PNN provides unambiguous naming within broader contexts.
 
 ## Examples
-
 ```ruby
 # Traditional pieces
 Sashite::Pnn.parse("KING")        # => #<Pnn::Name value="KING">
 Sashite::Pnn.parse("queen")       # => #<Pnn::Name value="queen">
 
+# Terminal pieces
+Sashite::Pnn.parse("KING^")       # => #<Pnn::Name value="KING^">
+Sashite::Pnn.parse("general^")    # => #<Pnn::Name value="general^">
+
 # State modifiers
 Sashite::Pnn.parse("+ROOK")       # => #<Pnn::Name value="+ROOK">
 Sashite::Pnn.parse("-pawn")       # => #<Pnn::Name value="-pawn">
 
+# Combined modifiers
+Sashite::Pnn.parse("+KING^")      # => #<Pnn::Name value="+KING^">
+Sashite::Pnn.parse("-pawn^")      # => #<Pnn::Name value="-pawn^">
+
 # Validation
 Sashite::Pnn.valid?("BISHOP")     # => true
+Sashite::Pnn.valid?("KING^")      # => true
+Sashite::Pnn.valid?("+ROOK^")     # => true
 Sashite::Pnn.valid?("Bishop")     # => false (mixed case)
 Sashite::Pnn.valid?("KING1")      # => false (no digits allowed)
+Sashite::Pnn.valid?("^KING")      # => false (terminal marker must be suffix)
 ```
 
 ## API Reference
 
 ### Main Module
 
-* `Sashite::Pnn.valid?(str)` â€" Returns `true` if the string is valid PNN.
-* `Sashite::Pnn.parse(str)` â€" Returns a `Sashite::Pnn::Name` object.
-* `Sashite::Pnn.name(sym_or_str)` â€" Alias for constructing a name.
+* `Sashite::Pnn.valid?(str)` — Returns `true` if the string is valid PNN.
+* `Sashite::Pnn.parse(str)` — Returns a `Sashite::Pnn::Name` object.
+* `Sashite::Pnn.name(sym_or_str)` — Alias for constructing a name.
 
 ### `Sashite::Pnn::Name`
 
-* `#value` â€" Returns the canonical string value.
-* `#to_s` â€" Returns the string representation.
-* `#base_name` â€" Returns the name without state modifier.
-* `#enhanced?` â€" Returns `true` if piece has enhanced state (`+` prefix).
-* `#diminished?` â€" Returns `true` if piece has diminished state (`-` prefix).
-* `#normal?` â€" Returns `true` if piece has normal state (no prefix).
-* `#first_player?` â€" Returns `true` if piece belongs to first player (uppercase).
-* `#second_player?` â€" Returns `true` if piece belongs to second player (lowercase).
-* `#same_base_name?(other)` â€" Returns `true` if both pieces have same base name.
-* `#==`, `#eql?`, `#hash` â€" Value-based equality.
+* `#value` — Returns the canonical string value.
+* `#to_s` — Returns the string representation.
+* `#base_name` — Returns the name without state modifier or terminal marker.
+* `#enhanced?` — Returns `true` if piece has enhanced state (`+` prefix).
+* `#diminished?` — Returns `true` if piece has diminished state (`-` prefix).
+* `#normal?` — Returns `true` if piece has normal state (no prefix).
+* `#terminal?` — Returns `true` if piece is a terminal piece (`^` suffix).
+* `#first_player?` — Returns `true` if piece belongs to first player (uppercase).
+* `#second_player?` — Returns `true` if piece belongs to second player (lowercase).
+* `#same_base_name?(other)` — Returns `true` if both pieces have same base name.
+* `#==`, `#eql?`, `#hash` — Value-based equality.
 
 ## Development
-
 ```sh
 # Clone the repository
 git clone https://github.com/sashite/pnn.rb.git
@@ -240,4 +293,4 @@ Available as open source under the [MIT License](https://opensource.org/licenses
 
 ## About
 
-Maintained by [Sashité](https://sashite.com/) â€" promoting chess variants and sharing the beauty of board game cultures.
+Maintained by [Sashité](https://sashite.com/) — promoting chess variants and sharing the beauty of board game cultures.

data/lib/sashite/pnn/name.rb

@@ -6,13 +6,14 @@ module Sashite
     #
     # 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, encoding piece identity, player assignment,
-    # and state in a human-readable format.
+    # 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/
+      PNN_PATTERN = /\A([+-]?)([A-Z]+|[a-z]+)(\^?)\z/
 
       # Error messages
       ERROR_INVALID_NAME = "Invalid PNN string: %s"
@@ -22,7 +23,7 @@ module Sashite
 
       # Create a new piece name instance
       #
-      # @param name [String, Symbol] the piece name (e.g., "KING", :queen, "+ROOK", "-pawn")
+      # @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
@@ -40,8 +41,10 @@ module Sashite
       # @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("+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
@@ -55,6 +58,7 @@ module Sashite
       #   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)
@@ -75,14 +79,16 @@ module Sashite
         value
       end
 
-      # Returns the base name without state modifier
+      # Returns the base name without state modifier or terminal marker
       #
-      # @return [String] the piece name without + or - prefix
+      # @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("+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
@@ -92,8 +98,9 @@ module Sashite
       # @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
+      #   Sashite::Pnn::Name.parse("KING").enhanced?     # => false
+      #   Sashite::Pnn::Name.parse("+KING^").enhanced?   # => true
       def enhanced?
         @parsed[:state_modifier] == "+"
       end
@@ -103,8 +110,9 @@ module Sashite
       # @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
+      #   Sashite::Pnn::Name.parse("pawn").diminished?   # => false
+      #   Sashite::Pnn::Name.parse("-pawn^").diminished? # => true
       def diminished?
         @parsed[:state_modifier] == "-"
       end
@@ -114,19 +122,34 @@ module Sashite
       # @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
+      #   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
+      #   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
@@ -136,13 +159,14 @@ module Sashite
       # @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
+      #   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 and state)
+      # 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
@@ -151,9 +175,11 @@ module Sashite
       #   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?(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)
 
@@ -187,8 +213,9 @@ module Sashite
       def parse_components(str)
         match = str.match(PNN_PATTERN)
         {
-          state_modifier: match[1],
-          base_name:      match[2]
+          state_modifier:  match[1],
+          base_name:       match[2],
+          terminal_marker: match[3]
         }
       end
     end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: sashite-pnn
 version: !ruby/object:Gem::Version
-  version: 3.0.0
+  version: 3.1.0
 platform: ruby
 authors:
 - Cyril Kato
@@ -13,9 +13,10 @@ description: |
   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 (e.g., "KING", "queen",
-  "+ROOK", "-pawn") to unambiguously refer to game pieces across variants and traditions.
-  Ideal for engines, protocols, and tools that need clear and extensible piece identifiers.
+  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: []
@@ -50,7 +51,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.7.1
+rubygems_version: 3.7.2
 specification_version: 4
 summary: PNN (Piece Name Notation) implementation for Ruby with immutable piece name
   objects