sashite-pin 3.2.0 → 4.0.0

data/lib/sashite/pin/identifier.rb

@@ -1,441 +1,464 @@
 # frozen_string_literal: true
 
+require_relative "constants"
+require_relative "errors"
+
 module Sashite
   module Pin
-    # Represents an identifier in PIN (Piece Identifier Notation) format.
+    # 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)
+    # - State: the piece state (:normal, :enhanced, or :diminished)
+    # - Terminal: whether the piece is terminal (true or false)
     #
-    # An identifier consists of a single ASCII letter with optional state modifiers:
-    # - Enhanced state: prefix '+'
-    # - Diminished state: prefix '-'
-    # - Normal state: no modifier
+    # Instances are immutable (frozen after creation).
     #
-    # The case of the letter determines ownership:
-    # - Uppercase (A-Z): first player
-    # - Lowercase (a-z): second player
+    # @example Creating identifiers
+    #   pin = Identifier.new(:K, :first)
+    #   pin = Identifier.new(:R, :second, :enhanced)
+    #   pin = Identifier.new(:K, :first, :normal, terminal: true)
     #
-    # All instances are immutable - state manipulation methods return new instances.
-    # This follows the Game Protocol's piece model with Type, Side, and State attributes.
+    # @example String conversion
+    #   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
-      # PIN validation pattern matching the specification
-      PIN_PATTERN = /\A(?<prefix>[-+])?(?<letter>[a-zA-Z])(?<terminal>\^)?\z/
-
-      # Valid state modifiers
-      ENHANCED_PREFIX = "+"
-      DIMINISHED_PREFIX = "-"
-      NORMAL_PREFIX = ""
-
-      # Terminal marker
-      TERMINAL_MARKER = "^"
-
-      # State constants
-      ENHANCED_STATE = :enhanced
-      DIMINISHED_STATE = :diminished
-      NORMAL_STATE = :normal
-
-      # Player side constants
-      FIRST_PLAYER = :first
-      SECOND_PLAYER = :second
-
-      # Valid types (A-Z)
-      VALID_TYPES = (:A..:Z).to_a.freeze
-
-      # Valid sides
-      VALID_SIDES = [FIRST_PLAYER, SECOND_PLAYER].freeze
-
-      # Valid states
-      VALID_STATES = [NORMAL_STATE, ENHANCED_STATE, DIMINISHED_STATE].freeze
-
-      # Error messages
-      ERROR_INVALID_PIN = "Invalid PIN string: %s"
-      ERROR_INVALID_TYPE = "Type must be a symbol from :A to :Z, got: %s"
-      ERROR_INVALID_SIDE = "Side must be :first or :second, got: %s"
-      ERROR_INVALID_STATE = "State must be :normal, :enhanced, or :diminished, got: %s"
-
-      # @return [Symbol] the piece type (:A to :Z)
+      # @return [Symbol] Piece type (:A to :Z, always uppercase)
       attr_reader :type
 
-      # @return [Symbol] the player side (:first or :second)
+      # @return [Symbol] Player side (:first or :second)
       attr_reader :side
 
-      # @return [Symbol] the piece state (:normal, :enhanced, or :diminished)
+      # @return [Symbol] Piece state (:normal, :enhanced, or :diminished)
       attr_reader :state
 
-      # @return [Boolean] whether the piece is a terminal piece
-      attr_reader :terminal
-
-      # Create a new identifier instance
+      # Creates a new Identifier instance.
+      #
+      # @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] A new frozen Identifier instance
+      # @raise [Errors::Argument] If any attribute is 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] whether the piece is a terminal piece
-      # @raise [ArgumentError] if parameters are invalid
-      def initialize(type, side, state = NORMAL_STATE, terminal: false)
-        self.class.validate_type(type)
-        self.class.validate_side(side)
-        self.class.validate_state(state)
+      # @example
+      #   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)
+        validate_side!(side)
+        validate_state!(state)
+        validate_terminal!(terminal)
 
         @type = type
         @side = side
         @state = state
-        @terminal = !!terminal
+        @terminal = terminal
 
         freeze
       end
 
-      # Parse a PIN string into an Identifier object
+      # Returns the terminal status.
       #
