sashite-qpi 1.0.0 → 2.0.0

data/lib/sashite/qpi.rb

@@ -5,54 +5,34 @@ require_relative "qpi/identifier"
 module Sashite
   # QPI (Qualified Piece Identifier) implementation for Ruby
   #
-  # Provides a rule-agnostic format for identifying game pieces in abstract strategy board games
-  # by combining Style Identifier Notation (SIN) and Piece Identifier Notation (PIN) primitives
-  # with a colon separator. This combination enables complete piece identification across different
-  # game styles and contexts.
+  # Provides complete piece identification by combining two primitive notations:
+  # - SIN (Style Identifier Notation) — identifies the piece style
+  # - PIN (Piece Identifier Notation) — identifies the piece attributes
   #
-  # ## Concept
+  # A QPI identifier is simply a pair of (SIN, PIN) with one constraint:
+  # both components must represent the same player.
   #
-  # QPI addresses the fundamental need to uniquely identify game pieces across different style
-  # systems while maintaining complete attribute information. By combining SIN and PIN primitives,
-  # QPI provides explicit representation of all four fundamental piece attributes from the
-  # Sashité Protocol.
+  # ## Core Concept
   #
-  # ## Four Fundamental Attributes
+  # QPI is pure composition:
   #
-  # QPI represents all four piece attributes through primitive combination:
-  # - **Family**: Style identification from SIN component
-  # - **Type**: Piece type from PIN component
-  # - **Side**: Player assignment from both components (must be consistent)
-  # - **State**: Piece state from PIN component
+  #   sin = Sashite::Sin.parse("C")
+  #   pin = Sashite::Pin.parse("K^")
+  #   qpi = Sashite::Qpi.new(sin, pin)
+  #   qpi.to_s  # => "C:K^"
+  #   qpi.sin   # => SIN::Identifier instance
+  #   qpi.pin   # => PIN::Identifier instance
   #
-  # ## Format Structure
+  # All piece attributes come from the components.
   #
-  # A QPI identifier consists of two primitive components separated by a colon:
-  # - **SIN component**: Style identification with player assignment
-  # - **PIN component**: Piece identification with type, side, and state
-  # - **Separator**: Colon (:) provides clear delimitation
+  # ## Five Fundamental Attributes
   #
-  # The components must maintain semantic consistency: both SIN and PIN must represent
-  # the same player (first or second) through their respective case encodings.
-  #
-  # ## Semantic Consistency Constraint
-  #
-  # QPI enforces a critical constraint: the style identified by the SIN component must be
-  # associated with the same player as indicated by the PIN component. This ensures that
-  # piece ownership and style ownership remain aligned, preventing impossible combinations
-  # like a first player style with a second player piece.
-  #
-  # Examples of semantic consistency:
-  # - SIN "C" (first player) + PIN "K" (first player) = Valid
-  # - SIN "c" (second player) + PIN "k" (second player) = Valid
-  # - SIN "C" (first player) + PIN "k" (second player) = Invalid
-  # - SIN "c" (second player) + PIN "K" (first player) = Invalid
-  #
-  # ## Cross-Style Gaming Support
-  #
-  # QPI enables cross-style gaming scenarios where different players use different game
-  # traditions. The explicit style identification allows pieces from different systems
-  # to coexist while maintaining clear attribution to their respective players.
+  # QPI exposes all five attributes from the Sashité Game Protocol:
+  # - **Piece Style** — via qpi.sin.family
+  # - **Piece Name** — via qpi.pin.type
+  # - **Piece Side** — via qpi.sin.side or qpi.pin.side
+  # - **Piece State** — via qpi.pin.state
+  # - **Terminal Status** — via qpi.pin.terminal?
   #
   # ## Format Specification
   #
@@ -62,159 +42,94 @@ module Sashite
   #   <qpi> ::= <uppercase-qpi> | <lowercase-qpi>
   #   <uppercase-qpi> ::= <uppercase-letter> ":" <uppercase-pin>
   #   <lowercase-qpi> ::= <lowercase-letter> ":" <lowercase-pin>
