sashite-feen 0.3.0 → 0.5.0

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

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+require_relative "../shared/ascii"
+
+module Sashite
+  module Feen
+    module Dumper
+      # Serializer for the FEEN Hands field (Field 2).
+      #
+      # Converts hand maps (piece → count) into the canonical FEEN string.
+      #
+      # @api private
+      module Hands
+        # Serializes hands to a FEEN Hands field string.
+        #
+        # @param first_player_hand [Hash{String => Integer}] First player's pieces
+        # @param second_player_hand [Hash{String => Integer}] Second player's pieces
+        # @return [String] Canonical Hands field string
+        def self.dump(first_player_hand, second_player_hand)
+          "#{dump_hand(first_player_hand)}/#{dump_hand(second_player_hand)}"
+        end
+
+        class << self
+          private
+
+          def dump_hand(hand)
+            return "" if hand.empty?
+
+            items = hand.to_a
+
+            items.sort! do |a, b|
+              # a = [piece, count], b = [piece, count]
+              cmp = b[1] <=> a[1]
+              cmp == 0 ? compare_pieces(a[0], b[0]) : cmp
+            end
+
+            result = String.new
+            items.each do |piece, count|
+              result << count.to_s if count >= 2
+              result << piece
+            end
+            result
+          end
+
+          # Compares two EPIN strings according to canonical ordering.
+          def compare_pieces(str_a, str_b)
+            pos_a = 0
+            byte_a = str_a.getbyte(pos_a)
+
+            if byte_a == Ascii::MINUS
+              state_a = 0; pos_a += 1; byte_a = str_a.getbyte(pos_a)
+            elsif byte_a == Ascii::PLUS
+              state_a = 1; pos_a += 1; byte_a = str_a.getbyte(pos_a)
+            else
+              state_a = 2
+            end
+
+            pos_b = 0
+            byte_b = str_b.getbyte(pos_b)
+
+            if byte_b == Ascii::MINUS
+              state_b = 0; pos_b += 1; byte_b = str_b.getbyte(pos_b)
+            elsif byte_b == Ascii::PLUS
+              state_b = 1; pos_b += 1; byte_b = str_b.getbyte(pos_b)
+            else
+              state_b = 2
+            end
+
+            # 2. By base letter -- case-insensitive
+            cmp = (byte_a | 0x20) <=> (byte_b | 0x20)
+            return cmp unless cmp == 0
+
+            # 3. By letter case -- uppercase before lowercase
+            cmp = (byte_a < Ascii::LOWER_A ? 0 : 1) <=> (byte_b < Ascii::LOWER_A ? 0 : 1)
+            return cmp unless cmp == 0
+
+            # 4. By state modifier
+            cmp = state_a <=> state_b
+            return cmp unless cmp == 0
+
+            pos_a += 1; byte_a = str_a.getbyte(pos_a)
+            pos_b += 1; byte_b = str_b.getbyte(pos_b)
+
+            # 5. By terminal marker
+            ta = byte_a == Ascii::CARET ? 1 : 0
+            tb = byte_b == Ascii::CARET ? 1 : 0
+            cmp = ta <=> tb
+            return cmp unless cmp == 0
+
+            if ta == 1; byte_a = str_a.getbyte(pos_a + 1); end
+            if tb == 1; byte_b = str_b.getbyte(pos_b + 1); end
+
+            # 6. By derivation marker
+            (byte_a == Ascii::APOSTROPHE ? 1 : 0) <=> (byte_b == Ascii::APOSTROPHE ? 1 : 0)
+          end
+        end
+
+        private_class_method :dump_hand,
+                             :compare_pieces
+
+        freeze
+      end
+    end
+  end
+end

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

@@ -3,163 +3,95 @@
 module Sashite
   module Feen
     module Dumper
-      # Dumper for the piece placement field (first field of FEEN).
+      # Serializer for the FEEN Piece Placement field (Field 1).
       #
-      # 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
+      # Converts a flat board + shape into the canonical FEEN string
+      # with run-length encoding and dimensional separators.
       #
-      # The dumper produces canonical FEEN strings that enable perfect
-      # round-trip conversion (dump → parse → dump).
-      #
-      # @see https://sashite.dev/specs/feen/1.0.0/
+      # @api private
       module PiecePlacement
