feen 5.0.0.beta2 → 5.0.0.beta4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3dbd219b5b2e7870e60da133faae1f342179e35682590d2f5fbe06c4f0130d39
-  data.tar.gz: c1042208ec1799d5700e87327bafaa39dc918b5e101304c9b90a67e22be76c25
+  metadata.gz: de87bfc9b071e9f1ff14b6f7378ba0a6f9f78cdb9a9bfe32ca00f2494a1be2cd
+  data.tar.gz: fd4d19e8a3b7fb845f081b127a859ff0791c8c11c05e1efb4846152044f67c18
 SHA512:
-  metadata.gz: e8480101aa872bba2295a2ee74d47f4bde63a7d94c50b6504e8acadbf8347ee5a136bc962b65fdbb75aed3dd887693b6b012b53aed77c4e101313fd2189c59d5
-  data.tar.gz: fde52d865df00f7602017789aeb9d6520b809be88fad13a14215f289abcc60f61d88ae73624cf01fd3a158aa62a94b98814bb0a1aff510b2e218833fb59094d9
+  metadata.gz: e9fe95297b8577a3bf171a865deca0dc9c2eed91a7d039c04f97077d53d3fa912ca553f28f448f0dd987087926d3ca5225624d7f2d8d08a9275a16a11efe26e0
+  data.tar.gz: b82b7e00f5ece6f5e5859750226be3c74db23e694c8e53def8c8c656fe2fb3ecba7f0f4166cf3d9a4f6c7b4ab7af3cf6544da87a2684e438a389d96e04b3dc75

data/README.md

@@ -1,28 +1,28 @@
 # Feen.rb
 
