feen 5.0.0.beta9 → 5.0.0.beta10

data/lib/feen/parser/style_turn.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+require "sashite-snn"
+
+module Feen
+  module Parser
+    # Handles parsing of the style turn section of a FEEN string
+    module StyleTurn
+      # Error messages for style turn parsing
+      ERRORS = {
+        invalid_type:   "Style turn must be a string, got %s",
+        empty_string:   "Style turn string cannot be empty",
+        invalid_format: "Invalid style turn format. Expected format: UPPERCASE/lowercase or lowercase/UPPERCASE",
+        invalid_snn:    "Invalid SNN notation in style turn: %s"
+      }.freeze
+
+      # Pattern matching the FEEN specification for style turn
+      # <style-turn> ::= <style-id-uppercase> "/" <style-id-lowercase>
+      #                | <style-id-lowercase> "/" <style-id-uppercase>
+      VALID_STYLE_TURN_PATTERN = %r{
+        \A                                    # Start of string
+        (?:                                   # Non-capturing group for alternatives
+          (?<uppercase_first>[A-Z][A-Z0-9]*) # Named group: uppercase style identifier first
+          /                                   # Separator
+          (?<lowercase_second>[a-z][a-z0-9]*) # Named group: lowercase style identifier second
+          |                                   # OR
+          (?<lowercase_first>[a-z][a-z0-9]*) # Named group: lowercase style identifier first
+          /                                   # Separator
+          (?<uppercase_second>[A-Z][A-Z0-9]*) # Named group: uppercase style identifier second
+        )
+        \z                                    # End of string
+      }x
+
+      # Parses the style turn section of a FEEN string
+      #
+      # @param style_turn_str [String] FEEN style turn string
+      # @return [Array<String>] Array containing [active_style, inactive_style]
+      # @raise [ArgumentError] If the input string is invalid
+      #
+      # @example Valid style turn string with uppercase first
+      #   StyleTurn.parse("CHESS/shogi")
+      #   # => ["CHESS", "shogi"]
+      #
+      # @example Valid style turn string with lowercase first
+      #   StyleTurn.parse("chess/SHOGI")
+      #   # => ["chess", "SHOGI"]
+      #
+      # @example Valid style turn with numeric identifiers
+      #   StyleTurn.parse("CHESS960/makruk")
+      #   # => ["CHESS960", "makruk"]
+      def self.parse(style_turn_str)
+        validate_input_type(style_turn_str)
+
+        match = VALID_STYLE_TURN_PATTERN.match(style_turn_str)
+        raise ::ArgumentError, ERRORS[:invalid_format] unless match
+
+        style_identifiers = extract_style_identifiers(match)
+        validate_snn_compliance(style_identifiers)
+
+        style_identifiers
+      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
+
+      # Extracts style identifiers from regexp match captures
+      #
+      # @param match [MatchData] Regexp match data with named captures
+      # @return [Array<String>] Array containing [active_style, inactive_style]
+      private_class_method def self.extract_style_identifiers(match)
+        captures = match.named_captures
+
+        if captures["uppercase_first"]
+          [captures["uppercase_first"], captures["lowercase_second"]]
+        else
+          [captures["lowercase_first"], captures["uppercase_second"]]
+        end
+      end
+
+      # Validates that both style identifiers comply with SNN specification
+      #
+      # @param identifiers [Array<String>] Array of style identifiers to validate
+      # @raise [ArgumentError] If any identifier is invalid SNN notation
+      # @return [void]
+      private_class_method def self.validate_snn_compliance(identifiers)
+        identifiers.each do |identifier|
+          # Validate using the sashite-snn gem
+          # @see https://rubygems.org/gems/sashite-snn
+          raise ::ArgumentError, format(ERRORS[:invalid_snn], identifier) unless ::Sashite::Snn.valid?(identifier)
+        end
+      end
+    end
+  end
+end

data/lib/feen/parser.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require_relative File.join("parser", "games_turn")
+require_relative File.join("parser", "style_turn")
 require_relative File.join("parser", "piece_placement")
 require_relative File.join("parser", "pieces_in_hand")
 
@@ -21,8 +21,8 @@ module Feen
     # @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 (base form only)
-    #   - :games_turn [Array<String>] - A two-element array with [active_variant, inactive_variant]
+    #   - :pieces_in_hand [Array<String>] - Pieces available for dropping onto the board (may include modifiers)
+    #   - :style_turn [Array<String>] - A two-element array with [active_style, inactive_style]
     # @raise [ArgumentError] If the FEEN string is invalid
     #
     # @example Parsing a standard chess initial position
@@ -40,7 +40,7 @@ module Feen
     #   #        ["R", "N", "B", "Q", "K", "B", "N", "R"]
     #   #      ],
     #   #      pieces_in_hand: [],
