sashite-feen 0.3.0 → 0.5.0

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

@@ -1,103 +1,107 @@
 # frozen_string_literal: true
 
-require_relative "../error"
-require_relative "../styles"
-
-require "sashite/sin"
+require_relative "../shared/ascii"
+require_relative "../errors/style_turn_error"
 
 module Sashite
   module Feen
     module Parser
-      # Parser for the style-turn field (third field of FEEN).
+      # Parser for the FEEN Style-Turn field (Field 3).
       #
-      # Converts a FEEN style-turn string into a Styles object,
-      # decoding game style identifiers and the active player indicator.
+      # Format: <ACTIVE-STYLE>/<INACTIVE-STYLE>
+      # Each style is a valid SIN token (exactly one ASCII letter).
+      # The two tokens must be of opposite case.
       #
-      # @see https://sashite.dev/specs/feen/1.0.0/
-      # @see https://sashite.dev/specs/sin/1.0.0/
+      # @api private
       module StyleTurn
-        # Style separator in style-turn field.
-        STYLE_SEPARATOR = "/"
-
-        # 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
-        #
-        # @example Chess game, white to move
-        #   parse("C/c")  # => Styles.new(sin_C, sin_c)
+        # Parses a Style-Turn field, returning nil on failure.
         #
-        # @example Chess game, black to move
-        #   parse("c/C")  # => Styles.new(sin_c, sin_C)
-        #
-        # @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)
+        # @param input [String] The Style-Turn field string
+        # @return [Hash, nil]
+        def self.safe_parse(input)
+          # Exactly 3 bytes: letter "/" letter
+          return nil unless input.bytesize == 3
 
-          active = parse_style(active_str)
-          inactive = parse_style(inactive_str)
+          return nil unless input.getbyte(1) == Ascii::SLASH
 
-          Styles.new(active, inactive)
-        end
+          active_byte = input.getbyte(0)
+          inactive_byte = input.getbyte(2)
 
-        # 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)
+          # Both must be ASCII letters (inline SIN validation)
+          active_lowered = active_byte | 0x20
+          return nil if active_lowered < Ascii::LOWER_A || active_lowered > Ascii::LOWER_Z
 
-          raise Error::Syntax, "style-turn must contain '#{STYLE_SEPARATOR}' separator" unless parts.size == 2
+          inactive_lowered = inactive_byte | 0x20
+          return nil if inactive_lowered < Ascii::LOWER_A || inactive_lowered > Ascii::LOWER_Z
 
-          raise Error::Syntax, "active style cannot be empty" if parts[0].empty?
-          raise Error::Syntax, "inactive style cannot be empty" if parts[1].empty?
+          # Must be opposite case
+          active_upper = active_byte < Ascii::LOWER_A
+          inactive_upper = inactive_byte < Ascii::LOWER_A
+          return nil if active_upper == inactive_upper
 
-          parts
-        end
+          active_str = input.byteslice(0, 1)
+          inactive_str = input.byteslice(2, 1)
 
-        # 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)"
+          if active_upper
+            { styles: { first: active_str, second: inactive_str }, turn: :first }
+          else
+            { styles: { first: inactive_str, second: active_str }, turn: :second }
           end
-
-          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.
+        # Parses a Style-Turn field, raising on failure.
         #
-        # @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])
+        # @param input [String] The Style-Turn field string
+        # @return [Hash]
+        # @raise [StyleTurnError] If the input is not valid
+        def self.parse(input)
+          result = safe_parse(input)
+          return result unless result.nil?
+
+          raise_specific_error!(input)
         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")
