Put in the core infrastructure for loading boards.

Author: eriq-augustine

pacai/boards/medium-classic.txt

@@ -0,0 +1,11 @@
+%%%%%%%%%%%%%%%%%%%%
+%o...%........%....%
+%.%%.%.%%%%%%.%.%%.%
+%.%..............%.%
+%.%.%%.%%  %%.%%.%.%
+%......%G  G%......%
+%.%.%%.%%%%%%.%%.%.%
+%.%..............%.%
+%.%%.%.%%%%%%.%.%%.%
+%....%...P....%...o%
+%%%%%%%%%%%%%%%%%%%%

pacai/core/board.py

@@ -1,8 +1,65 @@
+import os
+import re
+
+import pacai.util.file
+import pacai.util.json
+import pacai.util.reflection
+
+THIS_DIR: str = os.path.join(os.path.dirname(os.path.realpath(__file__)))
+BOARDS_DIR: str = os.path.join(THIS_DIR, '..', 'boards')
+
+SEPARATOR_PATTERN: re.Pattern = re.compile(r'^\s*-{3,}\s*$')
+
+DEFAULT_BOARD_CLASS = 'pacai.core.board.Board'
+
 class Board:
     """
     A board represents the static (non-agent) components of a game.
-    For example, a layout contains the walls and collectable items.
+    For example, a board contains the walls and collectable items.
+
+    Most types of games (anything that would subclass pacai.core.game.Game) should probably
+    also subclass this to make their own type of board.
+
+    On disk, boards are represented in files that have two sections (divided by a '---' line).
+    The first section is a JSON object that holds any options for the board.
+    The second section is a textual representation of the board.
+    The specific board class (usually specified by the board options) should know how to interpret the text-based board.
     """
 
-    # TEST
-    pass
+    def __init__(self, marker_wall = '%', **kwargs) -> None:
+        # TEST
+        pass
+
+def load_path(path: str) -> Board:
+    """ Load a board from a file. """
+
+    text = pacai.util.file.read(path, strip = False)
+    return load_string(text)
+
+def load_string(text: str) -> Board:
+    """ Load a board from a string. """
+
+    separator_index = -1
+    lines = text.split("\n")
+
+    for i in range(len(lines)):
+        if (SEPARATOR_PATTERN.match(lines[i])):
+            separator_index = i
+            break
+
+    if (separator_index == -1):
+        # No separator was found.
+        options_text = ''
+        board_text = "\n".join(lines)
+    else:
+        options_text = "\n".join(lines[:i])
+        board_text = "\n".join(lines[(i + 1):])
+
+    options_text = options_text.strip()
+    if (len(options_text) == 0):
+        options = {}
+    else:
+        options = pacai.util.json.loads(options_text)
+
+    board_class = options.get('class', DEFAULT_BOARD_CLASS)
+    return pacai.util.reflection.new_object(board_class, **options)

pacai/core/test_agent.py

@@ -19,4 +19,3 @@ def test_ordering_base(self):
             (lower_ticket, higher_ticket) = test_cases[i]
             with self.subTest(msg = f"Case {i}: {lower_ticket} < {higher_ticket}"):
                 self.assertTrue((lower_ticket < higher_ticket))
-

pacai/core/test_board.py

