sashite-qpi 1.0.0 → 2.1.0

data/lib/sashite/qpi/parser.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+require "sashite/sin"
+require "sashite/pin"
+
+require_relative "constants"
+require_relative "errors"
+
+module Sashite
+  module Qpi
+    # Parser for QPI (Qualified Piece Identifier) strings.
+    #
+    # This parser splits the QPI string on the colon separator and delegates
+    # parsing of each component to the SIN and PIN libraries.
+    #
+    # @example
+    #   Parser.parse("C:K")   # => { sin: <Sin::Identifier>, pin: <Pin::Identifier> }
+    #   Parser.parse("s:+r^") # => { sin: <Sin::Identifier>, pin: <Pin::Identifier> }
+    #
+    # @see https://sashite.dev/specs/qpi/1.0.0/
+    module Parser
+      # Parses a QPI string into its components.
+      #
+      # @param input [String] The QPI string to parse
+      # @return [Hash] A hash with :sin and :pin keys containing Identifier instances
+      # @raise [Errors::Argument] If the input is not a valid QPI string
+      def self.parse(input)
+        validate_input_type(input)
+        validate_not_empty(input)
+
+        sin_string, pin_string = split_components(input)
+
+        sin = parse_sin(sin_string)
+        pin = parse_pin(pin_string)
+
+        { sin: sin, pin: pin }
+      end
+
+      # Validates a QPI string without raising an exception.
+      #
+      # @param input [String] The QPI string to validate
+      # @return [Boolean] true if valid, false otherwise
+      def self.valid?(input)
+        return false unless ::String === input
+
+        parse(input)
+        true
+      rescue Errors::Argument
+        false
+      end
+
+      class << self
+        private
+
+        # Validates that input is a String.
+        #
+        # @param input [Object] The input to validate
+        # @raise [Errors::Argument] If input is not a String
+        def validate_input_type(input)
+          return if ::String === input
+
+          raise Errors::Argument, Errors::Argument::Messages::EMPTY_INPUT
+        end
+
+        # Validates that input is not empty.
+        #
+        # @param input [String] The input to validate
+        # @raise [Errors::Argument] If input is empty
+        def validate_not_empty(input)
+          return unless input.empty?
+
+          raise Errors::Argument, Errors::Argument::Messages::EMPTY_INPUT
+        end
+
+        # Splits the input into SIN and PIN components.
+        #
+        # @param input [String] The QPI string to split
+        # @return [Array<String>] An array with [sin_string, pin_string]
+        # @raise [Errors::Argument] If the separator is missing or components are empty
+        def split_components(input)
+          unless input.include?(Constants::SEPARATOR)
+            raise Errors::Argument, Errors::Argument::Messages::MISSING_SEPARATOR
+          end
+
+          sin_string, pin_string = input.split(Constants::SEPARATOR, 2)
+
+          if sin_string.nil? || sin_string.empty?
+            raise Errors::Argument, Errors::Argument::Messages::MISSING_SIN
+          end
+
+          if pin_string.nil? || pin_string.empty?
+            raise Errors::Argument, Errors::Argument::Messages::MISSING_PIN
+          end
+
+          [sin_string, pin_string]
+        end
+
+        # Parses the SIN component.
+        #
+        # @param sin_string [String] The SIN string to parse
+        # @return [Sashite::Sin::Identifier] The parsed SIN identifier
+        # @raise [Errors::Argument] If the SIN is invalid
+        def parse_sin(sin_string)
+          Sashite::Sin.parse(sin_string)
+        rescue ::ArgumentError => e
+          raise Errors::Argument, "#{Errors::Argument::Messages::INVALID_SIN}: #{e.message}"
+        end
+
+        # Parses the PIN component.
+        #
+        # @param pin_string [String] The PIN string to parse
+        # @return [Sashite::Pin::Identifier] The parsed PIN identifier
+        # @raise [Errors::Argument] If the PIN is invalid
+        def parse_pin(pin_string)
+          Sashite::Pin.parse(pin_string)
+        rescue ::ArgumentError => e
+          raise Errors::Argument, "#{Errors::Argument::Messages::INVALID_PIN}: #{e.message}"
+        end
+      end
+    end
+  end
+end

