sashite-feen 0.1.0 → 0.3.0

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

@@ -3,83 +3,163 @@
 module Sashite
   module Feen
     module Dumper
+      # Dumper for the piece placement field (first field of FEEN).
+      #
+      # Converts a Placement object into its FEEN string representation,
+      # encoding board configuration using EPIN notation with:
+      # - Empty square compression (consecutive nils → numbers)
+      # - Exact separator preservation (from Placement.separators)
+      # - Support for any irregular board structure
+      #
+      # The dumper produces canonical FEEN strings that enable perfect
+      # round-trip conversion (dump → parse → dump).
+      #
+      # @see https://sashite.dev/specs/feen/1.0.0/
       module PiecePlacement
-        # Separator between ranks
-        RANK_SEPARATOR = "/"
-
-        module_function
-
-        # Dump a Placement grid to FEEN ranks (e.g., "rnbqkbnr/pppppppp/8/...")
+        # Dump a Placement object into its FEEN piece placement string.
         #
-        # @param placement [Sashite::Feen::Placement]
-        # @return [String]
-        def dump(placement)
-          pl = _coerce_placement(placement)
-
-          grid = pl.grid
-          raise Error::Bounds, "empty grid" if grid.empty?
-          raise Error::Bounds, "grid must be an Array of rows" unless grid.is_a?(Array)
-
-          width = nil
-          dumped_rows = grid.each_with_index.map do |row, r_idx|
-            raise Error::Bounds, "row #{r_idx + 1} must be an Array, got #{row.class}" unless row.is_a?(Array)
-
-            width ||= row.length
-            raise Error::Bounds, "row #{r_idx + 1} has zero width" if width.zero?
-
-            if row.length != width
-              raise Error::Bounds,
-                    "inconsistent row width at row #{r_idx + 1} (expected #{width}, got #{row.length})"
-            end
-
-            _dump_row(row, r_idx)
-          end
-
-          dumped_rows.join(RANK_SEPARATOR)
+        # Process:
+        # 1. For 1D boards: dump single rank directly
+        # 2. For multi-D boards: interleave ranks with their separators
+        # 3. Compress consecutive empty squares into numbers
+        # 4. Convert pieces to EPIN strings
+        #
+        # @param placement [Placement] The board placement object
+        # @return [String] FEEN piece placement field string
+        #
+        # @example Chess starting position
+        #   dump(placement)
+        #   # => "+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"
+        #
+        # @example Empty 8x8 board
+        #   dump(placement)
+        #   # => "8/8/8/8/8/8/8/8"
+        #
+        # @example 1D board
+        #   dump(placement)
+        #   # => "K2P3k"
+        #
+        # @example Irregular 3D board
+        #   dump(placement)
+        #   # => "5/5//5/5/5"
+        #
+        # @example Very large board
+        #   dump(placement)
+        #   # => "100/100/100"
+        def self.dump(placement)
+          # Special case: 1D board (no separators)
+          return dump_rank(placement.ranks[0]) if placement.one_dimensional?
+
+          # Multi-dimensional: interleave ranks and separators
+          dump_multi_dimensional(placement)
         end
 
-        # -- internals ---------------------------------------------------------
+        # Dump multi-dimensional placement.
+        #
+        # Alternates between ranks and separators:
+        # rank[0] + sep[0] + rank[1] + sep[1] + ... + rank[n]
+        #
+        # @param placement [Placement] Placement object
+        # @return [String] FEEN string with separators
+        #
+        # @example 2D board
+        #   dump_multi_dimensional(placement)
+        #   # => "r1/r2/r3"
+        #
+        # @example 3D board with mixed separators
+        #   dump_multi_dimensional(placement)
+        #   # => "r1/r2//r3"
+        private_class_method def self.dump_multi_dimensional(placement)
+          result = []
+
+          placement.ranks.each_with_index do |rank, idx|
+            # Dump the rank
+            result << dump_rank(rank)
+
+            # Add separator if not last rank
+            result << placement.separators[idx] if idx < placement.separators.size
+          end
 
-        # Accept nil (and legacy "") as empty cells
-        def _empty_cell?(cell)
-          cell.nil? || cell == ""
+          result.join
         end
-        private_class_method :_empty_cell?
-
-        def _dump_row(row, r_idx)
-          out = +""
-          empty_run = 0
-
-          row.each_with_index do |cell, c_idx|
-            if _empty_cell?(cell)
-              empty_run += 1
-              next
-            end
-
-            if empty_run.positive?
-              out << empty_run.to_s
-              empty_run = 0
-            end
 