+        class << self
+          private
+
+          def raise_specific_error!(input)
+            # Find single slash delimiter
+            slash_pos = nil
+            i = 0
+            len = input.bytesize
+
+            while i < len
+              if input.getbyte(i) == Ascii::SLASH
+                raise StyleTurnError, StyleTurnError::INVALID_DELIMITER if slash_pos
+
+                slash_pos = i
+              end
+              i += 1
+            end
+
+            raise StyleTurnError, StyleTurnError::INVALID_DELIMITER unless slash_pos
+
+            # Validate each SIN token (single ASCII letter)
+            unless slash_pos == 1 && valid_sin_byte?(input.getbyte(0))
+              raise StyleTurnError, StyleTurnError::INVALID_STYLE_TOKEN
+            end
+
+            unless (len - slash_pos - 1) == 1 && valid_sin_byte?(input.getbyte(slash_pos + 1))
+              raise StyleTurnError, StyleTurnError::INVALID_STYLE_TOKEN
+            end
+
+            raise StyleTurnError, StyleTurnError::SAME_CASE
+          end
+
+          def valid_sin_byte?(byte)
+            byte && (byte | 0x20) >= Ascii::LOWER_A && (byte | 0x20) <= Ascii::LOWER_Z
+          end
         end
+
+        private_class_method :raise_specific_error!,
+                             :valid_sin_byte?
+
+        freeze
       end
     end
   end

data/lib/sashite/feen/parser.rb

@@ -1,80 +1,211 @@
 # frozen_string_literal: true
 
+require "qi"
+
+require_relative "shared/limits"
+require_relative "errors/parse_error"
+require_relative "errors/cardinality_error"
 require_relative "parser/piece_placement"
-require_relative "parser/pieces_in_hand"
+require_relative "parser/hands"
 require_relative "parser/style_turn"
 
-require_relative "error"
-require_relative "position"
-
 module Sashite
   module Feen
-    # Parser for FEEN (Forsyth–Edwards Enhanced Notation) strings.
+    # Parser for FEEN strings into Qi positions.
     #
-    # Parses a complete FEEN string by splitting it into three space-separated
-    # fields and delegating parsing to specialized parsers for each component.
+    # Uses a dual-path architecture:
+    # - {.valid?} uses exception-free sub-parsers, never constructs a Qi
+    # - {.parse} uses the same path, raises once at the boundary
     #
-    # @see https://sashite.dev/specs/feen/1.0.0/
+    # @api private
     module Parser
-      # Field separator in FEEN notation.
-      FIELD_SEPARATOR = " "
-
-      # Number of required fields in a valid FEEN string.
       FIELD_COUNT = 3
 
-      # 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.
+      # Parses a FEEN string into a Qi position.
       #
-      # @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)
+      # @param input [String] The FEEN string to parse
+      # @return [Qi] An immutable position object
+      # @raise [ParseError] If the input is not a valid FEEN string
+      def self.parse(input)
+        raise ParseError, ParseError::INPUT_TOO_LONG if input.bytesize > Limits::MAX_STRING_LENGTH
+
+        fields = input.split(" ", -1)
+        raise ParseError, ParseError::INVALID_FIELD_COUNT unless fields.size == FIELD_COUNT
+
+        f1, f2, f3 = fields
 
-        placement = Parser::PiecePlacement.parse(fields[0])
-        hands     = Parser::PiecesInHand.parse(fields[1])
-        styles    = Parser::StyleTurn.parse(fields[2])
+        # Try safe_parse first, delegate to raising path on failure
+        pp_result = PiecePlacement.safe_parse(f1)
+        hands_result = Hands.safe_parse(f2)
+        st_result = StyleTurn.safe_parse(f3)
 
-        Position.new(placement, hands, styles)
+        PiecePlacement.parse(f1) if pp_result.nil?
+        Hands.parse(f2) if hands_result.nil?
+        StyleTurn.parse(f3) if st_result.nil?
+
+        flat_board, shape = flatten_with_shape(pp_result)
+
+        first_player_hand = to_count_map(hands_result[:first])
+        second_player_hand = to_count_map(hands_result[:second])
+
+        validate_cardinality!(flat_board, first_player_hand, second_player_hand)
+
+        build_position(flat_board, shape, first_player_hand, second_player_hand,
+                       st_result[:styles][:first], st_result[:styles][:second],
+                       st_result[:turn])
       end
 