-  #   <uppercase-pin> ::= ["+" | "-"] <uppercase-letter>
-  #   <lowercase-pin> ::= ["+" | "-"] <lowercase-letter>
-  #
-  # Regular Expression: `/\A([A-Z]:[-+]?[A-Z]|[a-z]:[-+]?[a-z])\z/`
+  #   <uppercase-pin> ::= ["+" | "-"] <uppercase-letter> ["^"]
+  #   <lowercase-pin> ::= ["+" | "-"] <lowercase-letter> ["^"]
   #
-  # ## Attribute Mapping
+  # Regular Expression: `/\A([A-Z]:[-+]?[A-Z]\^?|[a-z]:[-+]?[a-z]\^?)\z/`
   #
-  # QPI encodes piece attributes through primitive combination:
+  # ## Semantic Constraint
   #
-  # | Piece Attribute | QPI Encoding | Examples |
-  # |-----------------|--------------|----------|
-  # | **Family** | SIN component | `C:K` = Chess family, `O:K` = Ogi family |
-  # | **Type** | PIN letter choice | `C:K` = King, `C:P` = Pawn |
-  # | **Side** | Component cases | `C:K` = First player, `c:k` = Second player |
-  # | **State** | PIN prefix modifier | `O:+P` = Enhanced, `C:-P` = Diminished |
-  #
-  # ## System Constraints
-  #
-  # - **Semantic Consistency**: SIN and PIN components must represent the same player
-  # - **Component Validation**: Each component must be valid according to its specification
-  # - **Complete Attribution**: All four fundamental piece attributes explicitly represented
-  # - **Cross-Style Support**: Enables multi-tradition gaming environments
+  # The SIN and PIN components must represent the same player:
+  # - Valid: "C:K" (both first player), "c:k" (both second player)
+  # - Invalid: "C:k" (side mismatch), "c:K" (side mismatch)
   #
   # ## Examples
   #
-  # ### Single-Style Games
-  #
-  #   # Chess (both players use Chess style)
-  #   white_king = Sashite::Qpi.parse("C:K")     # Chess king, first player
-  #   black_king = Sashite::Qpi.parse("c:k")     # Chess king, second player
-  #
-  #   # Ogi (both players use Ogi style)
-  #   sente_king = Sashite::Qpi.parse("O:K")     # Ogi king, first player (sente)
-  #   gote_rook  = Sashite::Qpi.parse("o:+r")    # Ogi promoted rook, second player (gote)
-  #
-  # ### Cross-Style Games
+  #   # Parse QPI string
+  #   qpi = Sashite::Qpi.parse("C:K^")
+  #   qpi.sin.family        # => :C (Piece Style)
+  #   qpi.pin.type          # => :K (Piece Name)
+  #   qpi.sin.side          # => :first (Piece Side)
+  #   qpi.pin.state         # => :normal (Piece State)
+  #   qpi.pin.terminal?     # => true (Terminal Status)
   #
-  #   # Chess vs. Ogi match
-  #   chess_player = Sashite::Qpi.parse("C:K")   # First player uses Chess
-  #   ogi_player   = Sashite::Qpi.parse("o:k")   # Second player uses Ogi
+  #   # Create from components
+  #   sin = Sashite::Sin.parse("S")
+  #   pin = Sashite::Pin.parse("+R^")
+  #   qpi = Sashite::Qpi.new(sin, pin)
+  #   qpi.to_s              # => "S:+R^"
   #
-  #   # Verify cross-style scenario
-  #   chess_player.cross_family?(ogi_player)   # => true
+  #   # Transform via components
+  #   qpi.with_sin(qpi.sin.with_family(:C))     # => "C:+R^"
+  #   qpi.with_pin(qpi.pin.with_type(:B))       # => "S:+B^"
   #
