sashite-pin 3.3.0 → 4.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 629bf8b689b39a81e6b52ca9b1386f53c6c807f5f57ae608fb99449ceb08854e
-  data.tar.gz: '0883b5de633e958ddbf72908ffd49832e999e0a1f99b615ce8aa5fa1222cd4f5'
+  metadata.gz: 9d3f359a3d215523ac369b662e9a6d1a290acd6076db4f34829d0eb579ac8e2a
+  data.tar.gz: a25dc1c9f2f47ed6121f82a839ee28d070c5a5c8bb11bd10abeb2e589d4dae30
 SHA512:
-  metadata.gz: a64ac32e1afb6b84c388823f81022efe6eda1a469ce82920b4d8119f0e747e4f5a8788c92d397a48165b36fcfda45111df785dad8523f3e861e31acb55e6fd68
-  data.tar.gz: 99a1e0e87304f2b1f525483cf952a4a0d9fdf0768297010894e6d429f4431b7c5476f287f94e3e85dd9c4c46669546ed094c2afc0fdd6296c9bccebcd8aa255b
+  metadata.gz: 79a1949901c57b7057498f1157a68cf71169a034f2645d6f69c9cb2d4a1272a422d54b794930013af7b0042277951dc32bffaa80a49abc88e7fe8ed5161a8644
+  data.tar.gz: e475211bb7e79ac75df02bfcf58023354e602479e40b76ae453942ae5f3fe38a1af310f477db8ccbf57c070bd1e0d0dab2422c2eab9013e896b5f90f79d4b007

data/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2025 Cyril Kato
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

data/README.md

