feen 5.0.0.beta1 → 5.0.0.beta3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2fa56bccbb1911f15569f2f5643646986cbf83661efba3165c69978e7c85fd56
-  data.tar.gz: 13d706d1bfe1c09f6d015d0a8f28af621754677711074ec60ec96e395f1a1061
+  metadata.gz: ad6a4426ae68ac5344888465a23eea36cf28b3e0137b50af8483b98288012969
+  data.tar.gz: f9f42840240c5b75629cdb5459f492f966d3fc2706a354c18abc9841a9f17e21
 SHA512:
-  metadata.gz: 5479cbd02c902aa8c45cc12ecfab31c7b7283eb1f8ec60b110c889505a7ebbcf76fa7b0d2e6ad44c60da954312fa85ae03cd4981d929207b0612754f1d62a033
-  data.tar.gz: b6268ce619808bf2c2f889261b55007edbfc030bc37b8edea7f73f505de55e8c0fc1cd4a268e8e2bdc71fe21c9fa33f904c8b26a23b92b471e406e109494bd97
+  metadata.gz: 31141ae8b866a11ffec6eed44308b475d03e75174ec0bc12b14ff0dc60bfe8b21ad60af3d32e1747d7dce94fe0cff0bbd5add502f26c26aeffac97104fbeeaca
+  data.tar.gz: 82c82de3cf0024e596d9f318e612a8077069a9b519e6b4e753dc808bbee91045f72328489a26307f0877194a4e99ffc8502dd3d3d1610900215ab697fa479ce4

data/LICENSE.md

@@ -1,6 +1,6 @@
 # The MIT License
 
-Copyright (c) 2020-2023 Sashité
+Copyright (c) 2020-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

data/README.md

@@ -1,89 +1,215 @@
 # 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 Expanded Notation) support for the Ruby language.
+> **FEEN** (Format for Encounter & Entertainment Notation) support for the Ruby language.
 
-## Overview
+## What is FEEN?
 