-  # ### Attribute Access and Manipulation
-  #
-  #   identifier = Sashite::Qpi.parse("O:+R")
-  #
-  #   # Four fundamental attributes
-  #   identifier.family                           # => :O
-  #   identifier.type                             # => :R
-  #   identifier.side                             # => :first
-  #   identifier.state                            # => :enhanced
-  #
-  #   # Component extraction
-  #   identifier.to_sin                           # => "O"
-  #   identifier.to_pin                           # => "+R"
-  #
-  #   # Immutable transformations
-  #   flipped = identifier.flip                   # => "o:+r"
-  #   different_type = identifier.with_type(:Q)   # => "O:+Q"
-  #   different_family = identifier.with_family(:C) # => "C:+R"
+  #   # Flip both components (only convenience method)
+  #   qpi.flip              # => "s:+r^"
   #
   # ## Design Properties
   #
-  # - **Rule-agnostic**: Independent of specific game mechanics
-  # - **Complete identification**: Explicit representation of all four piece attributes
-  # - **Cross-style support**: Enables multi-tradition gaming environments
-  # - **Semantic validation**: Ensures consistency between style and piece ownership
-  # - **Primitive foundation**: Built from foundational SIN and PIN building blocks
-  # - **Extension-ready**: Can be enhanced by human-readable naming systems
-  # - **Context-flexible**: Adaptable to various identification needs
-  # - **Immutable**: All instances are frozen and transformations return new objects
-  # - **Functional**: Pure functions with no side effects
+  # - **Rule-agnostic**: Independent of game mechanics
+  # - **Pure composition**: Zero feature duplication
+  # - **Minimal API**: Only 5 core methods
+  # - **Component transparency**: Direct primitive access
+  # - **Immutable**: Frozen instances
+  # - **Semantic validation**: Automatic side consistency
   #
   # @see https://sashite.dev/specs/qpi/1.0.0/ QPI Specification v1.0.0
-  # @see https://sashite.dev/specs/qpi/1.0.0/examples/ QPI Examples
   # @see https://sashite.dev/specs/sin/1.0.0/ Style Identifier Notation (SIN)
   # @see https://sashite.dev/specs/pin/1.0.0/ Piece Identifier Notation (PIN)
   module Qpi
     # Check if a string is a valid QPI notation
     #
-    # Validates the string format and semantic consistency between SIN and PIN components.
-    # Both components must be individually valid and represent the same player through
-    # their respective case encodings.
-    #
     # @param qpi_string [String] the string to validate
     # @return [Boolean] true if valid QPI, false otherwise
     #
-    # @example Validate various QPI formats
-    #   Sashite::Qpi.valid?("C:K")      # => true (Chess king, first player)
-    #   Sashite::Qpi.valid?("c:k")      # => true (Chess king, second player)
-    #   Sashite::Qpi.valid?("O:+P")     # => true (Ogi enhanced pawn, first player)
-    #   Sashite::Qpi.valid?("o:-r")     # => true (Ogi diminished rook, second player)
-    #   Sashite::Qpi.valid?("C:k")      # => false (semantic mismatch: first player style, second player piece)
-    #   Sashite::Qpi.valid?("c:K")      # => false (semantic mismatch: second player style, first player piece)
-    #   Sashite::Qpi.valid?("CHESS:K")  # => false (multi-character SIN component)
-    #   Sashite::Qpi.valid?("C")        # => false (missing PIN component)
+    # @example
+    #   Sashite::Qpi.valid?("C:K^")   # => true
+    #   Sashite::Qpi.valid?("C:k")    # => false (side mismatch)
     def self.valid?(qpi_string)
       Identifier.valid?(qpi_string)
     end
 
     # Parse a QPI string into an Identifier object
     #
-    # Creates a new QPI identifier by parsing the string into SIN and PIN components,
-    # validating each component, and ensuring semantic consistency between them.
-    #
     # @param qpi_string [String] QPI notation string (format: sin:pin)