-    #   #      games_turn: ["CHESS", "chess"]
+    #   #      style_turn: ["CHESS", "chess"]
     #   #    }
     def self.parse(feen_string)
       feen_string = String(feen_string)
@@ -52,18 +52,18 @@ module Feen
       raise ::ArgumentError, INVALID_FORMAT_ERROR unless match
 
       # Capture the three distinct parts
-      piece_placement_string, pieces_in_hand_string, games_turn_string = match.captures
+      piece_placement_string, pieces_in_hand_string, style_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)
+      style_turn = StyleTurn.parse(style_turn_string)
 
       # Create a structured representation of the position
       {
         piece_placement:,
         pieces_in_hand:,
-        games_turn:
+        style_turn:
       }
     end
 
@@ -78,7 +78,7 @@ module Feen
     # @example Parsing a valid FEEN string
     #   feen = "rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR / CHESS/chess"
     #   result = Feen::Parser.safe_parse(feen)
-    #   # => {piece_placement: [...], pieces_in_hand: [...], games_turn: [...]}
+    #   # => {piece_placement: [...], pieces_in_hand: [...], style_turn: [...]}
     #
     # @example Parsing an invalid FEEN string
     #   feen = "invalid feen string"

data/lib/feen.rb

@@ -17,11 +17,11 @@ module Feen
   # @param piece_placement [Array] Board position data structure representing the spatial
   #                               distribution of pieces across the board
   # @param pieces_in_hand [Array<String>] Pieces available for dropping onto the board.
-  #                                      MUST be in base form only (no modifiers allowed)
-  # @param games_turn [Array<String>] A two-element array where the first element is the
-  #                                  active player's variant and the second is the inactive player's variant
+  #                                      May include PNN modifiers (per FEEN v1.0.0 specification)
+  # @param style_turn [Array<String>] A two-element array where the first element is the
+  #                                  active player's style and the second is the inactive player's style
   # @return [String] FEEN notation string
-  # @raise [ArgumentError] If any parameter is invalid or pieces_in_hand contains modifiers
+  # @raise [ArgumentError] If any parameter is invalid
   # @example
   #   piece_placement = [
   #     ["r", "n", "b", "q", "k", "b", "n", "r"],
@@ -36,11 +36,11 @@ module Feen
   #   Feen.dump(
   #     piece_placement: piece_placement,
   #     pieces_in_hand: [],
-  #     games_turn: ["CHESS", "chess"]
+  #     style_turn: ["CHESS", "chess"]
   #   )
   #   # => "rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR / CHESS/chess"
-  def self.dump(piece_placement:, pieces_in_hand:, games_turn:)
-    Dumper.dump(piece_placement:, pieces_in_hand:, games_turn:)
+  def self.dump(piece_placement:, pieces_in_hand:, style_turn:)
+    Dumper.dump(piece_placement:, pieces_in_hand:, style_turn:)
   end
 
   # Parses a FEEN string into position components.
@@ -48,8 +48,8 @@ module Feen
   # @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 (base form only)
-  #   - :games_turn [Array<String>] - A two-element array with [active_variant, inactive_variant]
+  #   - :pieces_in_hand [Array<String>] - Pieces available for dropping onto the board (may include modifiers)
+  #   - :style_turn [Array<String>] - A two-element array with [active_style, inactive_style]
   # @raise [ArgumentError] If the FEEN string is invalid
   # @example
   #   feen_string = "rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR / CHESS/chess"
@@ -66,7 +66,7 @@ module Feen
   #   #        ["R", "N", "B", "Q", "K", "B", "N", "R"]
   #   #      ],
   #   #      pieces_in_hand: [],
-  #   #      games_turn: ["CHESS", "chess"]
+  #   #      style_turn: ["CHESS", "chess"]
   #   #    }
   def self.parse(feen_string)
     Parser.parse(feen_string)
@@ -82,7 +82,7 @@ module Feen
   # @example
   #   # Valid FEEN string
   #   Feen.safe_parse("rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR / CHESS/chess")
-  #   # => {piece_placement: [...], pieces_in_hand: [...], games_turn: [...]}
+  #   # => {piece_placement: [...], pieces_in_hand: [...], style_turn: [...]}
   #
   #   # Invalid FEEN string
   #   Feen.safe_parse("invalid feen string")
@@ -101,12 +101,15 @@ module Feen
   # This approach guarantees that the string not only follows FEEN syntax
   # but is also in its most compact, canonical representation.
   #