-      # Split a FEEN string into its three constituent fields.
-      #
-      # Validates that exactly three space-separated fields are present.
-      # Supports empty piece placement field (board-less positions).
-      #
-      # @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
+      # Validates a FEEN string without raising.
       #
-      # @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 Empty piece placement field
-      #   split_fields(" / C/c")
-      #   # => ["", "/", "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)
-        # Use regex separator to preserve empty leading fields
-        # String#split with " " treats leading spaces specially and discards them
-        fields = string.split(/ /, FIELD_COUNT)
-
-        unless fields.size == FIELD_COUNT
-          raise Error::Syntax, "FEEN must have exactly #{FIELD_COUNT} space-separated fields, got #{fields.size}"
+      # @param input [String] The FEEN string to validate
+      # @return [Boolean]
+      def self.valid?(input)
+        return false unless ::String === input
+        return false if input.bytesize > Limits::MAX_STRING_LENGTH
+
+        fields = input.split(" ", -1)
+        return false unless fields.size == FIELD_COUNT
+
+        f1, f2, f3 = fields
+
+        pp_result = PiecePlacement.safe_parse(f1)
+        return false if pp_result.nil?
+
+        hands_result = Hands.safe_parse(f2)
+        return false if hands_result.nil?
+
+        st_result = StyleTurn.safe_parse(f3)
+        return false if st_result.nil?
+
+        total_squares, board_pieces = count_squares_and_pieces(pp_result)
+        hand_pieces = count_hand(hands_result[:first]) + count_hand(hands_result[:second])
+
+        (board_pieces + hand_pieces) <= total_squares
+      end
+
+      class << self
+        private
+
+        # Extracts flat board and shape from a dimensioned board structure.
+        def flatten_with_shape(board)
+          first = board[0]
+          unless first.is_a?(::Array)
+            return [board, [board.size]]
+          end
+
+          first_inner = first[0]
+          unless first_inner.is_a?(::Array)
+            # 2D
+            return [board.flatten, [board.size, first.size]]
+          end
+
+          # 3D
+          [board.flatten, [board.size, first.size, first_inner.size]]
+        end
+
+        # Counts total squares and occupied squares without flattening.
+        # Used by valid? to avoid allocating a flat array.
+        def count_squares_and_pieces(board)
+          first = board[0]
+          unless first.is_a?(::Array)
+            pieces = 0
+            board.each { |sq| pieces += 1 if sq }
+            return [board.size, pieces]
+          end
+
+          total = 0
+          pieces = 0
+
+          first_inner = first[0]
+          if first_inner.is_a?(::Array)
+            # 3D
+            board.each do |layer|
+              layer.each do |rank|
+                rank.each { |sq| pieces += 1 if sq }
+                total += rank.size
+              end
+            end
+          else
+            # 2D
+            board.each do |rank|
+              rank.each { |sq| pieces += 1 if sq }
+              total += rank.size
+            end
+          end
+
+          [total, pieces]
+        end
+
+        # Counts pieces in an expanded hand array.
+        def count_hand(expanded)
+          expanded.size
+        end
+
+        # Validates cardinality, raising on failure.
+        def validate_cardinality!(flat_board, first_hand, second_hand)
+          total_squares = flat_board.size
+          board_pieces = 0
+          flat_board.each { |sq| board_pieces += 1 if sq }
+
+          hand_pieces = sum_hand(first_hand) + sum_hand(second_hand)
+
+          return if (board_pieces + hand_pieces) <= total_squares
+
+          raise CardinalityError, CardinalityError::TOO_MANY_PIECES
         end
 