@@ -1,17 +1,15 @@
-# Sashite::Pin
+# pin.rb
 
 [![Version](https://img.shields.io/github/v/tag/sashite/pin.rb?label=Version&logo=github)](https://github.com/sashite/pin.rb/tags)
 [![Yard documentation](https://img.shields.io/badge/Yard-documentation-blue.svg?logo=github)](https://rubydoc.info/github/sashite/pin.rb/main)
-![Ruby](https://github.com/sashite/pin.rb/actions/workflows/main.yml/badge.svg?branch=main)
-[![License](https://img.shields.io/github/license/sashite/pin.rb?label=License&logo=github)](https://github.com/sashite/pin.rb/raw/main/LICENSE.md)
+[![CI](https://github.com/sashite/pin.rb/actions/workflows/ruby.yml/badge.svg?branch=main)](https://github.com/sashite/pin.rb/actions)
+[![License](https://img.shields.io/github/license/sashite/pin.rb)](https://github.com/sashite/pin.rb/blob/main/LICENSE)
 
 > **PIN** (Piece Identifier Notation) implementation for Ruby.
 
-## What is PIN?
+## Overview
 
-PIN (Piece Identifier Notation) provides an ASCII-based format for representing pieces in abstract strategy board games. PIN translates piece attributes from the [Game Protocol](https://sashite.dev/game-protocol/) into a compact, portable notation system.
-
-This gem implements the [PIN Specification v1.0.0](https://sashite.dev/specs/pin/1.0.0/).
+This library implements the [PIN Specification v1.0.0](https://sashite.dev/specs/pin/1.0.0/).
 
 ## Installation
 
@@ -28,213 +26,256 @@ gem install sashite-pin
 
 ## Usage
 
+### Parsing (String → Identifier)
+
+Convert a PIN string into an `Identifier` object.
+
 ```ruby
 require "sashite/pin"
 
-# Parse PIN strings
+# Standard parsing (raises on error)
 pin = Sashite::Pin.parse("K")
-pin.type      # => :K
-pin.side      # => :first
-pin.state     # => :normal
-pin.terminal  # => false
+pin.type       # => :K
+pin.side       # => :first
+pin.state      # => :normal
+pin.terminal?  # => false
+
+# With state modifier
+pin = Sashite::Pin.parse("+R")
+pin.state  # => :enhanced
+
+# With terminal marker
+pin = Sashite::Pin.parse("K^")
+pin.terminal?  # => true
+
+# Combined
+pin = Sashite::Pin.parse("+K^")
+pin.state      # => :enhanced
+pin.terminal?  # => true
+
+# Invalid input raises ArgumentError
+Sashite::Pin.parse("invalid")  # => raises ArgumentError
+```
+
+### Formatting (Identifier → String)
+
+Convert an `Identifier` back to a PIN string.
 
+```ruby
+# From Identifier object
+pin = Sashite::Pin::Identifier.new(:K, :first)
 pin.to_s  # => "K"
 
-# Parse with different attributes
-king = Sashite::Pin.parse("K^")      # Terminal king
-rook = Sashite::Pin.parse("+R")      # Enhanced rook
-pawn = Sashite::Pin.parse("-p")      # Diminished second player pawn
+# With attributes
+pin = Sashite::Pin::Identifier.new(:R, :second, :enhanced)
+pin.to_s  # => "+r"
+
+pin = Sashite::Pin::Identifier.new(:K, :first, :normal, terminal: true)
+pin.to_s  # => "K^"
+```
 
-# Create identifiers directly
-pin = Sashite::Pin.new(:K, :first)
-pin = Sashite::Pin.new(:R, :second, :enhanced)
-pin = Sashite::Pin.new(:K, :first, :normal, terminal: true)
+### Validation
 
-# Validation
+```ruby
+# Boolean check
 Sashite::Pin.valid?("K")        # => true
 Sashite::Pin.valid?("+R")       # => true
 Sashite::Pin.valid?("K^")       # => true
 Sashite::Pin.valid?("invalid")  # => false
+```
+
+### Accessing Identifier Data
 
-# State transformations (return new instances)
-enhanced = pin.enhance
-enhanced.to_s  # => "+K"
+```ruby
+pin = Sashite::Pin.parse("+K^")
+
+# Get attributes
+pin.type       # => :K
+pin.side       # => :first
+pin.state      # => :enhanced
+pin.terminal?  # => true
+
+# Get string components
+pin.letter  # => "K"
+pin.prefix  # => "+"
+pin.suffix  # => "^"
+```
+
+### Transformations
+
+All transformations return new immutable instances.
 
-diminished = pin.diminish
-diminished.to_s  # => "-K"
+```ruby
+pin = Sashite::Pin.parse("K")
 
-normalized = enhanced.normalize
-normalized.to_s  # => "K"
+# State transformations
+pin.enhance.to_s    # => "+K"
+pin.diminish.to_s   # => "-K"
+pin.normalize.to_s  # => "K"
 
 # Side transformation
-flipped = pin.flip
-flipped.to_s  # => "k"
+pin.flip.to_s  # => "k"
 
 # Terminal transformations
-terminal = pin.mark_terminal
-terminal.to_s  # => "K^"
+pin.mark_terminal.to_s    # => "K^"
+pin.unmark_terminal.to_s  # => "K"
+
+# Attribute changes
+pin.with_type(:Q).to_s       # => "Q"
+pin.with_side(:second).to_s  # => "k"
+pin.with_state(:enhanced).to_s    # => "+K"
+pin.with_terminal(true).to_s      # => "K^"
+```
 
-non_terminal = terminal.unmark_terminal
-non_terminal.to_s  # => "K"
+### Queries
 
-# Type transformation
-queen = pin.with_type(:Q)
-queen.to_s  # => "Q"
+```ruby
+pin = Sashite::Pin.parse("+K^")
 
 # State queries
-pin.normal?     # => true
-enhanced.enhanced?    # => true
-diminished.diminished?  # => true
+pin.normal?      # => false
+pin.enhanced?    # => true
+pin.diminished?  # => false
 
 # Side queries
 pin.first_player?   # => true
-flipped.second_player?  # => true
+pin.second_player?  # => false
 
-# Terminal queries
-terminal.terminal?  # => true
+# Terminal query
+pin.terminal?  # => true
 
-# Comparison
-king1 = Sashite::Pin.parse("K")
-king2 = Sashite::Pin.parse("k")
-
-king1.same_type?(king2)  # => true
-king1.same_side?(king2)  # => false
+# Comparison queries
+other = Sashite::Pin.parse("k")
+pin.same_type?(other)      # => true
+pin.same_side?(other)      # => false
+pin.same_state?(other)     # => false
+pin.same_terminal?(other)  # => false
 ```
 
-## Format Specification
+## API Reference
 
-### Structure
+### Types
 
+```ruby
+# Identifier represents a parsed PIN with all attributes.
+class Sashite::Pin::Identifier
+  # Creates an Identifier from attributes.
+  # Raises ArgumentError if attributes are invalid.
+  #
+  # @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)
+  # @param terminal [Boolean] Terminal status
+  # @return [Identifier]
+  def initialize(type, side, state = :normal, terminal: false)
+
+  # Returns the piece type (always uppercase symbol).
+  #
+  # @return [Symbol]
+  def type
+
+  # Returns the player side.
+  #
+  # @return [Symbol] :first or :second
+  def side
+
+  # Returns the piece state.
+  #
+  # @return [Symbol] :normal, :enhanced, or :diminished
+  def state
+
+  # Returns the terminal status.
+  #
+  # @return [Boolean]
+  def terminal?
+
+  # Returns the PIN string representation.
+  #
+  # @return [String]
+  def to_s
+end
 ```
-[<state-modifier>]<letter>[<terminal-marker>]
-```
-
-### Components
-
-| Component | Values | Description |
-|-----------|--------|-------------|
-| Letter | `A-Z`, `a-z` | Piece type and side |
-| State Modifier | `+`, `-`, (none) | Enhanced, diminished, or normal |
-| Terminal Marker | `^`, (none) | Terminal piece or not |
-
-### Side Convention
-
-- **Uppercase** (`A-Z`): First player
-- **Lowercase** (`a-z`): Second player
-
-### Examples
-
-| PIN | Side | State | Terminal | Description |
-|-----|------|-------|----------|-------------|
-| `K` | First | Normal | No | Standard king |
-| `K^` | First | Normal | Yes | Terminal king |
-| `+R` | First | Enhanced | No | Promoted rook |
-| `-p` | Second | Diminished | No | Weakened pawn |
-| `+K^` | First | Enhanced | Yes | Enhanced terminal king |
-
-## API Reference
 
-### Parsing and Validation
+### Constants
 
 ```ruby
-Sashite::Pin.parse(pin_string)  # => Sashite::Pin | raises ArgumentError
-Sashite::Pin.valid?(pin_string) # => boolean
+Sashite::Pin::Constants::VALID_TYPES       # => [:A, :B, ..., :Z]
+Sashite::Pin::Constants::VALID_SIDES       # => [:first, :second]
+Sashite::Pin::Constants::VALID_STATES      # => [:normal, :enhanced, :diminished]
+Sashite::Pin::Constants::MAX_STRING_LENGTH # => 3
 ```
 
-### Creation
+### Parsing
 
 ```ruby
-Sashite::Pin.new(type, side)
-Sashite::Pin.new(type, side, state)
-Sashite::Pin.new(type, side, state, terminal: boolean)
+# Parses a PIN string into an Identifier.
+# Raises ArgumentError if the string is not valid.
+#
+# @param string [String] PIN string
+# @return [Identifier]
+# @raise [ArgumentError] if invalid
+def Sashite::Pin.parse(string)
 ```
 
-### Conversion
+### Validation
 
 ```ruby
-pin.to_s    # => String
-pin.letter  # => String (case determined by side)
-pin.prefix  # => String ("+" | "-" | "")
-pin.suffix  # => String ("^" | "")
+# Reports whether string is a valid PIN.
+#
+# @param string [String] PIN string
+# @return [Boolean]
+def Sashite::Pin.valid?(string)
 ```
 
 ### Transformations
 
-All transformations return new `Sashite::Pin` instances:
-
 ```ruby
-# State
-pin.enhance     # => Sashite::Pin with :enhanced state
-pin.diminish    # => Sashite::Pin with :diminished state
-pin.normalize   # => Sashite::Pin with :normal state
+# State transformations (return new Identifier)
+def enhance     # => Identifier with :enhanced state
+def diminish    # => Identifier with :diminished state
+def normalize   # => Identifier with :normal state
 
-# Side
-pin.flip        # => Sashite::Pin with opposite side
+# Side transformation
+def flip        # => Identifier with opposite side
 
-# Terminal
-pin.mark_terminal    # => Sashite::Pin with terminal: true
-pin.unmark_terminal  # => Sashite::Pin with terminal: false
+# Terminal transformations
+def mark_terminal    # => Identifier with terminal: true
+def unmark_terminal  # => Identifier with terminal: false
 
 # Attribute changes
-pin.with_type(new_type)       # => Sashite::Pin with different type
-pin.with_side(new_side)       # => Sashite::Pin with different side
-pin.with_state(new_state)     # => Sashite::Pin with different state
-pin.with_terminal(boolean)    # => Sashite::Pin with specified terminal status
-```
-
-### Queries
-
-```ruby
-# State
-pin.normal?
-pin.enhanced?
-pin.diminished?
-
-# Side
-pin.first_player?
-pin.second_player?
-
-# Terminal
-pin.terminal?
-
-# Comparison
-pin.same_type?(other)
-pin.same_side?(other)
-pin.same_state?(other)
-pin.same_terminal?(other)
+def with_type(new_type)        # => Identifier with different type
+def with_side(new_side)        # => Identifier with different side
+def with_state(new_state)      # => Identifier with different state
+def with_terminal(new_terminal) # => Identifier with specified terminal status
 ```
 
-## Data Structure
+### Errors
 
-```ruby
-Sashite::Pin
-  #type     => :A..:Z           # Piece type (always uppercase symbol)
-  #side     => :first | :second # Player side
-  #state    => :normal | :enhanced | :diminished
-  #terminal => true | false
-```
+All parsing and validation errors raise `ArgumentError` with descriptive messages:
 
-## Protocol Mapping
+| Message | Cause |
+|---------|-------|
+| `"empty input"` | String length is 0 |
+| `"input exceeds 3 characters"` | String too long |
+| `"must contain exactly one letter"` | Missing or multiple letters |
+| `"invalid state modifier"` | Invalid prefix character |
+| `"invalid terminal marker"` | Invalid suffix character |
 
-Following the [Game Protocol](https://sashite.dev/game-protocol/):
+## Design Principles
 
-| Protocol Attribute | PIN Encoding |
-|-------------------|--------------|
-| Piece Name | ASCII letter choice |
-| Piece Side | Letter case |
-| Piece State | Optional prefix (`+`/`-`) |
-| Terminal Status | Optional suffix (`^`) |
+- **Bounded values**: Explicit validation of types, sides, states
+- **Object-oriented**: `Identifier` class enables methods and encapsulation
+- **Ruby idioms**: `valid?` predicate, `to_s` conversion, `ArgumentError` for invalid input
+- **Immutable identifiers**: Frozen instances prevent mutation
+- **Transformation methods**: Return new instances for state changes
+- **No dependencies**: Pure Ruby standard library only
 
 ## Related Specifications
 
 - [Game Protocol](https://sashite.dev/game-protocol/) — Conceptual foundation
-- [PNN](https://sashite.dev/specs/pnn/) — Piece Name Notation
 - [PIN Specification](https://sashite.dev/specs/pin/1.0.0/) — Official specification
+- [PIN Examples](https://sashite.dev/specs/pin/1.0.0/examples/) — Usage examples
 
 ## 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/pin/constants.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Sashite
+  module Pin
+    # Constants for PIN (Piece Identifier Notation).
+    #
+    # This module defines the valid values for PIN attributes.
+    module Constants
+      # Valid piece types (uppercase symbols A-Z).
+      VALID_TYPES = %i[A B C D E F G H I J K L M N O P Q R S T U V W X Y Z].freeze
+
+      # Valid player sides.
+      VALID_SIDES = %i[first second].freeze
+
+      # Valid piece states.
+      VALID_STATES = %i[normal enhanced diminished].freeze
+
+      # Maximum length of a valid PIN string.
+      # Corresponds to "+K^" (state modifier + letter + terminal marker).
+      MAX_STRING_LENGTH = 3
+
+      # State modifier for enhanced state.
+      ENHANCED_PREFIX = "+"
+
+      # State modifier for diminished state.
+      DIMINISHED_PREFIX = "-"
+
+      # Empty string (no modifier).
+      EMPTY_STRING = ""
+
+      # Terminal marker suffix.
+      TERMINAL_SUFFIX = "^"
+    end
+  end
+end