sashite-feen 0.3.0 → 0.5.0

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: sashite-feen
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Cyril Kato
@@ -10,68 +10,52 @@ cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
-  name: sashite-epin
+  name: qi
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.1'
+        version: 13.0.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.1'
-- !ruby/object:Gem::Dependency
-  name: sashite-sin
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '2.1'
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '2.1'
+        version: 13.0.0
 description: |
-  FEEN (Forsyth—Edwards Enhanced Notation) provides a universal, rule-agnostic format for
-  representing board game positions. This gem implements the FEEN Specification v1.0.0 with
-  a modern Ruby interface featuring immutable position objects and functional programming
-  principles. FEEN extends traditional FEN notation to support multiple game systems (chess,
-  shōgi, xiangqi, makruk), cross-style games, multi-dimensional boards, and captured pieces
-  held in reserve. Built on EPIN (piece notation) and SIN (style notation) foundations,
-  FEEN enables canonical position representation across diverse abstract strategy board games.
-  Perfect for game engines, position analysis tools, and hybrid gaming systems requiring
-  comprehensive board state representation.
+  FEEN (Field Expression Encoding Notation) implementation for Ruby.
+  Encodes board game positions with piece placement, hands, and style-turn fields
+  for abstract strategy board games with a canonical, rule-agnostic format.
 email: contact@cyril.email
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- LICENSE.md
 - README.md
 - lib/sashite-feen.rb
 - lib/sashite/feen.rb
 - lib/sashite/feen/dumper.rb
+- lib/sashite/feen/dumper/hands.rb
 - lib/sashite/feen/dumper/piece_placement.rb
-- lib/sashite/feen/dumper/pieces_in_hand.rb
 - lib/sashite/feen/dumper/style_turn.rb
 - lib/sashite/feen/error.rb
-- lib/sashite/feen/hands.rb
+- lib/sashite/feen/errors/cardinality_error.rb
+- lib/sashite/feen/errors/hands_error.rb
+- lib/sashite/feen/errors/parse_error.rb
+- lib/sashite/feen/errors/piece_placement_error.rb
+- lib/sashite/feen/errors/style_turn_error.rb
 - lib/sashite/feen/parser.rb
+- lib/sashite/feen/parser/hand.rb
+- lib/sashite/feen/parser/hands.rb
 - lib/sashite/feen/parser/piece_placement.rb
-- lib/sashite/feen/parser/pieces_in_hand.rb
 - lib/sashite/feen/parser/style_turn.rb
-- lib/sashite/feen/placement.rb
-- lib/sashite/feen/position.rb
-- lib/sashite/feen/styles.rb
+- lib/sashite/feen/shared/ascii.rb
+- lib/sashite/feen/shared/limits.rb
+- lib/sashite/feen/shared/separators.rb
 homepage: https://github.com/sashite/feen.rb
 licenses:
-- MIT
+- Apache-2.0
 metadata:
   bug_tracker_uri: https://github.com/sashite/feen.rb/issues
   documentation_uri: https://rubydoc.info/github/sashite/feen.rb/main
@@ -93,8 +77,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.7.1
+rubygems_version: 4.0.5
 specification_version: 4
-summary: FEEN (Forsyth—Edwards Enhanced Notation) implementation for Ruby with universal
-  position representation
+summary: FEEN (Field Expression Encoding Notation) implementation for Ruby providing
+  rule-agnostic board position encoding.
 test_files: []

data/LICENSE.md

@@ -1,21 +0,0 @@
-# The MIT License
-
-Copyright (c) 2025 Sashité
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in
-all copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
-THE SOFTWARE.

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

@@ -1,149 +0,0 @@
-# frozen_string_literal: true
-
-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
-        # Player separator in pieces-in-hand field.
-        PLAYER_SEPARATOR = "/"
-
-        # 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)
-        #   # => "/"
-        #
-        # @example First player has pieces
-        #   dump(hands)
-        #   # => "2P/p"
-        #
-        # @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)
-
-          "#{first_player_str}#{PLAYER_SEPARATOR}#{second_player_str}"
-        end
-
-        # 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?
-
-          grouped = group_pieces(pieces)
-          sorted = sort_grouped_pieces(grouped)
-          format_pieces(sorted)
-        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
-
-        # 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
-
-        # 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
-
-        # 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?("+")
-
-          2
-        end
-
-        # 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
-      end
-    end
-  end
-end

data/lib/sashite/feen/hands.rb