-            begin
-              out << ::Sashite::Epin.dump(cell)
-            rescue StandardError => e
-              raise Error::Piece,
-                    "invalid EPIN value at (row #{r_idx + 1}, col #{c_idx + 1}): #{e.message}"
+        # Dump a single rank into its FEEN representation.
+        #
+        # Converts a rank (array of pieces and nils) into FEEN notation by:
+        # 1. Converting pieces to EPIN strings (via piece.to_s)
+        # 2. Compressing consecutive nils into number strings
+        #
+        # Algorithm:
+        # - Iterate through rank squares
+        # - Count consecutive nils (empty_count)
+        # - When hitting a piece: flush count (if > 0), add piece
+        # - At end: flush final count (if > 0)
+        #
+        # @param rank [Array] Array of piece objects and nils
+        # @return [String] FEEN rank string
+        #
+        # @example Rank with pieces only
+        #   dump_rank([K, Q, R, B])
+        #   # => "KQRB"
+        #
+        # @example Rank with empty squares
+        #   dump_rank([K, nil, nil, Q])
+        #   # => "K2Q"
+        #
+        # @example Rank all empty
+        #   dump_rank([nil, nil, nil, nil, nil, nil, nil, nil])
+        #   # => "8"
+        #
+        # @example Very large empty count
+        #   dump_rank(Array.new(100, nil))
+        #   # => "100"
+        #
+        # @example Complex rank
+        #   dump_rank([+K, nil, nil, -p', nil, R])
+        #   # => "+K2-p'1R"
+        private_class_method def self.dump_rank(rank)
+          result = []
+          empty_count = 0
+
+          rank.each do |square|
+            if square.nil?
+              # Empty square: increment counter
+              empty_count += 1
+            else
+              # Piece: flush empty count, add piece
+              flush_empty_count!(result, empty_count)
+              result << square.to_s
+              empty_count = 0
             end
           end
 
-          out << empty_run.to_s if empty_run.positive?
-          out
-        end
-        private_class_method :_dump_row
+          # Flush final empty count
+          flush_empty_count!(result, empty_count)
 
-        def _coerce_placement(obj)
-          return obj if obj.is_a?(Placement)
+          result.join
+        end
 
-          raise TypeError, "expected Sashite::Feen::Placement, got #{obj.class}"
+        # Flush accumulated empty count to result array.
+        #
+        # If empty_count > 0, appends the number as a string.
+        # This enables compression of consecutive empty squares.
+        #
+        # @param result [Array<String>] Result array being built
+        # @param empty_count [Integer] Number of consecutive empty squares
+        # @return [void]
+        #
+        # @example Flush count
+        #   result = ["K"]
+        #   flush_empty_count!(result, 5)
+        #   result  # => ["K", "5"]
+        #
+        # @example No flush (zero count)
+        #   result = ["K"]
+        #   flush_empty_count!(result, 0)
+        #   result  # => ["K"]
+        private_class_method def self.flush_empty_count!(result, empty_count)
+          result << empty_count.to_s if empty_count > 0
         end
-        private_class_method :_coerce_placement
       end
     end
   end

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

@@ -3,56 +3,146 @@
 module Sashite
   module Feen
     module Dumper
+      # Dumper for the pieces-in-hand field (second field of FEEN).
+      #
+      # Converts a Hands object into its FEEN string representation,
+      # encoding captured pieces held by each player in canonical sorted order.
+      #
+      # @see https://sashite.dev/specs/feen/1.0.0/
       module PiecesInHand
-        # Separator between hand entries
-        ENTRY_SEPARATOR = ","
+        # Player separator in pieces-in-hand field.
+        PLAYER_SEPARATOR = "/"
 
-        module_function
-
-        # Dump a Hands multiset to FEEN (e.g., "-", "P,2xN,R")
+        # Dump a Hands object into its FEEN pieces-in-hand string.
+        #
+        # Generates canonical representation with pieces sorted according to
+        # FEEN ordering rules: by quantity (descending), base letter (ascending),
+        # case (uppercase first), prefix (-, +, none), and suffix (none, ').
+        #
+        # @param hands [Hands] The hands object containing pieces for both players
+        # @return [String] FEEN pieces-in-hand field string
+        #
+        # @example No pieces in hand
+        #   dump(hands)
+        #   # => "/"
         #
-        # Canonicalization:
-        #   - entries sorted lexicographically by EPIN token
-        #   - counts rendered as "NxTOKEN" when N > 1
+        # @example First player has pieces
+        #   dump(hands)
+        #   # => "2P/p"
         #
-        # @param hands [Sashite::Feen::Hands]
-        # @return [String]
-        def dump(hands)
-          h = _coerce_hands(hands)
+        # @example Both players have pieces
+        #   dump(hands)
+        #   # => "RBN/2p"
+        def self.dump(hands)
+          first_player_str = dump_player_pieces(hands.first_player)
+          second_player_str = dump_player_pieces(hands.second_player)
 
-          map = h.map
-          raise Error::Count, "negative counts are not allowed" if map.values.any? { |v| Integer(v).negative? }
+          "#{first_player_str}#{PLAYER_SEPARATOR}#{second_player_str}"
+        end
 