-        fields
+        # Sums piece count in a hand map.
+        def sum_hand(hand)
+          total = 0
+          hand.each_value { |c| total += c }
+          total
+        end
+
+        # Converts expanded piece array into count map.
+        def to_count_map(expanded)
+          map = {}
+          expanded.each do |piece|
+            map[piece] = (map[piece] || 0) + 1
+          end
+          map
+        end
+
+        # Constructs a Qi position from parsed components.
+        def build_position(flat_board, shape, first_player_hand, second_player_hand,
+                           first_player_style, second_player_style, turn)
+          position = ::Qi.new(shape,
+                              first_player_style: first_player_style,
+                              second_player_style: second_player_style)
+
+          board_diffs = {}
+          flat_board.each_with_index do |sq, i|
+            board_diffs[i] = sq if sq
+          end
+
+          position = position.board_diff(**board_diffs) unless board_diffs.empty?
+
+          unless first_player_hand.empty?
+            position = position.first_player_hand_diff(**first_player_hand.transform_keys(&:to_sym))
+          end
+
+          unless second_player_hand.empty?
+            position = position.second_player_hand_diff(**second_player_hand.transform_keys(&:to_sym))
+          end
+
+          position = position.toggle if turn == :second
+          position
+        end
       end
+
+      private_class_method :flatten_with_shape,
+                           :count_squares_and_pieces,
+                           :count_hand,
+                           :validate_cardinality!,
+                           :sum_hand,
+                           :to_count_map,
+                           :build_position
+
+      freeze
     end
   end
 end

data/lib/sashite/feen/shared/ascii.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Sashite
+  module Feen
+    # ASCII byte constants and predicates for efficient parsing.
+    #
+    # All predicates accept the return value of String#getbyte (Integer or nil)
+    # and return a truthy/falsey value. They are nil-safe via short-circuit
+    # evaluation: +byte && ...+ returns nil (falsey) when byte is nil.
+    #
+    # @api private
+    module Ascii
+      ZERO       = 0x30
+      NINE       = 0x39
+      UPPER_A    = 0x41
+      UPPER_Z    = 0x5A
+      LOWER_A    = 0x61
+      LOWER_Z    = 0x7A
+      PLUS       = 0x2B
+      MINUS      = 0x2D
+      SLASH      = 0x2F
+      CARET      = 0x5E
+      APOSTROPHE = 0x27
+
+      # Tests whether a byte is an ASCII digit (0-9).
+      def self.digit?(byte)
+        byte && byte >= ZERO && byte <= NINE
+      end
+
+      # Tests whether a byte is an ASCII letter (A-Z or a-z).
+      #
+      # Uses a bit trick: OR with 0x20 maps A-Z to a-z while leaving a-z
+      # unchanged. Characters between Z (0x5A) and a (0x61) map to 0x7B+,
+      # which falls outside the a-z range, so no false positives occur.
+      def self.letter?(byte)
+        byte && (byte | 0x20) >= LOWER_A && (byte | 0x20) <= LOWER_Z
+      end
+
+      # Tests whether a byte is an uppercase ASCII letter (A-Z).
+      def self.uppercase?(byte)
+        byte && byte >= UPPER_A && byte <= UPPER_Z
+      end
+
+      # Tests whether a byte is a lowercase ASCII letter (a-z).
+      def self.lowercase?(byte)
+        byte && byte >= LOWER_A && byte <= LOWER_Z
+      end
+
+      freeze
+    end
+  end
+end

data/lib/sashite/feen/shared/limits.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Sashite
+  module Feen
+    # Implementation limits for bounded parsing.
+    #
+    # These constraints enable safe parsing with predictable memory usage
+    # while remaining sufficient for all realistic board game positions.
+    #
+    # @api private
+    module Limits
+      # Maximum allowed length for a FEEN string in bytes.
+      MAX_STRING_LENGTH = 4_096
+
+      # Maximum number of board dimensions (1D, 2D, 3D).
+      MAX_DIMENSIONS = 3
+
+      # Maximum size of any single dimension (fits in 8-bit unsigned).
+      MAX_DIMENSION_SIZE = 255
+
+      freeze
+    end
+  end
+end

data/lib/sashite/feen/shared/separators.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Sashite
+  module Feen
+    # Field and segment separator constants for FEEN parsing and dumping.
+    #
+    # @api private
+    module Separators
+      # Separates the three FEEN fields (ASCII space).
+      FIELD = " "
+
+      # Separates segments within fields (ASCII forward slash).
+      SEGMENT = "/"
+
+      freeze
+    end
+  end
+end

