chess_cli 0.9.2

data/lib/console_game/chess/utilities/chess_utils.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module ConsoleGame
+  module Chess
+    # ChessUtils is a module that provides shared logics that's used across multiple classes in chess.
+    # @author Ancient Nimbus
+    module ChessUtils
+      # Algebraic chess notation to positional value hash
+      ALG_MAP = [*"a".."h"].each_with_index.flat_map do |file, col|
+        [*"#{file}1".."#{file}8"].map.with_index { |alg, row| [alg.to_sym, row * 8 + col] }
+      end.to_h.freeze
+
+      # Chess Piece notations reference
+      ALG_REF = {
+        k: { class: "King", notation: :k }, q: { class: "Queen", notation: :q }, r: { class: "Rook", notation: :r },
+        b: { class: "Bishop", notation: :b }, n: { class: "Knight", notation: :n }, p: { class: "Pawn", notation: :p }
+      }.freeze
+
+      # Default symbol for white and black
+      SIDES_SYM = %i[white black].freeze
+
+      # Preferred time format
+      STR_TIME = "%m/%d/%Y %I:%M %p"
+
+      # == Algebraic natation ==
+
+      # Call the algebraic chess notation to positional value reference hash
+      # @return [Hash<Integer>]
+      def alg_map = ALG_MAP
+
+      # Convert positional value to Algebraic notation string
+      # @param pos [Integer]
+      # @param filter [Symbol] :f to return file value only and :r to return rank value only
+      # @return [String]
+      def to_alg_pos(pos, filter = :none)
+        alg_pos = alg_map.key(pos).to_s
+        case filter
+        when :f then alg_pos[0]
+        when :r then alg_pos[1]
+        else alg_pos
+        end
+      end
+
+      # Fetch positional value from Algebraic notation string or symbol
+      # @param alg_pos [String, Symbol] expects notation e.g., `"e4"` or `:e4`
+      # @return [Integer] 1D board positional value
+      def to_1d_pos(alg_pos) = alg_map.fetch((alg_pos.is_a?(Symbol) ? alg_pos : alg_pos.to_sym))
+
+      # == Board logics ==
+
+      # Returns white as symbol
+      def w_sym = SIDES_SYM[0]
+
+      # Returns black as symbol
+      def b_sym = SIDES_SYM[1]
+
+      # Flip-flop, return :black if it is :white
+      # @param side [Symbol] expects argument to be :black or :white
+      # @return [Symbol, nil] :black or :white
+      def opposite_of(side)
+        return nil unless SIDES_SYM.include?(side)
+
+        side == w_sym ? b_sym : w_sym
+      end
+    end
+  end
+end

