sashite-feen 0.1.0 → 0.3.0

data/lib/sashite/feen/error.rb

@@ -2,39 +2,82 @@
 
 module Sashite
   module Feen
-    # Namespaced error types for FEEN
-    module Error
-      # Base FEEN error (immutable, with optional context payload)
-      class Base < StandardError
-        # @return [Hash, nil] optional contextual information (e.g., { rank: 3, col: 5 })
-        attr_reader :context
+    # Base error class for all FEEN-related errors.
+    #
+    # All FEEN parsing and validation errors inherit from this class,
+    # allowing callers to rescue all FEEN errors with a single rescue clause.
+    #
+    # @see https://sashite.dev/specs/feen/1.0.0/
+    class Error < StandardError
+      # Error raised when FEEN structure is malformed.
+      #
+      # Indicates problems with the overall FEEN format, such as:
+      # - Missing or incorrect number of fields
+      # - Missing required separators
+      # - Empty fields where content is required
+      # - Invalid field structure
+      #
+      # @example Missing field separator
+      #   raise Error::Syntax, "FEEN must have exactly 3 space-separated fields"
+      #
+      # @example Empty required field
+      #   raise Error::Syntax, "active style cannot be empty"
+      class Syntax < Error; end
 
-        # @param message [String, nil]
-        # @param context [Hash, nil] optional structured context (will be frozen)
-        def initialize(message = nil, context: nil)
-          @context = context&.dup&.freeze
-          super(message)
-          freeze
-        end
-      end
+      # Error raised when EPIN (Extended Piece Identifier Notation) is invalid.
+      #
+      # Indicates problems with piece notation, such as:
+      # - Invalid EPIN format
+      # - Unrecognized piece characters
+      # - Malformed state modifiers or derivation suffixes
+      # - EPIN parsing failures
+      #
+      # @example Invalid EPIN format
+      #   raise Error::Piece, "invalid EPIN notation: K#"
+      #
+      # @example Failed EPIN parsing
+      #   raise Error::Piece, "failed to parse EPIN 'X': unknown piece type"
+      class Piece < Error; end
 
-      # Raised when the FEEN text does not match the required grammar
-      class Syntax < Base; end
+      # Error raised when SIN (Style Identifier Notation) is invalid.
+      #
+      # Indicates problems with style notation, such as:
+      # - Invalid SIN format
+      # - Non-letter characters in style identifier
+      # - Multi-character style identifiers
+      # - SIN parsing failures
+      #
+      # @example Invalid SIN format
+      #   raise Error::Style, "invalid SIN notation: '1' (must be a single letter)"
+      #
+      # @example Failed SIN parsing
+      #   raise Error::Style, "failed to parse SIN 'XY': too long"
+      class Style < Error; end
 
-      # Raised for structural/semantic violations after syntactic parsing
-      class Validation < Base; end
+      # Error raised when piece counts are invalid.
+      #
+      # Indicates problems with piece quantity specifications, such as:
+      # - Count less than 1
+      # - Count exceeding reasonable limits
+      # - Invalid count format
+      #
+      # @example Count too small
+      #   raise Error::Count, "piece count must be at least 1, got 0"
+      #
+      # @example Count too large
+      #   raise Error::Count, "piece count too large: 9999"
+      class Count < Error; end
 
-      # Raised when an EPIN token/value is invalid in the current context
-      class Piece < Base; end
-
-      # Raised when a SIN token/value or the style/turn field is invalid
-      class Style < Base; end
-
-      # Raised when a numeric count (e.g., run-length or hand quantity) is invalid
-      class Count < Base; end
-
-      # Raised when board/grid dimensions are empty/inconsistent/out of bounds
-      class Bounds < Base; end
+      # Error raised for other semantic validation failures.
+      #
+      # Indicates problems that don't fit other error categories, such as:
+      # - Inconsistent position state
+      # - Rule violations
+      # - Other semantic constraints
+      #
+      # @example Semantic constraint violation
+      #   raise Error::Validation, "position violates conservation principle"
+      class Validation < Error; end
     end
   end
 end

data/lib/sashite/feen/hands.rb

@@ -2,36 +2,78 @@
 
 module Sashite
   module Feen
-    # Immutable multiset of pieces-in-hand, keyed by EPIN value (as returned by Sashite::Epin.parse)
+    # Immutable representation of pieces held in hand by each player.
+    #
+    # Stores captured pieces that players hold in reserve, available for
+    # placement back onto the board in games that support drop mechanics
+    # (such as shogi, crazyhouse, etc.).
+    #
+    # @see https://sashite.dev/specs/feen/1.0.0/
     class Hands
-      attr_reader :map
+      # @return [Array] Array of pieces held by first player
+      attr_reader :first_player
 
-      # @param map [Hash<any, Integer>] counts per EPIN value
-      def initialize(map)
-        raise TypeError, "hands map must be a Hash, got #{map.class}" unless map.is_a?(Hash)
+      # @return [Array] Array of pieces held by second player
+      attr_reader :second_player
 
-        # Coerce counts to Integer and validate
-        coerced = {}
-        map.each do |k, v|
-          c = Integer(v)
-          raise Error::Count, "hand count must be >= 0, got #{c}" if c.negative?
-          next if c.zero? # normalize: skip zeros
+      # Create a new immutable Hands object.
+      #
+      # @param first_player [Array] Pieces in first player's hand
+      # @param second_player [Array] Pieces in second player's hand
+      #
+      # @example Empty hands
+      #   hands = Hands.new([], [])
+      #
+      # @example First player has captured pieces
+      #   hands = Hands.new([pawn1, pawn2], [])
+      #
+      # @example Both players have captured pieces
+      #   hands = Hands.new([rook, bishop], [pawn1, pawn2, knight])
+      def initialize(first_player, second_player)
+        @first_player = first_player.sort_by(&:to_s).freeze
+        @second_player = second_player.sort_by(&:to_s).freeze
 
-          coerced[k] = c
-        end
-
-        # Freeze shallowly (keys may already be complex frozen EPIN values)
-        @map = coerced.each_with_object({}) { |(k, v), h| h[k] = v }.freeze
         freeze
       end
 
-      # Convenience
+      # Check if both hands are empty.
+      #
+      # @return [Boolean] True if neither player has pieces in hand
+      #
+      # @example
+      #   hands.empty?  # => true
       def empty?
-        @map.empty?
+        first_player.empty? && second_player.empty?
+      end
+
+      # Convert hands to their FEEN string representation.
+      #
+      # @return [String] FEEN pieces-in-hand field
+      #
+      # @example
+      #   hands.to_s
+      #   # => "2P/p"
+      def to_s
+        Dumper::PiecesInHand.dump(self)
       end
 
-      def each(&)
-        @map.each(&)
+      # Compare two hands for equality.
+      #
+      # @param other [Hands] Another hands object
+      # @return [Boolean] True if both players' pieces are equal
+      def ==(other)
+        other.is_a?(Hands) &&
+          first_player == other.first_player &&
+          second_player == other.second_player
+      end
+
+      alias eql? ==
+
+      # Generate hash code for hands.
+      #
+      # @return [Integer] Hash code based on both players' pieces
+      def hash
+        [first_player, second_player].hash
       end
     end
   end