data/lib/sashite/feen.rb

@@ -1,67 +1,40 @@
 # frozen_string_literal: true
 
-require_relative "feen/dumper"
 require_relative "feen/parser"
+require_relative "feen/dumper"
 
 module Sashite
-  # FEEN (Forsyth–Edwards Enhanced Notation) module provides parsing and dumping
-  # functionality for board game positions.
+  # FEEN (Field Expression Encoding Notation) implementation for Ruby.
   #
-  # FEEN is a universal, rule-agnostic notation for representing board game positions.
-  # It extends traditional FEN to support multiple game systems, cross-style games,
-  # multi-dimensional boards, and captured pieces.
-  #
-  # A FEEN string consists of three space-separated fields:
-  # 1. Piece placement: Board configuration using EPIN notation
-  # 2. Pieces in hand: Captured pieces held by each player
-  # 3. Style-turn: Game styles and active player
+  # Provides serialization and deserialization of board game positions
+  # between FEEN strings and Qi objects.
   #
   # @see https://sashite.dev/specs/feen/1.0.0/
+  # @api public
   module Feen
-    # 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, ensuring
-    # position equality can be tested via string comparison.
+    # Parses a FEEN string into a Qi position.
     #
-    # @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 = Sashite::Feen.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"
-    #
-    # @example Round-trip parsing and dumping
-    #   original = "+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"
-    #   position = Sashite::Feen.parse(original)
-    #   Sashite::Feen.dump(position) == original  # => true
-    def self.dump(position)
-      Dumper.dump(position)
+    # @param feen_string [String] The FEEN string to parse
+    # @return [Qi] An immutable position object
+    # @raise [ParseError] If the string is not a valid FEEN
+    def self.parse(feen_string)
+      Parser.parse(feen_string)
     end
 
-    # Parse a FEEN string into an immutable Position object.
-    #
-    # This method parses the three FEEN fields and constructs an immutable position
-    # object with placement, hands, and styles components.
+    # Reports whether a string is a valid FEEN position.
     #
-    # @param string [String] A FEEN notation string with three space-separated fields
-    # @return [Position] Immutable position object
-    # @raise [Error::Syntax] If the FEEN structure is malformed
-    # @raise [Error::Piece] If EPIN notation is invalid
-    # @raise [Error::Style] If SIN notation is invalid
-    # @raise [Error::Count] If piece counts are invalid
-    # @raise [Error::Validation] For other semantic violations
-    #
-    # @example Parse a chess starting position
-    #   position = Sashite::Feen.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")
-    #   position.placement  # => Placement object (board configuration)
-    #   position.hands      # => Hands object (pieces in hand)
-    #   position.styles     # => Styles object (style-turn information)
+    # @param feen_string [String] The string to validate
+    # @return [Boolean] true if valid, false otherwise
+    def self.valid?(feen_string)
+      Parser.valid?(feen_string)
+    end
+
+    # Serializes a Qi position to a canonical FEEN string.
     #
-    # @example Parse a shogi position with captured pieces
-    #   position = Sashite::Feen.parse("lnsgkgsnl/1r5b1/ppppppppp/9/9/9/PPPPPPPPP/1B5R1/LNSGKGSNL P/p S/s")
-    def self.parse(string)
-      Parser.parse(string)
+    # @param position [Qi] The position to serialize
+    # @return [String] Canonical FEEN string
+    def self.dump(position)
+      Dumper.dump(position)
     end
   end
 end

data/lib/sashite-feen.rb

@@ -1,14 +1,3 @@
 # frozen_string_literal: true
 
 require_relative "sashite/feen"
-
-# Sashité namespace for board game notation libraries
-#
-# Sashité provides a collection of libraries for representing and manipulating
-# board game concepts according to the Sashité Protocol specifications.
-#
-# @see https://sashite.dev/protocol/ Sashité Protocol
-# @see https://sashite.dev/specs/ Sashité Specifications
-# @author Sashité
-module Sashite
-end