sashite-epin 2.0.0 → 2.2.0

data/lib/sashite/epin.rb

@@ -1,224 +1,80 @@
 # frozen_string_literal: true
 
+require "sashite/pin"
+
+require_relative "epin/constants"
+require_relative "epin/errors"
 require_relative "epin/identifier"
+require_relative "epin/parser"
 
 module Sashite
-  # EPIN (Extended Piece Identifier Notation) implementation for Ruby
-  #
-  # Extends PIN (Piece Identifier Notation) with a derivation marker to track piece style
-  # in cross-style games. EPIN is simply: PIN + optional style derivation marker (').
-  #
-  # ## Core Concept
-  #
-  # EPIN addresses the need to distinguish between:
-  # - **Native pieces**: Using their own side's native style (no marker)
-  # - **Derived pieces**: Using the opponent's native style (marked with ')
-  #
-  # This distinction is essential for cross-style games where different players use
-  # different game traditions (e.g., Chess vs Makruk, Chess vs Shogi).
-  #
-  # ## Pure Composition
-  #
-  # EPIN doesn't reimplement PIN - it's pure composition:
-  #
-  #   EPIN = PIN + derived flag
-  #
-  # All piece attributes (name, side, state, terminal) come from the PIN component.
-  # EPIN adds only the 5th attribute: piece style (native vs derived).
-  #
-  # ## Minimal API
-  #
-  # Module-level methods (3 total):
-  # 1. valid?(epin_string) - validate EPIN string
-  # 2. parse(epin_string) - parse into Identifier
-  # 3. new(pin, derived: false) - create from PIN component
-  #
-  # ## Five Fundamental Attributes
-  #
-  # EPIN represents all five piece attributes from the Sashité Game Protocol:
-  #
-  # From PIN component (4 attributes):
-  # - **Piece Name**: epin.pin.type
-  # - **Piece Side**: epin.pin.side
-  # - **Piece State**: epin.pin.state
-  # - **Terminal Status**: epin.pin.terminal?
-  #
-  # From EPIN (5th attribute):
-  # - **Piece Style**: epin.derived? (native vs derived)
-  #
-  # ## Format Structure
-  #
-  # Structure: `<pin>[']`
-  #
-  # Grammar (BNF):
-  #   <epin> ::= <pin> | <pin> "'"
-  #   <pin> ::= ["+" | "-"] <letter> ["^"]
-  #   <letter> ::= "A" | ... | "Z" | "a" | ... | "z"
-  #
-  # Regular Expression: `/\A[-+]?[A-Za-z]\^?'?\z/`
-  #
-  # ## Semantics
-  #
-  # ### Native vs Derived
-  #
-  # In cross-style games (e.g., Chess vs Makruk):
-  # - First player's native style: Chess
-  # - Second player's native style: Makruk
-  #
-  # Then:
-  # - "K" = First player king in Chess style (native)
-  # - "K'" = First player king in Makruk style (derived from opponent)
-  # - "k" = Second player king in Makruk style (native)
-  # - "k'" = Second player king in Chess style (derived from opponent)
+  # EPIN (Extended Piece Identifier Notation) implementation for Ruby.
   #
-  # ### Backward Compatibility
+  # EPIN extends PIN with an optional derivation marker (') that flags
+  # whether a piece uses a native or derived style.
   #
-  # Every valid PIN token is a valid EPIN token:
-  # - "K" is valid PIN and valid EPIN (native)
-  # - "+R^" is valid PIN and valid EPIN (native)
-  # - All PIN semantics preserved
+  # == Format
   #
-  # EPIN extends PIN by adding the optional derivation marker:
-  # - "K'" is valid EPIN (derived)
-  # - "+R^'" is valid EPIN (enhanced, terminal, derived)
+  #   <pin>[']
   #
-  # ## Examples
+  # - *PIN*: Any valid PIN token (abbr, side, state, terminal)
+  # - *Derivation marker*: <tt>'</tt> (derived) or absent (native)
   #
-  # ### Basic Usage
+  # == Examples
   #
-  #   # Parse EPIN strings
-  #   native = Sashite::Epin.parse("K^")      # Native king
-  #   derived = Sashite::Epin.parse("K^'")    # Derived king
+  #   epin = Sashite::Epin.parse("K^'")
+  #   epin.pin.abbr      # => :K
+  #   epin.pin.side      # => :first
+  #   epin.pin.terminal? # => true
+  #   epin.derived?      # => true
   #
-  #   # Access attributes via PIN component
-  #   native.pin.type       # => :K
-  #   native.pin.terminal?  # => true
-  #   native.derived?       # => false
+  #   epin = Sashite::Epin.parse("+R")
+  #   epin.to_s  # => "+R"
   #