-      # @param pin_string [String] PIN notation string
-      # @return [Identifier] new identifier instance
-      # @raise [ArgumentError] if the PIN string is invalid
-      # @example
-      #   Pin::Identifier.parse("k")     # => #<Pin::Identifier type=:K side=:second state=:normal terminal=false>
-      #   Pin::Identifier.parse("+R")    # => #<Pin::Identifier type=:R side=:first state=:enhanced terminal=false>
-      #   Pin::Identifier.parse("-p")    # => #<Pin::Identifier type=:P side=:second state=:diminished terminal=false>
-      #   Pin::Identifier.parse("K^")    # => #<Pin::Identifier type=:K side=:first state=:normal terminal=true>
-      #   Pin::Identifier.parse("+K^")   # => #<Pin::Identifier type=:K side=:first state=:enhanced terminal=true>
-      def self.parse(pin_string)
-        string_value = String(pin_string)
-        matches = match_pattern(string_value)
-
-        letter = matches[:letter]
-        enhanced = matches[:prefix] == ENHANCED_PREFIX
-        diminished = matches[:prefix] == DIMINISHED_PREFIX
-        is_terminal = matches[:terminal] == TERMINAL_MARKER
-
-        type = letter.upcase.to_sym
-        side = letter == letter.upcase ? FIRST_PLAYER : SECOND_PLAYER
-        state = if enhanced
-                  ENHANCED_STATE
-                elsif diminished
-                  DIMINISHED_STATE
-                else
-                  NORMAL_STATE
-                end
-
-        new(type, side, state, terminal: is_terminal)
-      end
-
-      # Check if a string is a valid PIN notation
-      #
-      # @param pin_string [String] The string to validate
-      # @return [Boolean] true if valid PIN, false otherwise
+      # @return [Boolean] true if terminal piece, false otherwise
       #
       # @example
-      #   Sashite::Pin::Identifier.valid?("K")    # => true
-      #   Sashite::Pin::Identifier.valid?("+R")   # => true
-      #   Sashite::Pin::Identifier.valid?("-p")   # => true
-      #   Sashite::Pin::Identifier.valid?("KK")   # => false
-      #   Sashite::Pin::Identifier.valid?("++K")  # => false
-      def self.valid?(pin_string)
-        return false unless pin_string.is_a?(::String)
-
-        pin_string.match?(PIN_PATTERN)
+      #   Identifier.new(:K, :first).terminal?                        # => false
+      #   Identifier.new(:K, :first, :normal, terminal: true).terminal? # => true
+      def terminal?
+        @terminal
       end
 
-      # Convert the identifier to its PIN string representation
+      # ========================================================================
+      # String Conversion
+      # ========================================================================
+
+      # Returns the PIN string representation.
+      #
+      # @return [String] The PIN string
       #
-      # @return [String] PIN notation string
       # @example
-      #   identifier.to_s  # => "+R"
-      #   terminal_king.to_s  # => "K^"
-      #   enhanced_terminal.to_s  # => "+K^"
+      #   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}"
       end
 
-      # Get the letter representation
+      # Returns the letter component of the PIN.
+      #
+      # @return [String] Uppercase for first player, lowercase for second
       #
-      # @return [String] letter representation combining type and side
+      # @example
+      #   Identifier.new(:K, :first).letter  # => "K"
+      #   Identifier.new(:K, :second).letter # => "k"
       def letter
-        first_player? ? type.to_s.upcase : type.to_s.downcase
+        case side
+        when :first then String(type.upcase)
+        when :second then String(type.downcase)
+        end
       end
 
-      # Get the prefix representation
+      # Returns the state prefix of the PIN.
+      #
+      # @return [String] "+" for enhanced, "-" for diminished, "" for normal
       #
-      # @return [String] prefix representing the state
+      # @example
+      #   Identifier.new(:K, :first, :enhanced).prefix   # => "+"
+      #   Identifier.new(:K, :first, :diminished).prefix # => "-"
+      #   Identifier.new(:K, :first, :normal).prefix     # => ""
       def prefix
         case state
