sashite-feen 0.1.0 → 0.2.0

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

@@ -1,76 +1,248 @@
 # frozen_string_literal: true
 
+require_relative "../error"
+require_relative "../hands"
+
+require "sashite/epin"
+
 module Sashite
   module Feen
     module Parser
+      # Parser for the pieces-in-hand field (second field of FEEN).
+      #
+      # Converts a FEEN pieces-in-hand string into a Hands object,
+      # decoding captured pieces held by each player with optional
+      # count prefixes.
+      #
+      # @see https://sashite.dev/specs/feen/1.0.0/
       module PiecesInHand
-        module_function
+        # Player separator in pieces-in-hand field.
+        PLAYER_SEPARATOR = "/"
+
+        # Pattern to match EPIN pieces (optional state prefix, letter, optional derivation suffix).
+        EPIN_PATTERN = /\A[-+]?[A-Za-z]'?\z/
+
+        # Parse a FEEN pieces-in-hand string into a Hands object.
+        #
+        # @param string [String] FEEN pieces-in-hand field string
+        # @return [Hands] Parsed hands object
+        # @raise [Error::Syntax] If hands format is invalid
+        # @raise [Error::Piece] If EPIN notation is invalid
+        # @raise [Error::Count] If piece counts are invalid
+        #
+        # @example No pieces in hand
+        #   parse("/")  # => Hands.new([], [])
+        #
+        # @example First player has pieces
+        #   parse("2P/p")  # => Hands.new([P, P], [p])
+        #
+        # @example Both players have pieces
+        #   parse("RBN/2p")  # => Hands.new([R, B, N], [p, p])
+        def self.parse(string)
+          first_str, second_str = split_players(string)
+
+          first_player_pieces = parse_player_pieces(first_str)
+          second_player_pieces = parse_player_pieces(second_str)
+
+          Hands.new(first_player_pieces, second_player_pieces)
+        end
+
+        # Split pieces-in-hand string into first and second player parts.
+        #
+        # @param string [String] Pieces-in-hand field string
+        # @return [Array(String, String)] First and second player strings
+        # @raise [Error::Syntax] If separator is missing
+        #
+        # @example
+        #   split_players("2P/p")  # => ["2P", "p"]
+        #   split_players("/")     # => ["", ""]
+        private_class_method def self.split_players(string)
+          parts = string.split(PLAYER_SEPARATOR, 2)
+
+          raise Error::Syntax, "pieces-in-hand must contain '#{PLAYER_SEPARATOR}' separator" unless parts.size == 2
+
+          parts
+        end
+
+        # Parse pieces for a single player.
+        #
+        # Extracts pieces with optional count prefixes and expands them
+        # into individual piece objects.
+        #
+        # @param string [String] Player's pieces string (e.g., "2PRB")
+        # @return [Array] Array of piece objects
+        # @raise [Error::Syntax] If format is invalid
+        # @raise [Error::Piece] If EPIN notation is invalid
+        # @raise [Error::Count] If counts are invalid
+        #
+        # @example Single pieces
+        #   parse_player_pieces("RBN")  # => [R, B, N]
+        #
+        # @example With counts
+        #   parse_player_pieces("3P2R")  # => [P, P, P, R, R]
+        #
+        # @example Empty
+        #   parse_player_pieces("")  # => []
+        private_class_method def self.parse_player_pieces(string)
+          return [] if string.empty?
+
+          pieces = []
+          chars = string.chars
+          i = 0
+
+          while i < chars.size
+            count, epin_str, consumed = extract_piece_with_count(chars, i)
+            piece = parse_piece(epin_str)
+
+            count.times { pieces << piece }
+            i += consumed
+          end
 
-        # Parse the pieces-in-hand field into a Hands value object.
+          pieces
+        end
+
+        # Extract a piece with optional count prefix from character array.
+        #
+        # Handles multi-digit counts and EPIN notation extraction.
+        #
+        # @param chars [Array<String>] Array of characters
+        # @param start_index [Integer] Starting index
+        # @return [Array(Integer, String, Integer)] Count, EPIN string, and chars consumed
+        # @raise [Error::Syntax] If format is invalid
+        # @raise [Error::Count] If count is invalid
         #