data/lib/console_game/chess/utilities/fen_export.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+require_relative "chess_utils"
+
+module ConsoleGame
+  module Chess
+    # FenExport is a class that performs FEN data export operations.
+    # It is compatible with most online chess site, and machine readable.
+    # @author Ancient Nimbus
+    # @version v1.1.0
+    class FenExport
+      include ChessUtils
+
+      # FEN Export method entry point
+      # @return [String]
+      def self.to_fen(...) = new(...).to_fen
+
+      # @!attribute [r] turn_data
+      #   @return [Array<ChessPiece, String>] complete state of the current turn
+      # @!attribute [r] white_turn
+      #   @return [Boolean]
+      # @!attribute [r] castling_states
+      #   @return [Hash]
+      # @!attribute [r] en_passant
+      #   @return [Hash]
+      # @!attribute [r] half_move
+      #   @return [Integer]
+      # @!attribute [r] full_move
+      #   @return [Integer]
+      attr_reader :turn_data, :white_turn, :castling_states, :en_passant, :half_move, :full_move
+
+      # @param level [Level] expects a Chess::Level class object
+      def initialize(level)
+        @level = level
+        @turn_data = level.turn_data
+        @white_turn = level.white_turn
+        @castling_states = level.castling_states
+        @en_passant = level.en_passant
+        @half_move = level.half_move
+        @full_move = level.full_move
+      end
+
+      # == FEN Export ==
+
+      # FEN core export method
+      # Transform internal turn data to FEN string
+      # @return [String]
+      def to_fen
+        [to_turn_data, to_active_color, to_castling_states, to_en_passant, half_move.to_s, full_move.to_s].join(" ")
+      end
+
+      private
+
+      # Convert internal turn data to string
+      # @return [String] FEN position placements as string
+      def to_turn_data
+        str_arr = []
+        turn_data.each_slice(8) do |row|
+          compressed_row = compress_row_str(row_data_to_str(row))
+          str_arr << compressed_row.join("")
+        end
+        str_arr.join("/").reverse
+      end
+
+      # Helper: Convert row data to string
+      # @param row [Array<ChessPiece>]
+      # @return [Array<String>]
+      def row_data_to_str(row)
+        row.map do |tile|
+          next "0" unless tile.is_a?(ChessPiece)
+
+          tile.side == w_sym ? tile.notation : tile.notation.downcase
+        end
+      end
+
+      # Helper: Compress empty tile
+      # @param row_str_arr [Array<String>]
+      # @param count [Integer]
+      # @param compressed_row [Array<String>]
+      # @return [Array<String>]
+      def compress_row_str(row_str_arr, count: 0, compressed_row: [])
+        row_str_arr.reverse_each do |elem|
+          if elem == "0"
+            count += 1
+          else
+            compressed_row.push(count.to_s) if count.positive?
+            compressed_row.push(elem)
+            count = 0
+          end
+        end
+        compressed_row.tap { |arr| arr.push(count.to_s) if count.positive? }
+      end
+
+      # Convert internal white_turn to FEN active colour field
+      # @return [String]
+      def to_active_color = white_turn ? "w" : "b"
+
+      # Convert castling states to FEN castling status field
+      # @return [String]
+      def to_castling_states
+        str = castling_states.reject { |_, v| v == false }.keys.map(&:to_s).join("")
+        str.empty? ? "-" : str
+      end
+
+      # Convert en passant states to FEN en passant field
+      # @return [String]
+      def to_en_passant
+        value = en_passant.nil? ? "-" : en_passant.fetch(-1)
+        value = to_alg_pos(value) if value.is_a?(Integer)
+        value
+      end
+    end
+  end
+end

data/lib/console_game/chess/utilities/fen_import.rb