-This is an implementation of [FEEN](https://github.com/sashite/specs/blob/main/forsyth-edwards-expanded-notation.md), a flexible and minimalist format for describing chess variant positions.
+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.
 
-## Installation
+This gem implements the [FEEN Specification v1.0.0](https://sashite.dev/documents/feen/1.0.0/), providing a Ruby interface for:
+- 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
 
-Add this line to your application's Gemfile:
+## Installation
 
 ```ruby
-gem "feen", ">= 5.0.0.beta1"
+# In your Gemfile
+gem "feen", ">= 5.0.0.beta3"
 ```
 
-And then execute:
+Or install manually:
 
 ```sh
-bundle install
+gem install feen --pre
 ```
 
-Or install it yourself as:
+## FEEN Format
 
-```sh
-gem install feen --pre
+A FEEN record consists of three space-separated fields:
+
+```
+<PIECE-PLACEMENT> <PIECES-IN-HAND> <GAMES-TURN>
 ```
 
-## Usage
+## Basic Usage
 
-### Serialization
+### Parsing FEEN Strings
 
-A position can be serialized by filling in these fields:
+Convert a FEEN string into a structured Ruby object:
 
-- **Board shape**: An array of integers. For instance, it would be `[10, 9]` for a Xiangqi board. Or it would be `[8, 8]` for a Chess board.
-- **Piece placement**: Describes the placement of pieces on the board with a hash that references each piece on the board.
-- **Side to move**: A char that indicates who moves next. In chess, "`w`" would mean that White can play a move.
+```ruby
+require "feen"
+
+feen_string = "rnbqk=bnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQK=BNR - CHESS/chess"
+position = Feen.parse(feen_string)
+
+# 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"]
+#   ],
+#   "games_turn" => ["CHESS", "chess"],
+#   "pieces_in_hand" => []
+# }
+```
 
-#### Example
+### Creating FEEN Strings
 
-From a classic Tsume Shogi problem:
+Convert position components to a FEEN string using named arguments:
 
 ```ruby
 require "feen"
 
-Feen.dump(
-  board_shape:     [9, 9],
-  side_to_move:    "s",
-  piece_placement: {
-    3  => "s",
-    4  => "k",
-    5  => "s",
-    22 => "+P",
-    43 => "+B"
-  }
+# 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:  []
 )
-# => "3sks3/9/4+P4/9/7+B1/9/9/9/9 s"
+# => "rnbqk=bnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQK=BNR - CHESS/chess"
+```
+
+### Validation
+
+Check if a string is valid FEEN notation:
+
+```ruby
+require "feen"
+
+Feen.valid?("rnbqk=bnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQK=BNR - CHESS/chess")
+# => true
+
+Feen.valid?("invalid feen string")
+# => false
+```
+
+## Game Examples
+
+As FEEN is rule-agnostic, it can represent positions from various board games. Here are some examples:
+
+### International Chess
+
+```ruby
+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
+
+### Shogi (Japanese Chess)
+
+```ruby
+feen_string = "lnsgk3l/5g3/p1ppB2pp/9/8B/2P6/P2PPPPPP/3K3R1/5rSNL N5P2g2snl SHOGI/shogi"
+```
+
+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
+- `N5P2g2snl` shows the pieces in hand: Sente has a Knight (N) and 5 Pawns (P), while Gote has 2 Golds (g), 2 Silvers (s), a Knight (n), and a Lance (l)
+
+### Makruk (Thai Chess)
+
+```ruby
+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.
+
+### Xiangqi (Chinese Chess)
+
+```ruby
+feen_string = "rheagaehr/9/1c5c1/s1s1s1s1s/9/9/S1S1S1S1S/1C5C1/9/RHEAGAEHR - XIANGQI/xiangqi"
 ```
 
-### Deserialization
+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
 
-Serialized positions can be converted back to fields.
+### Multi-dimensional Boards
 
-#### Example
+FEEN supports arbitrary-dimensional board configurations:
 
 ```ruby
 require "feen"
 
-Feen.parse("3sks3/9/4+P4/9/7+B1/9/9/9/9 s")
-# {:board_shape=>[9, 9],
-#  :piece_placement=>{3=>"s", 4=>"k", 5=>"s", 22=>"+P", 43=>"+B"},
-#  :side_to_move=>"s"}
+# 3D board
+piece_placement = [
+  [
+    %w[r n b],
+    %w[q k p]
+  ],
+  [
+    ["P", "R", ""],
+    ["", "K", "Q"]
+  ]
+]
+
+result = Feen.dump(
+  piece_placement: piece_placement,
+  games_turn:      %w[FOO bar],
+  pieces_in_hand:  []
+)
+# => "rnb/qkp//PR1/1KQ - FOO/bar"
 ```
 
+### Piece Modifiers
+
+FEEN supports prefixes and suffixes for pieces to denote various states or capabilities:
+
+- **Prefix `+`**: May indicate promotion or special state
+  - Example in shogi: `+P` may represent a promoted pawn
+
+- **Suffix `=`**: May indicate dual-option status
+  - Example in chess: `K=` may represent a king eligible for both kingside and queenside castling
+
+- **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
+
+- **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
+
+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](https://sashite.dev/documents/feen/1.0.0/)
+- [API Documentation](https://rubydoc.info/github/sashite/feen.rb/main)
+
 ## License
 
-The code 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

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module Feen
+  module Dumper
+    # Handles conversion of games turn data to FEEN notation string
+    module GamesTurn
+      ERRORS = {
+        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
+
+      # 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
+      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 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
+
+        # 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
+
+        # If both have the same casing (both uppercase or both lowercase), raise error
+        raise ArgumentError, ERRORS[:casing] if active_uppercase == inactive_uppercase
+
+        # 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
+
+        if inactive_uppercase && inactive != inactive.upcase
+          raise ArgumentError, format(ERRORS[:mixed], "Inactive variant", inactive)
+        end
+
+        if !active_uppercase && active != active.downcase
+          raise ArgumentError, format(ERRORS[:mixed], "Active variant", active)
+        end
+
+        if !inactive_uppercase && inactive != inactive.downcase
+          raise ArgumentError, format(ERRORS[:mixed], "Inactive variant", inactive)
+        end
+
+        true
+      end
+    end
+  end
+end

data/lib/feen/dumper/piece_placement.rb

@@ -2,84 +2,133 @@
 
 module Feen
   module Dumper
-    # The PiecePlacement class.
-    #
-    # @example Dump an empty board of Xiangqi
-    #   PiecePlacement.new([10, 9]).to_s # => "9/9/9/9/9/9/9/9/9/9"
-    #
-    # @example Dump the Xiangqi starting position board
-    #   PiecePlacement.new(
-    #     [10, 9],
-    #     {
-    #        0 => "車",
-    #        1 => "馬",
-    #        2 => "象",
-    #        3 => "士",
-    #        4 => "將",
-    #        5 => "士",
-    #        6 => "象",
-    #        7 => "馬",
-    #        8 => "車",
-    #       19 => "砲",
-    #       25 => "砲",
-    #       27 => "卒",
-    #       29 => "卒",
-    #       31 => "卒",
-    #       33 => "卒",
-    #       35 => "卒",
-    #       54 => "兵",
-    #       56 => "兵",
-    #       58 => "兵",
-    #       60 => "兵",
-    #       62 => "兵",
-    #       64 => "炮",
-    #       70 => "炮",
-    #       81 => "俥",
-    #       82 => "傌",
-    #       83 => "相",
-    #       84 => "仕",
-    #       85 => "帥",
-    #       86 => "仕",
-    #       87 => "相",
-    #       88 => "傌",
-    #       89 => "俥"
-    #     }
-    #   ).to_s # => "車馬象士將士象馬車/9/1砲5砲1/卒1卒1卒1卒1卒/9/9/兵1兵1兵1兵1兵/1炮5炮1/9/俥傌相仕帥仕相傌俥"
-    class PiecePlacement
-      # @param indexes [Array] The shape of the board.
-      # @param piece_placement [Hash] The index of each piece on the board.
-      def initialize(indexes, piece_placement = {})
-        @indexes = indexes
-        @squares = ::Array.new(length) { |i| piece_placement.fetch(i, nil) }
+    module PiecePlacement
+      # Converts a piece placement structure to a FEEN-compliant string
+      #
+      # @param piece_placement [Array] Hierarchical array representing the board where:
+      #   - Empty squares are represented by empty strings ("")
+      #   - Pieces are represented by strings (e.g., "r", "K=", "+P")
+      #   - Dimensions are represented by nested arrays
+      # @return [String] FEEN piece placement string
+      # @raise [ArgumentError] If the piece placement structure is invalid
+      def self.dump(piece_placement)
+        # Détecter la forme du tableau directement à partir de la structure
+        detect_shape(piece_placement)
+
+        # Formater directement la structure en chaîne FEEN
+        format_placement(piece_placement)
+      end
+
+      # Detects the shape of the board based on the piece_placement structure
+      #
+      # @param piece_placement [Array] Hierarchical array structure representing the board
+      # @return [Array<Integer>] Array of dimension sizes
+      # @raise [ArgumentError] If the piece_placement structure is invalid
+      def self.detect_shape(piece_placement)
+        return [] if piece_placement.empty?
+
+        dimensions = []
+        current = piece_placement
+
+        # Traverse the structure to determine shape
+        while current.is_a?(Array) && !current.empty?
+          dimensions << current.size
+
+          # Check if all elements at this level have the same structure
+          validate_dimension_uniformity(current)
+
+          # Check if we've reached the leaf level (array of strings)
+          break if current.first.is_a?(String) ||
+                   (current.first.is_a?(Array) && current.first.empty?)
+
+          current = current.first
+        end
+
+        dimensions
       end
 
-      # @return [String] The string representing the board.
-      def to_s
-        unflatten(@squares, @indexes)
+      # Validates that all elements in a dimension have the same structure
+      #
+      # @param dimension [Array] Array of elements at a particular dimension level
+      # @raise [ArgumentError] If elements have inconsistent structure
+      def self.validate_dimension_uniformity(dimension)
+        return if dimension.empty?
+
+        first_type = dimension.first.class
+        first_size = dimension.first.is_a?(Array) ? dimension.first.size : nil
+
+        dimension.each do |element|
+          unless element.class == first_type
+            raise ArgumentError, "Inconsistent element types in dimension: #{first_type} vs #{element.class}"
+          end
+
+          if element.is_a?(Array) && element.size != first_size
+            raise ArgumentError, "Inconsistent dimension sizes: expected #{first_size}, got #{element.size}"
+          end
+        end
       end
 
-      private
+      # Formats the piece placement structure into a FEEN string
+      #
+      # @param placement [Array] Piece placement structure
+      # @return [String] FEEN piece placement string
+      def self.format_placement(placement)
+        # For 1D arrays (ranks), format directly
+        if !placement.is_a?(Array) ||
+           (placement.is_a?(Array) && (placement.empty? || !placement.first.is_a?(Array)))
+          return format_rank(placement)
+        end
 
-      def length
-        @indexes.inject(:*)
+        # For 2D+ arrays, format each sub-element and join with appropriate separator
+        depth = calculate_depth(placement) - 1
+        separator = "/" * depth
+
+        # Important: Ne pas inverser le tableau - nous voulons maintenir l'ordre original
+        elements = placement
+        elements.map { |element| format_placement(element) }.join(separator)
       end
 
-      def unflatten(squares, remaining_indexes)
-        return row(squares) if remaining_indexes.length == 1
+      # Formats a rank (1D array of cells)
+      #
+      # @param rank [Array] 1D array of cells
+      # @return [String] FEEN rank string
+      def self.format_rank(rank)
+        return "" if !rank.is_a?(Array) || rank.empty?
+
+        result = ""
+        empty_count = 0
 
-        squares
-          .each_slice(squares.length / remaining_indexes.fetch(0))
-          .to_a
-          .map { |sub_squares| unflatten(sub_squares, remaining_indexes[1..]) }
-          .join("/" * remaining_indexes.length.pred)
+        rank.each do |cell|
+          if cell.empty?
+            empty_count += 1
+          else
+            # Add accumulated empty squares
+            result += empty_count.to_s if empty_count > 0
+            empty_count = 0
+
+            # Add the piece
+            result += cell
+          end
+        end
+
+        # Add any trailing empty squares
+        result += empty_count.to_s if empty_count > 0
+
+        result
       end
 
-      def row(squares)
-        squares
-          .map { |square| square.nil? ? 1 : square }
-          .join(",")
-          .gsub(/1,[1,]*1/) { |str| str.split(",").length }
-          .delete(",")
+      # Calculates the depth of a nested structure
+      #
+      # @param structure [Array] Structure to analyze
+      # @return [Integer] Depth of the structure
+      def self.calculate_depth(structure)
+        return 0 unless structure.is_a?(Array) && !structure.empty?
+
+        if structure.first.is_a?(Array)
+          1 + calculate_depth(structure.first)
+        else
+          1
+        end
       end
     end
   end

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

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Feen
+  module Dumper
+    module PiecesInHand
+      Errors = {
+        invalid_type:   "Piece at index: %<index>s must be a String, got type: %<type>s",
+        invalid_format: "Piece at index: %<index>s has an invalid format: '%<value>s'"
+      }.freeze
+    end
+  end
+end

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

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module Feen
+  module Dumper
+    module PiecesInHand
+      # Character used to represent no pieces in hand
+      NoPieces = "-"
+    end
+  end
+end

data/lib/feen/dumper/pieces_in_hand.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+require_relative File.join("pieces_in_hand", "no_pieces")
+require_relative File.join("pieces_in_hand", "errors")
+
+module Feen
+  module Dumper
+    # Handles conversion of pieces in hand data to FEEN notation string
+    module PiecesInHand
+      # Converts an array of piece identifiers to a FEEN-formatted pieces in hand string
+      #
+      # @param piece_chars [Array<String>] Array of single-character piece identifiers
+      # @return [String] FEEN-formatted pieces in hand string
+      # @raise [ArgumentError] If any piece identifier is invalid
+      # @example
+      #   PiecesInHand.dump("P", "p", "B")
+      #   # => "BPp"
+      #
+      #   PiecesInHand.dump
+      #   # => "-"
+      def self.dump(*piece_chars)
+        # If no pieces in hand, return the standardized empty indicator
+        return NoPieces if piece_chars.empty?
+
+        # Validate each piece character according to the FEEN specification
+        validated_chars = validate_piece_chars(piece_chars)
+
+        # Sort pieces in ASCII lexicographic order and join them
+        validated_chars.sort.join
+      end
+
+      # Validates all piece characters according to FEEN specification
+      #
+      # @param piece_chars [Array<Object>] Array of piece character candidates
+      # @return [Array<String>] Array of validated piece characters
+      # @raise [ArgumentError] If any piece character is invalid
+      private_class_method def self.validate_piece_chars(piece_chars)
+        piece_chars.each_with_index.map do |char, index|
+          validate_piece_char(char, index)
+        end
+      end
+
+      # Validates a single piece character according to FEEN specification
+      #
+      # @param char [Object] Piece character candidate
+      # @param index [Integer] Index of the character in the original array
+      # @return [String] Validated piece character
+      # @raise [ArgumentError] If the piece character is invalid
+      private_class_method def self.validate_piece_char(char, index)
+        # Validate type
+        unless char.is_a?(::String)
+          raise ::ArgumentError, format(
+            Errors[:invalid_type],
+            index: index,
+            type:  char.class
+          )
+        end
+
+        # Validate format (single alphabetic character)
+        unless char.match?(/\A[a-zA-Z]\z/)
+          raise ::ArgumentError, format(
+            Errors[:invalid_format],
+            index: index,
+            value: char
+          )
+        end
+
+        char
+      end
+    end
+  end
+end