-        # Dump a Placement object into its FEEN piece placement string.
-        #
-        # 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)
+        # Serializes a flat board to a FEEN Piece Placement field string.
+        #
+        # @param board [Array<String, nil>] Flat board (row-major order)
+        # @param shape [Array<Integer>] Board dimensions
+        # @return [String] Canonical Piece Placement string
+        def self.dump(board, shape)
+          case shape.size
+          when 1
+            result = String.new
+            dump_rank_into(result, board, 0, shape[0])
+            result
+          when 2
+            dump_2d(board, shape[0], shape[1])
+          when 3
+            dump_3d(board, shape[0], shape[1], shape[2])
+          end
         end
 
-        # 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
+        class << self
+          private
+
+          def dump_2d(board, ranks, files)
+            result = String.new
+            offset = 0
+
+            ranks.times do |i|
+              result << "/" if i > 0
+              dump_rank_into(result, board, offset, files)
+              offset += files
+            end
+
+            result
           end
 
-          result.join
-        end
+          def dump_3d(board, layers, ranks, files)
+            result = String.new
+            offset = 0
 
-        # 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
+            layers.times do |li|
+              result << "//" if li > 0
+
+              ranks.times do |ri|
+                result << "/" if ri > 0
+                dump_rank_into(result, board, offset, files)
+                offset += files
+              end
             end
+
+            result
           end
 
-          # Flush final empty count
-          flush_empty_count!(result, empty_count)
+          # Appends a run-length-encoded rank into a buffer.
+          def dump_rank_into(result, board, offset, length)
+            empty_count = 0
+            stop = offset + length
 
-          result.join
-        end
+            while offset < stop
+              square = board[offset]
 
-        # 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
+              if square.nil?
+                empty_count += 1
+              else
+                if empty_count > 0
+                  result << empty_count.to_s
+                  empty_count = 0
+                end
+
+                result << square
+              end
+
+              offset += 1
+            end
+
+            result << empty_count.to_s if empty_count > 0
+          end
         end
+
+        private_class_method :dump_2d,
+                             :dump_3d,
+                             :dump_rank_into
+
+        freeze
       end
     end
   end

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

@@ -3,40 +3,25 @@
 module Sashite
   module Feen
     module Dumper
-      # Dumper for the style-turn field (third field of FEEN).
+      # Serializer for the FEEN Style-Turn field (Field 3).
       #
-      # 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/
+      # @api private
       module StyleTurn
-        # Style separator in style-turn field.
-        STYLE_SEPARATOR = "/"
-
-        # Dump a Styles object into its FEEN style-turn string.
-        #
-        # 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 [Styles] The styles object with active and inactive styles
-        # @return [String] FEEN style-turn field string
+        # Serializes styles and turn to a 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}"
+        # @param first_player_style [String] SIN token for the first player
+        # @param second_player_style [String] SIN token for the second player
+        # @param turn [Symbol] :first or :second
+        # @return [String] Canonical Style-Turn field string
+        def self.dump(first_player_style, second_player_style, turn)
+          if turn == :first
+            "#{first_player_style}/#{second_player_style}"
+          else
+            "#{second_player_style}/#{first_player_style}"
+          end
         end
+
+        freeze
       end
     end
   end

data/lib/sashite/feen/dumper.rb

@@ -1,59 +1,29 @@
 # frozen_string_literal: true
 
 require_relative "dumper/piece_placement"
-require_relative "dumper/pieces_in_hand"
+require_relative "dumper/hands"
 require_relative "dumper/style_turn"
 
 module Sashite
   module Feen
-    # Dumper for FEEN (Forsyth–Edwards Enhanced Notation) positions.
+    # Serializer for FEEN strings. Converts a Qi position into a
+    # canonical FEEN string with three space-separated fields.
     #
-    # 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/
+    # @api private
     module Dumper
-      # Field separator in FEEN notation.
-      FIELD_SEPARATOR = " "
-
-      # Number of fields in a FEEN string.
-      FIELD_COUNT = 3
-
-      # Dump a Position object into its canonical FEEN string representation.
-      #
-      # 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
+      # Serializes a Qi position to a canonical FEEN 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"
+      # @param position [Qi] The position to serialize
+      # @return [String] Canonical FEEN string
       def self.dump(position)