@@ -0,0 +1,196 @@
+# frozen_string_literal: true
+
+require_relative "chess_utils"
+
+module ConsoleGame
+  module Chess
+    # FenImport is a class that performs FEN data parsing operations.
+    # It is compatible with most online chess site, and machine readable.
+    # @author Ancient Nimbus
+    # @version v1.3.0
+    class FenImport
+      include ChessUtils
+      # FEN default values
+      FEN = { w_start: "rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1" }.merge(ALG_REF).freeze
+
+      # Pieces limits
+      LIMITS = { "k" => 1, "q" => 9, "b" => 10, "n" => 10, "r" => 10, "p" => 8 }.freeze
+
+      # Basic parse pattern
+      FEN_PATTERN = /\A[kqrbnp1-8]+\z/i
+
+      # FEN Raw data parser (FEN import)
+      # @return [Hash<Hash>] FEN data hash for internal use
+      def self.parse_fen(...) = new(...).parse_fen
+
+      # @!attribute [r] level
+      #   @return [Level] chess Level object
+      # @!attribute [r] fen_str
+      #   @return [String] a complete FEN string
+      attr_reader :level, :fen_str
+      attr_accessor :turn_data
+
+      # @param level [Level] expects chess Level object
+      # @param fen_import [String, nil] expects a complete FEN string
+      def initialize(level, fen_import = nil)
+        @level = level
+        @fen_str = fen_import.nil? ? FEN[:w_start] : fen_import
+        @turn_data = Array.new(8) { [] }
+      end
+
+      # == FEN Import ==
+
+      # FEN Raw data parser (FEN import)
+      # @return [Hash<Hash>] FEN data hash for internal use
+      def parse_fen
+        fen = fen_str&.split
+        return fen_error if fen.nil? || fen.size != 6
+
+        fen_data = process_fen_data(fen)
+        return fen_error if fen_data.any?(&:nil?)
+
+        board_data, active_player, castling, en_passant, h_move, f_move = fen_data
+        { **board_data, **active_player, **castling, **en_passant, **h_move, **f_move }
+      end
+
+      private
+
+      # Helper: Batch process FEN parsing operations
+      # @param fen_data [Array<String>] expects splitted FEN as an array
+      # @return [Array<Hash, nil>]
+      def process_fen_data(fen_data)
+        fen_board, active_color, c_state, ep_state, half_move, full_move = fen_data
+        [
+          parse_piece_placement(fen_board), parse_active_color(active_color), parse_castling_str(c_state),
+          parse_en_passant(ep_state), parse_move_num(half_move, :half_move), parse_move_num(full_move, :full_move)
+        ]
+      end
+
+      # Process flow when there is an issue during FEN parsing
+      # @param err_msg [String] error message during FEN error
+      def fen_error(err_msg: "FEN error, '#{fen_str}' is not a valid sequence. Starting a new game...")
+        level.loading_msg(err_msg, time: 3)
+        self.class.parse_fen(level)
+      end
+
+      # Process FEN board data field
+      # @param fen_board [String] expects an Array with FEN positions data
+      # @return [Hash<Array<ChessPiece, String>>, nil] chess position data starts from a1..h8
+      def parse_piece_placement(fen_board)
+        return nil unless good_fen?(fen_board)
+
+        pos_value = 0
+        fen_board.split("/").reverse.each_with_index do |rank, row|
+          return nil unless valid_row?(rank, row)
+
+          normalise_fen_rank(rank).each_with_index do |unit, col|
+            turn_data[row][col] = /\A\d\z/.match?(unit) ? "" : piece_maker(pos_value, unit)
+            pos_value += 1
+          end
+        end
+        @board_data = { turn_data: turn_data.flatten }
+      end
+
+      # FEN board acceptance checks
+      # @return [Boolean] true if there is one key on each side and not too many pieces.
+      def good_fen?(...) = one_king_only?(...) && !too_many_pieces?(...)
+
+      # Counting checks for the rest of the pieces
+      # @param fen_board [String] expects an Array with FEN positions data
+      # @return [Boolean]
+      def too_many_pieces?(fen_board)
+        allies = LIMITS.keys[1..].join("")
+        all_pieces = allies + allies.upcase
+        return true if fen_board.count(all_pieces) > 30
+
+        all_pieces.split("").any? { |ally| fen_board.count(ally) > LIMITS[ally.downcase] }
+      end
+
+      # Counting checks for the king (Lazy evaluation)
+      # Main criteria: One K and one k
+      # @param fen_board [String] expects an Array with FEN positions data
+      # @return [Boolean]
+      def one_king_only?(fen_board) = fen_board.count("K") == LIMITS["k"] && fen_board.count("k") == LIMITS["k"]
+
+      # Row acceptance check
+      # @return [Boolean]
+      def valid_row?(...) = no_pawn_in_back_row?(...) && valid_characters?(...)
+
+      # Pattern matching checks for FEN string
+      # @param rank [String]
+      # @return [Boolean]
+      def valid_characters?(rank, _row) = rank.match?(FEN_PATTERN)
+
+      # Acceptance checks for the first row and last row (Lazy evaluation)
+      # Main criteria: No black pawn in rank 8 and no white pawn in rank 1
+      # @param rank [String]
+      # @param row [Integer]
+      # @return [Boolean]
+      def no_pawn_in_back_row?(rank, row) = [*1..6].include?(row) || rank.count(row.zero? ? "P" : "p").zero?
+
+      # Process the active colour field
+      # @param color [String]
+      # @return [Hash<Boolean>, nil]
+      def parse_active_color(color) = %w[b w].include?(color) ? { white_turn: color == "w" } : nil
+
+      # Process FEN castling field
+      # @param c_state [String] expects a string with castling data
+      # @return [Hash<Hash<Boolean>>, nil] a hash of castling statuses
+      def parse_castling_str(c_state)
+        castling_states = { K: false, Q: false, k: false, q: false }
+        return { castling_states: castling_states } if c_state.empty? || c_state == "-"
+
+        c_state.split("").each do |char|
+          char_as_sym = char.to_sym
+          return nil unless castling_states.key?(char_as_sym)
+
+          castling_states[char_as_sym] = true
+        end
+        { castling_states: castling_states }
+      end
+
+      # Process FEN En-passant target square field
+      # @param ep_state [String] expects a string with En-passant target square data
+      # @return [Hash, nil] a hash of En-passant status
+      def parse_en_passant(ep_state)
+        return nil unless ep_state.match?(/\A[a-h][36]|-\z/)
+
+        ep_pawn_rank = ep_state.include?("6") ? "5" : "4"
+        ep_pawn = "#{ep_state[0]}#{ep_pawn_rank}"
+
+        { en_passant: ep_state == "-" ? nil : [fetch_ep_pawn(ep_pawn), ep_ghost_pos(ep_state)] }
+      end
+
+      # En-passant helper: convert en passant pawn location to real pawn object
+      # @param alg_pos [String] expects algebraic notation
+      def fetch_ep_pawn(alg_pos) = @board_data[:turn_data].fetch(to_1d_pos(alg_pos))
+
+      # En-passant helper: convert ghost position to positional value
+      # @param alg_pos [String] expects algebraic notation
+      def ep_ghost_pos(alg_pos) = to_1d_pos(alg_pos)
+
+      # Process FEN Half-move clock or Full-move field
+      # @param num [String] expects a string with either half-move or full-move data
+      # @param type [Symbol] specify the key type for the hash
+      # @return [Hash, nil] a hash of either half-move or full-move data
+      def parse_move_num(num, type)
+        num.match?(/\A\d+\z/) && %i[half_move full_move].include?(type) ? { type => num.to_i } : nil
+      end
+
+      # Initialize chess piece via string value
+      # @param pos [Integer] positional value
+      # @param fen_notation [String] expects a single letter that follows the FEN standard
+      # @return [Chess::King, Chess::Queen, Chess::Bishop, Chess::Rook, Chess::Knight, Chess::Pawn]
+      def piece_maker(pos, fen_notation)
+        side = fen_notation == fen_notation.capitalize ? :white : :black
+        class_name = FEN[fen_notation.downcase.to_sym][:class]
+        Chess.const_get(class_name).new(pos, side, level:)
+      end
+
+      # Helper method to uncompress FEN empty cell values so that all arrays share the same size
+      # @param str [String]
+      # @return [Array] processed rank data array
+      def normalise_fen_rank(str) = str.split("").map { |c| c.sub(/\A\d\z/, "0" * c.to_i).split("") }.flatten
+    end
+  end
+end