-  #   # Create from PIN component
-  #   pin = Sashite::Pin.parse("K^")
-  #   epin = Sashite::Epin.new(pin, derived: false)
-  #   epin.to_s             # => "K^"
+  #   Sashite::Epin.valid?("K^'")     # => true
+  #   Sashite::Epin.valid?("invalid") # => false
   #
-  # ### Transformations
-  #
-  #   epin = Sashite::Epin.parse("K^")
-  #
-  #   # Mark as derived
-  #   derived = epin.mark_derived
-  #   derived.to_s          # => "K^'"
-  #
-  #   # Transform PIN component
-  #   queen = epin.with_pin(epin.pin.with_type(:Q))
-  #   queen.to_s            # => "Q^"
-  #
-  #   # Transform both
-  #   derived_queen = epin
-  #     .with_pin(epin.pin.with_type(:Q))
-  #     .mark_derived
-  #   derived_queen.to_s    # => "Q^'"
-  #
-  # ### Cross-Style Games
-  #
-  #   # Chess vs Makruk match
-  #   # First player = Chess, Second player = Makruk
-  #
-  #   chess_king = Sashite::Epin.parse("K^")     # Native Chess king
-  #   makruk_pawn = Sashite::Epin.parse("P'")    # Derived Makruk pawn
-  #
-  #   chess_king.native?       # => true (uses Chess style)
-  #   makruk_pawn.derived?     # => true (uses Makruk style)
-  #
-  # ## Design Properties
-  #
-  # - **Rule-agnostic**: Independent of game mechanics
-  # - **Pure composition**: Extends PIN minimally (PIN + derived flag)
-  # - **Minimal API**: Only 3 module methods, 6 instance methods
-  # - **Component transparency**: Direct PIN access via epin.pin
-  # - **Backward compatible**: All PIN tokens are valid EPIN tokens
-  # - **Immutable**: All instances frozen, transformations return new objects
-  # - **Type-safe**: Full PIN type preservation
-  # - **Style-aware**: Tracks native vs derived pieces
-  # - **Compact**: Single character overhead for style information
-  #
-  # @see https://sashite.dev/specs/epin/1.0.0/ EPIN Specification v1.0.0
-  # @see https://sashite.dev/specs/epin/1.0.0/examples/ EPIN Examples
-  # @see https://sashite.dev/specs/pin/1.0.0/ PIN Specification (base component)
+  # @see https://sashite.dev/specs/epin/1.0.0/
   module Epin
-    # Check if a string is a valid EPIN notation
+    # Parses an EPIN string into an Identifier.
     #
-    # Validates both the EPIN format and the underlying PIN component.
+    # @param string [String] The EPIN string to parse
+    # @return [Identifier] A new Identifier instance
+    # @raise [Errors::Argument] If the string is not a valid EPIN
     #
-    # @param epin_string [String] the string to validate
-    # @return [Boolean] true if valid EPIN, false otherwise
+    # @example
+    #   Sashite::Epin.parse("K")
+    #   # => #<Sashite::Epin::Identifier K>
     #
-    # @example Validate EPIN strings
-    #   Sashite::Epin.valid?("K^")     # => true (valid PIN, native)
-    #   Sashite::Epin.valid?("K^'")    # => true (valid PIN with derivation)
-    #   Sashite::Epin.valid?("+R'")    # => true (enhanced derived rook)
-    #   Sashite::Epin.valid?("K^''")   # => false (multiple markers)
-    #   Sashite::Epin.valid?("KK'")    # => false (invalid PIN part)
-    #   Sashite::Epin.valid?("invalid") # => false (invalid format)
-    def self.valid?(epin_string)
-      Identifier.valid?(epin_string)
-    end
-
-    # Parse an EPIN string into an Identifier object
-    #
-    # Creates a new EPIN identifier by parsing the string, extracting the PIN part
-    # and derivation marker, validating the PIN component, and creating an identifier
-    # with the appropriate derivation status.
+    #   Sashite::Epin.parse("K^'")
+    #   # => #<Sashite::Epin::Identifier K^'>
     #