data/lib/sashite/qpi.rb

@@ -1,220 +1,92 @@
 # frozen_string_literal: true
 
+require_relative "qpi/constants"
+require_relative "qpi/errors"
 require_relative "qpi/identifier"
+require_relative "qpi/parser"
 
 module Sashite
-  # QPI (Qualified Piece Identifier) implementation for Ruby
+  # 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.
+  # QPI provides complete piece identification by combining two primitive notations:
+  # - SIN (Style Identifier Notation) for Piece Style
+  # - PIN (Piece Identifier Notation) for Piece Name, Side, State, and Terminal Status
   #
-  # ## Concept
+  # == Format
   #
-  # 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.
+  #   <sin>:<pin>
   #
-  # ## Four Fundamental Attributes
+  # - *SIN*: Single ASCII letter encoding Piece Style and a side tag
+  # - *PIN*: Piece identifier with optional state modifier and terminal marker
   #
-  # 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
+  # == Piece Identity Attributes
   #
-  # ## Format Structure
+  # A QPI token encodes complete Piece Identity:
   #
-  # 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
+  # - *Piece Style* → SIN letter (case-insensitive identity)
+  # - *Piece Name* → PIN letter (case-insensitive identity)
+  # - *Piece Side* → PIN letter case (uppercase = first, lowercase = second)
+  # - *Piece State* → PIN modifier (+/-)
+  # - *Terminal Status* → PIN marker (^)
   #
-  # The components must maintain semantic consistency: both SIN and PIN must represent
-  # the same player (first or second) through their respective case encodings.
+  # == Native/Derived Relationship
   #
-  # ## Semantic Consistency Constraint
+  # QPI defines a deterministic relationship based on case comparison:
   #
-  # 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.
+  # - *Native*: SIN case matches PIN case (sin.side == pin.side)
+  # - *Derived*: SIN case differs from PIN case (sin.side != pin.side)
   #
-  # 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
+  # == Examples
   #
-  # ## Cross-Style Gaming Support
+  #   qpi = Sashite::Qpi.parse("C:K^")
+  #   qpi.sin.style      # => :C
+  #   qpi.pin.type       # => :K
+  #   qpi.pin.side       # => :first
+  #   qpi.pin.state      # => :normal
+  #   qpi.pin.terminal?  # => true
+  #   qpi.native?        # => true
   #
-  # 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 = Sashite::Qpi.parse("C:k")
+  #   qpi.derived?  # => true
+  #   qpi.native.to_s  # => "C:K"
   #
-  # ## Format Specification
+  #   Sashite::Qpi.valid?("C:K^")     # => true
+  #   Sashite::Qpi.valid?("invalid")  # => false
   #
-  # Structure: `<sin>:<pin>`
-  #
-  # Grammar (BNF):
-  #   <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/`
-  #
-  # ## Attribute Mapping
-  #
-  # QPI encodes piece attributes through primitive combination:
-  #
-  # | 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
-  #
-  # ## 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
-  #
-  #   # 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
-  #
-  #   # Verify cross-style scenario
-  #   chess_player.cross_family?(ogi_player)   # => true
-  #
-  # ### 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"
-  #
-  # ## 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
-  #
-  # @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)
+  # @see https://sashite.dev/specs/qpi/1.0.0/
   module Qpi
-    # Check if a string is a valid QPI notation
+    # Parses a QPI string into an Identifier.
     #
-    # 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 string [String] The QPI string to parse
+    # @return [Identifier] A new Identifier instance
+    # @raise [Errors::Argument] If the string is not a valid QPI
     #
-    # @param qpi_string [String] the string to validate
-    # @return [Boolean] true if valid QPI, false otherwise
+    # @example
+    #   Sashite::Qpi.parse("C:K")
+    #   # => #<Sashite::Qpi::Identifier C:K>
     #
-    # @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)
-    def self.valid?(qpi_string)
-      Identifier.valid?(qpi_string)
-    end
-
-    # Parse a QPI string into an Identifier object
+    #   Sashite::Qpi.parse("s:+r^")
+    #   # => #<Sashite::Qpi::Identifier s:+r^>
     #