-        # Strictness:
-        #   - "-"  => empty hands (valid)
-        #   - ""   => invalid (raises Error::Syntax)
+        # @example Single piece
+        #   extract_piece_with_count(['K', 'Q'], 0)  # => [1, "K", 1]
         #
-        # Grammar (tolerant for counts notation):
-        #   hands   := "-" | entry ("," entry)*
-        #   entry   := epin | int ("x"|"*") epin | epin ("x"|"*") int
-        #   int     := [1-9][0-9]*
+        # @example Multiple pieces
+        #   extract_piece_with_count(['3', 'P', 'R'], 0)  # => [3, "P", 2]
         #
-        # @param field [String]
-        # @return [Sashite::Feen::Hands]
-        def parse(field)
-          src = String(field).strip
-          raise Error::Syntax, "empty hands field" if src.empty?
-          return Hands.new({}.freeze) if src == "-"
+        # @example Large count
+        #   extract_piece_with_count(['1', '2', 'P'], 0)  # => [12, "P", 3]
+        private_class_method def self.extract_piece_with_count(chars, start_index)
+          i = start_index
 
-          entries = src.split(",").map(&:strip).reject(&:empty?)
-          raise Error::Syntax, "malformed hands field" if entries.empty?
+          # Extract optional count (may be multi-digit)
+          count_chars = []
+          while i < chars.size && digit?(chars[i])
+            count_chars << chars[i]
+            i += 1
+          end
 
-          counts = Hash.new(0)
+          count = if count_chars.empty?
+                    1
+                  else
+                    count_str = count_chars.join
+                    count_val = count_str.to_i
+                    validate_count(count_val, count_str)
+                    count_val
+                  end
 
-          entries.each_with_index do |entry, idx|
-            epin_token, qty = _parse_hand_entry(entry, idx)
-            epin_id = _parse_epin(epin_token, idx)
-            counts[epin_id] += qty
+          # Extract EPIN piece
+          if i >= chars.size
+            raise Error::Syntax, "expected piece after count at position #{start_index}"
           end
 
-          frozen_counts = {}
-          counts.each { |k, v| frozen_counts[k] = Integer(v) }
+          epin_str, epin_consumed = extract_epin(chars, i)
+          i += epin_consumed
 
-          Hands.new(frozen_counts.freeze)
+          consumed = i - start_index
+          [count, epin_str, consumed]
         end
 
-        # Accepts forms: "P", "2xP", "P*2", "10*R", "[Shogi:P]*3"
-        def _parse_hand_entry(str, _idx)
-          s = str.strip
+        # Extract EPIN notation from character array.
+        #
+        # Handles state prefixes (+/-), base letter, and derivation suffix (').
+        #
+        # @param chars [Array<String>] Array of characters
+        # @param start_index [Integer] Starting index
+        # @return [Array(String, Integer)] EPIN string and number of characters consumed
+        # @raise [Error::Syntax] If EPIN format is incomplete
+        #
+        # @example Simple piece
+        #   extract_epin(['K', 'Q'], 0)  # => ["K", 1]
+        #
+        # @example Enhanced piece with derivation
+        #   extract_epin(['+', 'R', "'", 'B'], 0)  # => ["+R'", 3]
+        private_class_method def self.extract_epin(chars, start_index)
+          i = start_index
+          piece_chars = []
 
-          if (m = /\A(\d+)\s*[x*]\s*(.+)\z/.match(s))
-            n = Integer(m[1])
-            raise Error::Count, "hand count must be >= 1, got #{n}" if n <= 0
+          # Optional state prefix
+          if i < chars.size && (chars[i] == "+" || chars[i] == "-")
+            piece_chars << chars[i]
+            i += 1
+          end
 