-        when ENHANCED_STATE then ENHANCED_PREFIX
-        when DIMINISHED_STATE then DIMINISHED_PREFIX
-        else NORMAL_PREFIX
+        when :enhanced then Constants::ENHANCED_PREFIX
+        when :diminished then Constants::DIMINISHED_PREFIX
+        else Constants::EMPTY_STRING
         end
       end
 
-      # Get the suffix representation
+      # Returns the terminal suffix of the PIN.
+      #
+      # @return [String] "^" if terminal, "" otherwise
       #
-      # @return [String] suffix representing terminal status
+      # @example
+      #   Identifier.new(:K, :first, :normal, terminal: true).suffix # => "^"
+      #   Identifier.new(:K, :first).suffix                          # => ""
       def suffix
-        terminal? ? TERMINAL_MARKER : ""
+        terminal? ? Constants::TERMINAL_SUFFIX : Constants::EMPTY_STRING
       end
 
-      # Create a new identifier with enhanced state
+      # ========================================================================
+      # State Transformations
+      # ========================================================================
+
+      # Returns a new Identifier with enhanced state.
+      #
+      # @return [Identifier] A new Identifier with :enhanced state
       #
-      # @return [Identifier] new identifier instance with enhanced state
+      # @example
+      #   pin = Identifier.new(:K, :first)
+      #   pin.enhance.to_s # => "+K"
       def enhance
         return self if enhanced?
 
-        self.class.new(type, side, ENHANCED_STATE, terminal: terminal)
+        self.class.new(type, side, :enhanced, terminal: terminal?)
       end
 
-      # Create a new identifier without enhanced state
+      # Returns a new Identifier with diminished state.
       #
-      # @return [Identifier] new identifier instance with normal state
-      def unenhance
-        return self unless enhanced?
-
-        self.class.new(type, side, NORMAL_STATE, terminal: terminal)
-      end
-
-      # Create a new identifier with diminished state
+      # @return [Identifier] A new Identifier with :diminished state
       #
-      # @return [Identifier] new identifier instance with diminished state
+      # @example
+      #   pin = Identifier.new(:K, :first)
+      #   pin.diminish.to_s # => "-K"
       def diminish
         return self if diminished?
 
-        self.class.new(type, side, DIMINISHED_STATE, terminal: terminal)
+        self.class.new(type, side, :diminished, terminal: terminal?)
       end
 
-      # Create a new identifier without diminished state
+      # Returns a new Identifier with normal state.
       #
-      # @return [Identifier] new identifier instance with normal state
-      def undiminish
-        return self unless diminished?
-
-        self.class.new(type, side, NORMAL_STATE, terminal: terminal)
-      end
-
-      # Create a new identifier with normal state (no modifiers)
+      # @return [Identifier] A new Identifier with :normal state
       #
-      # @return [Identifier] new identifier instance with normal state
+      # @example
+      #   pin = Identifier.new(:K, :first, :enhanced)
+      #   pin.normalize.to_s # => "K"
       def normalize
         return self if normal?
 
-        self.class.new(type, side, NORMAL_STATE, terminal: terminal)
+        self.class.new(type, side, :normal, terminal: terminal?)
+      end
+
+      # ========================================================================
+      # Side Transformations
+      # ========================================================================
+
+      # Returns a new Identifier with the opposite side.
+      #
+      # @return [Identifier] A new Identifier with flipped side
+      #
+      # @example
+      #   pin = Identifier.new(:K, :first)
+      #   pin.flip.to_s # => "k"
+      def flip
+        new_side = first_player? ? :second : :first
+        self.class.new(type, new_side, state, terminal: terminal?)
       end
 
-      # Create a new identifier marked as terminal
+      # ========================================================================
+      # Terminal Transformations
+      # ========================================================================
+
+      # Returns a new Identifier marked as terminal.
+      #
+      # @return [Identifier] A new Identifier with terminal: true
       #
-      # @return [Identifier] new identifier instance marked as terminal
+      # @example
+      #   pin = Identifier.new(:K, :first)
+      #   pin.mark_terminal.to_s # => "K^"
       def mark_terminal
         return self if terminal?
 
         self.class.new(type, side, state, terminal: true)
       end
 
