sashite-feen 0.1.0 → 0.2.0

data/lib/sashite/feen/dumper/style_turn.rb

@@ -3,56 +3,40 @@
 module Sashite
   module Feen
     module Dumper
+      # Dumper for the style-turn field (third field of FEEN).
+      #
+      # Converts a Styles object into its FEEN string representation,
+      # encoding game styles and indicating the active player.
+      #
+      # @see https://sashite.dev/specs/feen/1.0.0/
       module StyleTurn
-        # Separator between turn and styles
-        TURN_STYLES_SEPARATOR = ";"
-        # Separator between multiple style tokens
-        STYLES_SEPARATOR = ","
+        # Style separator in style-turn field.
+        STYLE_SEPARATOR = "/"
 
-        module_function
-
-        # Dump the style/turn field (e.g., "w", "b;rule1,variantX")
+        # Dump a Styles object into its FEEN style-turn string.
         #
-        # Canonicalization:
-        #   - styles sorted lexicographically by SIN token
+        # Formats the active and inactive player styles with the active
+        # player's style appearing first. The case of each style identifier
+        # indicates which player uses it (uppercase = first player,
+        # lowercase = second player).
         #
-        # @param styles [Sashite::Feen::Styles]
-        # @return [String]
-        def dump(styles)
-          st = _coerce_styles(styles)
-
-          turn_str = _dump_turn(st.turn)
-
-          return turn_str if st.list.nil? || st.list.empty?
-
-          tokens = st.list.map do |sin_value|
-            ::Sashite::Sin.dump(sin_value)
-          rescue StandardError => e
-            raise Error::Style, "invalid SIN value in styles: #{e.message}"
-          end
-
-          tokens.sort!
-          "#{turn_str}#{TURN_STYLES_SEPARATOR}#{tokens.join(STYLES_SEPARATOR)}"
-        end
-
-        # -- internals ---------------------------------------------------------
-
-        def _dump_turn(turn)
-          case turn
-          when :first  then "w"
-          when :second then "b"
-          else
-            raise Error::Style, "invalid turn symbol #{turn.inspect}"
-          end
-        end
-        private_class_method :_dump_turn
-
-        def _coerce_styles(obj)
-          return obj if obj.is_a?(Styles)
-
-          raise TypeError, "expected Sashite::Feen::Styles, got #{obj.class}"
+        # @param styles [Styles] The styles object with active and inactive styles
+        # @return [String] FEEN style-turn field string
+        #
+        # @example Chess game, white to move
+        #   dump(styles)
+        #   # => "C/c"
+        #
+        # @example Chess game, black to move
+        #   dump(styles)
+        #   # => "c/C"
+        #
+        # @example Cross-style game, first player to move
+        #   dump(styles)
+        #   # => "C/m"
+        def self.dump(styles)
+          "#{styles.active}#{STYLE_SEPARATOR}#{styles.inactive}"
         end
-        private_class_method :_coerce_styles
       end
     end
   end

data/lib/sashite/feen/dumper.rb

@@ -1,49 +1,59 @@
 # frozen_string_literal: true
 
-# FEEN Dumper (entry point)
-# -------------------------
-# Serializes a Position object into its canonical FEEN string by delegating
-# each field to its dedicated sub-dumper.
-#
-# Sub-dumpers:
-#   dumper/piece_placement.rb
-#   dumper/pieces_in_hand.rb
-#   dumper/style_turn.rb
-
 require_relative "dumper/piece_placement"
 require_relative "dumper/pieces_in_hand"
 require_relative "dumper/style_turn"
 
 module Sashite
   module Feen
+    # Dumper for FEEN (Forsyth–Edwards Enhanced Notation) positions.
+    #
+    # Converts a Position object into its canonical FEEN string representation
+    # by delegating serialization to specialized dumpers for each component.
+    #
+    # @see https://sashite.dev/specs/feen/1.0.0/
     module Dumper
-      # Separator used between the three FEEN fields
+      # Field separator in FEEN notation.
       FIELD_SEPARATOR = " "
 
-      module_function
+      # Number of fields in a FEEN string.
+      FIELD_COUNT = 3
 
-      # Dump a Position into a FEEN string
+      # Dump a Position object into its canonical FEEN string representation.
       #
-      # @param position [Sashite::Feen::Position]
-      # @return [String]
-      def dump(position)
-        pos = _coerce_position(position)
-
-        [
-          PiecePlacement.dump(pos.placement),
-          PiecesInHand.dump(pos.hands),
-          StyleTurn.dump(pos.styles)
-        ].join(FIELD_SEPARATOR)
+      # Generates a deterministic FEEN string from a position object. The same
+      # position will always produce the same canonical string.
+      #
+      # @param position [Position] A position object with placement, hands, and styles
+      # @return [String] Canonical FEEN notation string
+      #
+      # @example Dump a position to FEEN
+      #   feen_string = Dumper.dump(position)
+      #   # => "+rnbq+kbn+r/+p+p+p+p+p+p+p+p/8/8/8/8/+P+P+P+P+P+P+P+P/+RNBQ+KBN+R / C/c"
+      def self.dump(position)
+        fields = [
+          Dumper::PiecePlacement.dump(position.placement),
+          Dumper::PiecesInHand.dump(position.hands),
+          Dumper::StyleTurn.dump(position.styles)
+        ]
+
+        join_fields(fields)
       end
 
-      # -- helpers -------------------------------------------------------------
-
-      def _coerce_position(obj)
-        return obj if obj.is_a?(Position)
-
-        raise TypeError, "expected Sashite::Feen::Position, got #{obj.class}"
+      # Join the three FEEN fields into a single string.
+      #
+      # Combines the piece placement, pieces in hand, and style-turn fields
+      # with the field separator.
+      #
+      # @param fields [Array<String>] Array of three field strings
+      # @return [String] Complete FEEN string
+      #
+      # @example Join three fields
+      #   join_fields(["rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR", "/", "C/c"])
+      #   # => "rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR / C/c"
+      private_class_method def self.join_fields(fields)
+        fields.join(FIELD_SEPARATOR)
       end
-      private_class_method :_coerce_position
     end
   end
 end

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.freeze
+        @second_player = second_player.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