data/lib/console_game/chess/utilities/load_manager.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require_relative "chess_utils"
+
+module ConsoleGame
+  module Chess
+    # The Load Manager class handles the session loading process of chess
+    # @author Ancient Nimbus
+    class LoadManager
+      include ChessUtils
+
+      # Select game session from list of sessions
+      # @return [Array]
+      def self.select_session(...) = new(...).select_session
+
+      attr_reader :game, :sessions, :controller
+
+      # @param game [Game] expects chess game manager object
+      def initialize(game)
+        @game = game
+        @sessions = game.sessions
+        @controller = game.controller
+      end
+
+      # Select game session from list of sessions
+      # @return [Array]
+      def select_session
+        user_opt = sessions.empty? ? game.new_game(err: true) : load_from_list
+        session = sessions[user_opt]
+        [user_opt, session]
+      end
+
+      private
+
+      # Load from list
+      # @return [Symbol, Integer]
+      def load_from_list
+        print_sessions_to_load
+        controller.pick_from(sessions.keys)
+      end
+
+      # Helper to print list of sessions to load
+      def print_sessions_to_load = game.print_msg(*game.build_table(data: sessions_list, head: game.s("load.f2a")))
+
+      # Build list of sessions to load
+      # This method select the event and date field within sessions, format the Date field and returns a list.
+      # @return [Hash] list of sessions
+      def sessions_list = sessions.transform_values { |session| session.select { |k, _| %i[event date].include?(k) } }
+    end
+  end
+end