-          return "-" if map.empty?
+        # Dump pieces for a single player.
+        #
+        # Groups identical pieces, counts them, sorts canonically, and formats
+        # with count prefix when needed (e.g., "3P" for three pawns).
+        #
+        # @param pieces [Array] Array of piece objects for one player
+        # @return [String] Formatted piece string (empty if no pieces)
+        #
+        # @example Single piece types
+        #   dump_player_pieces([pawn1, pawn2, pawn3, rook1])
+        #   # => "3PR"
+        #
+        # @example Empty hand
+        #   dump_player_pieces([])
+        #   # => ""
+        private_class_method def self.dump_player_pieces(pieces)
+          return "" if pieces.empty?
 
-          entries = map.map do |epin_value, count|
-            c = Integer(count)
-            raise Error::Count, "hand count must be >= 1, got #{c}" if c <= 0
+          grouped = group_pieces(pieces)
+          sorted = sort_grouped_pieces(grouped)
+          format_pieces(sorted)
+        end
 
-            token = begin
-              ::Sashite::Epin.dump(epin_value)
-            rescue StandardError => e
-              raise Error::Piece, "invalid EPIN value in hands: #{e.message}"
-            end
+        # Group identical pieces and count occurrences.
+        #
+        # @param pieces [Array] Array of piece objects
+        # @return [Hash] Hash mapping piece strings to counts
+        #
+        # @example
+        #   group_pieces([pawn1, pawn2, rook1])
+        #   # => {"P" => 2, "R" => 1}
+        private_class_method def self.group_pieces(pieces)
+          pieces.group_by(&:to_s).transform_values(&:size)
+        end
 
-            [token, c]
+        # Sort grouped pieces according to FEEN canonical ordering.
+        #
+        # Sorting rules (in order of precedence):
+        # 1. By quantity (descending) - most pieces first
+        # 2. By base letter (ascending, case-insensitive)
+        # 3. By case - uppercase before lowercase
+        # 4. By prefix - "-", "+", then none
+        # 5. By suffix - none, then "'"
+        #
+        # @param grouped [Hash] Hash of piece strings to counts
+        # @return [Array<Array>] Sorted array of [piece_string, count] pairs
+        #
+        # @example
+        #   sort_grouped_pieces({"p" => 2, "P" => 3, "R" => 1, "+K" => 1, "K'" => 1})
+        #   # => [["+K", 1], ["K'", 1], ["P", 3], ["p", 2], ["R", 1]]
+        private_class_method def self.sort_grouped_pieces(grouped)
+          grouped.sort_by do |piece_str, count|
+            [
+              -count,                              # Quantity (descending)
+              extract_base_letter(piece_str),      # Base letter (ascending)
+              piece_str.match?(/[A-Z]/) ? 0 : 1,   # Case (uppercase first)
+              prefix_order(piece_str),             # Prefix order
+              piece_str.end_with?("'") ? 1 : 0     # Suffix order (none first)
+            ]
           end
+        end
 
-          # Sort by EPIN token for deterministic output
-          entries.sort_by! { |(token, _)| token }
-
-          entries.map { |token, c| c == 1 ? token : "#{c}x#{token}" }
-                 .join(ENTRY_SEPARATOR)
+        # Extract base letter from piece string (without modifiers).
+        #
+        # @param piece_str [String] EPIN piece string
+        # @return [String] Uppercase base letter
+        #
+        # @example
+        #   extract_base_letter("+K'")  # => "K"
+        #   extract_base_letter("-p")   # => "P"
+        private_class_method def self.extract_base_letter(piece_str)
+          piece_str.gsub(/[+\-']/, "").upcase
         end
 
-        # -- helpers -----------------------------------------------------------
+        # Determine prefix sorting order.
+        #
+        # @param piece_str [String] EPIN piece string
+        # @return [Integer] Sort order (0 for "-", 1 for "+", 2 for none)
+        #
+        # @example
+        #   prefix_order("-K")  # => 0
+        #   prefix_order("+K")  # => 1
+        #   prefix_order("K")   # => 2
+        private_class_method def self.prefix_order(piece_str)
+          return 0 if piece_str.start_with?("-")
+          return 1 if piece_str.start_with?("+")
 
-        def _coerce_hands(obj)
-          return obj if obj.is_a?(Hands)
+          2
+        end
 
-          raise TypeError, "expected Sashite::Feen::Hands, got #{obj.class}"
+        # Format sorted pieces with count prefixes.
+        #
+        # @param sorted [Array<Array>] Sorted array of [piece_string, count] pairs
+        # @return [String] Formatted piece string
+        #
+        # @example
+        #   format_pieces([["P", 3], ["R", 1], ["p", 2]])
+        #   # => "3PR2p"
+        private_class_method def self.format_pieces(sorted)
+          sorted.map do |piece_str, count|
+            count > 1 ? "#{count}#{piece_str}" : piece_str
+          end.join
         end
-        private_class_method :_coerce_hands
       end
     end
   end

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