sashite-pin 4.0.0 → 4.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9d3f359a3d215523ac369b662e9a6d1a290acd6076db4f34829d0eb579ac8e2a
-  data.tar.gz: a25dc1c9f2f47ed6121f82a839ee28d070c5a5c8bb11bd10abeb2e589d4dae30
+  metadata.gz: e00046935bd19fe218aed6188bc310389c9a93e5e36aad8b91890d36046c4165
+  data.tar.gz: e90e9430c444175c658262c486eddfe3c09a6e5da2c88b0b1365fb91f14616a0
 SHA512:
-  metadata.gz: 79a1949901c57b7057498f1157a68cf71169a034f2645d6f69c9cb2d4a1272a422d54b794930013af7b0042277951dc32bffaa80a49abc88e7fe8ed5161a8644
-  data.tar.gz: e475211bb7e79ac75df02bfcf58023354e602479e40b76ae453942ae5f3fe38a1af310f477db8ccbf57c070bd1e0d0dab2422c2eab9013e896b5f90f79d4b007
+  metadata.gz: f716220c9d53ba9003712d64c3335f20b395c2174637b2432f43ca01c654dca7586b84f3057747126cf899003478afc071de31cd93e76ce0dc49dd7f7a9f99d5
+  data.tar.gz: 0aedbcd707733bbd81dd6fa48608a52f66016aec2e63162c5f841cbaf359959d3f902d8dddca2e08848d57dce1f3ccb31e3baeebb791812bea91c678a1f9fe0f

data/LICENSE

@@ -186,7 +186,7 @@
       same "printed page" as the copyright notice for easier
       identification within third-party archives.
 
-   Copyright 2025 Cyril Kato
+   Copyright 2025-2026 Cyril Kato
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.

data/README.md

@@ -35,7 +35,7 @@ require "sashite/pin"
 
 # Standard parsing (raises on error)
 pin = Sashite::Pin.parse("K")
-pin.type       # => :K
+pin.abbr       # => :K
 pin.side       # => :first
 pin.state      # => :normal
 pin.terminal?  # => false
@@ -84,23 +84,6 @@ Sashite::Pin.valid?("K^")       # => true
 Sashite::Pin.valid?("invalid")  # => false
 ```
 
-### Accessing Identifier Data
-
-```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.
@@ -117,12 +100,12 @@ pin.normalize.to_s  # => "K"
 pin.flip.to_s  # => "k"
 
 # Terminal transformations
-pin.mark_terminal.to_s    # => "K^"
-pin.unmark_terminal.to_s  # => "K"
+pin.terminal.to_s      # => "K^"
+pin.non_terminal.to_s  # => "K"
 
 # Attribute changes