-        fields = [
-          Dumper::PiecePlacement.dump(position.placement),
-          Dumper::PiecesInHand.dump(position.hands),
-          Dumper::StyleTurn.dump(position.styles)
-        ]
+        pp = PiecePlacement.dump(position.board, position.shape)
+        hands = Hands.dump(position.first_player_hand, position.second_player_hand)
+        st = StyleTurn.dump(position.first_player_style, position.second_player_style, position.turn)
 
-        join_fields(fields)
+        "#{pp} #{hands} #{st}"
       end
 
-      # 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
+      freeze
     end
   end
 end

data/lib/sashite/feen/error.rb

@@ -4,80 +4,12 @@ module Sashite
   module Feen
     # 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.
+    # Inherits from ArgumentError for compatibility with standard Ruby
+    # error handling patterns.
     #
-    # @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
-
-      # 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
-
-      # 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
-
-      # 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
-
-      # 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
+    # @api public
+    class Error < ::ArgumentError
+      freeze
     end
   end
 end

data/lib/sashite/feen/errors/cardinality_error.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require_relative "parse_error"
+
+module Sashite
+  module Feen
+    # Error raised when cardinality constraints are violated.
+    #
+    # Total pieces (board + hands) must not exceed total squares.
+    #
+    # @api public
+    class CardinalityError < ParseError
+      TOO_MANY_PIECES = "too many pieces for board size"
+
+      freeze
+    end
+  end
+end

data/lib/sashite/feen/errors/hands_error.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require_relative "parse_error"
+
+module Sashite
+  module Feen
+    # Error raised when Hands field (Field 2) parsing fails.
+    #
+    # @api public
+    class HandsError < ParseError
+      INVALID_DELIMITER   = "invalid hands delimiter"
+      INVALID_COUNT       = "invalid hand count"
+      INVALID_PIECE_TOKEN = "invalid piece token"
+      NOT_AGGREGATED      = "hand items not aggregated"
+      NOT_CANONICAL       = "hand items not in canonical order"
+
+      freeze
+    end
+  end
+end

data/lib/sashite/feen/errors/parse_error.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require_relative "../error"
+
+module Sashite
+  module Feen
+    # Error raised when FEEN parsing fails at the top level.
+    #
+    # Covers general failures (input length, field count). Field-specific
+    # errors have their own subclasses.
+    #
+    # @api public
+    class ParseError < Error
+      INPUT_TOO_LONG      = "input exceeds maximum length"
+      INVALID_FIELD_COUNT = "invalid field count"
+
+      freeze
+    end
+  end
+end

data/lib/sashite/feen/errors/piece_placement_error.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require_relative "parse_error"
+
+module Sashite
+  module Feen
+    # Error raised when Piece Placement field (Field 1) parsing fails.
+    #
+    # @api public
+    class PiecePlacementError < ParseError
+      EMPTY                    = "piece placement is empty"
+      STARTS_WITH_SEPARATOR    = "piece placement starts with separator"
+      ENDS_WITH_SEPARATOR      = "piece placement ends with separator"
+      EMPTY_SEGMENT            = "empty segment"
+      INVALID_EMPTY_COUNT      = "invalid empty count"
+      INVALID_PIECE_TOKEN      = "invalid piece token"
+      CONSECUTIVE_EMPTY_COUNTS = "consecutive empty counts must be merged"
+      DIMENSIONAL_COHERENCE    = "dimensional coherence violation"
+      EXCEEDS_MAX_DIMENSIONS   = "exceeds maximum dimensions"
+      DIMENSION_SIZE_EXCEEDED  = "dimension size exceeded"
+
+      freeze
+    end
+  end
+end

data/lib/sashite/feen/errors/style_turn_error.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require_relative "parse_error"
+
+module Sashite
+  module Feen
+    # Error raised when Style-Turn field (Field 3) parsing fails.
+    #
+    # @api public
+    class StyleTurnError < ParseError
+      INVALID_DELIMITER   = "invalid style-turn delimiter"
+      INVALID_STYLE_TOKEN = "invalid style token"
+      SAME_CASE           = "style tokens must have opposite case"
+
+      freeze
+    end
+  end
+end