feen 5.0.0.beta1 → 5.0.0.beta3

data/lib/feen/parser/pieces_in_hand.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module Feen
+  module Parser
+    # Handles parsing of the pieces in hand section of a FEEN string.
+    # Pieces in hand represent pieces available for dropping onto the board.
+    module PiecesInHand
+      # Character used to represent no pieces in hand
+      NO_PIECES = "-"
+
+      # Error messages for validation
+      ERRORS = {
+        invalid_type:   "Pieces in hand must be a string, got %s",
+        empty_string:   "Pieces in hand string cannot be empty",
+        invalid_format: "Invalid pieces in hand format: %s",
+        sorting_error:  "Pieces in hand must be in ASCII lexicographic order"
+      }.freeze
+
+      # Valid pattern for pieces in hand based on BNF:
+      # <pieces-in-hand> ::= "-" | <piece> <pieces-in-hand>
+      # <piece> ::= [a-zA-Z]
+      VALID_FORMAT_PATTERN = /\A(?:-|[a-zA-Z]+)\z/
+
+      # Parses the pieces in hand section of a FEEN string.
+      #
+      # @param pieces_in_hand_str [String] FEEN pieces in hand string
+      # @return [Array<String>] Array of single-character piece identifiers in the
+      #   format specified in the FEEN string (no prefixes or suffixes), sorted in ASCII
+      #   lexicographic order. Empty array if no pieces are in hand.
+      # @raise [ArgumentError] If the input string is invalid
+      #
+      # @example Parse no pieces in hand
+      #   PiecesInHand.parse("-")
+      #   # => []
+      #
+      # @example Parse multiple pieces in hand
+      #   PiecesInHand.parse("BNPPb")
+      #   # => ["B", "N", "P", "P", "b"]
+      def self.parse(pieces_in_hand_str)
+        validate_input_type(pieces_in_hand_str)
+        validate_format(pieces_in_hand_str)
+
+        return [] if pieces_in_hand_str == NO_PIECES
+
+        pieces = pieces_in_hand_str.chars
+        validate_pieces_order(pieces)
+
+        pieces
+      end
+
+      # Validates that the input is a non-empty string.
+      #
+      # @param str [String] Input string to validate
+      # @raise [ArgumentError] If input is not a string or is empty
+      # @return [void]
+      private_class_method def self.validate_input_type(str)
+        raise ::ArgumentError, format(ERRORS[:invalid_type], str.class) unless str.is_a?(::String)
+        raise ::ArgumentError, ERRORS[:empty_string] if str.empty?
+      end
+
+      # Validates that the input string matches the expected format.
+      #
+      # @param str [String] Input string to validate
+      # @raise [ArgumentError] If format is invalid
+      # @return [void]
+      private_class_method def self.validate_format(str)
+        return if str.match?(VALID_FORMAT_PATTERN)
+
+        raise ::ArgumentError, format(ERRORS[:invalid_format], str)
+      end
+
+      # Validates that pieces are sorted in ASCII lexicographic order.
+      #
+      # @param pieces [Array<String>] Array of piece identifiers
+      # @raise [ArgumentError] If pieces are not sorted
+      # @return [void]
+      private_class_method def self.validate_pieces_order(pieces)
+        return if pieces == pieces.sort
+
+        raise ::ArgumentError, ERRORS[:sorting_error]
+      end
+    end
+  end
+end

data/lib/feen/parser.rb

@@ -1,51 +1,89 @@
 # frozen_string_literal: true
 
-require_relative File.join("parser", "board_shape")
+require_relative File.join("parser", "games_turn")
+require_relative File.join("parser", "piece_placement")
+require_relative File.join("parser", "pieces_in_hand")
 
 module Feen
-  # The parser module.
+  # Module responsible for parsing FEEN notation strings into internal data structures.
+  # FEEN (Format for Encounter & Entertainment Notation) is a compact, canonical, and rule-agnostic
+  # textual format for representing static board positions in two-player piece-placement games.
   module Parser
-    # Parse a FEEN string into position params.
+    # Regular expression pattern for matching a valid FEEN string structure
+    # Captures exactly three non-space components separated by single spaces
+    FEEN_PATTERN = /\A([^\s]+)\s([^\s]+)\s([^\s]+)\z/
+
+    # Error message for invalid FEEN format
+    INVALID_FORMAT_ERROR = "Invalid FEEN format: expected exactly 3 fields separated by single spaces"
+
+    # Parses a complete FEEN string into a structured representation
     #
