[llvm] [Dexter] Add basic structured script parsing (PR #193710)

[Orlando Cazalet-Hyams via llvm-commits]

================
@@ -0,0 +1,238 @@
+# DExTer : Debugging Experience Tester
+# ~~~~~~   ~         ~~         ~   ~~
+#
+# Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+# See https://llvm.org/LICENSE.txt for license information.
+# SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+"""This file defines the DexterScript class. Using Nodes as building blocks, the DexterScript defines a complete Dexter
+test, a structured definition of locations, values, and actions used to drive a debugging session and evaluate the
+results.
+"""
+
+from pathlib import PurePath
+import os
+from typing import Any, Callable, Optional, Set, Union
+import yaml
+
+from dex.test_script.Nodes import (
+    Expect,
+    Where,
+    setup_yaml_parser,
+)
+
+from dex.utils.Exceptions import Error
+from dex.utils.Timer import Timer
+
+
+class DexterScriptError(Error):
+    pass
+
+
+class Scope:
+    """Helper class used to simplify queries about the context of a Node in the Dexter Script. The context for a given
+    Node consists of some base context information in the root of the script, and then all Where nodes in the parent
+    chain of the current Node. Therefore each Script has a root Scope object, and each Node's context is given by a
+    Scope chain built from the root Scope and every Where between the root and the given Node.
+    """
+
+    def __init__(
+        self,
+        file: Union[str, None] = None,
+        where: Union[Where, None] = None,
+        parent_scope: "Union[Scope, None]" = None,
+    ):
+        """Can be initialized with either a file for the default Scope, or with the properties of a Where
+        for any script-nested Scope.
+        """
+        if where is not None:
+            assert (
+                parent_scope is not None
+            ), "Scope for a Where node must have a parent scope!"
+            assert (
+                file is None
+            ), "Scope for a Where node cannot have a separately-defined file!"
+            self.file = None
+            self.where = where
+            self.parent_scope = parent_scope
+        else:
+            assert (
+                parent_scope is None
+            ), "Scope for a Root node cannot have a parent scope!"
+            self.file = file
+            self.where = None
+            self.parent_scope = None
+
+    def add_where(self, where: Where):
+        """Adds `where` to this Scope's chain."""
+        return Scope(where=where, parent_scope=self)
+
+
+class DexterScript:
+    def __init__(
+        self,
+        context,
+        script_obj,
+        scope: Scope,
+    ):
+        self.context = context
+        self.script_obj = script_obj
+        self.root_scope = scope
+        # `visit_script` will validate the structure of the script, as it traverses the full script and raises an
+        # exception if it sees anything unexpected.
+        self.visit_script()
+
+    # If a truthy value is returned, abort further visiting and return that value..
----------------
OCHyams wrote:

nit: double full stop

https://github.com/llvm/llvm-project/pull/193710