sashite-epin 2.1.0 → 2.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7d7d828306ad61693e22bc32ebe246c320ee67ca61968eaccb1bca519af89fbd
-  data.tar.gz: 0a254450dc845cd83ca5d5a545d0d267de8e16210871e8b8e69201fc30b62637
+  metadata.gz: 1490d9f28fb1193e779995a461a8af0c569077070fa4d84e698fe368dace28e7
+  data.tar.gz: cd58beb135dd350afc08ab316a9249dad8ba26a5a293a4ce092c705ffe621b94
 SHA512:
-  metadata.gz: 4668940a081b1c6e478f65f651fbf4045d76f04bb459623da4675f47c1ead9410d4b3c627cf0a2e43b1b76dcb4e7aaba7734ab631447b63f72e952293f02dc27
-  data.tar.gz: 306339f389f69cec419b15e5e517e7050bca0d0c3bfb5c3dff4b0d39328215715ab3b11b11b34485a60e9e4808a401cab9ed1fda31dfd437cbccff22f4b680be
+  metadata.gz: b811b8c087a3e98f0f960a316a293c239ebbb423401a33b3b5c45f1ba2533ff9625d5adcf304bba96c220febea73ef0ce139fd2554d1ce2f9555083dfee483b7
+  data.tar.gz: 3366a948b81091c255daa9111de74d6bc1e52a2e2597bd239ca0c834706b8fdc4695d833c5272074835bea397213eee999326cb62768692b6e9df824f0833510

data/README.md

