feen 5.0.0.beta1 → 5.0.0.beta2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2fa56bccbb1911f15569f2f5643646986cbf83661efba3165c69978e7c85fd56
-  data.tar.gz: 13d706d1bfe1c09f6d015d0a8f28af621754677711074ec60ec96e395f1a1061
+  metadata.gz: 3dbd219b5b2e7870e60da133faae1f342179e35682590d2f5fbe06c4f0130d39
+  data.tar.gz: c1042208ec1799d5700e87327bafaa39dc918b5e101304c9b90a67e22be76c25
 SHA512:
-  metadata.gz: 5479cbd02c902aa8c45cc12ecfab31c7b7283eb1f8ec60b110c889505a7ebbcf76fa7b0d2e6ad44c60da954312fa85ae03cd4981d929207b0612754f1d62a033
-  data.tar.gz: b6268ce619808bf2c2f889261b55007edbfc030bc37b8edea7f73f505de55e8c0fc1cd4a268e8e2bdc71fe21c9fa33f904c8b26a23b92b471e406e109494bd97
+  metadata.gz: e8480101aa872bba2295a2ee74d47f4bde63a7d94c50b6504e8acadbf8347ee5a136bc962b65fdbb75aed3dd887693b6b012b53aed77c4e101313fd2189c59d5
+  data.tar.gz: fde52d865df00f7602017789aeb9d6520b809be88fad13a14215f289abcc60f61d88ae73624cf01fd3a158aa62a94b98814bb0a1aff510b2e218833fb59094d9

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