-            return [m[2].strip, n]
+          # Base letter (required)
+          if i >= chars.size || !letter?(chars[i])
+            raise Error::Syntax, "expected letter in EPIN notation at position #{start_index}"
           end
 
-          if (m = /\A(.+?)\s*[x*]\s*(\d+)\z/.match(s))
-            n = Integer(m[2])
-            raise Error::Count, "hand count must be >= 1, got #{n}" if n <= 0
+          piece_chars << chars[i]
+          i += 1
 
-            return [m[1].strip, n]
+          # Optional derivation suffix
+          if i < chars.size && chars[i] == "'"
+            piece_chars << chars[i]
+            i += 1
           end
 
-          # Default: single piece
-          [s, 1]
+          piece_str = piece_chars.join
+          consumed = i - start_index
+
+          [piece_str, consumed]
+        end
+
+        # Check if character is a digit.
+        #
+        # @param char [String] Single character
+        # @return [Boolean] True if character is 0-9
+        private_class_method def self.digit?(char)
+          char >= "0" && char <= "9"
         end
-        module_function :_parse_hand_entry
-        private_class_method :_parse_hand_entry
 
-        def _parse_epin(token, idx)
-          ::Sashite::Epin.parse(token)
+        # Check if character is a letter.
+        #
+        # @param char [String] Single character
+        # @return [Boolean] True if character is A-Z or a-z
+        private_class_method def self.letter?(char)
+          (char >= "A" && char <= "Z") || (char >= "a" && char <= "z")
+        end
+
+        # Validate piece count.
+        #
+        # @param count [Integer] Piece count
+        # @param count_str [String] Original count string for error messages
+        # @raise [Error::Count] If count is invalid
+        private_class_method def self.validate_count(count, count_str)
+          if count < 1
+            raise Error::Count, "piece count must be at least 1, got #{count_str}"
+          end
+
+          if count > 999
+            raise Error::Count, "piece count too large: #{count_str}"
+          end
+        end
+
+        # Parse EPIN string into a piece object.
+        #
+        # @param epin_str [String] EPIN notation string
+        # @return [Object] Piece identifier object
+        # @raise [Error::Piece] If EPIN is invalid
+        #
+        # @example
+        #   parse_piece("K")    # => Epin::Identifier
+        #   parse_piece("+R'")  # => Epin::Identifier
+        private_class_method def self.parse_piece(epin_str)
+          unless EPIN_PATTERN.match?(epin_str)
+            raise Error::Piece, "invalid EPIN notation: #{epin_str}"
+          end
+
+          Sashite::Epin.parse(epin_str)
         rescue StandardError => e
-          raise Error::Piece, "invalid EPIN token in hands (entry #{idx + 1}): #{token.inspect} (#{e.message})"
+          raise Error::Piece, "failed to parse EPIN '#{epin_str}': #{e.message}"
         end
-        private_class_method :_parse_epin
       end
     end
   end

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

@@ -1,62 +1,102 @@
 # frozen_string_literal: true
 
+require_relative "../error"
+require_relative "../styles"
+
+require "sashite/sin"
+
 module Sashite
   module Feen
     module Parser
+      # Parser for the style-turn field (third field of FEEN).
+      #
+      # Converts a FEEN style-turn string into a Styles object,
+      # decoding game style identifiers and the active player indicator.
+      #
+      # @see https://sashite.dev/specs/feen/1.0.0/
+      # @see https://sashite.dev/specs/sin/1.0.0/
       module StyleTurn
-        module_function
+        # Style separator in style-turn field.
+        STYLE_SEPARATOR = "/"
 
-        # Strict FEEN + SIN:
-        #   style_turn := LETTER "/" LETTER              # no whitespace
-        #   semantics :
-        #     - Uppercase marks the side to move.
-        #     - Exactly one uppercase among the two.
-        #     - Each letter is a SIN style code (validated via Sashite::Sin.parse).
+        # Parse a FEEN style-turn string into a Styles object.
+        #
+        # @param string [String] FEEN style-turn field string
+        # @return [Styles] Parsed styles object
+        # @raise [Error::Syntax] If style-turn format is invalid
+        # @raise [Error::Style] If SIN notation is invalid
         #