-pin.with_type(:Q).to_s       # => "Q"
-pin.with_side(:second).to_s  # => "k"
+pin.with_abbr(: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^"
 ```
@@ -146,7 +129,7 @@ pin.terminal?  # => true
 
 # Comparison queries
 other = Sashite::Pin.parse("k")
-pin.same_type?(other)      # => true
+pin.same_abbr?(other)      # => true
 pin.same_side?(other)      # => false
 pin.same_state?(other)     # => false
 pin.same_terminal?(other)  # => false
@@ -162,19 +145,19 @@ 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 abbr [Symbol] Piece name abbreviation (:A to :Z)
+  # @param side [Symbol] Piece 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)
+  def initialize(abbr, side, state = :normal, terminal: false)
 
-  # Returns the piece type (always uppercase symbol).
+  # Returns the piece name abbreviation (always uppercase symbol).
   #
   # @return [Symbol]
-  def type
+  def abbr
 
-  # Returns the player side.
+  # Returns the piece side.
   #
   # @return [Symbol] :first or :second
   def side
@@ -199,7 +182,7 @@ end
 ### Constants
 
 ```ruby
-Sashite::Pin::Constants::VALID_TYPES       # => [:A, :B, ..., :Z]
+Sashite::Pin::Constants::VALID_ABBRS       # => [: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
@@ -229,8 +212,10 @@ def Sashite::Pin.valid?(string)
 
 ### Transformations
 
+All transformations return new `Sashite::Pin::Identifier` instances:
+
 ```ruby
-# State transformations (return new Identifier)
+# State transformations
 def enhance     # => Identifier with :enhanced state
 def diminish    # => Identifier with :diminished state
 def normalize   # => Identifier with :normal state
@@ -239,16 +224,38 @@ def normalize   # => Identifier with :normal state
 def flip        # => Identifier with opposite side
 
 # Terminal transformations
-def mark_terminal    # => Identifier with terminal: true
-def unmark_terminal  # => Identifier with terminal: false
+def terminal      # => Identifier with terminal: true
+def non_terminal  # => Identifier with terminal: false
 
 # Attribute changes
-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_abbr(new_abbr)         # => Identifier with different abbreviation
+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
 ```
 
+### Queries
+
+```ruby
+# State queries
+def normal?      # => Boolean
+def enhanced?    # => Boolean
+def diminished?  # => Boolean
+
+# Side queries
+def first_player?   # => Boolean
+def second_player?  # => Boolean
+
+# Terminal query
+def terminal?  # => Boolean
+
+# Comparison queries
+def same_abbr?(other)      # => Boolean
+def same_side?(other)      # => Boolean
+def same_state?(other)     # => Boolean
+def same_terminal?(other)  # => Boolean
+```
+
 ### Errors
 
 All parsing and validation errors raise `ArgumentError` with descriptive messages:
@@ -263,11 +270,11 @@ All parsing and validation errors raise `ArgumentError` with descriptive message
 
 ## Design Principles
 
-- **Bounded values**: Explicit validation of types, sides, states
+- **Bounded values**: Explicit validation of abbreviations, sides, and 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
+- **Transformation methods**: Return new instances for attribute changes
 - **No dependencies**: Pure Ruby standard library only
 
 ## Related Specifications

data/lib/sashite/pin/constants.rb

@@ -6,8 +6,8 @@ module Sashite
     #
     # 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 piece name abbreviations (uppercase symbols A-Z).
+      VALID_ABBRS = %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

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

@@ -17,7 +17,7 @@ module Sashite
           INVALID_TERMINAL_MARKER = "invalid terminal marker"
 
           # Validation errors (constructor)
-          INVALID_TYPE = "type must be a symbol from :A to :Z"
+          INVALID_ABBR = "abbr must be a symbol from :A to :Z"
           INVALID_SIDE = "side must be :first or :second"
           INVALID_STATE = "state must be :normal, :enhanced, or :diminished"
           INVALID_TERMINAL = "terminal must be true or false"

data/lib/sashite/pin/identifier.rb

@@ -8,8 +8,8 @@ module Sashite
     # Represents a parsed PIN (Piece Identifier Notation) identifier.
     #
     # An Identifier encodes four attributes of a piece:
-    # - Type: the piece type (A-Z as uppercase symbol)
-    # - Side: the player side (:first or :second)
+    # - Abbr: the piece name abbreviation (A-Z as uppercase symbol)
+    # - Side: the piece side (:first or :second)
     # - State: the piece state (:normal, :enhanced, or :diminished)
     # - Terminal: whether the piece is terminal (true or false)
     #
@@ -21,16 +21,16 @@ module Sashite
     #   pin = Identifier.new(:K, :first, :normal, terminal: true)
     #
     # @example String conversion
-    #   Identifier.new(:K, :first).to_s                        # => "K"
-    #   Identifier.new(:R, :second, :enhanced).to_s            # => "+r"
+    #   Identifier.new(:K, :first).to_s                          # => "K"
+    #   Identifier.new(:R, :second, :enhanced).to_s              # => "+r"
     #   Identifier.new(:K, :first, :normal, terminal: true).to_s # => "K^"
     #
     # @see https://sashite.dev/specs/pin/1.0.0/
     class Identifier
-      # @return [Symbol] Piece type (:A to :Z, always uppercase)
-      attr_reader :type
+      # @return [Symbol] Piece name abbreviation (:A to :Z, always uppercase)
+      attr_reader :abbr
 
-      # @return [Symbol] Player side (:first or :second)
+      # @return [Symbol] Piece side (:first or :second)
       attr_reader :side
 
       # @return [Symbol] Piece state (:normal, :enhanced, or :diminished)
@@ -38,8 +38,8 @@ module Sashite
 
       # Creates a new Identifier instance.
       #
-      # @param type [Symbol] Piece type (:A to :Z)
-      # @param side [Symbol] Player side (:first or :second)
+      # @param abbr [Symbol] Piece name abbreviation (:A to :Z)
+      # @param side [Symbol] Piece side (:first or :second)
       # @param state [Symbol] Piece state (:normal, :enhanced, or :diminished)
       # @param terminal [Boolean] Terminal status
       # @return [Identifier] A new frozen Identifier instance
@@ -49,13 +49,13 @@ module Sashite
       #   Identifier.new(:K, :first)
       #   Identifier.new(:R, :second, :enhanced)
       #   Identifier.new(:K, :first, :normal, terminal: true)
-      def initialize(type, side, state = :normal, terminal: false)
-        validate_type!(type)
+      def initialize(abbr, side, state = :normal, terminal: false)
+        validate_abbr!(abbr)
         validate_side!(side)
         validate_state!(state)
         validate_terminal!(terminal)
 
-        @type = type
+        @abbr = abbr
         @side = side
         @state = state
         @terminal = terminal
@@ -68,7 +68,7 @@ module Sashite
       # @return [Boolean] true if terminal piece, false otherwise
       #
       # @example
-      #   Identifier.new(:K, :first).terminal?                        # => false
+      #   Identifier.new(:K, :first).terminal?                          # => false
       #   Identifier.new(:K, :first, :normal, terminal: true).terminal? # => true
       def terminal?
         @terminal
@@ -83,8 +83,8 @@ module Sashite
       # @return [String] The PIN string
       #
       # @example
-      #   Identifier.new(:K, :first).to_s                        # => "K"
-      #   Identifier.new(:R, :second, :enhanced).to_s            # => "+r"
+      #   Identifier.new(:K, :first).to_s                          # => "K"
+      #   Identifier.new(:R, :second, :enhanced).to_s              # => "+r"
       #   Identifier.new(:K, :first, :normal, terminal: true).to_s # => "K^"
       def to_s
         "#{prefix}#{letter}#{suffix}"
@@ -99,8 +99,8 @@ module Sashite
       #   Identifier.new(:K, :second).letter # => "k"
       def letter
         case side
-        when :first then String(type.upcase)
-        when :second then String(type.downcase)
+        when :first then String(abbr.upcase)
+        when :second then String(abbr.downcase)
         end
       end
 
@@ -145,7 +145,7 @@ module Sashite
       def enhance
         return self if enhanced?
 
-        self.class.new(type, side, :enhanced, terminal: terminal?)
+        self.class.new(abbr, side, :enhanced, terminal: terminal?)
       end
 
       # Returns a new Identifier with diminished state.
@@ -158,7 +158,7 @@ module Sashite
       def diminish
         return self if diminished?
 
-        self.class.new(type, side, :diminished, terminal: terminal?)
+        self.class.new(abbr, side, :diminished, terminal: terminal?)
       end
 
       # Returns a new Identifier with normal state.
@@ -171,7 +171,7 @@ module Sashite
       def normalize
         return self if normal?
 
-        self.class.new(type, side, :normal, terminal: terminal?)
+        self.class.new(abbr, side, :normal, terminal: terminal?)
       end
 
       # ========================================================================
@@ -187,7 +187,7 @@ module Sashite
       #   pin.flip.to_s # => "k"
       def flip
         new_side = first_player? ? :second : :first
-        self.class.new(type, new_side, state, terminal: terminal?)
+        self.class.new(abbr, new_side, state, terminal: terminal?)
       end
 
       # ========================================================================
@@ -200,11 +200,11 @@ module Sashite
       #
       # @example
       #   pin = Identifier.new(:K, :first)
-      #   pin.mark_terminal.to_s # => "K^"
-      def mark_terminal
+      #   pin.terminal.to_s # => "K^"
+      def terminal
         return self if terminal?
 
-        self.class.new(type, side, state, terminal: true)
+        self.class.new(abbr, side, state, terminal: true)
       end
 
       # Returns a new Identifier unmarked as terminal.
@@ -213,30 +213,30 @@ module Sashite
       #
       # @example
       #   pin = Identifier.new(:K, :first, :normal, terminal: true)
-      #   pin.unmark_terminal.to_s # => "K"
-      def unmark_terminal
+      #   pin.non_terminal.to_s # => "K"
+      def non_terminal
         return self unless terminal?
 
-        self.class.new(type, side, state, terminal: false)
+        self.class.new(abbr, side, state, terminal: false)
       end
 
       # ========================================================================
       # Attribute Transformations
       # ========================================================================
 
-      # Returns a new Identifier with a different type.
+      # Returns a new Identifier with a different abbreviation.
       #
-      # @param new_type [Symbol] The new piece type (:A to :Z)
-      # @return [Identifier] A new Identifier with the specified type
-      # @raise [Errors::Argument] If the type is invalid
+      # @param new_abbr [Symbol] The new piece name abbreviation (:A to :Z)
+      # @return [Identifier] A new Identifier with the specified abbreviation
+      # @raise [Errors::Argument] If the abbreviation is invalid
       #
       # @example
       #   pin = Identifier.new(:K, :first)
-      #   pin.with_type(:Q).to_s # => "Q"
-      def with_type(new_type)
-        return self if type.equal?(new_type)
+      #   pin.with_abbr(:Q).to_s # => "Q"
+      def with_abbr(new_abbr)
+        return self if abbr.equal?(new_abbr)
 
-        self.class.new(new_type, side, state, terminal: terminal?)
+        self.class.new(new_abbr, side, state, terminal: terminal?)
       end
 
       # Returns a new Identifier with a different side.
@@ -251,7 +251,7 @@ module Sashite
       def with_side(new_side)
         return self if side.equal?(new_side)
 
-        self.class.new(type, new_side, state, terminal: terminal?)
+        self.class.new(abbr, new_side, state, terminal: terminal?)
       end
 
       # Returns a new Identifier with a different state.
@@ -266,7 +266,7 @@ module Sashite
       def with_state(new_state)
         return self if state.equal?(new_state)
 
-        self.class.new(type, side, new_state, terminal: terminal?)
+        self.class.new(abbr, side, new_state, terminal: terminal?)
       end
 
       # Returns a new Identifier with a different terminal status.
@@ -281,7 +281,7 @@ module Sashite
       def with_terminal(new_terminal)
         return self if terminal?.equal?(new_terminal)
 
-        self.class.new(type, side, state, terminal: new_terminal)
+        self.class.new(abbr, side, state, terminal: new_terminal)
       end
 
       # ========================================================================
@@ -346,17 +346,17 @@ module Sashite
       # Comparison Queries
       # ========================================================================
 
-      # Checks if two Identifiers have the same type.
+      # Checks if two Identifiers have the same abbreviation.
       #
       # @param other [Identifier] The other Identifier to compare
-      # @return [Boolean] true if same type
+      # @return [Boolean] true if same abbreviation
       #
       # @example
       #   pin1 = Identifier.new(:K, :first)
       #   pin2 = Identifier.new(:K, :second)
-      #   pin1.same_type?(pin2) # => true
-      def same_type?(other)
-        type.equal?(other.type)
+      #   pin1.same_abbr?(pin2) # => true
+      def same_abbr?(other)
+        abbr.equal?(other.abbr)
       end
 
       # Checks if two Identifiers have the same side.
@@ -409,7 +409,7 @@ module Sashite
       def ==(other)
         return false unless self.class === other
 
-        type.equal?(other.type) &&
+        abbr.equal?(other.abbr) &&
           side.equal?(other.side) &&
           state.equal?(other.state) &&
           terminal?.equal?(other.terminal?)
@@ -421,7 +421,7 @@ module Sashite
       #
       # @return [Integer] Hash code
       def hash
-        [type, side, state, terminal?].hash
+        [abbr, side, state, terminal?].hash
       end
 
       # Returns an inspect string for the Identifier.
@@ -437,10 +437,10 @@ module Sashite
       # Private Validation
       # ========================================================================
 
-      def validate_type!(type)
-        return if Constants::VALID_TYPES.include?(type)
+      def validate_abbr!(abbr)
+        return if Constants::VALID_ABBRS.include?(abbr)
 
-        raise Errors::Argument, Errors::Argument::Messages::INVALID_TYPE
+        raise Errors::Argument, Errors::Argument::Messages::INVALID_ABBR
       end
 
       def validate_side!(side)

data/lib/sashite/pin/parser.rb

@@ -11,15 +11,15 @@ module Sashite
     # to prevent ReDoS attacks and ensure strict ASCII compliance.
     #
     # @example
-    #   Parser.parse("K")   # => { type: :K, side: :first, state: :normal, terminal: false }
-    #   Parser.parse("+r^") # => { type: :R, side: :second, state: :enhanced, terminal: true }
+    #   Parser.parse("K")   # => { abbr: :K, side: :first, state: :normal, terminal: false }
+    #   Parser.parse("+r^") # => { abbr: :R, side: :second, state: :enhanced, terminal: true }
     #
     # @see https://sashite.dev/specs/pin/1.0.0/
     module Parser
       # Parses a PIN string into its components.
       #
       # @param input [String] The PIN string to parse
-      # @return [Hash] A hash with :type, :side, :state, and :terminal keys
+      # @return [Hash] A hash with :abbr, :side, :state, and :terminal keys
       # @raise [Errors::Argument] If the input is not a valid PIN string
       def self.parse(input)
         validate_input_type(input)
@@ -78,7 +78,7 @@ module Sashite
         # Parses the PIN string into its components.
         #
         # @param input [String] The validated PIN string
-        # @return [Hash] A hash with :type, :side, :state, and :terminal keys
+        # @return [Hash] A hash with :abbr, :side, :state, and :terminal keys
         # @raise [Errors::Argument] If the structure is invalid
         def parse_components(input)
           pos = 0
@@ -98,7 +98,7 @@ module Sashite
           byte = input.getbyte(pos)
           raise Errors::Argument, Errors::Argument::Messages::MUST_CONTAIN_ONE_LETTER unless ascii_letter?(byte)
 
-          type = byte.chr.upcase.to_sym
+          abbr = byte.chr.upcase.to_sym
           side = uppercase_letter?(byte) ? :first : :second
           pos += 1
 
@@ -114,7 +114,7 @@ module Sashite
           # Ensure no extra characters
           raise Errors::Argument, Errors::Argument::Messages::MUST_CONTAIN_ONE_LETTER if pos < input.bytesize
 
-          { type: type, side: side, state: state, terminal: terminal }
+          { abbr: abbr, side: side, state: state, terminal: terminal }
         end
 
         # Checks if a byte is a state modifier (+ or -).

data/lib/sashite/pin.rb

@@ -16,7 +16,7 @@ module Sashite
   #
   #   [<state-modifier>]<letter>[<terminal-marker>]
   #
-  # - *Letter* (+A-Z+, +a-z+): Piece type and side
+  # - *Letter* (+A-Z+, +a-z+): Piece name abbreviation and side
   # - *State modifier*: <tt>+</tt> (enhanced), <tt>-</tt> (diminished), or none (normal)
   # - *Terminal marker*: <tt>^</tt> (terminal piece) or none
   #
@@ -32,7 +32,7 @@ module Sashite
   # == Examples
   #
   #   pin = Sashite::Pin.parse("K")
-  #   pin.type       # => :K
+  #   pin.abbr       # => :K
   #   pin.side       # => :first
   #   pin.state      # => :normal
   #   pin.terminal?  # => false
@@ -70,7 +70,7 @@ module Sashite
       components = Parser.parse(string)
 
       Identifier.new(
-        components[:type],
+        components[:abbr],
         components[:side],
         components[:state],
         terminal: components[:terminal]

data/lib/sashite-pin.rb

@@ -1,14 +1,3 @@
 # frozen_string_literal: true
 
 require_relative "sashite/pin"
-
-# 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-pin
 version: !ruby/object:Gem::Version
-  version: 4.0.0
+  version: 4.1.0
 platform: ruby
 authors:
 - Cyril Kato