-    # 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>
-    #
-    # @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
-    def self.parse(qpi_string)
-      Identifier.parse(qpi_string)
+    #   Sashite::Qpi.parse("invalid")
+    #   # => raises Errors::Argument
+    def self.parse(string)
+      components = Parser.parse(string)
+
+      Identifier.new(components[:sin], components[:pin])
     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"
+    # Checks if a string is a valid QPI notation.
     #
-    # @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 string [String] The string to validate
+    # @return [Boolean] true if valid, false otherwise
     #
-    #   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
+    #   Sashite::Qpi.valid?("C:K")       # => true
+    #   Sashite::Qpi.valid?("s:+r^")     # => true
+    #   Sashite::Qpi.valid?("invalid")   # => false
+    def self.valid?(string)
+      Parser.valid?(string)
     end
   end
 end

data/lib/sashite-qpi.rb

@@ -1,14 +1,3 @@
 # frozen_string_literal: true
 
 require_relative "sashite/qpi"
-
-# 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
-end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: sashite-qpi
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 2.1.0
 platform: ruby
 authors:
 - Cyril Kato
@@ -15,56 +15,57 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.1'
+        version: 4.0.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.1'
+        version: 4.0.0
 - !ruby/object:Gem::Dependency
   name: sashite-sin
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.1'
+        version: 3.0.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.1'
-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
-  Identifier Notation (PIN) primitives. This gem implements the QPI Specification v1.0.0 with
-  a modern Ruby interface featuring immutable identifier objects and functional programming
-  principles. QPI enables complete piece identification with all four fundamental attributes
-  (family, type, side, state) while supporting cross-style gaming environments. Perfect for
-  multi-tradition board games, hybrid gaming systems, and game engines requiring comprehensive
-  piece identification across different game styles and traditions.
+        version: 3.0.0
+description: QPI (Qualified Piece Identifier) implementation for Ruby. Provides a
+  rule-agnostic format for complete piece identification in abstract strategy board
+  games by combining SIN and PIN primitives, with Native/Derived relationship support.
 email: contact@cyril.email
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- LICENSE.md
+- LICENSE
 - README.md
 - lib/sashite-qpi.rb
 - lib/sashite/qpi.rb
+- lib/sashite/qpi/constants.rb
+- lib/sashite/qpi/errors.rb
+- lib/sashite/qpi/errors/argument.rb
+- lib/sashite/qpi/errors/argument/messages.rb
 - lib/sashite/qpi/identifier.rb
+- lib/sashite/qpi/parser.rb
 homepage: https://github.com/sashite/qpi.rb
 licenses:
-- MIT
+- Apache-2.0
 metadata:
   bug_tracker_uri: https://github.com/sashite/qpi.rb/issues
   documentation_uri: https://rubydoc.info/github/sashite/qpi.rb/main
   homepage_uri: https://github.com/sashite/qpi.rb
   source_code_uri: https://github.com/sashite/qpi.rb
   specification_uri: https://sashite.dev/specs/qpi/1.0.0/
+  wiki_uri: https://sashite.dev/specs/qpi/1.0.0/examples/
+  funding_uri: https://github.com/sponsors/sashite
   rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths:
@@ -80,7 +81,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.7.1
+rubygems_version: 4.0.3
 specification_version: 4
 summary: QPI (Qualified Piece Identifier) implementation for Ruby with immutable identifier
   objects

data/LICENSE.md

@@ -1,22 +0,0 @@
-Copyright (c) 2014-2025 Sashite
-
-MIT License
-
-Permission is hereby granted, free of charge, to any person obtaining
-a copy of this software and associated documentation files (the
-"Software"), to deal in the Software without restriction, including
-without limitation the rights to use, copy, modify, merge, publish,
-distribute, sublicense, and/or sell copies of the Software, and to
-permit persons to whom the Software is furnished to do so, subject to
-the following conditions:
-
-The above copyright notice and this permission notice shall be
-included in all copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
-EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
-MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
-NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
-LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
-OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
-WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.