-    # @param feen [String] The FEEN string representing a position.
+    # @param feen_string [String] Complete FEEN notation string
+    # @return [Hash] Hash containing the parsed position data with the following keys:
+    #   - :piece_placement [Array] - Hierarchical array structure representing the board
+    #   - :pieces_in_hand [Array<String>] - Pieces available for dropping onto the board
+    #   - :games_turn [Array<String>] - A two-element array with [active_variant, inactive_variant]
+    # @raise [ArgumentError] If the FEEN string is invalid or any component cannot be parsed
     #
-    # @example Parse a classic Tsume Shogi problem
-    #   call("3sks3/9/4+P4/9/7+B1/9/9/9/9 s")
+    # @example Parsing a standard chess initial position
+    #   feen = "rnbqk=bnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQK=BNR - CHESS/chess"
+    #   result = Feen::Parser.parse(feen)
     #   # => {
-    #   #      "board_shape": [9, 9],
-    #   #      "side_to_move": "s",
-    #   #      "piece_placement": {
-    #   #         3 => "s",
-    #   #         4 => "k",
-    #   #         5 => "s",
-    #   #        22 => "+P",
-    #   #        43 => "+B"
-    #   #      }
+    #   #      piece_placement: [
+    #   #        ["r", "n", "b", "q", "k=", "b", "n", "r"],
+    #   #        ["p", "p", "p", "p", "p", "p", "p", "p"],
+    #   #        ["", "", "", "", "", "", "", ""],
+    #   #        ["", "", "", "", "", "", "", ""],
+    #   #        ["", "", "", "", "", "", "", ""],
+    #   #        ["", "", "", "", "", "", "", ""],
+    #   #        ["P", "P", "P", "P", "P", "P", "P", "P"],
+    #   #        ["R", "N", "B", "Q", "K=", "B", "N", "R"]
+    #   #      ],
+    #   #      pieces_in_hand: [],
+    #   #      games_turn: ["CHESS", "chess"]
+    #   #    }
     #
-    # @return [Hash] The position params representing the position.
-    def self.call(feen, regex: /\+?[a-z]/i)
-      piece_placement_str, side_to_move_str = feen.split
+    # @example Parsing a shogi position (from a Tempo Loss Bishop Exchange opening) with pieces in hand
+    #   feen = "lnsgk2nl/1r4gs1/p1pppp1pp/1p4p2/7P1/2P6/PP1PPPP1P/1SG4R1/LN2KGSNL Bb SHOGI/shogi"
+    #   result = Feen::Parser.parse(feen)
+    #   # => {
+    #   #      piece_placement: [
+    #   #        ["l", "n", "s", "g", "k", "", "", "n", "l"],
+    #   #        ["", "r", "", "", "", "", "g", "s", ""],
+    #   #        ["p", "", "p", "p", "p", "p", "", "p", "p"],
+    #   #        ["", "p", "", "", "", "", "p", "", ""],
+    #   #        ["", "", "", "", "", "", "", "P", ""],
+    #   #        ["", "", "P", "", "", "", "", "", ""],
+    #   #        ["P", "P", "", "P", "P", "P", "P", "", "P"],
+    #   #        ["", "S", "G", "", "", "", "", "R", ""],
+    #   #        ["L", "N", "", "", "K", "G", "S", "N", "L"]
+    #   #      ],
+    #   #      pieces_in_hand: ["B", "b"],
+    #   #      games_turn: ["SHOGI", "shogi"]
+    #   #    }
+    def self.parse(feen_string)
+      feen_string = String(feen_string)
+
+      # Match the FEEN string against the expected pattern
+      match = FEEN_PATTERN.match(feen_string)
+
+      # Raise an error if the format doesn't match the expected pattern
+      raise ::ArgumentError, INVALID_FORMAT_ERROR unless match
 
+      # Capture the three distinct parts
+      piece_placement_string, pieces_in_hand_string, games_turn_string = match.captures
+
+      # Parse each field using the appropriate submodule
+      piece_placement = PiecePlacement.parse(piece_placement_string)
+      pieces_in_hand = PiecesInHand.parse(pieces_in_hand_string)
+      games_turn = GamesTurn.parse(games_turn_string)
+
+      # Create a structured representation of the position
       {
-        board_shape:     BoardShape.new(piece_placement_str, regex:).to_a,
-        piece_placement: piece_placement(piece_placement_str, regex:),
-        side_to_move:    side_to_move_str
+        piece_placement:,
+        pieces_in_hand:,
+        games_turn:
       }
     end