-      # Create a new identifier unmarked as terminal
+      # Returns a new Identifier unmarked as terminal.
+      #
+      # @return [Identifier] A new Identifier with terminal: false
       #
-      # @return [Identifier] new identifier instance unmarked as terminal
+      # @example
+      #   pin = Identifier.new(:K, :first, :normal, terminal: true)
+      #   pin.unmark_terminal.to_s # => "K"
       def unmark_terminal
         return self unless terminal?
 
         self.class.new(type, side, state, terminal: false)
       end
 
-      # Create a new identifier with opposite side
-      #
-      # @return [Identifier] new identifier instance with opposite side
-      def flip
-        self.class.new(type, opposite_side, state, terminal: terminal)
-      end
+      # ========================================================================
+      # Attribute Transformations
+      # ========================================================================
 
-      # Create a new identifier with a different type
+      # Returns a new Identifier with a different type.
       #
-      # @param new_type [Symbol] new type (:A to :Z)
-      # @return [Identifier] new identifier instance with new type
+      # @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
+      #
+      # @example
+      #   pin = Identifier.new(:K, :first)
+      #   pin.with_type(:Q).to_s # => "Q"
       def with_type(new_type)
-        self.class.validate_type(new_type)
-        return self if type == new_type
+        return self if type.equal?(new_type)
 
-        self.class.new(new_type, side, state, terminal: terminal)
+        self.class.new(new_type, side, state, terminal: terminal?)
       end
 
-      # Create a new identifier with a different side
+      # Returns a new Identifier with a different side.
       #
-      # @param new_side [Symbol] new side (:first or :second)
-      # @return [Identifier] new identifier instance with new side
+      # @param new_side [Symbol] The new side (:first or :second)
+      # @return [Identifier] A new Identifier with the specified side
+      # @raise [Errors::Argument] If the side is invalid
+      #
+      # @example
+      #   pin = Identifier.new(:K, :first)
+      #   pin.with_side(:second).to_s # => "k"
       def with_side(new_side)
-        self.class.validate_side(new_side)
-        return self if side == new_side
+        return self if side.equal?(new_side)
 
-        self.class.new(type, new_side, state, terminal: terminal)
+        self.class.new(type, new_side, state, terminal: terminal?)
       end
 
-      # Create a new identifier with a different state
+      # Returns a new Identifier with a different state.
       #
-      # @param new_state [Symbol] new state (:normal, :enhanced, or :diminished)
-      # @return [Identifier] new identifier instance with new state
+      # @param new_state [Symbol] The new state (:normal, :enhanced, or :diminished)
+      # @return [Identifier] A new Identifier with the specified state
+      # @raise [Errors::Argument] If the state is invalid
+      #
+      # @example
+      #   pin = Identifier.new(:K, :first)
+      #   pin.with_state(:enhanced).to_s # => "+K"
       def with_state(new_state)
-        self.class.validate_state(new_state)
-        return self if state == new_state
+        return self if state.equal?(new_state)
 
-        self.class.new(type, side, new_state, terminal: terminal)
+        self.class.new(type, side, new_state, terminal: terminal?)
       end
 
-      # Create a new identifier with a different terminal status
+      # Returns a new Identifier with a different terminal status.
+      #
+      # @param new_terminal [Boolean] The new terminal status
+      # @return [Identifier] A new Identifier with the specified terminal status
+      # @raise [Errors::Argument] If the terminal is not a boolean
       #
-      # @param new_terminal [Boolean] new terminal status
-      # @return [Identifier] new identifier instance with new terminal status
+      # @example
+      #   pin = Identifier.new(:K, :first)
+      #   pin.with_terminal(true).to_s # => "K^"
       def with_terminal(new_terminal)
-        new_terminal_bool = !!new_terminal
-        return self if terminal? == new_terminal_bool
+        return self if terminal?.equal?(new_terminal)
 
-        self.class.new(type, side, state, terminal: new_terminal_bool)
+        self.class.new(type, side, state, terminal: new_terminal)
       end
 
-      # Check if the identifier has enhanced state
+      # ========================================================================
+      # State Queries
+      # ========================================================================
+
+      # Checks if the Identifier has normal state.
       #