-        # Examples (valid):
-        #   "C/c"  -> first to move,  first_style="C", second_style="C" (Chess vs Chess)
-        #   "c/C"  -> second to move
-        #   "S/o"  -> first to move,  first_style="S" (Shogi), second_style="O" (Ōgi)
+        # @example Chess game, white to move
+        #   parse("C/c")  # => Styles.new(sin_C, sin_c)
         #
-        # Examples (invalid):
-        #   "w" , "C / c", "Cc", "c/c", "C/C", "x/y "  (wrong pattern or spaces)
+        # @example Chess game, black to move
+        #   parse("c/C")  # => Styles.new(sin_c, sin_C)
         #
-        # @param field [String]
-        # @return [Sashite::Feen::Styles] with signature Styles.new(first_style, second_style, turn)
-        def parse(field)
-          s = String(field)
-          raise Error::Syntax, "empty style/turn field" if s.empty?
-          raise Error::Syntax, "whitespace not allowed in style/turn" if s.match?(/\s/)
+        # @example Cross-style game, first player to move
+        #   parse("C/m")  # => Styles.new(sin_C, sin_m)
+        def self.parse(string)
+          active_str, inactive_str = split_styles(string)
 
-          m = %r{\A([A-Za-z])/([A-Za-z])\z}.match(s)
-          raise Error::Syntax, "invalid style/turn format" unless m
+          active = parse_style(active_str)
+          inactive = parse_style(inactive_str)
 
-          a_raw = m[1]
-          b_raw = m[2]
-          a_is_up = a_raw.between?("A", "Z")
-          b_is_up = b_raw.between?("A", "Z")
+          Styles.new(active, inactive)
+        end
 
-          # Exactly one uppercase marks side to move
-          raise Error::Style, "ambiguous side-to-move: exactly one letter must be uppercase" unless a_is_up ^ b_is_up
+        # Split style-turn string into active and inactive parts.
+        #
+        # @param string [String] Style-turn field string
+        # @return [Array(String, String)] Active and inactive style strings
+        # @raise [Error::Syntax] If separator is missing or format is invalid
+        #
+        # @example
+        #   split_styles("C/c")  # => ["C", "c"]
+        #   split_styles("S/m")  # => ["S", "m"]
+        private_class_method def self.split_styles(string)
+          parts = string.split(STYLE_SEPARATOR, 2)
 
-          # Canonical SIN tokens are uppercase (style identity is case-insensitive in FEEN)
-          a_tok = a_raw.upcase
-          b_tok = b_raw.upcase
+          raise Error::Syntax, "style-turn must contain '#{STYLE_SEPARATOR}' separator" unless parts.size == 2
 
-          first_style = begin
-            ::Sashite::Sin.parse(a_tok)
-          rescue StandardError => e
-            raise Error::Style, "invalid SIN token for first side #{a_tok.inspect}: #{e.message}"
-          end
+          raise Error::Syntax, "active style cannot be empty" if parts[0].empty?
+          raise Error::Syntax, "inactive style cannot be empty" if parts[1].empty?
+
+          parts
+        end
 
-          second_style = begin
-            ::Sashite::Sin.parse(b_tok)
-          rescue StandardError => e
-            raise Error::Style, "invalid SIN token for second side #{b_tok.inspect}: #{e.message}"
+        # Parse a SIN string into a style identifier object.
+        #
+        # @param sin_str [String] SIN notation string (single letter)
+        # @return [Object] Style identifier object
+        # @raise [Error::Style] If SIN is invalid
+        #
+        # @example
+        #   parse_style("C")  # => Sin::Identifier (Chess, first player)
+        #   parse_style("c")  # => Sin::Identifier (Chess, second player)
+        #   parse_style("S")  # => Sin::Identifier (Shogi, first player)
+        private_class_method def self.parse_style(sin_str)
+          unless valid_sin_format?(sin_str)
+            raise Error::Style, "invalid SIN notation: '#{sin_str}' (must be a single letter A-Z or a-z)"
           end
 