-  # According to FEEN specification:
-  # - Pieces in hand must be in base form only (no modifiers like +, -, ')
-  # - Pieces in hand must be sorted canonically within each case section:
-  #   1. By quantity (descending)
-  #   2. By piece letter (alphabetically ascending)
-  # - Case separation is enforced (uppercase/lowercase)
+  # According to FEEN v1.0.0 specification:
+  # - Pieces in hand may include PNN modifiers (prefixes and suffixes)
+  # - Pieces in hand must be sorted canonically according to the sorting algorithm:
+  #   1. By player (uppercase/lowercase separated by '/')
+  #   2. By quantity (descending)
+  #   3. By base letter (ascending)
+  #   4. By prefix (specific order: '-', '+', then no prefix)
+  #   5. By suffix (specific order: no suffix, then "'")
+  # - Style identifiers must follow SNN specification with semantic casing
   #
   # @param feen_string [String] FEEN string to validate
   # @return [Boolean] True if the string is a valid and canonical FEEN string
@@ -117,24 +120,21 @@ module Feen
   #   # Invalid syntax
   #   Feen.valid?("invalid feen string") # => false
   #
-  #   # Valid syntax but non-canonical form (pieces in hand with modifiers)
-  #   Feen.valid?("8/8/8/8/8/8/8/8 +P/ FOO/bar") # => false
-  #
   #   # Valid syntax but non-canonical form (wrong ordering in pieces in hand)
   #   Feen.valid?("8/8/8/8/8/8/8/8 P3K/ FOO/bar") # => false
+  #
+  #   # Canonical form with modifiers in pieces in hand
+  #   Feen.valid?("8/8/8/8/8/8/8/8 2+B5BK3-P-P'3+P'9PR2SS'/ FOO/bar") # => true
   def self.valid?(feen_string)
     # First check: Basic syntax validation
-    begin
-      parsed_data = parse(feen_string)
-    rescue ::ArgumentError
-      return false
-    end
+    parsed_data = safe_parse(feen_string)
+    return false if parsed_data.nil?
 
     # Second check: Canonicity validation through round-trip conversion
     # Generate a fresh FEEN string from the parsed data
     canonical_feen = dump(**parsed_data)
 
-    # Compare the original string with the canonical form
-    feen_string == canonical_feen
+    # Compare the canonical form with the original string
+    canonical_feen == feen_string
   end
 end

metadata

@@ -1,17 +1,45 @@
 --- !ruby/object:Gem::Specification
 name: feen
 version: !ruby/object:Gem::Version
-  version: 5.0.0.beta9
+  version: 5.0.0.beta10
 platform: ruby
 authors:
 - Cyril Kato
 bindir: bin
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
-dependencies: []
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: pnn
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 2.0.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 2.0.0
+- !ruby/object:Gem::Dependency
+  name: sashite-snn
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.0.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.0.0
 description: A Ruby interface for data serialization and deserialization in FEEN format.
   FEEN is a compact, canonical, and rule-agnostic textual format for representing
-  static board positions in two-player piece-placement games like Chess, Shogi, Xiangqi,
+  static board positions in two-player piece-placement games like Chess, Shōgi, Xiangqi,
   and others.
 email: contact@cyril.email
 executables: []
@@ -22,13 +50,13 @@ 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/style_turn.rb
 - lib/feen/parser.rb
-- lib/feen/parser/games_turn.rb
 - lib/feen/parser/piece_placement.rb
 - lib/feen/parser/pieces_in_hand.rb
+- lib/feen/parser/style_turn.rb
 homepage: https://github.com/sashite/feen.rb
 licenses:
 - MIT
@@ -39,8 +67,6 @@ metadata:
   source_code_uri: https://github.com/sashite/feen.rb
   specification_uri: https://sashite.dev/documents/feen/1.0.0/
   rubygems_mfa_required: 'true'
-  keywords: board, board-games, chess, deserialization, feen, fen, game, makruk, notation,
-    serialization, shogi, xiangqi"
 rdoc_options: []
 require_paths:
 - lib

data/lib/feen/dumper/games_turn.rb