-      # @return [Boolean] true if enhanced
-      def enhanced?
-        state == ENHANCED_STATE
+      # @return [Boolean] true if normal state
+      #
+      # @example
+      #   Identifier.new(:K, :first).normal? # => true
+      def normal?
+        state.equal?(:normal)
       end
 
-      # Check if the identifier has diminished state
+      # Checks if the Identifier has enhanced state.
       #
-      # @return [Boolean] true if diminished
-      def diminished?
-        state == DIMINISHED_STATE
+      # @return [Boolean] true if enhanced state
+      #
+      # @example
+      #   Identifier.new(:K, :first, :enhanced).enhanced? # => true
+      def enhanced?
+        state.equal?(:enhanced)
       end
 
-      # Check if the identifier has normal state
+      # Checks if the Identifier has diminished state.
       #
-      # @return [Boolean] true if normal
-      def normal?
-        state == NORMAL_STATE
+      # @return [Boolean] true if diminished state
+      #
+      # @example
+      #   Identifier.new(:K, :first, :diminished).diminished? # => true
+      def diminished?
+        state.equal?(:diminished)
       end
 
-      # Check if the identifier belongs to the first player
+      # ========================================================================
+      # Side Queries
+      # ========================================================================
+
+      # Checks if the Identifier belongs to the first player.
       #
       # @return [Boolean] true if first player
+      #
+      # @example
+      #   Identifier.new(:K, :first).first_player? # => true
       def first_player?
-        side == FIRST_PLAYER
+        side.equal?(:first)
       end
 
-      # Check if the identifier belongs to the second player
+      # Checks if the Identifier belongs to the second player.
       #
       # @return [Boolean] true if second player
+      #
+      # @example
+      #   Identifier.new(:K, :second).second_player? # => true
       def second_player?
-        side == SECOND_PLAYER
+        side.equal?(:second)
       end
 
-      # Check if the identifier is a terminal piece
-      #
-      # @return [Boolean] true if terminal
-      def terminal?
-        terminal
-      end
+      # ========================================================================
+      # Comparison Queries
+      # ========================================================================
 
-      # Check if this identifier is the same type as another
+      # Checks if two Identifiers have the same type.
       #
-      # @param other [Identifier] identifier to compare with
+      # @param other [Identifier] The other Identifier to compare
       # @return [Boolean] true if same type
+      #
+      # @example
+      #   pin1 = Identifier.new(:K, :first)
+      #   pin2 = Identifier.new(:K, :second)
+      #   pin1.same_type?(pin2) # => true
       def same_type?(other)
-        return false unless other.is_a?(self.class)
-
-        type == other.type
+        type.equal?(other.type)
       end
 
-      # Check if this identifier has the same side as another
+      # Checks if two Identifiers have the same side.
       #
-      # @param other [Identifier] identifier to compare with
+      # @param other [Identifier] The other Identifier to compare
       # @return [Boolean] true if same side
+      #
+      # @example
+      #   pin1 = Identifier.new(:K, :first)
+      #   pin2 = Identifier.new(:Q, :first)
+      #   pin1.same_side?(pin2) # => true
       def same_side?(other)
-        return false unless other.is_a?(self.class)
-
-        side == other.side
+        side.equal?(other.side)
       end
 
-      # Check if this identifier has the same state as another
+      # Checks if two Identifiers have the same state.
       #
-      # @param other [Identifier] identifier to compare with
+      # @param other [Identifier] The other Identifier to compare
       # @return [Boolean] true if same state
+      #
+      # @example
+      #   pin1 = Identifier.new(:K, :first, :enhanced)
+      #   pin2 = Identifier.new(:Q, :second, :enhanced)
+      #   pin1.same_state?(pin2) # => true
       def same_state?(other)
-        return false unless other.is_a?(self.class)
-
-        state == other.state
+        state.equal?(other.state)
       end
 
-      # Check if this identifier has the same terminal status as another
+      # Checks if two Identifiers have the same terminal status.
       #
-      # @param other [Identifier] identifier to compare with
+      # @param other [Identifier] The other Identifier to compare
       # @return [Boolean] true if same terminal status