-          turn = a_is_up ? :first : :second
-          Styles.new(first_style, second_style, turn)
+          Sashite::Sin.parse(sin_str)
+        rescue ::StandardError => e
+          raise Error::Style, "failed to parse SIN '#{sin_str}': #{e.message}"
+        end
+
+        # Check if string is a valid SIN format.
+        #
+        # @param string [String] String to validate
+        # @return [Boolean] True if string is a single ASCII letter
+        private_class_method def self.valid_sin_format?(string)
+          string.length == 1 && letter?(string[0])
+        end
+
+        # Check if character is a letter.
+        #
+        # @param char [String] Single character
+        # @return [Boolean] True if character is A-Z or a-z
+        private_class_method def self.letter?(char)
+          (char >= "A" && char <= "Z") || (char >= "a" && char <= "z")
         end
       end
     end

data/lib/sashite/feen/parser.rb

@@ -4,32 +4,68 @@ require_relative "parser/piece_placement"
 require_relative "parser/pieces_in_hand"
 require_relative "parser/style_turn"
 
+require_relative "error"
+require_relative "position"
+
 module Sashite
   module Feen
+    # Parser for FEEN (Forsyth–Edwards Enhanced Notation) strings.
+    #
+    # Parses a complete FEEN string by splitting it into three space-separated
+    # fields and delegating parsing to specialized parsers for each component.
+    #
+    # @see https://sashite.dev/specs/feen/1.0.0/
     module Parser
-      module_function
+      # Field separator in FEEN notation.
+      FIELD_SEPARATOR = " "
+
+      # Number of required fields in a valid FEEN string.
+      FIELD_COUNT = 3
 
-      def parse(feen)
-        s = String(feen).strip
-        raise Error::Syntax, "empty FEEN input" if s.empty?
+      # Parse a FEEN string into an immutable Position object.
+      #
+      # Validates the overall FEEN structure, splits the string into three
+      # space-separated fields, and delegates parsing of each field to the
+      # appropriate specialized parser.
+      #
+      # @param string [String] A FEEN notation string
+      # @return [Position] Immutable position object
+      # @raise [Error::Syntax] If the FEEN structure is malformed
+      #
+      # @example Parse a complete FEEN string
+      #   position = Parser.parse("+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.parse(string)
+        fields = split_fields(string)
 
-        a, b, c = _split_3_fields(s)
-        placement = PiecePlacement.parse(a)
-        hands     = PiecesInHand.parse(b)
-        styles    = StyleTurn.parse(c)
+        placement = Parser::PiecePlacement.parse(fields[0])
+        hands     = Parser::PiecesInHand.parse(fields[1])
+        styles    = Parser::StyleTurn.parse(fields[2])
 
         Position.new(placement, hands, styles)
       end
 
-      def _split_3_fields(s)
-        parts = s.split(/\s+/, 3)
-        unless parts.length == 3
-          raise Error::Syntax,
-                "FEEN must have 3 whitespace-separated fields (got #{parts.length})"
-        end
-        parts
+      # Split a FEEN string into its three constituent fields.
+      #
+      # Validates that exactly three space-separated fields are present.
+      #
+      # @param string [String] A FEEN notation string
+      # @return [Array<String>] Array of three field strings
+      # @raise [Error::Syntax] If field count is not exactly 3
+      #
+      # @example Valid FEEN string
+      #   split_fields("rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR / C/c")
+      #   # => ["rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR", "/", "C/c"]
+      #
+      # @example Invalid FEEN string (too few fields)
+      #   split_fields("rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR /")
+      #   # raises Error::Syntax
+      private_class_method def self.split_fields(string)
+        fields = string.split(FIELD_SEPARATOR, FIELD_COUNT)
+
+        raise Error::Syntax, "FEEN must have exactly #{FIELD_COUNT} space-separated fields, got #{fields.size}" unless fields.size == FIELD_COUNT
+
+        fields
       end