-    # @return [Qpi::Identifier] parsed identifier object with family, type, side, and state attributes
-    # @raise [ArgumentError] if the QPI string is invalid or semantically inconsistent
-    #
-    # @example Parse different QPI formats with complete attribute access
-    #   Sashite::Qpi.parse("C:K")   # => #<Qpi::Identifier family=:C type=:K side=:first state=:normal>
-    #   Sashite::Qpi.parse("c:k")   # => #<Qpi::Identifier family=:C type=:K side=:second state=:normal>
-    #   Sashite::Qpi.parse("O:+R")  # => #<Qpi::Identifier family=:O type=:R side=:first state=:enhanced>
-    #   Sashite::Qpi.parse("x:-s")  # => #<Qpi::Identifier family=:X type=:S side=:second state=:diminished>
+    # @return [Qpi::Identifier] identifier with sin and pin components
+    # @raise [ArgumentError] if invalid or semantically inconsistent
     #
-    # @example Traditional game styles
-    #   chess_king   = Sashite::Qpi.parse("C:K")  # Chess king, first player
-    #   ogi_rook     = Sashite::Qpi.parse("o:+r") # Ogi promoted rook, second player
-    #   xiongqi_king = Sashite::Qpi.parse("X:K")  # Xiongqi king, first player
+    # @example
+    #   qpi = Sashite::Qpi.parse("C:K^")
+    #   qpi.sin.family        # => :C
+    #   qpi.pin.type          # => :K
+    #   qpi.pin.terminal?     # => true
     def self.parse(qpi_string)
       Identifier.parse(qpi_string)
     end
 
-    # Create a new identifier instance with explicit parameters
-    #
-    # Constructs a QPI identifier by directly specifying all four fundamental attributes.
-    # This method provides parameter-based construction as an alternative to string parsing,
-    # enabling immediate validation and clearer API usage.
-    #
-    # @param family [Symbol] style family identifier (single ASCII letter as symbol)
-    # @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 [Qpi::Identifier] new immutable identifier instance
-    # @raise [ArgumentError] if parameters are invalid or semantically inconsistent
-    #
-    # @example Create identifiers with explicit parameters
-    #   Sashite::Qpi.identifier(:C, :K, :first, :normal)     # => "C:K"
-    #   Sashite::Qpi.identifier(:c, :K, :second, :normal)    # => "c:k"
-    #   Sashite::Qpi.identifier(:O, :R, :first, :enhanced)   # => "O:+R"
-    #   Sashite::Qpi.identifier(:x, :S, :second, :diminished) # => "x:-s"
+    # Create a new identifier from SIN and PIN components
     #
-    # @example Cross-style game setup
-    #   chess_player = Sashite::Qpi.identifier(:C, :K, :first, :normal)   # Chess king, first player
-    #   ogi_player   = Sashite::Qpi.identifier(:o, :K, :second, :normal)  # Ogi king, second player
+    # @param sin [Sin::Identifier] SIN component
+    # @param pin [Pin::Identifier] PIN component
+    # @return [Qpi::Identifier] new identifier instance
+    # @raise [ArgumentError] if components have different sides
     #
-    #   chess_player.cross_family?(ogi_player)  # => true (different families)
-    #   chess_player.same_type?(ogi_player)     # => true (both kings)
-    #   chess_player.same_side?(ogi_player)     # => false (different players)
-    def self.identifier(family, type, side, state = Pin::Identifier::NORMAL_STATE)
-      Identifier.new(family, type, side, state)
+    # @example
+    #   sin = Sashite::Sin.parse("C")
+    #   pin = Sashite::Pin.parse("K^")
+    #   qpi = Sashite::Qpi.new(sin, pin)
+    #   qpi.to_s              # => "C:K^"
+    def self.new(sin, pin)
+      Identifier.new(sin, pin)
     end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: sashite-qpi
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 2.0.0
 platform: ruby
 authors:
 - Cyril Kato
@@ -15,28 +15,28 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.1'
+        version: 3.2.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.1'
+        version: 3.2.0
 - !ruby/object:Gem::Dependency
   name: sashite-sin
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.1'
+        version: 2.1.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.1'
+        version: 2.1.0
 description: |
   QPI (Qualified Piece Identifier) provides a rule-agnostic format for identifying game pieces
   in abstract strategy board games by combining Style Identifier Notation (SIN) and Piece
@@ -80,7 +80,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: QPI (Qualified Piece Identifier) implementation for Ruby with immutable identifier
   objects