@@ -1,19 +1,17 @@
-# Sashite::Epin
+# epin.rb
 
 [![Version](https://img.shields.io/github/v/tag/sashite/epin.rb?label=Version&logo=github)](https://github.com/sashite/epin.rb/tags)
 [![Yard documentation](https://img.shields.io/badge/Yard-documentation-blue.svg?logo=github)](https://rubydoc.info/github/sashite/epin.rb/main)
-![Ruby](https://github.com/sashite/epin.rb/actions/workflows/main.yml/badge.svg?branch=main)
-[![License](https://img.shields.io/github/license/sashite/epin.rb?label=License&logo=github)](https://github.com/sashite/epin.rb/raw/main/LICENSE.md)
+[![CI](https://github.com/sashite/epin.rb/actions/workflows/ruby.yml/badge.svg?branch=main)](https://github.com/sashite/epin.rb/actions)
+[![License](https://img.shields.io/github/license/sashite/epin.rb?label=License&logo=github)](https://github.com/sashite/epin.rb/raw/main/LICENSE)
 
 > **EPIN** (Extended Piece Identifier Notation) implementation for Ruby.
 
-## What is EPIN?
+## Overview
 
-EPIN (Extended Piece Identifier Notation) extends [PIN](https://sashite.dev/specs/pin/1.0.0/) by adding a **derivation marker** to track piece style in cross-style games.
+This library implements the [EPIN Specification v1.0.0](https://sashite.dev/specs/epin/1.0.0/).
 
-**EPIN is simply: PIN + optional style derivation marker (`'`)**
-
-This gem implements the [EPIN Specification v1.0.0](https://sashite.dev/specs/epin/1.0.0/) with a minimal compositional API.
+EPIN extends [PIN](https://sashite.dev/specs/pin/1.0.0/) with an optional derivation marker (`'`) that flags whether a piece uses a native or derived style.
 
 ## Installation
 
@@ -28,67 +26,67 @@ Or install manually:
 gem install sashite-epin
 ```
 
-This will also install `sashite-pin` as a dependency.
-
-## Core Concept
+## Dependencies
 
 ```ruby
-require "sashite/epin"
-
-# EPIN is just PIN + derived flag
-pin = Sashite::Pin.parse("K^")
-epin = Sashite::Epin.new(pin)
-
-epin.to_s     # => "K^" (native)
-epin.pin      # => #<Sashite::Pin K^>
-epin.derived  # => false
-
-# Mark as derived
-derived_epin = epin.mark_derived
-derived_epin.to_s # => "K^'" (derived from opposite side's style)
+gem "sashite-pin"  # Piece Identifier Notation
 ```
 
-**That's it.** All piece attributes come from the PIN component.
-
 ## Usage
 
+### Parsing (String → Identifier)
+
+Convert an EPIN string into an `Identifier` object.
+
 ```ruby
 require "sashite/epin"
 
-# Parse EPIN strings
+# Standard parsing (raises on error)
 epin = Sashite::Epin.parse("K^'")
-epin.to_s # => "K^'"
+epin.to_s  # => "K^'"
+
+# Access PIN attributes through the component
+epin.pin.abbr       # => :K
+epin.pin.side       # => :first
+epin.pin.state      # => :normal
+epin.pin.terminal?  # => true
 
-# Access five fundamental attributes through PIN component + derived flag
-epin.pin.type       # => :K (Piece Name)
-epin.pin.side       # => :first (Piece Side)
-epin.pin.state      # => :normal (Piece State)
-epin.pin.terminal   # => true (Terminal Status)
-epin.derived        # => true (Piece Style: derived vs native)
+# Access derivation status
+epin.derived?  # => true
+epin.native?   # => false
 
-# PIN component is a full Sashite::Pin instance
+# PIN component is a full Sashite::Pin::Identifier instance
 epin.pin.enhanced?      # => false
-epin.pin.letter         # => "K"
 epin.pin.first_player?  # => true
+
+# Invalid input raises ArgumentError
+Sashite::Epin.parse("invalid")  # => raises ArgumentError
 ```
 
-### Creating Identifiers
+### Formatting (Identifier → String)
 
-```ruby
-# Parse from string
-epin = Sashite::Epin.parse("K^")    # Native
-epin = Sashite::Epin.parse("K^'")   # Derived
+Convert an `Identifier` back to an EPIN string.
 
-# Create from PIN component
+```ruby
+# From PIN component
 pin = Sashite::Pin.parse("K^")
-epin = Sashite::Epin.new(pin)                 # Native (default)
-epin = Sashite::Epin.new(pin, derived: true)  # Derived
-
-# Validation
-Sashite::Epin.valid?("K^")    # => true
-Sashite::Epin.valid?("K^'")   # => true
-Sashite::Epin.valid?("K^''")  # => false (multiple markers)
-Sashite::Epin.valid?("K'^")   # => false (wrong order)
+epin = Sashite::Epin::Identifier.new(pin)
+epin.to_s  # => "K^"
+
+# With derivation
+epin = Sashite::Epin::Identifier.new(pin, derived: true)
+epin.to_s  # => "K^'"
+```
+
+### Validation
+
+```ruby
+# Boolean check
+Sashite::Epin.valid?("K")         # => true
+Sashite::Epin.valid?("+R^'")      # => true
+Sashite::Epin.valid?("invalid")   # => false
+Sashite::Epin.valid?("K''")       # => false
+Sashite::Epin.valid?("K'^")       # => false
 ```
 
 ### Accessing Components
@@ -97,16 +95,15 @@ Sashite::Epin.valid?("K'^")   # => false (wrong order)
 epin = Sashite::Epin.parse("+R^'")
 
 # Get PIN component
-epin.pin         # => #<Sashite::Pin +R^>
-epin.pin.to_s    # => "+R^"
+epin.pin       # => #<Sashite::Pin::Identifier +R^>
+epin.pin.to_s  # => "+R^"
 
 # Check derivation
-epin.derived     # => true
-epin.derived?    # => true
-epin.native?     # => false
+epin.derived?  # => true
+epin.native?   # => false
 
 # Serialize
-epin.to_s # => "+R^'"
+epin.to_s  # => "+R^'"
 ```
 
 ### Transformations
@@ -116,17 +113,13 @@ All transformations return new immutable instances.
 ```ruby
 epin = Sashite::Epin.parse("K^")
 
-# Mark as derived
-derived = epin.mark_derived
-derived.to_s # => "K^'"
-
-# Mark as native
-native = derived.unmark_derived
-native.to_s # => "K^"
+# Derivation transformations
+epin.derive.to_s  # => "K^'"
+epin.native.to_s  # => "K^"
 
-# Set explicitly
-toggled = epin.with_derived(true)
-toggled.to_s # => "K^'"
+# Replace PIN component
+new_pin = Sashite::Pin.parse("+Q^")
+epin.with_pin(new_pin).to_s  # => "+Q^"
 ```
 
 ### Transform via PIN Component
@@ -134,33 +127,17 @@ toggled.to_s # => "K^'"
 ```ruby
 epin = Sashite::Epin.parse("K^'")
 
-# Replace PIN component
-new_pin = epin.pin.with_type(:Q)
-epin.with_pin(new_pin).to_s # => "Q^'"
+# Change abbr
+epin.with_pin(epin.pin.with_abbr(:Q)).to_s  # => "Q^'"
 
 # Change state
-new_pin = epin.pin.enhance
-epin.with_pin(new_pin).to_s # => "+K^'"
-
-# Remove terminal marker
-new_pin = epin.pin.unmark_terminal
-epin.with_pin(new_pin).to_s # => "K'"
+epin.with_pin(epin.pin.enhance).to_s  # => "+K^'"
 
 # Change side
-new_pin = epin.pin.flip
-epin.with_pin(new_pin).to_s # => "k^'"
-```
+epin.with_pin(epin.pin.flip).to_s  # => "k^'"
 
-### Multiple Transformations
-
-```ruby
-epin = Sashite::Epin.parse("K^")
-
-# Transform PIN and derivation
-new_pin = epin.pin.with_type(:Q).enhance
-transformed = epin.with_pin(new_pin).mark_derived
-
-transformed.to_s # => "+Q^'"
+# Remove terminal
+epin.with_pin(epin.pin.non_terminal).to_s  # => "K'"
 ```
 
 ### Component Queries
@@ -170,255 +147,131 @@ Use the PIN API directly:
 ```ruby
 epin = Sashite::Epin.parse("+P^'")
 
-# PIN queries (name, side, state, terminal)
-epin.pin.type                # => :P
-epin.pin.side                # => :first
-epin.pin.state               # => :enhanced
-epin.pin.terminal            # => true
-epin.pin.first_player?       # => true
-epin.pin.enhanced?           # => true
-epin.pin.letter              # => "P"
-epin.pin.prefix              # => "+"
-epin.pin.suffix              # => "^"
-
-# EPIN queries (style)
-epin.derived?                # => true
-epin.native?                 # => false
+# PIN queries
+epin.pin.abbr          # => :P
+epin.pin.side          # => :first
+epin.pin.state         # => :enhanced
+epin.pin.terminal?     # => true
+epin.pin.first_player? # => true
+epin.pin.enhanced?     # => true
+
+# EPIN queries
+epin.derived?  # => true
+epin.native?   # => false
 
 # Compare EPINs
 other = Sashite::Epin.parse("+P^")
-epin.pin.same_type?(other.pin)   # => true (both P)
-epin.pin.same_state?(other.pin)  # => true (both enhanced)
-epin.same_derived?(other)        # => false (different derivation)
-```
-
-## Five Fundamental Attributes
-
-EPIN exposes all five attributes from the [Sashité Game Protocol](https://sashite.dev/game-protocol/):
-
-| Protocol Attribute | EPIN Access | Example |
-|-------------------|-------------|---------|
-| **Piece Name** | `epin.pin.type` | `:K` (King), `:R` (Rook) |
-| **Piece Side** | `epin.pin.side` | `:first`, `:second` |
-| **Piece State** | `epin.pin.state` | `:normal`, `:enhanced`, `:diminished` |
-| **Terminal Status** | `epin.pin.terminal` | `true`, `false` |
-| **Piece Style** | `epin.derived` | `false` (native), `true` (derived) |
-
-## Format Specification
-
-### Structure
-
-```
-<pin>[']
-```
-
-Where:
-- `<pin>` is any valid PIN token
-- `'` is the optional derivation marker
-
-### Grammar (EBNF)
-
-```ebnf
-epin ::= pin | pin "'"
-pin  ::= ["+" | "-"] letter ["^"]
-letter ::= "A" | ... | "Z" | "a" | ... | "z"
-```
-
-### Regular Expression
-
-```ruby
-/\A[-+]?[A-Za-z]\^?'?\z/
-```
-
-### Examples
-
-| EPIN | Side | State | Terminal | Derived | Description |
-|------|------|-------|----------|---------|-------------|
-| `K` | First | Normal | No | No | Standard native king |
-| `K'` | First | Normal | No | Yes | Derived king |
-| `K^` | First | Normal | Yes | No | Terminal native king |
-| `K^'` | First | Normal | Yes | Yes | Terminal derived king |
-| `+R'` | First | Enhanced | No | Yes | Enhanced derived rook |
-| `-p` | Second | Diminished | No | No | Diminished native pawn |
-
-## Cross-Style Game Example
-
-In a chess-vs-makruk cross-style match where:
-- First side native style = chess
-- Second side native style = makruk
-
-```ruby
-# First player pieces
-chess_king = Sashite::Epin.parse("K^")   # Native Chess king
-makruk_pawn = Sashite::Epin.parse("P'")  # Derived Makruk pawn (foreign)
-
-chess_king.native?      # => true (uses own style)
-makruk_pawn.derived?    # => true (uses opponent's style)
-
-# Second player pieces
-makruk_king = Sashite::Epin.parse("k^")  # Native Makruk king
-chess_pawn = Sashite::Epin.parse("p'")   # Derived Chess pawn (foreign)
-
-makruk_king.native?     # => true
-chess_pawn.derived?     # => true
+epin.pin.same_abbr?(other.pin)   # => true
+epin.pin.same_state?(other.pin)  # => true
+epin.same_derived?(other)        # => false
 ```
 
 ## API Reference
 
-### Parsing and Validation
+### Types
 
 ```ruby
-Sashite::Epin.parse(epin_string)  # => Sashite::Epin | raises ArgumentError
-Sashite::Epin.valid?(epin_string) # => boolean
+# Identifier represents a parsed EPIN combining PIN with derivation status.
+class Sashite::Epin::Identifier
+  # Creates an Identifier from a PIN component.
+  # Raises ArgumentError if the PIN is invalid.
+  #
+  # @param pin [Sashite::Pin::Identifier] PIN component
+  # @param derived [Boolean] Derived status
+  # @return [Identifier]
+  def initialize(pin, derived: false)
+
+  # Returns the PIN component.
+  #
+  # @return [Sashite::Pin::Identifier]
+  def pin
+
+  # Returns true if derived style.
+  #
+  # @return [Boolean]
+  def derived?
+
+  # Returns true if native style.
+  #
+  # @return [Boolean]
+  def native?
+
+  # Returns the EPIN string representation.
+  #
+  # @return [String]
+  def to_s
+end
 ```
 
-### Creation
+### Parsing
 
 ```ruby
-Sashite::Epin.new(pin)                 # Native (default)
-Sashite::Epin.new(pin, derived: true)  # Derived
+# Parses an EPIN string into an Identifier.
+# Raises ArgumentError if the string is not valid.
+#
+# @param string [String] EPIN string
+# @return [Identifier]
+# @raise [ArgumentError] if invalid
+def Sashite::Epin.parse(string)
 ```
 
-### Conversion
+### Validation
 
 ```ruby
-epin.to_s # => String
+# Reports whether string is a valid EPIN.
+#
+# @param string [String] EPIN string
+# @return [Boolean]
+def Sashite::Epin.valid?(string)
 ```
 
 ### Transformations
 
-All transformations return new `Sashite::Epin` instances:
-
 ```ruby
-# PIN replacement
-epin.with_pin(new_pin) # => Sashite::Epin with different PIN
+# PIN replacement (returns new Identifier)
+def with_pin(new_pin)  # => Identifier with different PIN
 
-# Derivation
-epin.mark_derived            # => Sashite::Epin with derived: true
-epin.unmark_derived          # => Sashite::Epin with derived: false
-epin.with_derived(boolean)   # => Sashite::Epin with specified derivation
+# Derivation transformations
+def derive  # => Identifier with derived: true
+def native  # => Identifier with derived: false
 ```
 
-### Queries
-
-```ruby
-# Derivation
-epin.derived?                # => true if derived
-epin.native?                 # => true if not derived
-
-# Comparison
-epin.same_derived?(other) # => true if same derivation status
-```
+### Errors
 
-## Data Structure
+All parsing and validation errors raise `ArgumentError` with descriptive messages:
 
-```ruby
-Sashite::Epin
-  #pin     => Sashite::Pin     # Underlying PIN instance
-  #derived => true | false     # Derivation status
-```
+| Message | Cause |
+|---------|-------|
+| `"invalid derivation marker"` | Derivation marker misplaced or duplicated |
+| `"invalid PIN component: ..."` | PIN parsing failed |
 
-## Comparison with PIN
+## PIN Compatibility
 
-### What EPIN Adds
+Every valid PIN is a valid EPIN (native by default):
 
 ```ruby
-# PIN: 4 attributes
-pin = Sashite::Pin.parse("K^")
-pin.type       # Piece Name
-pin.side       # Piece Side
-pin.state      # Piece State
-pin.terminal   # Terminal Status
-
-# EPIN: 5 attributes (PIN + style)
-epin = Sashite::Epin.parse("K^'")
-epin.pin.type       # Piece Name
-epin.pin.side       # Piece Side
-epin.pin.state      # Piece State
-epin.pin.terminal   # Terminal Status
-epin.derived        # Piece Style (5th attribute)
-```
-
-### When to Use EPIN vs PIN
-
-**Use PIN when:**
-- Single-style games (both players use same style)
-- Style information not needed
-- Maximum compatibility required
-
-**Use EPIN when:**
-- Cross-style games (different styles per player)
-- Pieces can change style (promotion to foreign piece)
-- Need to track native vs derived pieces
-
-## Design Principles
-
-### 1. Pure Composition
-
-EPIN doesn't reimplement PIN features — it extends PIN minimally:
-
-```ruby
-def initialize(pin, derived: false)
-  @pin = pin
-  @derived = !!derived
-  freeze
+%w[K +R -p K^ +R^].each do |pin_token|
+  epin = Sashite::Epin.parse(pin_token)
+  epin.native?  # => true
+  epin.to_s     # => pin_token
 end
 ```
 
-### 2. Minimal API
-
-**6 core methods only:**
-1. `new` — create from PIN
-2. `pin` — get PIN component
-3. `derived` / `derived?` — check derivation
-4. `to_s` — serialize
-5. `with_pin` — replace PIN
-6. `with_derived` / `mark_derived` / `unmark_derived` — change derivation
-
-Everything else uses the PIN API directly.
-
-### 3. Component Transparency
-
-Access PIN directly — no wrappers:
-
-```ruby
-# Use PIN API directly
-epin.pin.type
-epin.pin.with_type(:Q)
-epin.pin.enhanced?
-epin.pin.flip
-
-# No need for wrapper methods like:
-# epin.type
-# epin.with_type(:Q)
-# epin.enhanced?
-# epin.flip
-```
-
-### 4. Backward Compatibility
+## Design Principles
 
-Every valid PIN is a valid EPIN (without derivation marker):
-
-```ruby
-# All PIN identifiers work as EPIN
-%w[K +R -p K^ +R^].each do |token|
-  epin = Sashite::Epin.parse(token)
-  epin.native?  # => true
-  epin.to_s     # => token
-end
-```
+- **Pure composition**: EPIN composes PIN without reimplementing features
+- **Minimal API**: Core methods (`pin`, `derived?`, `native?`, `to_s`) plus transformations
+- **Component transparency**: Access PIN directly, no wrapper methods
+- **Immutable identifiers**: Frozen instances prevent mutation
+- **Ruby idioms**: `valid?` predicate, `to_s` conversion, `ArgumentError` for invalid input
 
 ## Related Specifications
 
-- [EPIN Specification v1.0.0](https://sashite.dev/specs/epin/1.0.0/) — Technical specification
+- [Game Protocol](https://sashite.dev/game-protocol/) — Conceptual foundation
+- [EPIN Specification](https://sashite.dev/specs/epin/1.0.0/) — Official specification
 - [EPIN Examples](https://sashite.dev/specs/epin/1.0.0/examples/) — Usage examples
-- [PIN Specification v1.0.0](https://sashite.dev/specs/pin/1.0.0/) — Base component
-- [Sashité Game Protocol](https://sashite.dev/game-protocol/) — Foundation
+- [PIN Specification](https://sashite.dev/specs/pin/1.0.0/) — Base component
 
 ## License
 
-Available as open source under the [MIT License](https://opensource.org/licenses/MIT).
-
-## About
-
-Maintained by [Sashité](https://sashite.com/) — promoting chess variants and sharing the beauty of board game cultures.
+Available as open source under the [Apache License 2.0](https://opensource.org/licenses/Apache-2.0).

data/lib/sashite/epin/constants.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Sashite
+  module Epin
+    # Constants for EPIN (Extended Piece Identifier Notation).
+    #
+    # EPIN extends PIN with a single derivation marker.
+    # PIN constants (VALID_TYPES, VALID_SIDES, VALID_STATES, etc.)
+    # are accessed through the sashite-pin dependency.
+    module Constants
+      # Derivation marker suffix.
+      DERIVATION_SUFFIX = "'"
+    end
+  end
+end

data/lib/sashite/epin/errors/argument/messages.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Sashite
+  module Epin
+    module Errors
+      class Argument < ::ArgumentError
+        # Centralized error messages for EPIN parsing and validation.
+        #
+        # PIN-related errors (empty input, must contain exactly one letter, etc.)
+        # are propagated from the sashite-pin dependency.
+        #
+        # @example
+        #   raise Errors::Argument, Messages::INVALID_DERIVATION_MARKER
+        module Messages
+          # Parsing error
+          INVALID_DERIVATION_MARKER = "invalid derivation marker"
+
+          # Validation errors (constructor)
+          INVALID_PIN = "pin must be a Sashite::Pin::Identifier"
+          INVALID_DERIVED = "derived must be true or false"
+        end
+      end
+    end
+  end
+end

data/lib/sashite/epin/errors/argument.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require_relative "argument/messages"
+
+module Sashite
+  module Epin
+    module Errors
+      # Error raised when EPIN parsing or validation fails.
+      #
+      # @example
+      #   raise Argument, Argument::Messages::INVALID_DERIVATION_MARKER
+      class Argument < ::ArgumentError
+      end
+    end
+  end
+end

data/lib/sashite/epin/errors.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative "errors/argument"