@@ -0,0 +1,81 @@
+import glob
+import os
+
+import pacai.core.board
+import pacai.test.base
+
+class BoardTest(pacai.test.base.BaseTest):
+    # Load all the known/included boards.
+    def test_load_default_boards(self):
+        for path in glob.glob(os.path.join(pacai.core.board.BOARDS_DIR, '*.txt')):
+            pacai.core.board.load_path(path)
+
+    def test_load_test_boards(self):
+        # [(board, expected error substring), ...]
+        test_cases = [
+            ('', None),
+            (TEST_BOARD_NO_SEP, None),
+            (TEST_BOARD_OPTIONS, None),
+            (TEST_BOARD_SEP_EMPTY_OPTIONS, None),
+            (TEST_BOARD_EMPTY_BOARD, None),
+            (TEST_BOARD_FULL_EMPTY, None),
+            (TEST_BOARD_FULL_EMPTY_SEP, None),
+
+            (TEST_BOARD_ERROR_BAD_CLASS, "Cannot find class 'ZZZ' in module 'pacai.core.board'."),
+        ]
+
+        for i in range(len(test_cases)):
+            (text_board, error_substring) = test_cases[i]
+            with self.subTest(msg = f"Case {i}:"):
+                try:
+                    pacai.core.board.load_string(text_board)
+                except Exception as ex:
+                    if (error_substring is None):
+                        self.fail(f"Unexpected error: '{str(ex)}'.")
+
+                    self.assertIn(error_substring, str(ex), 'Error is not as expected.')
+                    continue
+
+                if (error_substring is not None):
+                    self.fail(f"Did not get expected error: '{error_substring}'.")
+
+TEST_BOARD_NO_SEP = '''
+%%%%%
+%. P%
+%%%%%
+'''
+
+TEST_BOARD_OPTIONS = '''
+{"marker_wall": "#"}
+---
+#####
+#. P#
+#####
+'''
+
+TEST_BOARD_SEP_EMPTY_OPTIONS = '''
+---
+%%%%%
+%. P%
+%%%%%
+'''
+
+TEST_BOARD_EMPTY_BOARD = '''
+{"marker_wall": "#"}
+---
+'''
+
+TEST_BOARD_FULL_EMPTY = '''
+'''
+
+TEST_BOARD_FULL_EMPTY_SEP = '''
+---
+'''
+
+TEST_BOARD_ERROR_BAD_CLASS = '''
+{"class": "pacai.core.board.ZZZ"}
+---
+%%%%%
+%. P%
+%%%%%
+'''

pacai/util/file.py

@@ -0,0 +1,21 @@
+def read(path, strip = True):
+    with open(path, 'r') as file:
+        contents = file.read()
+
+    if (strip):
+        contents = contents.strip()
+
+    return contents
+
+def write(path, contents, strip = True, newline = True):
+    if (contents is None):
+        contents = ''
+
+    if (strip):
+        contents = contents.strip()
+
+    if (newline):
+        contents += "\n"
+
+    with open(path, 'w') as file:
+        file.write(contents)

pacai/util/json.py

@@ -0,0 +1,32 @@
+"""
+This file standardizes how we write and read JSON files.
+Specifically, we try to be flexible when reading (using JSON5),
+and strict when writing (using vanilla JSON).
+"""
+
+import json
+
+import json5
+
+def load(file_obj, **kwargs):
+    return json5.load(file_obj, **kwargs)
+
+def loads(text, **kwargs):
+    return json5.loads(text, **kwargs)
+
+def load_path(path, **kwargs):
+    try:
+        with open(path, 'r') as file:
+            return load(file, **kwargs)
+    except Exception as ex:
+        raise ValueError(f"Failed to read JSON file '{path}'.") from ex
+
+def dump(data, file_obj, **kwargs):
+    return json.dump(data, file_obj, **kwargs)
+
+def dumps(data, **kwargs):
+    return json.dumps(data, **kwargs)
+
+def dump_path(data, path, **kwargs):
+    with open(path, 'w') as file:
+        dump(data, file, **kwargs)

pacai/util/reflection.py

@@ -0,0 +1,38 @@
+"""
+Reflection is the ability for a program to examine and modify its own code and structure when running.
+For example, you may want to find the type of a variable or create an object without knowing its type when you write the code.
+See: https://en.wikipedia.org/wiki/Reflective_programming .
+
+This file aims to contain all the reflection necessary for this project
+(as it can be confusing for students).
+"""
+
+import importlib
+import typing
+
+def new_object(class_name: str, *args, **kwargs) -> typing.Any:
+    """
+    Create a new instance of the specified class,
+    passing along the args and kwargs.
+    The class name should be fully qualified, e.g., 'pacai.core.agent.Agent', not just 'Agent'.
+
+    The module must be importable (i.e., already in the PATH).
+    """
+
+    parts = class_name.split('.')
+    module_name = '.'.join(parts[0:-1])
+    target_name = parts[-1]
+
+    if (len(parts) == 1):
+        raise ValueError(f"Non-qualified name supplied '{class_name}'.")
+
+    try:
+        module = importlib.import_module(module_name)
+    except ImportError:
+        raise ValueError(f"Unable to locate module '{module_name}'.")
+
+    target_class = getattr(module, target_name, None)
+    if (target_class is None):
+        raise ValueError(f"Cannot find class '{target_name}' in module '{module_name}'.")
+
+    return target_class(*args, **kwargs)

requirements.txt

@@ -1 +1,2 @@
 Pillow>=8.3.2
+json5>=0.9.14