@@ -1,80 +0,0 @@
-# frozen_string_literal: true
-
-module Sashite
-  module Feen
-    # Immutable representation of pieces held in hand by each player.
-    #
-    # Stores captured pieces that players hold in reserve, available for
-    # placement back onto the board in games that support drop mechanics
-    # (such as shogi, crazyhouse, etc.).
-    #
-    # @see https://sashite.dev/specs/feen/1.0.0/
-    class Hands
-      # @return [Array] Array of pieces held by first player
-      attr_reader :first_player
-
-      # @return [Array] Array of pieces held by second player
-      attr_reader :second_player
-
-      # Create a new immutable Hands object.
-      #
-      # @param first_player [Array] Pieces in first player's hand
-      # @param second_player [Array] Pieces in second player's hand
-      #
-      # @example Empty hands
-      #   hands = Hands.new([], [])
-      #
-      # @example First player has captured pieces
-      #   hands = Hands.new([pawn1, pawn2], [])
-      #
-      # @example Both players have captured pieces
-      #   hands = Hands.new([rook, bishop], [pawn1, pawn2, knight])
-      def initialize(first_player, second_player)
-        @first_player = first_player.sort_by(&:to_s).freeze
-        @second_player = second_player.sort_by(&:to_s).freeze
-
-        freeze
-      end
-
-      # Check if both hands are empty.
-      #
-      # @return [Boolean] True if neither player has pieces in hand
-      #
-      # @example
-      #   hands.empty?  # => true
-      def empty?
-        first_player.empty? && second_player.empty?
-      end
-
-      # Convert hands to their FEEN string representation.
-      #
-      # @return [String] FEEN pieces-in-hand field
-      #
-      # @example
-      #   hands.to_s
-      #   # => "2P/p"
-      def to_s
-        Dumper::PiecesInHand.dump(self)
-      end
-
-      # Compare two hands for equality.
-      #
-      # @param other [Hands] Another hands object
-      # @return [Boolean] True if both players' pieces are equal
-      def ==(other)
-        other.is_a?(Hands) &&
-          first_player == other.first_player &&
-          second_player == other.second_player
-      end
-
-      alias eql? ==
-
-      # Generate hash code for hands.
-      #
-      # @return [Integer] Hash code based on both players' pieces
-      def hash
-        [first_player, second_player].hash
-      end
-    end
-  end
-end

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

@@ -1,243 +0,0 @@
-# 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
-        # 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
-
-          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
-        #
-        # @example Single piece
-        #   extract_piece_with_count(['K', 'Q'], 0)  # => [1, "K", 1]
-        #
-        # @example Multiple pieces
-        #   extract_piece_with_count(['3', 'P', 'R'], 0)  # => [3, "P", 2]
-        #
-        # @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
-
-          # Extract optional count (may be multi-digit)
-          count_chars = []
-          while i < chars.size && digit?(chars[i])
-            count_chars << chars[i]
-            i += 1
-          end
-
-          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
-
-          # Extract EPIN piece
-          raise Error::Syntax, "expected piece after count at position #{start_index}" if i >= chars.size
-
-          epin_str, epin_consumed = extract_epin(chars, i)
-          i += epin_consumed
-
-          consumed = i - start_index
-          [count, epin_str, consumed]
-        end
-
-        # 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 = []
-
-          # Optional state prefix
-          if i < chars.size && ["+", "-"].include?(chars[i])
-            piece_chars << chars[i]
-            i += 1
-          end
-
-          # Base letter (required)
-          if i >= chars.size || !letter?(chars[i])
-            raise Error::Syntax, "expected letter in EPIN notation at position #{start_index}"
-          end
-
-          piece_chars << chars[i]
-          i += 1
-
-          # Optional derivation suffix
-          if i < chars.size && chars[i] == "'"
-            piece_chars << chars[i]
-            i += 1
-          end
-
-          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
-
-        # 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)
-          raise Error::Count, "piece count must be at least 1, got #{count_str}" if count < 1
-
-          return unless count > 999
-
-          raise Error::Count, "piece count too large: #{count_str}"
-        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)
-          raise Error::Piece, "invalid EPIN notation: #{epin_str}" unless EPIN_PATTERN.match?(epin_str)
-
-          Sashite::Epin.parse(epin_str)
-        rescue StandardError => e
-          raise Error::Piece, "failed to parse EPIN '#{epin_str}': #{e.message}"
-        end
-      end
-    end
-  end
-end