-[![Version](https://img.shields.io/github/v/tag/sashite/feen.rb?label=Version&logo=github)](https://github.com/sashite/feen.rb/releases)
+[![Version](https://img.shields.io/github/v/tag/sashite/feen.rb?label=Version&logo=github)](https://github.com/sashite/feen.rb/tags)
 [![Yard documentation](https://img.shields.io/badge/Yard-documentation-blue.svg?logo=github)](https://rubydoc.info/github/sashite/feen.rb/main)
-[![CI](https://github.com/sashite/feen.rb/workflows/CI/badge.svg?branch=main)](https://github.com/sashite/feen.rb/actions?query=workflow%3Aci+branch%3Amain)
-[![RuboCop](https://github.com/sashite/feen.rb/workflows/RuboCop/badge.svg?branch=main)](https://github.com/sashite/feen.rb/actions?query=workflow%3Arubocop+branch%3Amain)
+![Ruby](https://github.com/sashite/feen.rb/actions/workflows/main.yml/badge.svg?branch=main)
 [![License](https://img.shields.io/github/license/sashite/feen.rb?label=License&logo=github)](https://github.com/sashite/feen.rb/raw/main/LICENSE.md)
 
-> **FEEN** (Forsyth–Edwards Essential Notation) support for the Ruby language.
+> **FEEN** (Forsyth–Edwards Enhanced Notation) support for the Ruby language.
 
 ## What is FEEN?
 
-FEEN (Forsyth–Edwards Essential Notation) is a compact, canonical, and rule-agnostic textual format for representing static board positions in two-player piece-placement games.
+FEEN (Forsyth–Edwards Enhanced Notation) is a compact, canonical, and rule-agnostic textual format for representing static board positions in two-player piece-placement games.
 
 This gem implements the [FEEN Specification v1.0.0](https://sashite.dev/documents/feen/1.0.0/), providing a Ruby interface for:
-- Multiple game types (chess, shogi, xiangqi, etc.)
-- Hybrid or cross-game positions
-- Arbitrary-dimensional boards
-- Pieces in hand (as used in Shogi)
+- Representing positions from various games without knowledge of specific rules
+- Supporting boards of arbitrary dimensions
+- Encoding pieces in hand (as used in Shogi)
+- Facilitating serialization and deserialization of positions
+- Ensuring canonical representation for consistent data handling
 
 ## Installation
 
 ```ruby
 # In your Gemfile
-gem "feen", ">= 5.0.0.beta2"
+gem "feen", ">= 5.0.0.beta4"
 ```
 
 Or install manually:
@@ -36,7 +36,7 @@ gem install feen --pre
 A FEEN record consists of three space-separated fields:
 
 ```
-<PIECE-PLACEMENT> <GAMES-TURN> <PIECES-IN-HAND>
+<PIECE-PLACEMENT> <PIECES-IN-HAND> <GAMES-TURN>
 ```
 
 ## Basic Usage
@@ -48,81 +48,136 @@ Convert a FEEN string into a structured Ruby object:
 ```ruby
 require "feen"
 
-feen_string = "rnbqk=bnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQK=BNR CHESS/chess -"
+feen_string = "rnbqk=bnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQK=BNR - CHESS/chess"
 position = Feen.parse(feen_string)
 
-# Result is a hash with structured position data
-# position[:piece_placement] # 2D array of board pieces
-# position[:games_turn]      # Details about active player and game
-# position[:pieces_in_hand]  # Array of pieces held for dropping
+# Result is a hash:
+# {
+#   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"]
+# }
+```
+
+### Safe Parsing
+
+Parse a FEEN string without raising exceptions:
+
+```ruby
+require "feen"
+
+# Valid FEEN string
+result = Feen.safe_parse("rnbqk=bnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQK=BNR - CHESS/chess")
+# => {piece_placement: [...], pieces_in_hand: [...], games_turn: [...]}
+
+# Invalid FEEN string
+result = Feen.safe_parse("invalid feen string")
+# => nil
 ```
 
 ### Creating FEEN Strings
 
-Convert a position structure to a FEEN string:
+Convert position components to a FEEN string using named arguments:
 
 ```ruby
 require "feen"
 
-position = {
-  piece_placement: [
-    [{ id: "r" }, { id: "n" }, { id: "b" }, { id: "q" }, { id: "k", suffix: "=" }, { id: "b" }, { id: "n" }, { id: "r" }],
-    [{ id: "p" }, { id: "p" }, { id: "p" }, { id: "p" }, { id: "p" }, { id: "p" }, { id: "p" }, { id: "p" }],
-    [nil, nil, nil, nil, nil, nil, nil, nil],
-    [nil, nil, nil, nil, nil, nil, nil, nil],
-    [nil, nil, nil, nil, nil, nil, nil, nil],
-    [nil, nil, nil, nil, nil, nil, nil, nil],
-    [{ id: "P" }, { id: "P" }, { id: "P" }, { id: "P" }, { id: "P" }, { id: "P" }, { id: "P" }, { id: "P" }],
-    [{ id: "R" }, { id: "N" }, { id: "B" }, { id: "Q" }, { id: "K", suffix: "=" }, { id: "B" }, { id: "N" }, { id: "R" }]
-  ],
-  games_turn:      {
-    active_player:   "CHESS",
-    inactive_player: "chess"
-  },
+# Representation of a chess board in initial position
+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"]
+]
+
+result = Feen.dump(
+  piece_placement: piece_placement,
+  games_turn:      %w[CHESS chess],
   pieces_in_hand:  []
-}
-
-Feen.dump(position)
-# => "rnbqk=bnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQK=BNR CHESS/chess -"
+)
+# => "rnbqk=bnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQK=BNR - CHESS/chess"
 ```
 
 ### Validation
 
-Check if a string is valid FEEN notation:
+Check if a string is valid FEEN notation and in canonical form:
 
 ```ruby
 require "feen"
 
-Feen.valid?("rnbqk=bnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQK=BNR CHESS/chess -")
+# Canonical form
+Feen.valid?("lnsgk3l/5g3/p1ppB2pp/9/8B/2P6/P2PPPPPP/3K3R1/5rSNL N5P2gln2s SHOGI/shogi")
 # => true
 
+# Invalid syntax
 Feen.valid?("invalid feen string")
 # => false
+
+# Valid syntax but non-canonical form (pieces in hand not in lexicographic order)
+Feen.valid?("lnsgk3l/5g3/p1ppB2pp/9/8B/2P6/P2PPPPPP/3K3R1/5rSNL N5P2gn2sl SHOGI/shogi")
+# => false
 ```
 
-## FEN Compatibility
+The `valid?` method performs two levels of validation:
+1. **Syntax check**: Verifies the string can be parsed as FEEN
+2. **Canonicity check**: Ensures the string is in its canonical form through round-trip conversion
 
-### Converting FEN to FEEN
+## Game Examples
+
+As FEEN is rule-agnostic, it can represent positions from various board games. Here are some examples:
+
+### International Chess
 
 ```ruby
-require "feen"
+feen_string = "rnbqk=bnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQK=BNR - CHESS/chess"
+```
+
+In this initial chess position:
+- The `=` suffixes on kings indicate castling rights on both sides (though FEEN doesn't define this semantics)
+- The third field `CHESS/chess` indicates it's the player with uppercase pieces' turn to move
 
-fen_string = "rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1"
-feen_string = Feen.from_fen(fen_string)
-# => "rnbqk=bnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQK=BNR CHESS/chess -"
+### Shogi (Japanese Chess)
+
+```ruby
+feen_string = "lnsgk3l/5g3/p1ppB2pp/9/8B/2P6/P2PPPPPP/3K3R1/5rSNL N5P2gln2s SHOGI/shogi"
 ```
 
-### Converting FEEN to FEN
+In this shogi position:
+- The format supports promotions with the `+` prefix (e.g., `+P` for a promoted pawn)
+- The notation allows for pieces in hand, indicated in the second field
+- `SHOGI/shogi` indicates it's Sente's (Black's, uppercase) turn to move
+- `N5P2gln2s` shows the pieces in hand: Sente has a Knight (N) and 5 Pawns (5P), while Gote has 2 Golds (2g), a Lance (l), a Knight (n), and 2 Silvers (2s), all properly sorted in ASCII lexicographic order
+
+### Makruk (Thai Chess)
 
 ```ruby
-require "feen"
+feen_string = "rnbqkbnr/8/pppppppp/8/8/PPPPPPPP/8/RNBQKBNR - MAKRUK/makruk"
+```
+
+This initial Makruk position is easily represented in FEEN without needing to know the specific rules of the game.
 
-feen_string = "rnbqk=bnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQK=BNR CHESS/chess -"
-fen_string = Feen.to_fen(feen_string)
-# => "rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1"
+### Xiangqi (Chinese Chess)
+
+```ruby
+feen_string = "rheagaehr/9/1c5c1/s1s1s1s1s/9/9/S1S1S1S1S/1C5C1/9/RHEAGAEHR - XIANGQI/xiangqi"
 ```
 
-> ⚠️ `Feen.to_fen` only supports FEEN positions where `games_turn` is `CHESS/chess` or `chess/CHESS`.
+In this Xiangqi position:
+- The representation uses single letters for the different pieces
+- The format naturally adapts to the presence of a "river" (empty space in the middle)
 
 ## Advanced Features
 
@@ -134,61 +189,54 @@ FEEN supports arbitrary-dimensional board configurations:
 require "feen"
 
 # 3D board
-position = {
-  piece_placement: [
-    [
-      [{ id: "r" }, { id: "n" }, { id: "b" }],
-      [{ id: "q" }, { id: "k" }, { id: "p" }]
-    ],
-    [
-      [{ id: "P" }, { id: "R" }, nil],
-      [nil, { id: "K" }, { id: "Q" }]
-    ]
+piece_placement = [
+  [
+    %w[r n b],
+    %w[q k p]
   ],
-  games_turn:      {
-    active_player:   "CHESS",
-    inactive_player: "chess"
-  },
+  [
+    ["P", "R", ""],
+    ["", "K", "Q"]
+  ]
+]
+
+result = Feen.dump(
+  piece_placement: piece_placement,
+  games_turn:      %w[FOO bar],
   pieces_in_hand:  []
-}
-
-Feen.dump(position)
-# => "rnb/qkp//PR1/1KQ CHESS/chess -"
+)
+# => "rnb/qkp//PR1/1KQ - FOO/bar"
 ```
 
 ### Piece Modifiers
 
-FEEN supports prefixes and suffixes for pieces:
+FEEN supports prefixes and suffixes for pieces to denote various states or capabilities:
 
-- Prefix `+`: Often used for promotion (e.g., `+P` for promoted pawn in Shogi)
-- Suffix `=`: Dual-option status (e.g., `K=` for king eligible for both castling sides)
-- Suffix `<`: Left-side constraint (e.g., `K<` for queenside castling only)
-- Suffix `>`: Right-side constraint (e.g., `K>` for kingside castling only)
+- **Prefix `+`**: May indicate promotion or special state
+  - Example in shogi: `+P` may represent a promoted pawn
 
-### Sanitizing FEN Strings
+- **Suffix `=`**: May indicate dual-option status
+  - Example in chess: `K=` may represent a king eligible for both kingside and queenside castling
 
-FEEN includes utilities to clean FEN strings by validating and removing invalid castling rights and en passant targets:
+- **Suffix `<`**: May indicate left-side constraint
+  - Example in chess: `K<` may represent a king eligible for queenside castling only
+  - Example in chess: `P<` may represent a pawn that may be captured _en passant_ from the left
 
-```ruby
-require "feen"
+- **Suffix `>`**: May indicate right-side constraint
+  - Example in chess: `K>` may represent a king eligible for kingside castling only
+  - Example in chess: `P>` may represent a pawn that may be captured en passant from the right
 
-# FEN with invalid castling rights
-fen_string = "rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQ1BNR w KQkq - 0 1"
-cleaned_fen = Feen::Sanitizer.clean_fen(fen_string)
-# => "rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQ1BNR w kq - 0 1"
-```
+These modifiers have no defined semantics in the FEEN specification itself but provide a flexible framework for representing piece-specific conditions while maintaining FEEN's rule-agnostic nature.
 
 ## Documentation
 
-- [Official FEEN Specification v1.0.0](https://sashite.dev/documents/feen/1.0.0/)
+- [Official FEEN Specification](https://sashite.dev/documents/feen/1.0.0/)
 - [API Documentation](https://rubydoc.info/github/sashite/feen.rb/main)
 
 ## License
 
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+The [gem](https://rubygems.org/gems/feen) is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
 
 ## About Sashité
 
-This [gem](https://rubygems.org/gems/feen) is maintained by [Sashité](https://sashite.com/).
-
-With some [lines of code](https://github.com/sashite/), let's share the beauty of Chinese, Japanese and Western cultures through the game of chess!
+This project is maintained by [Sashité](https://sashite.com/) - a project dedicated to promoting chess variants and sharing the beauty of Chinese, Japanese, and Western chess cultures.

data/lib/feen/dumper/games_turn.rb

@@ -2,90 +2,65 @@
 
 module Feen
   module Dumper
-    # Handles conversion of games turn data structure to FEEN notation string
+    # Handles conversion of games turn data to FEEN notation string
     module GamesTurn
       ERRORS = {
-        missing_key:        "Missing required key in games_turn: %s",
-        invalid_type:       "Invalid type for games_turn[%s]: expected String, got %s",
-        empty_string:       "Empty string for games_turn[%s]",
-        casing_requirement: "One game must be uppercase and the other lowercase",
-        invalid_chars:      "Game identifiers must contain only alphabetic characters (a-z, A-Z)"
+        type:   "%s must be a String, got %s",
+        empty:  "%s cannot be empty",
+        mixed:  "%s has mixed case: %s",
+        casing: "One variant must be uppercase and the other lowercase",
+        chars:  "Variant identifiers must contain only alphabetic characters (a-z, A-Z)"
       }.freeze
 
-      REQUIRED_KEYS = %i[active_player inactive_player].freeze
-
-      # Converts the internal games turn representation to a FEEN string
+      # Converts the active and inactive variant identifiers to a FEEN-formatted games turn string
       #
-      # @param games_turn [Hash] Hash containing game turn information
+      # @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
-      def self.dump(games_turn)
-        validate_games_turn(games_turn)
-
-        # Format is <active_player>/<inactive_player>
-        "#{games_turn[:active_player]}/#{games_turn[:inactive_player]}"
-      end
-
-      # Validates the games turn data structure
-      #
-      # @param games_turn [Hash] The games turn data to validate
-      # @raise [ArgumentError] If the games turn data is invalid
-      # @return [Boolean] true if the validation passes
-      def self.validate_games_turn(games_turn)
-        validate_structure(games_turn)
-        validate_casing(games_turn)
-        validate_character_set(games_turn)
-
-        true
+      def self.dump(active_variant, inactive_variant)
+        validate_variants(active_variant, inactive_variant)
+        "#{active_variant}/#{inactive_variant}"
       end
 
-      # Validates the basic structure of games_turn
+      # Validates the game variant identifiers
       #
-      # @param games_turn [Hash] The games turn data to validate
-      # @raise [ArgumentError] If the structure is invalid
+      # @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_structure(games_turn)
-        REQUIRED_KEYS.each do |key|
-          raise ArgumentError, format(ERRORS[:missing_key], key) unless games_turn.key?(key)
-
-          unless games_turn[key].is_a?(String)
-            raise ArgumentError, format(ERRORS[:invalid_type], key, games_turn[key].class)
-          end
-
-          raise ArgumentError, format(ERRORS[:empty_string], key) if games_turn[key].empty?
+      private_class_method def self.validate_variants(active, inactive)
+        # Validate basic type and presence
+        [["Active variant", active], ["Inactive variant", inactive]].each do |name, variant|
+          raise ArgumentError, format(ERRORS[:type], name, variant.class) unless variant.is_a?(String)
+          raise ArgumentError, format(ERRORS[:empty], name) if variant.empty?
+          raise ArgumentError, ERRORS[:chars] unless variant.match?(/\A[a-zA-Z]+\z/)
         end
-      end
 
-      # Validates the casing requirement (one uppercase, one lowercase)
-      #
-      # @param games_turn [Hash] The games turn data to validate
-      # @raise [ArgumentError] If the casing requirement is not met
-      # @return [void]
-      private_class_method def self.validate_casing(games_turn)
-        active_has_uppercase = games_turn[:active_player].match?(/[A-Z]/)
-        inactive_has_uppercase = games_turn[:inactive_player].match?(/[A-Z]/)
+        # Validate casing (one must be uppercase, one must be lowercase)
+        active_uppercase = active == active.upcase && active != active.downcase
+        inactive_uppercase = inactive == inactive.upcase && inactive != inactive.downcase
 
-        # Ensure exactly one has uppercase
-        raise ArgumentError, ERRORS[:casing_requirement] if active_has_uppercase == inactive_has_uppercase
+        # If both have the same casing (both uppercase or both lowercase), raise error
+        raise ArgumentError, ERRORS[:casing] if active_uppercase == inactive_uppercase
 
-        # Check that uppercase game is all caps and lowercase game has no caps
-        if active_has_uppercase && games_turn[:active_player].match?(/[a-z]/)
-          raise ArgumentError, "Active game has mixed case: #{games_turn[:active_player]}"
+        # Check for mixed case (must be all uppercase or all lowercase)
+        if active_uppercase && active != active.upcase
+          raise ArgumentError, format(ERRORS[:mixed], "Active variant", active)
         end
 
-        return unless inactive_has_uppercase && games_turn[:inactive_player].match?(/[a-z]/)
+        if inactive_uppercase && inactive != inactive.upcase
+          raise ArgumentError, format(ERRORS[:mixed], "Inactive variant", inactive)
+        end
 
-        raise ArgumentError, "Inactive game has mixed case: #{games_turn[:inactive_player]}"
-      end
+        if !active_uppercase && active != active.downcase
+          raise ArgumentError, format(ERRORS[:mixed], "Active variant", active)
+        end
 
-      # Validates that identifiers only contain allowed characters
-      #
-      # @param games_turn [Hash] The games turn data to validate
-      # @raise [ArgumentError] If invalid characters are present
-      # @return [void]
-      private_class_method def self.validate_character_set(games_turn)
-        REQUIRED_KEYS.each do |key|
-          raise ArgumentError, ERRORS[:invalid_chars] unless games_turn[key].match?(/\A[a-zA-Z]+\z/)
+        if !inactive_uppercase && inactive != inactive.downcase
+          raise ArgumentError, format(ERRORS[:mixed], "Inactive variant", inactive)
         end
+
+        true
       end
     end
   end