sashite-qpi 2.0.0 → 2.1.0

data/lib/sashite/qpi.rb

@@ -1,135 +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 complete piece identification by combining two primitive notations:
-  # - SIN (Style Identifier Notation) — identifies the piece style
-  # - PIN (Piece Identifier Notation) — identifies the piece attributes
+  # 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
   #
-  # A QPI identifier is simply a pair of (SIN, PIN) with one constraint:
-  # both components must represent the same player.
+  # == Format
   #
-  # ## Core Concept
+  #   <sin>:<pin>
   #
-  # QPI is pure composition:
+  # - *SIN*: Single ASCII letter encoding Piece Style and a side tag
+  # - *PIN*: Piece identifier with optional state modifier and terminal marker
   #
-  #   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
+  # == Piece Identity Attributes
   #
-  # All piece attributes come from the components.
+  # A QPI token encodes complete Piece Identity:
   #
-  # ## Five Fundamental Attributes
+  # - *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 (^)
   #
-  # 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?
+  # == Native/Derived Relationship
   #
-  # ## Format Specification
+  # QPI defines a deterministic relationship based on case comparison:
   #
-  # Structure: `<sin>:<pin>`
+  # - *Native*: SIN case matches PIN case (sin.side == pin.side)
+  # - *Derived*: SIN case differs from PIN case (sin.side != pin.side)
   #
-  # 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> ["^"]
+  # == Examples
   #
-  # Regular Expression: `/\A([A-Z]:[-+]?[A-Z]\^?|[a-z]:[-+]?[a-z]\^?)\z/`
-  #
-  # ## Semantic Constraint
-  #
-  # 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
-  #
-  #   # 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)
-  #
-  #   # Create from components
-  #   sin = Sashite::Sin.parse("S")
-  #   pin = Sashite::Pin.parse("+R^")
-  #   qpi = Sashite::Qpi.new(sin, pin)
-  #   qpi.to_s              # => "S:+R^"
-  #
-  #   # Transform via components
-  #   qpi.with_sin(qpi.sin.with_family(:C))     # => "C:+R^"
-  #   qpi.with_pin(qpi.pin.with_type(:B))       # => "S:+B^"
+  #   qpi.sin.style      # => :C
+  #   qpi.pin.type       # => :K
+  #   qpi.pin.side       # => :first
+  #   qpi.pin.state      # => :normal
+  #   qpi.pin.terminal?  # => true
+  #   qpi.native?        # => true
   #
-  #   # Flip both components (only convenience method)
-  #   qpi.flip              # => "s:+r^"
+  #   qpi = Sashite::Qpi.parse("C:k")
+  #   qpi.derived?  # => true
+  #   qpi.native.to_s  # => "C:K"
   #
-  # ## Design Properties
+  #   Sashite::Qpi.valid?("C:K^")     # => true
+  #   Sashite::Qpi.valid?("invalid")  # => false
   #
-  # - **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/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.
     #
-    # @param qpi_string [String] the string to validate
-    # @return [Boolean] true if valid QPI, false otherwise
+    # @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
     #
     # @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
+    #   Sashite::Qpi.parse("C:K")
+    #   # => #<Sashite::Qpi::Identifier C:K>
     #
-    # @param qpi_string [String] QPI notation string (format: sin:pin)
-    # @return [Qpi::Identifier] identifier with sin and pin components
-    # @raise [ArgumentError] if invalid or semantically inconsistent
+    #   Sashite::Qpi.parse("s:+r^")
+    #   # => #<Sashite::Qpi::Identifier s:+r^>
     #
-    # @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)
+    #   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 from SIN and PIN components
+    # Checks if a string is a valid QPI notation.
     #
-    # @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
+    # @param string [String] The string to validate
+    # @return [Boolean] true if valid, false otherwise
     #
     # @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)
+    #   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: 2.0.0
+  version: 2.1.0
 platform: ruby
 authors:
 - Cyril Kato
@@ -15,56 +15,57 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 3.2.0
+        version: 4.0.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 3.2.0
+        version: 4.0.0
 - !ruby/object:Gem::Dependency
   name: sashite-sin
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 2.1.0
+        version: 3.0.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        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
-  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.2
+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.