+      #
+      # @example
+      #   pin1 = Identifier.new(:K, :first, :normal, terminal: true)
+      #   pin2 = Identifier.new(:Q, :second, :normal, terminal: true)
+      #   pin1.same_terminal?(pin2) # => true
       def same_terminal?(other)
-        return false unless other.is_a?(self.class)
-
-        terminal? == other.terminal?
+        terminal?.equal?(other.terminal?)
       end
 
-      # Custom equality comparison
+      # ========================================================================
+      # Equality
+      # ========================================================================
+
+      # Checks equality with another Identifier.
       #
-      # @param other [Object] object to compare with
-      # @return [Boolean] true if identifiers are equal
+      # @param other [Object] The object to compare
+      # @return [Boolean] true if equal
       def ==(other)
-        return false unless other.is_a?(self.class)
+        return false unless self.class === other
 
-        type == other.type && side == other.side && state == other.state && terminal? == other.terminal?
+        type.equal?(other.type) &&
+          side.equal?(other.side) &&
+          state.equal?(other.state) &&
+          terminal?.equal?(other.terminal?)
       end
 
-      # Alias for == to ensure Set functionality works correctly
       alias eql? ==
 
-      # Custom hash implementation for use in collections
+      # Returns a hash code for the Identifier.
       #
-      # @return [Integer] hash value
+      # @return [Integer] Hash code
       def hash
-        [self.class, type, side, state, terminal?].hash
+        [type, side, state, terminal?].hash
       end
 
-      # Validate that the type is a valid symbol
+      # Returns an inspect string for the Identifier.
       #
-      # @param type [Symbol] the type to validate
-      # @raise [ArgumentError] if invalid
-      def self.validate_type(type)
-        return if VALID_TYPES.include?(type)
-
-        raise ::ArgumentError, format(ERROR_INVALID_TYPE, type.inspect)
+      # @return [String] Inspect representation
+      def inspect
+        "#<#{self.class} #{self}>"
       end
 
-      # Validate that the side is a valid symbol
-      #
-      # @param side [Symbol] the side to validate
-      # @raise [ArgumentError] if invalid
-      def self.validate_side(side)
-        return if VALID_SIDES.include?(side)
+      private
 
-        raise ::ArgumentError, format(ERROR_INVALID_SIDE, side.inspect)
-      end
+      # ========================================================================
+      # Private Validation
+      # ========================================================================
 
-      # Validate that the state is a valid symbol
-      #
-      # @param state [Symbol] the state to validate
-      # @raise [ArgumentError] if invalid
-      def self.validate_state(state)
-        return if VALID_STATES.include?(state)
+      def validate_type!(type)
+        return if Constants::VALID_TYPES.include?(type)
 
-        raise ::ArgumentError, format(ERROR_INVALID_STATE, state.inspect)
+        raise Errors::Argument, Errors::Argument::Messages::INVALID_TYPE
       end
 
-      # Match PIN pattern against string
-      #
-      # @param string [String] string to match
-      # @return [MatchData] match data
-      # @raise [ArgumentError] if string doesn't match
-      def self.match_pattern(string)
-        matches = PIN_PATTERN.match(string)
-        return matches if matches
+      def validate_side!(side)
+        return if Constants::VALID_SIDES.include?(side)
 
-        raise ::ArgumentError, format(ERROR_INVALID_PIN, string)
+        raise Errors::Argument, Errors::Argument::Messages::INVALID_SIDE
       end
 
-      private_class_method :match_pattern
+      def validate_state!(state)
+        return if Constants::VALID_STATES.include?(state)
 
-      private
+        raise Errors::Argument, Errors::Argument::Messages::INVALID_STATE
+      end
 
-      # Get the opposite side of the current identifier
-      #
-      # @return [Symbol] :first if current side is :second, :second if current side is :first
-      def opposite_side
-        first_player? ? SECOND_PLAYER : FIRST_PLAYER
+      def validate_terminal!(terminal)
+        return if ::TrueClass === terminal || ::FalseClass === terminal
+
+        raise Errors::Argument, Errors::Argument::Messages::INVALID_TERMINAL
       end
     end
   end