-
-    def self.piece_placement(string, regex:)
-      hash = {}
-      index = 0
-      string.scan(/(\d+|#{regex})/) do |match|
-        if /\d+/.match?(match[0])
-          index += match[0].to_i
-        else
-          hash[index] = match[0]
-          index += 1
-        end
-      end
-      hash
-    end
-    private_class_method :piece_placement
   end
 end

data/lib/feen.rb

@@ -6,56 +6,71 @@ require_relative File.join("feen", "parser")
 # This module provides a Ruby interface for data serialization and
 # deserialization in FEEN format.
 #
-# @see https://github.com/sashite/specs/blob/main/forsyth-edwards-expanded-notation.md
+# @see https://sashite.dev/documents/feen/1.0.0/
 module Feen
-  # Dumps position params into a FEEN string.
+  # Dumps position components into a FEEN string.
   #
-  # @param board_shape [Array] The shape of the board.
-  # @param side_to_move [String] The identifier of the player who must play.
-  # @param piece_placement [Hash] The index of each piece on the board.
-  #
-  # @example Dump a classic Tsume Shogi problem
-  #   dump(
-  #     "board_shape": [9, 9],
-  #     "side_to_move": "s",
-  #     "piece_placement": {
-  #        3 => "s",
-  #        4 => "k",
-  #        5 => "s",
-  #       22 => "+P",
-  #       43 => "+B"
-  #     }
+  # @see Feen::Dumper.dump for the detailed parameters documentation
+  # @return [String] FEEN notation string
+  # @raise [ArgumentError] If any parameter is invalid
+  # @example
+  #   piece_placement = [
+  #     ["r", "n", "b", "q", "k=", "b", "n", "r"],
+  #     ["p", "p", "p", "p", "p", "p", "p", "p"],
+  #     ["", "", "", "", "", "", "", ""],
+  #     ["", "", "", "", "", "", "", ""],
+  #     ["", "", "", "", "", "", "", ""],
+  #     ["", "", "", "", "", "", "", ""],
+  #     ["P", "P", "P", "P", "P", "P", "P", "P"],
+  #     ["R", "N", "B", "Q", "K=", "B", "N", "R"]
+  #   ]
+  #   Feen.dump(
+  #     piece_placement: piece_placement,
+  #     pieces_in_hand: [],
+  #     games_turn: ["CHESS", "chess"]
   #   )
-  #   # => "3sks3/9/4+P4/9/7+B1/9/9/9/9 s"
-  #
-  # @return [String] The FEEN string representing the position.
-  def self.dump(board_shape:, side_to_move:, piece_placement:)
-    Dumper.call(
-      board_shape:,
-      side_to_move:,
-      piece_placement:
-    )
+  #   # => "rnbqk=bnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQK=BNR - CHESS/chess"
+  def self.dump(...)
+    Dumper.dump(...)
   end
 
-  # Parses a FEEN string into position params.
-  #
-  # @param feen [String] The FEEN string representing a position.
+  # Parses a FEEN string into position components.
   #
-  # @example Parse a classic Tsume Shogi problem
-  #   parse("3sks3/9/4+P4/9/7+B1/9/9/9/9 s")
+  # @see Feen::Parser.parse for the detailed parameters and return value documentation
+  # @return [Hash] Hash containing the parsed position data
+  # @raise [ArgumentError] If the FEEN string is invalid
+  # @example
+  #   feen_string = "rnbqk=bnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQK=BNR - CHESS/chess"
+  #   Feen.parse(feen_string)
   #   # => {
-  #   #      "board_shape": [9, 9],
-  #   #      "side_to_move": "s",
-  #   #      "piece_placement": {
-  #   #         3 => "s",
-  #   #         4 => "k",
-  #   #         5 => "s",
-  #   #        22 => "+P",
-  #   #        43 => "+B"
-  #   #      }
+  #   #      piece_placement: [
+  #   #        ["r", "n", "b", "q", "k=", "b", "n", "r"],
+  #   #        ["p", "p", "p", "p", "p", "p", "p", "p"],
+  #   #        ["", "", "", "", "", "", "", ""],
+  #   #        ["", "", "", "", "", "", "", ""],
+  #   #        ["", "", "", "", "", "", "", ""],
+  #   #        ["", "", "", "", "", "", "", ""],
+  #   #        ["P", "P", "P", "P", "P", "P", "P", "P"],
+  #   #        ["R", "N", "B", "Q", "K=", "B", "N", "R"]
+  #   #      ],
+  #   #      pieces_in_hand: [],
+  #   #      games_turn: ["CHESS", "chess"]
+  #   #    }
+  def self.parse(...)
+    Parser.parse(...)
+  end
+
+  # Validates if the given string is a valid FEEN string
   #
-  # @return [Hash] The position params representing the position.
-  def self.parse(feen, regex: /\+?[a-z]/i)
-    Parser.call(feen, regex:)
+  # @see Feen.parse for parameter details
+  # @return [Boolean] True if the string is a valid FEEN string, false otherwise
+  # @example
+  #   Feen.valid?("rnbqk=bnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQK=BNR - CHESS/chess") # => true
+  #   Feen.valid?("invalid feen string") # => false
+  def self.valid?(...)
+    parse(...)
+    true
+  rescue ::ArgumentError
+    false
   end
 end

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: feen
 version: !ruby/object:Gem::Version
-  version: 5.0.0.beta1
+  version: 5.0.0.beta3
 platform: ruby
 authors:
 - Cyril Kato
-autorequire: 
 bindir: bin
 cert_chain: []
-date: 2023-04-27 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies: []
 description: A Ruby interface for data serialization and deserialization in FEEN format.
 email: contact@cyril.email
@@ -20,15 +19,25 @@ files:
 - README.md
 - lib/feen.rb
 - lib/feen/dumper.rb
+- lib/feen/dumper/games_turn.rb
 - lib/feen/dumper/piece_placement.rb
+- lib/feen/dumper/pieces_in_hand.rb
+- lib/feen/dumper/pieces_in_hand/errors.rb
+- lib/feen/dumper/pieces_in_hand/no_pieces.rb
 - lib/feen/parser.rb
-- lib/feen/parser/board_shape.rb
+- lib/feen/parser/games_turn.rb
+- lib/feen/parser/games_turn/errors.rb
+- lib/feen/parser/games_turn/valid_games_turn_pattern.rb
+- lib/feen/parser/piece_placement.rb
+- lib/feen/parser/pieces_in_hand.rb
+- lib/feen/parser/pieces_in_hand/errors.rb
+- lib/feen/parser/pieces_in_hand/no_pieces.rb
+- lib/feen/parser/pieces_in_hand/valid_format_pattern.rb
 homepage: https://github.com/sashite/feen.rb
 licenses:
 - MIT
 metadata:
   rubygems_mfa_required: 'true'
-post_install_message: 
 rdoc_options: []
 require_paths:
 - lib
@@ -39,12 +48,11 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: 3.2.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">"
+  - - ">="
     - !ruby/object:Gem::Version
-      version: 1.3.1
+      version: '0'
 requirements: []
-rubygems_version: 3.4.6
-signing_key: 
+rubygems_version: 3.6.7
 specification_version: 4
 summary: FEEN support for the Ruby language.
 test_files: []

data/lib/feen/parser/board_shape.rb

@@ -1,39 +0,0 @@
-# frozen_string_literal: true
-
-module Feen
-  module Parser
-    # The BoardShape class.
-    #
-    # @example Parse the shape of a shogiban
-    #   BoardShape.new("3sks3/9/4+P4/9/7+B1/9/9/9/9").to_a # => [9, 9]
-    class BoardShape
-      # @param board_str [String] The flatten board.
-      def initialize(board_str, regex: /\+?[a-z]/i)
-        @board_str = board_str
-        @regex = regex
-      end
-
-      # @return [Array] The size of each dimension of the board.
-      def to_a
-        indexes(@board_str, @board_str.scan(%r{/+}).sort.fetch(-1))
-      end
-
-      private
-
-      def indexes(string, separator)
-        if separator.empty?
-          last_index = string.scan(/(\d+|#{@regex})/).inject(0) do |counter, match|
-            sub_string = match[0]
-            number = sub_string.match?(/\d+/) ? Integer(sub_string) : 1
-            counter + number
-          end
-
-          return [last_index]
-        end
-
-        sub_strings = string.split(separator)
-        [sub_strings.length] + indexes(sub_strings.fetch(0), separator[1..])
-      end
-    end
-  end
-end