data/lib/console_game/chess/utilities/pgn_export.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+require "time"
+require_relative "chess_utils"
+require_relative "pgn_utils"
+require_relative "../../../nimbus_file_utils/nimbus_file_utils"
+
+module ConsoleGame
+  module Chess
+    # PGN Export is a class that focuses on converting internal game data to PGN file standard
+    # @author Ancient Nimbus
+    class PgnExport
+      include ChessUtils
+      include ::PgnUtils
+      include ::NimbusFileUtils
+
+      # PGN Export method entry point
+      # @return [Hash]
+      def self.export_session(...) = new(...).export_session
+
+      # @!attribute [r] session
+      #   @return [Hash] game session data
+      attr_reader :session, :date, :sub_path, :filename, :path
+
+      # Alias for NimbusFileUtils
+      F = NimbusFileUtils
+
+      def initialize(session)
+        @date = session[:date]
+        @session = session.slice(*TAGS.keys, :moves)
+        @sub_path = %w[user_data pgn_export]
+      end
+
+      # Export session as pgn file
+      # @param session [Hash] expects a single chess session, invalid moves data will result operation being cancelled.
+      # @return [Hash]
+      def export_session
+        process_time_field
+        pgn_filepath
+        export_data = to_pgn
+        F.write_to_disk(path, export_data)
+        { path:, filename:, export_data: }
+      end
+
+      private
+
+      # Create file name and return full file path
+      def pgn_filepath
+        name = build_name
+        begin
+          make_filename(name)
+          make_filepath
+          append_file_num(name)
+        rescue ArgumentError
+          name = handle_filename_err
+          retry
+        end
+      end
+
+      # Format filename
+      # @param name [String]
+      def make_filename(name) = @filename = F.formatted_filename(name, DOT_PGN)
+
+      # Format filepath
+      def make_filepath = @path = F.filepath(filename, *sub_path)
+
+      # Append number suffix if file exist
+      # @param name [String]
+      def append_file_num(name)
+        count = 0
+        while F.file_exist?(path, use_filetype: false)
+          count += 1
+          make_filename("#{name}_#{count}")
+          make_filepath
+        end
+      end
+
+      # Error handling when forbidden character is found in filename
+      # Likely due to my #formatted_filename method is a little too strict
+      # @return [String] default name
+      def handle_filename_err
+        puts "\n! Forbidden characters found in event name, a default filename will be used."
+        "chess session"
+      end
+
+      # Returns PGN ready string
+      # @return [String]
+      def to_pgn = PgnUtils.to_pgn(session.slice(*TAGS.keys, :moves))
+
+      # Helper to revert string time back to Time object
+      def process_time_field = session[:date] = Time.strptime(date, STR_TIME)
+
+      # Format filename
+      def build_name = "#{session[:event]}_#{session[:date].strftime('%Y_%m_%d')}"
+    end
+  end
+end