@@ -1,70 +0,0 @@
-# frozen_string_literal: true
-
-module Feen
-  module Dumper
-    # Handles conversion of games turn data to FEEN notation string
-    module GamesTurn
-      # Error messages for validation
-      ERRORS = {
-        invalid_type:  "%s must be a String, got %s",
-        empty_string:  "%s cannot be empty",
-        invalid_chars: "%s must contain only alphabetic characters (a-z, A-Z)",
-        mixed_case:    "%s has mixed case: %s",
-        same_casing:   "One variant must be uppercase and the other lowercase"
-      }.freeze
-
-      # Converts the active and inactive variant identifiers to a FEEN-formatted games turn string
-      #
-      # @param active_variant [String] Identifier for the player to move and their game variant
-      # @param inactive_variant [String] Identifier for the opponent and their game variant
-      # @return [String] FEEN-formatted games turn string
-      # @raise [ArgumentError] If the variant identifiers are invalid
-      #
-      # @example Valid games turn
-      #   GamesTurn.dump("CHESS", "chess")
-      #   # => "CHESS/chess"
-      #
-      # @example Invalid - same casing
-      #   GamesTurn.dump("CHESS", "MAKRUK")
-      #   # => ArgumentError: One variant must be uppercase and the other lowercase
-      def self.dump(active_variant, inactive_variant)
-        validate_variants(active_variant, inactive_variant)
-        "#{active_variant}/#{inactive_variant}"
-      end
-
-      # Validates the game variant identifiers
-      #
-      # @param active [String] The active player's variant identifier
-      # @param inactive [String] The inactive player's variant identifier
-      # @raise [ArgumentError] If the variant identifiers are invalid
-      # @return [void]
-      private_class_method def self.validate_variants(active, inactive)
-        # Validate basic type, presence and format
-        [["Active variant", active], ["Inactive variant", inactive]].each do |name, variant|
-          # Type validation
-          raise ArgumentError, format(ERRORS[:invalid_type], name, variant.class) unless variant.is_a?(String)
-
-          # Empty validation
-          raise ArgumentError, format(ERRORS[:empty_string], name) if variant.empty?
-
-          # Character validation
-          raise ArgumentError, format(ERRORS[:invalid_chars], name) unless variant.match?(/\A[a-zA-Z]+\z/)
-
-          # Mixed case validation
-          unless variant == variant.upcase || variant == variant.downcase
-            raise ArgumentError, format(ERRORS[:mixed_case], name, variant)
-          end
-        end
-
-        # Casing difference validation
-        active_is_uppercase = active == active.upcase
-        inactive_is_uppercase = inactive == inactive.upcase
-
-        # Both variants must have different casing
-        return unless active_is_uppercase == inactive_is_uppercase
-
-        raise ArgumentError, ERRORS[:same_casing]
-      end
-    end
-  end
-end

data/lib/feen/parser/games_turn.rb

@@ -1,78 +0,0 @@
-# frozen_string_literal: true
-
-module Feen
-  module Parser
-    # Handles parsing of the games turn section of a FEEN string
-    module GamesTurn
-      # Error messages for games turn parsing
-      ERRORS = {
-        invalid_type:   "Games turn must be a string, got %s",
-        empty_string:   "Games turn string cannot be empty",
-        invalid_format: "Invalid games turn format. Expected format: UPPERCASE/lowercase or lowercase/UPPERCASE"
-      }.freeze
-
-      # Pattern matching the FEEN specification for games turn
-      # <games-turn> ::= <game-id-uppercase> "/" <game-id-lowercase>
-      #                | <game-id-lowercase> "/" <game-id-uppercase>
-      VALID_GAMES_TURN_PATTERN = %r{
-        \A                            # Start of string
-        (?:                           # Non-capturing group for alternatives
-          (?<uppercase_first>[A-Z]+)  # Named group: uppercase identifier first
-          /                           # Separator
-          (?<lowercase_second>[a-z]+) # Named group: lowercase identifier second
-          |                           # OR
-          (?<lowercase_first>[a-z]+)  # Named group: lowercase identifier first
-          /                           # Separator
-          (?<uppercase_second>[A-Z]+) # Named group: uppercase identifier second
-        )
-        \z                            # End of string
-      }x
-
-      # Parses the games turn section of a FEEN string
-      #
-      # @param games_turn_str [String] FEEN games turn string
-      # @return [Array<String>] Array containing [active_player, inactive_player]
-      # @raise [ArgumentError] If the input string is invalid
-      #
-      # @example Valid games turn string with uppercase first
-      #   GamesTurn.parse("CHESS/ogi")
-      #   # => ["CHESS", "ogi"]
-      #
-      # @example Valid games turn string with lowercase first
-      #   GamesTurn.parse("chess/OGI")
-      #   # => ["chess", "OGI"]
-      def self.parse(games_turn_str)
-        validate_input_type(games_turn_str)
-
-        match = VALID_GAMES_TURN_PATTERN.match(games_turn_str)
-        raise ::ArgumentError, ERRORS[:invalid_format] unless match
-
-        extract_game_identifiers(match)
-      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
-
-      # Extracts game identifiers from regexp match captures
-      #
-      # @param match [MatchData] Regexp match data with named captures
-      # @return [Array<String>] Array containing [active_player, inactive_player]
-      private_class_method def self.extract_game_identifiers(match)
-        captures = match.named_captures
-
-        if captures["uppercase_first"]
-          [captures["uppercase_first"], captures["lowercase_second"]]
-        else
-          [captures["lowercase_first"], captures["uppercase_second"]]
-        end
-      end
-    end
-  end
-end