@@ -6,81 +6,186 @@
 [![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)
 [![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** (Forsyth–Edwards Essential 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 (Forsyth–Edwards Essential 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:
+- Multiple game types (chess, shogi, xiangqi, etc.)
+- Hybrid or cross-game positions
+- Arbitrary-dimensional boards
+- Pieces in hand (as used in Shogi)
 
-Add this line to your application's Gemfile:
+## Installation
 
 ```ruby
-gem "feen", ">= 5.0.0.beta1"
+# In your Gemfile
+gem "feen", ">= 5.0.0.beta2"
 ```
 
-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> <GAMES-TURN> <PIECES-IN-HAND>
+```
+
+## Basic Usage
+
+### Parsing FEEN Strings
+
+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 -"
+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
+```
+
+### Creating FEEN Strings
+
+Convert a position structure to a FEEN string:
+
+```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"
+  },
+  pieces_in_hand:  []
+}
+
+Feen.dump(position)
+# => "rnbqk=bnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQK=BNR CHESS/chess -"
 ```
 
-## Usage
+### Validation
 
-### Serialization
+Check if a string is valid FEEN notation:
 
-A position can be serialized by filling in these fields:
+```ruby
+require "feen"
+
+Feen.valid?("rnbqk=bnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQK=BNR CHESS/chess -")
+# => true
+
+Feen.valid?("invalid feen string")
+# => false
+```
+
+## FEN Compatibility
 
-- **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.
+### Converting FEN to FEEN
 
-#### Example
+```ruby
+require "feen"
+
+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 -"
+```
 
-From a classic Tsume Shogi problem:
+### Converting FEEN to FEN
 
 ```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"
-  }
-)
-# => "3sks3/9/4+P4/9/7+B1/9/9/9/9 s"
+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"
 ```
 
-### Deserialization
+> ⚠️ `Feen.to_fen` only supports FEEN positions where `games_turn` is `CHESS/chess` or `chess/CHESS`.
+
+## 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
+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" }]
+    ]
+  ],
+  games_turn:      {
+    active_player:   "CHESS",
+    inactive_player: "chess"
+  },
+  pieces_in_hand:  []
+}
+
+Feen.dump(position)
+# => "rnb/qkp//PR1/1KQ CHESS/chess -"
 ```
 
+### Piece Modifiers
+
+FEEN supports prefixes and suffixes for pieces:
+
+- 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)
+
+### Sanitizing FEN Strings
+
+FEEN includes utilities to clean FEN strings by validating and removing invalid castling rights and en passant targets:
+
+```ruby
+require "feen"
+
+# 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"
+```
+
+## Documentation
+
+- [Official FEEN Specification v1.0.0](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 is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
 
 ## About Sashité
 

data/lib/feen/converter/from_fen.rb

@@ -0,0 +1,170 @@
+# frozen_string_literal: true
+
+module Feen
+  module Converter
+    module FromFen
+      # Constants
+      WHITE_TURN = "CHESS/chess"
+      BLACK_TURN = "chess/CHESS"
+      NO_PIECES_IN_HAND = "-"
+      EN_PASSANT_NONE = "-"
+
+      # Castling-related constants
+      CASTLING_SUFFIX_BOTH = "="
+      CASTLING_SUFFIX_KINGSIDE = ">"
+      CASTLING_SUFFIX_QUEENSIDE = "<"
+      CASTLING_SUFFIX_NONE = ""
+
+      # Piece identifiers
+      WHITE_KING = "K"
+      BLACK_KING = "k"
+      WHITE_PAWN = "P"
+      BLACK_PAWN = "p"
+
+      # Board indices
+      WHITE_KING_STARTING_ROW = 7
+      BLACK_KING_STARTING_ROW = 0
+
+      # Converts a FEN string to a FEEN string for chess positions
+      # @param fen_string [String] Standard FEN notation string for chess
+      # @return [String] Equivalent FEEN notation string
+      # @raise [ArgumentError] If the FEN string is invalid
+      def self.call(fen_string)
+        unless fen_string.is_a?(String) && !fen_string.strip.empty?
+          raise ArgumentError, "FEN must be a non-empty string"
+        end
+
+        parts = fen_string.strip.split
+        raise ArgumentError, "Invalid FEN format: expected at least 4 fields" unless parts.size >= 4
+
+        placement_fen, active_color, castling, en_passant = parts[0..3]
+        board = parse_board(placement_fen)
+
+        apply_castling!(board, castling)
+        apply_en_passant!(board, en_passant)
+
+        piece_placement = format_board(board)
+        games_turn = active_color == "w" ? WHITE_TURN : BLACK_TURN
+
+        "#{piece_placement} #{games_turn} #{NO_PIECES_IN_HAND}"
+      end
+
+      # Parses the FEN piece placement into a 2D board array
+      # @param fen_placement [String] FEN piece placement string
+      # @return [Array<Array<String, nil>>] 2D array representing the board
+      def self.parse_board(fen_placement)
+        fen_placement.split("/").map do |row|
+          cells = []
+          row.each_char do |char|
+            if /[1-8]/.match?(char)
+              cells.concat([nil] * char.to_i)
+            else
+              cells << char
+            end
+          end
+          cells
+        end
+      end
+
+      # Applies castling rights to kings on the board
+      # @param board [Array<Array<String, nil>>] 2D board array
+      # @param castling [String] FEN castling rights string
+      # @return [void]
+      def self.apply_castling!(board, castling)
+        return if castling == EN_PASSANT_NONE
+
+        # Determine suffix for each king
+        wk_suffix = determine_castling_suffix(castling.include?("K"), castling.include?("Q"))
+        bk_suffix = determine_castling_suffix(castling.include?("k"), castling.include?("q"))
+
+        # Apply the suffixes to the kings
+        apply_king_suffix!(board, WHITE_KING, wk_suffix)
+        apply_king_suffix!(board, BLACK_KING, bk_suffix)
+      end
+
+      # Applies a castling suffix to a king on the board
+      # @param board [Array<Array<String, nil>>] 2D board array
+      # @param king_char [String] King character ('K' or 'k')
+      # @param suffix [String] Castling suffix to apply
+      # @return [void]
+      def self.apply_king_suffix!(board, king_char, suffix)
+        return if suffix.empty?
+
+        board.each_with_index do |row, r|
+          row.each_with_index do |cell, c|
+            board[r][c] = "#{king_char}#{suffix}" if cell == king_char
+          end
+        end
+      end
+
+      # Determines the appropriate castling suffix based on kingside and queenside rights
+      # @param kingside [Boolean] Whether kingside castling is allowed
+      # @param queenside [Boolean] Whether queenside castling is allowed
+      # @return [String] The castling suffix
+      def self.determine_castling_suffix(kingside, queenside)
+        if kingside && queenside
+          CASTLING_SUFFIX_BOTH
+        elsif kingside
+          CASTLING_SUFFIX_KINGSIDE
+        elsif queenside
+          CASTLING_SUFFIX_QUEENSIDE
+        else
+          CASTLING_SUFFIX_NONE
+        end
+      end
+
+      # Applies en passant rights to pawns on the board
+      # @param board [Array<Array<String, nil>>] 2D board array
+      # @param en_passant [String] FEN en passant target square
+      # @return [void]
+      def self.apply_en_passant!(board, en_passant)
+        return if en_passant == EN_PASSANT_NONE
+
+        col = en_passant[0].ord - "a".ord
+        row = 8 - en_passant[1].to_i
+
+        if row == 2 # White just moved: check black pawns on row 3
+          apply_en_passant_for_pawn!(board, 3, col, BLACK_PAWN)
+        elsif row == 5 # Black just moved: check white pawns on row 4
+          apply_en_passant_for_pawn!(board, 4, col, WHITE_PAWN)
+        end
+      end
+
+      # Applies en passant rights to pawns at a specific row and column
+      # @param board [Array<Array<String, nil>>] 2D board array
+      # @param pawn_row [Integer] Row where pawns can capture en passant
+      # @param target_col [Integer] Column of the pawn that moved two squares
+      # @param pawn_char [String] Pawn character ('P' or 'p')
+      # @return [void]
+      def self.apply_en_passant_for_pawn!(board, pawn_row, target_col, pawn_char)
+        [-1, 1].each do |dx|
+          x = target_col + dx
+
+          next unless x.between?(0, 7) && board[pawn_row][x] == pawn_char
+
+          # Determine the en passant suffix based on relative position
+          suffix = dx == -1 ? ">" : "<"
+          board[pawn_row][x] = "#{pawn_char}#{suffix}"
+        end
+      end
+
+      # Formats the board array back into FEN piece placement
+      # @param board [Array<Array<String, nil>>] 2D board array
+      # @return [String] FEN piece placement string
+      def self.format_board(board)
+        board.map do |row|
+          format_row(row)
+        end.join("/")
+      end
+
+      # Formats a row of the board into FEN notation
+      # @param row [Array<String, nil>] Row of the board
+      # @return [String] FEN notation for this row
+      def self.format_row(row)
+        row.chunk_while { |a, b| a.nil? == b.nil? }.map do |chunk|
+          chunk.first.nil? ? chunk.size.to_s : chunk.join
+        end.join
+      end
+    end
+  end
+end

data/lib/feen/converter/to_fen.rb

@@ -0,0 +1,153 @@
+# frozen_string_literal: true
+
+module Feen
+  module Converter
+    module ToFen
+      # Constants for game types and formats
+      WHITE_ACTIVE = "CHESS/chess"
+      BLACK_ACTIVE = "chess/CHESS"
+
+      # Constants for FEN components
+      NO_EN_PASSANT = "-"
+      NO_CASTLING = "-"
+      HALF_MOVE_DEFAULT = "0"
+      FULL_MOVE_DEFAULT = "1"
+
+      # Castling-related constants
+      WHITE_KINGSIDE = "K"
+      WHITE_QUEENSIDE = "Q"
+      BLACK_KINGSIDE = "k"
+      BLACK_QUEENSIDE = "q"
+
+      # En passant constants
+      EN_PASSANT_WHITE_RANK = "3"
+      EN_PASSANT_BLACK_RANK = "6"
+
+      # Converts a FEEN string to a standard FEN string for chess positions
+      # @param feen_string [String] FEEN notation string
+      # @return [String] Standard FEN notation string
+      # @raise [ArgumentError] If the FEEN string is invalid or not supported
+      def self.call(feen_string)
+        # Validate input
+        unless feen_string.is_a?(String) && !feen_string.strip.empty?
+          raise ArgumentError, "FEEN must be a non-empty string"
+        end
+
+        # Split into components
+        parts = feen_string.strip.split
+        raise ArgumentError, "Invalid FEEN format: expected 3 fields" unless parts.size == 3
+
+        piece_placement, games_turn, = parts
+
+        # Verify game type is supported
+        unless [WHITE_ACTIVE, BLACK_ACTIVE].include?(games_turn)
+          raise ArgumentError, "Only CHESS/chess FEEN formats are supported"
+        end
+
+        # Extract FEN components
+        castling_rights = extract_castling_rights(piece_placement)
+        en_passant = extract_en_passant(piece_placement)
+        fen_board = convert_board_to_fen(piece_placement)
+        active_color = games_turn.start_with?("CHESS") ? "w" : "b"
+
+        # Construct FEN string
+        "#{fen_board} #{active_color} #{castling_rights} #{en_passant} #{HALF_MOVE_DEFAULT} #{FULL_MOVE_DEFAULT}"
+      end
+
+      # Converts the FEEN board representation to FEN format by removing special markings
+      # @param piece_placement [String] FEEN piece placement string
+      # @return [String] FEN piece placement string
+      def self.convert_board_to_fen(piece_placement)
+        piece_placement.split("/").map do |row|
+          # Remove castling suffixes from kings
+          row_without_king_suffix = row.gsub(/([Kk])([=<>])/) { Regexp.last_match(1) }
+          # Remove en passant suffixes from pawns
+          row_without_suffixes = row_without_king_suffix.gsub(/([Pp])([<>])/) { Regexp.last_match(1) }
+          # Ensure only single character pieces (in case of promoted pieces with prefixes)
+          row_without_suffixes.gsub(/\d+|\w/) { |s| /\d/.match?(s) ? s : s[0] }
+        end.join("/")
+      end
+
+      # Extracts castling rights from FEEN piece placement
+      # @param piece_placement [String] FEEN piece placement string
+      # @return [String] FEN castling rights component
+      def self.extract_castling_rights(piece_placement)
+        castling = ""
+
+        # White castling rights - always in uppercase and first
+        piece_placement.split("/").each do |row|
+          castling += WHITE_KINGSIDE if row.include?("K>") || row.include?("K=")
+          castling += WHITE_QUEENSIDE if row.include?("K<") || row.include?("K=")
+        end
+
+        # Black castling rights - always in lowercase and after white
+        piece_placement.split("/").each do |row|
+          castling += BLACK_KINGSIDE if row.include?("k>") || row.include?("k=")
+          castling += BLACK_QUEENSIDE if row.include?("k<") || row.include?("k=")
+        end
+
+        castling.empty? ? NO_CASTLING : castling
+      end
+
+      # Extracts en passant target square from FEEN piece placement
+      # @param piece_placement [String] FEEN piece placement string
+      # @return [String] FEN en passant target square or "-" if none
+      # @raise [ArgumentError] If multiple en passant markers are detected
+      def self.extract_en_passant(piece_placement)
+        rows = piece_placement.split("/")
+        en_passant_targets = []
+
+        rows.each_with_index do |row, _rank|
+          file_index = 0
+          char_index = 0
+
+          while char_index < row.length
+            current_char = row[char_index]
+
+            if /[1-8]/.match?(current_char)
+              # Skip empty squares
+              file_index += current_char.to_i
+              char_index += 1
+            elsif char_index + 1 < row.length && row[char_index..(char_index + 1)] =~ /([Pp])([<>])/
+              # Found a pawn with en passant marker
+              pawn_type = ::Regexp.last_match(1) # 'P' or 'p'
+              ::Regexp.last_match(2) # '<' or '>'
+
+              # Calculate the file (column) letter
+              file_char = ("a".ord + file_index).chr
+
+              # Calculate the rank (row) number based on pawn type
+              # For white pawn (P) on rank 4 (index 3), the target is rank 3
+              # For black pawn (p) on rank 5 (index 2), the target is rank 6
+              rank_num = if pawn_type == "P"
+                           "3" # White pawn's en passant target is always on rank 3
+                         else
+                           "6" # Black pawn's en passant target is always on rank 6
+                         end
+
+              en_passant_targets << "#{file_char}#{rank_num}"
+
+              # Move past this pawn and its suffix
+              file_index += 1
+              char_index += 2
+            else
+              # Regular piece
+              file_index += 1
+              char_index += 1
+
+              # Skip any suffix attached to this piece
+              char_index += 1 if char_index < row.length && row[char_index] =~ /[<>=]/
+            end
+          end
+        end
+
+        # Only one en passant target should be present in a valid position
+        if en_passant_targets.size > 1
+          raise ArgumentError, "Multiple en passant markers detected: #{en_passant_targets.join(', ')}"
+        end
+
+        en_passant_targets.first || "-"
+      end
+    end
+  end
+end

data/lib/feen/converter.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require_relative File.join("converter", "from_fen")
+require_relative File.join("converter", "to_fen")
+
+module Feen
+  module Converter
+    def self.from_fen(fen_string)
+      FromFen.call(fen_string)
+    end
+
+    def self.to_fen(feen_string)
+      ToFen.call(feen_string)
+    end
+  end
+end

data/lib/feen/dumper/games_turn.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module Feen
+  module Dumper
+    # Handles conversion of games turn data structure 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)"
+      }.freeze
+
+      REQUIRED_KEYS = %i[active_player inactive_player].freeze
+
+      # Converts the internal games turn representation to a FEEN string
+      #
+      # @param games_turn [Hash] Hash containing game turn information
+      # @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
+      end
+
+      # Validates the basic structure of games_turn
+      #
+      # @param games_turn [Hash] The games turn data to validate
+      # @raise [ArgumentError] If the structure is 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?
+        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]/)
+
+        # Ensure exactly one has uppercase
+        raise ArgumentError, ERRORS[:casing_requirement] if active_has_uppercase == inactive_has_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]}"
+        end
+
+        return unless inactive_has_uppercase && games_turn[:inactive_player].match?(/[a-z]/)
+
+        raise ArgumentError, "Inactive game has mixed case: #{games_turn[:inactive_player]}"
+      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/)
+        end
+      end
+    end
+  end
+end