data/lib/console_game/chess/utilities/pgn_utils.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+# Helper module to perform PGN file related operations.
+# `.pgn` is a file type that stores detailed chess session data.
+# It is compatible with most online chess site, and extremely readable.
+# @author Ancient Nimbus
+# @version v1.1.0
+module PgnUtils
+  # Pgn file format
+  DOT_PGN = ".pgn"
+  # Essential tags in PGN
+  TAGS = { event: nil, site: nil, date: nil, round: nil, white: nil, black: nil, result: nil }.freeze
+  # Optional tags in PGN
+  OPT_TAGS = { annotator: nil, plyCount: nil, timeControl: nil, termination: nil, mode: nil, fen: nil }.freeze
+
+  class << self
+    # Convert pgn data file to usable hash
+    # @param pgn_data [String]
+    # @return [Hash] internal session data object
+    def parse_pgn(pgn_data)
+      metadata, others = pgn_data.lines.partition { |elem| elem.chomp!.start_with?("[") }
+      session = { moves: nil }
+      metadata.each do |elem|
+        k, v = parse_pgn_metadata(elem)
+        session[k] = v
+      end
+      session[:moves] = parse_pgn_moves(clean_pgn_moves(others))
+
+      session
+    end
+
+    # Expects a hash and returns a string object with PGN formatting.
+    # @param session [Hash] expects a single chess session, invalid moves data will result operation being cancelled.
+    # @return [String]
+    def to_pgn(session)
+      return nil unless session.key?(:moves)
+
+      data = []
+      moves = []
+      result = session.fetch(:result)
+      session.each do |k, v|
+        data << format_metadata(k, v) if k != :moves
+        moves = format_moves(v, result) if k == :moves
+      end
+
+      <<~PGN
+        #{data.join("\n")}
+
+        #{moves}
+      PGN
+    end
+
+    private
+
+    # Helper to format PGN metadata
+    # @param key [Symbol, String]
+    # @param value [Object]
+    # @return [String]
+    def format_metadata(key, value)
+      key = key.is_a?(Symbol) ? key.capitalize : key
+      case value
+      in String | Integer | Float
+        "[#{key} \"#{value}\"]"
+      in Time
+        "[#{key} \"#{value.strftime('%Y.%m.%d')}\"]"
+      else
+        "[#{key} \"#{value}\"]"
+      end
+    end
+
+    # Helper to turn metadata string to key, value array pair
+    # @param elem [String] expects a single metadata element
+    # @return [Array] key, value pair
+    def parse_pgn_metadata(elem)
+      str_data = elem.delete('"[]').split
+      key, value = str_data.partition { |part| str_data.index(part).zero? }
+      key = key.join.downcase.to_sym
+      raise ArgumentError, "#{key} is not a valid metadata field, please verify data integrity" unless TAGS.key?(key)
+
+      value = if key == :date
+                handle_date(value[0])
+              else
+                value.join(" ")
+              end
+      [key, value]
+    end
+
+    # Helper to try convert string value to a date, if it fails, returns a incomplete date as string
+    # @param str_date [String]
+    # @return [Time]
+    def handle_date(str_date)
+      y, m, d = str_date.tr(".", " ").split
+      Time.new(y, m, d)
+    rescue ArgumentError
+      y, m, d = [y, m, d].map { |elem| elem.to_i.zero? ? 1 : elem }
+      Time.new(y, m, d)
+    end
+
+    # Helper to format PGN moves
+    # @param moves [Hash] expects moves in Algebraic notation format
+    # @param result [String, nil] session result, if any.
+    # @return [String]
+    def format_moves(moves, result = nil)
+      moves_arr = moves.map { |k, v| "#{k}. #{v.join(' ')}" }
+      moves_arr << result unless result.nil?
+      moves_arr.each_slice(8).map { |line| line.join(" ") }.join("\n")
+    end
+
+    # Helper to turn pgn moves data to key, value array pair
+    # @param clean_moves [String]
+    # @return [Array]
+    def parse_pgn_moves(clean_moves)
+      moves = Hash.new { |h, k| h[k] = [] }
+
+      turn_tracker = 0
+      clean_moves.each do |elem|
+        if elem.include?(".")
+          turn_tracker = elem.sub(".", "").to_i
+        elsif moves[turn_tracker].size < 2
+          moves[turn_tracker] << elem
+        end
+      end
+      moves
+    end
+
+    # Helper to clean up raw string before further processing
+    # @param moves_data [Array]
+    # @return [Array]
+    def clean_pgn_moves(moves_data)
+      arr = moves_data.join(" ").split
+      arr.map! { |elem| elem.include?(".") ? elem.sub(".", ". ").split : elem }.flatten!
+    end
+  end
+end