-    # @param epin_string [String] EPIN notation string (format: <pin>['])
-    # @return [Epin::Identifier] parsed identifier with PIN component and derivation flag
-    # @raise [ArgumentError] if the EPIN string is invalid
-    #
-    # @example Parse different EPIN formats
-    #   Sashite::Epin.parse("K^")   # => Native king, terminal
-    #   Sashite::Epin.parse("K^'")  # => Derived king, terminal
-    #   Sashite::Epin.parse("+R")   # => Native rook, enhanced
-    #   Sashite::Epin.parse("+R'")  # => Derived rook, enhanced
-    #   Sashite::Epin.parse("-p")   # => Native pawn, diminished
-    #
-    # @example Access all five attributes
-    #   epin = Sashite::Epin.parse("+R^'")
-    #   epin.pin.type       # => :R (Piece Name)
-    #   epin.pin.side       # => :first (Piece Side)
-    #   epin.pin.state      # => :enhanced (Piece State)
-    #   epin.pin.terminal?  # => true (Terminal Status)
-    #   epin.derived?       # => true (Piece Style)
-    def self.parse(epin_string)
-      Identifier.parse(epin_string)
+    #   Sashite::Epin.parse("invalid")
+    #   # => raises Errors::Argument
+    def self.parse(string)
+      components = Parser.parse(string)
+
+      pin = ::Sashite::Pin::Identifier.new(
+        components[:pin][:abbr],
+        components[:pin][:side],
+        components[:pin][:state],
+        terminal: components[:pin][:terminal]
+      )
+
+      Identifier.new(pin, derived: components[:derived])
     end
 
-    # Create a new identifier from a PIN component and derivation flag
-    #
-    # Constructs an EPIN identifier by combining a PIN component (which provides
-    # the four base attributes: name, side, state, terminal) with a derivation flag
-    # (which provides the fifth attribute: style).
-    #
-    # @param pin [Pin::Identifier] PIN component providing base attributes
-    # @param derived [Boolean] whether the piece uses derived style (default: false)
-    # @return [Epin::Identifier] new immutable identifier instance
-    # @raise [ArgumentError] if pin is not a Pin::Identifier
-    #
-    # @example Create identifiers from PIN components
-    #   pin = Sashite::Pin.parse("K^")
-    #   native = Sashite::Epin.new(pin, derived: false)
-    #   native.to_s         # => "K^"
-    #
-    #   derived = Sashite::Epin.new(pin, derived: true)
-    #   derived.to_s        # => "K^'"
+    # Checks if a string is a valid EPIN notation.
     #
-    # @example Cross-style game setup
-    #   # First player uses Chess style, second uses Makruk style
-    #   chess_king = Sashite::Epin.new(Sashite::Pin.parse("K^"), derived: false)
-    #   makruk_pawn = Sashite::Epin.new(Sashite::Pin.parse("P"), derived: true)
+    # @param string [String] The string to validate
+    # @return [Boolean] true if valid, false otherwise
     #
-    #   chess_king.native?    # => true (uses own Chess style)
-    #   makruk_pawn.derived?  # => true (uses opponent's Makruk style)
-    def self.new(pin, derived: false)
-      Identifier.new(pin, derived: derived)
+    # @example
+    #   Sashite::Epin.valid?("K")        # => true
+    #   Sashite::Epin.valid?("K^'")      # => true
+    #   Sashite::Epin.valid?("invalid")  # => false
+    def self.valid?(string)
+      Parser.valid?(string)
     end
   end
 end

data/lib/sashite-epin.rb

@@ -1,14 +1,3 @@
 # frozen_string_literal: true
 
 require_relative "sashite/epin"
-
-# 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-epin
 version: !ruby/object:Gem::Version
-  version: 2.0.0
+  version: 2.2.0
 platform: ruby
 authors:
 - Cyril Kato
@@ -15,32 +15,32 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 3.2.0
+        version: 4.1.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 3.2.0
+        version: 4.1.0
 description: |
-  EPIN (Extended Piece Identifier Notation) extends PIN to provide style-aware piece representation
-  in abstract strategy board games. This gem implements the EPIN Specification v1.0.0 with
-  a modern Ruby interface featuring immutable identifier objects and functional programming
-  principles. EPIN 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.
+  EPIN (Extended Piece Identifier Notation) implementation for Ruby.
+  Extends PIN by adding a derivation marker to track piece style in cross-style
+  abstract strategy board games with a minimal compositional API.
 email: contact@cyril.email
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- LICENSE.md
 - README.md
 - lib/sashite-epin.rb
 - lib/sashite/epin.rb
+- lib/sashite/epin/constants.rb
+- lib/sashite/epin/errors.rb
+- lib/sashite/epin/errors/argument.rb
+- lib/sashite/epin/errors/argument/messages.rb
 - lib/sashite/epin/identifier.rb
+- lib/sashite/epin/parser.rb
 homepage: https://github.com/sashite/epin.rb
 licenses:
 - MIT
@@ -65,7 +65,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: EPIN (Extended Piece Identifier Notation) implementation for Ruby extending
   PIN with style derivation markers.

data/LICENSE.md

@@ -1,21 +0,0 @@
-# The MIT License
-
-Copyright (c) 2025 Sashité
-
-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.