-      private_class_method :_split_3_fields
     end
   end
 end

data/lib/sashite/feen/placement.rb

@@ -2,30 +2,76 @@
 
 module Sashite
   module Feen
-    # Immutable board placement: rectangular grid of cells (nil = empty, otherwise EPIN value)
+    # Immutable representation of board piece placement.
+    #
+    # Stores the configuration of pieces on a multi-dimensional board,
+    # where each position can contain a piece or be empty (nil).
+    #
+    # @see https://sashite.dev/specs/feen/1.0.0/
     class Placement
-      attr_reader :grid, :height, :width
-
-      # @param grid [Array<Array>]
-      #   Each row is an Array; all rows must have identical length.
-      def initialize(grid)
-        raise TypeError, "grid must be an Array of rows, got #{grid.class}" unless grid.is_a?(Array)
-        raise Error::Bounds, "grid cannot be empty" if grid.empty?
-        unless grid.all?(Array)
-          raise Error::Bounds, "grid must be an Array of rows (Array), got #{grid.map(&:class).inspect}"
-        end
-
-        widths = grid.map(&:length)
-        width = widths.first || 0
-        raise Error::Bounds, "rows cannot be empty" if width.zero?
-        raise Error::Bounds, "inconsistent row width (#{widths.uniq.join(', ')})" if widths.any? { |w| w != width }
-
-        # Deep-freeze
-        @grid = grid.map { |row| row.dup.freeze }.freeze
-        @height = @grid.length
-        @width  = width
+      # @return [Array<Array>] Array of ranks, each rank being an array of pieces/nils
+      attr_reader :ranks
+
+      # @return [Integer] Board dimensionality (2 for 2D, 3 for 3D, etc.)
+      attr_reader :dimension
+
+      # @return [Array<Integer>, nil] Section sizes for multi-dimensional boards (nil for 2D)
+      attr_reader :sections
+
+      # Create a new immutable Placement object.
+      #
+      # @param ranks [Array<Array>] Array of ranks with pieces and nils
+      # @param dimension [Integer] Board dimensionality (default: 2)
+      # @param sections [Array<Integer>, nil] Sizes of sections for dimension > 2
+      #
+      # @example Create a 2D placement
+      #   ranks = [
+      #     [rook, knight, bishop, queen, king, bishop, knight, rook],
+      #     [pawn, pawn, pawn, pawn, pawn, pawn, pawn, pawn]
+      #   ]
+      #   placement = Placement.new(ranks)
+      #
+      # @example Create a 3D placement
+      #   ranks = [...] # 15 ranks total
+      #   placement = Placement.new(ranks, 3, [5, 5, 5]) # 3 sections of 5 ranks each
+      def initialize(ranks, dimension = 2, sections = nil)
+        @ranks = ranks.freeze
+        @dimension = dimension
+        @sections = sections&.freeze
+
         freeze
       end
+
+      # Convert placement to its FEEN string representation.
+      #
+      # @return [String] FEEN piece placement field
+      #
+      # @example
+      #   placement.to_s
+      #   # => "+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"
+      def to_s
+        Dumper::PiecePlacement.dump(self)
+      end
+
+      # Compare two placements for equality.
+      #
+      # @param other [Placement] Another placement object
+      # @return [Boolean] True if ranks, dimensions, and sections are equal
+      def ==(other)
+        other.is_a?(Placement) &&
+          ranks == other.ranks &&
+          dimension == other.dimension &&
+          sections == other.sections
+      end
+
+      alias eql? ==
+
+      # Generate hash code for placement.
+      #
+      # @return [Integer] Hash code based on ranks, dimension, and sections
+      def hash
+        [ranks, dimension, sections].hash
+      end
     end
   end
 end