# ==================================================================================================================== #
#              _____ ____    _        _      ___  ______     ____     ____  __                                         #
#  _ __  _   _| ____|  _ \  / \      / \    / _ \/ ___\ \   / /\ \   / /  \/  |                                        #
# | '_ \| | | |  _| | | | |/ _ \    / _ \  | | | \___ \\ \ / /  \ \ / /| |\/| |                                        #
# | |_) | |_| | |___| |_| / ___ \  / ___ \ | |_| |___) |\ V /    \ V / | |  | |                                        #
# | .__/ \__, |_____|____/_/   \_\/_/   \_(_)___/|____/  \_/      \_/  |_|  |_|                                        #
# |_|    |___/                                                                                                         #
# ==================================================================================================================== #
# Authors:                                                                                                             #
#   Patrick Lehmann                                                                                                    #
#                                                                                                                      #
# License:                                                                                                             #
# ==================================================================================================================== #
# Copyright 2025-2026 Patrick Lehmann - Boetzingen, Germany                                                            #
#                                                                                                                      #
# Licensed under the Apache License, Version 2.0 (the "License");                                                      #
# you may not use this file except in compliance with the License.                                                     #
# You may obtain a copy of the License at                                                                              #
#                                                                                                                      #
#   http://www.apache.org/licenses/LICENSE-2.0                                                                         #
#                                                                                                                      #
# Unless required by applicable law or agreed to in writing, software                                                  #
# distributed under the License is distributed on an "AS IS" BASIS,                                                    #
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.                                             #
# See the License for the specific language governing permissions and                                                  #
# limitations under the License.                                                                                       #
#                                                                                                                      #
# SPDX-License-Identifier: Apache-2.0                                                                                  #
# ==================================================================================================================== #
#
"""
A TCL execution environment for OSVVM's ``*.pro`` files.
"""
from pathlib                         import Path
from textwrap                        import dedent
from tkinter                         import Tk, Tcl, TclError
from typing                          import Any, Dict, Callable, Optional as Nullable

from pyTooling.Decorators            import export, readonly
from pyTooling.MetaClasses           import ExtendedType
from pyTooling.Versioning            import YearMonthVersion
from pyVHDLModel                     import VHDLVersion

from pyEDAA.OSVVM                    import OSVVMException
from pyEDAA.OSVVM.Project            import Context, osvvmContext, Build, Project
from pyEDAA.OSVVM.Project.Procedures import noop, NoNullRangeWarning
from pyEDAA.OSVVM.Project.Procedures import FileExists, DirectoryExists, FindOsvvmSettingsDirectory
from pyEDAA.OSVVM.Project.Procedures import build, BuildName, include, library, analyze, simulate, generic
from pyEDAA.OSVVM.Project.Procedures import TestSuite, TestName, RunTest
from pyEDAA.OSVVM.Project.Procedures import ChangeWorkingDirectory, CreateOsvvmScriptSettingsPkg
from pyEDAA.OSVVM.Project.Procedures import SetVHDLVersion, GetVHDLVersion
from pyEDAA.OSVVM.Project.Procedures import SetCoverageAnalyzeEnable, SetCoverageSimulateEnable
from pyEDAA.OSVVM.Project.Procedures import ConstraintFile, ScopeToRef, ScopeToCell


@export
class TclEnvironment(metaclass=ExtendedType, slots=True):
	"""
	A TCL execution environment wrapping an embedded TCL interpreter based on :class:`tkinter.Tcl`.
	"""
	_tcl:        Tk                   #: The embedded TCL interpreter instance.
	_procedures: Dict[str, Callable]  #: A dictionary of registered TCL procedures implemented by Python functions.
	_context:    Context              #: The TCL execution context.

	def __init__(self, context: Context) -> None:
		"""
		Initialize a TCL execution environment.

		:param context: The TCL execution context.
		"""
		self._context = context
		context._processor = self

		self._tcl = Tcl()
		self._procedures = {}

	@readonly
	def TCL(self) -> Tk:
		"""
		Read-only property to access the embedded TCL interpreter instance (:attr:`_tcl`).

		:returns: TCL interpreter instance.
		"""
		return self._tcl

	@readonly
	def Procedures(self) -> Dict[str, Callable]:
		"""
		Read-only property to access the dictionary of registered TCL procedures implemented by Python functions (:attr:`_procedures`).

		:returns: The dictionary of registered procedures.
		"""
		return self._procedures

	@readonly
	def Context(self) -> Context:
		"""
		Read-only property to access the TCL execution context (:attr:`_context`).

		:returns: The TCL execution context.
		"""
		return self._context

	def RegisterPythonFunctionAsTclProcedure(self, pythonFunction: Callable, tclProcedureName: Nullable[str] = None) -> None:
		"""
		Register a Python function as TCL procedure.

		:param pythonFunction:   The Python function to be registered.
		:param tclProcedureName: Optional, name of the TCl procedure. |br|
		                         Default: derived the TCL procedure name from Python function name.
		"""
		if tclProcedureName is None:
			tclProcedureName = pythonFunction.__name__

		self._tcl.createcommand(tclProcedureName, pythonFunction)
		self._procedures[tclProcedureName] = pythonFunction

	def EvaluateTclCode(self, tclCode: str) -> None:
		"""
		Evaluate TCL source code.

		:param tclCode:         TCL source code to evaluate.
		:raises OSVVMException: When a :exc:`~tkinter.TclError` is caught while executing the TCL source code. |br|
		                        In case the error is unspecific, :func:`~pyEDAA.OSVVM.Project.TCL.getException` is used to
		                        look up and restore an exception, potentially coming from Python code called within TCL
		                        code.
		"""
		try:
			self._tcl.eval(tclCode)
		except TclError as e:
			e = getException(e, self._context)
			ex = OSVVMException(f"Caught TclError while evaluating TCL code.")
			ex.add_note(tclCode)
			raise ex from e

	def EvaluateProFile(self, path: Path) -> None:
		"""
		Evaluate TCL source file.

		:param path:            Path to a TCL source file for evaluation.
		:raises OSVVMException: When a :exc:`~tkinter.TclError` is caught while executing the TCL source code. |br|
		                        In case the error is unspecific, :func:`~pyEDAA.OSVVM.Project.TCL.getException` is used to
		                        look up and restore an exception, potentially coming from Python code called within TCL
		                        code.
		"""
		try:
			self._tcl.evalfile(str(path))
		except TclError as e:
			ex = getException(e, self._context)
			raise OSVVMException(f"Caught TclError while processing '{self._context.WorkingDirectory / path}'.") from ex

	def __setitem__(self, tclVariableName: str, value: Any) -> None:
		"""
		Set a TCL variable to a specific value.

		:param tclVariableName: Name of the TCL variable.
		:param value:           Value to be set.
		"""
		self._tcl.setvar(tclVariableName, value)

	def __getitem__(self, tclVariableName: str) -> None:
		"""
		Return a TCL variable's value.

		:param tclVariableName: Name of the TCL variable.
		:returns:               TCL variable's value.
		"""
		return self._tcl.getvar(tclVariableName)

	def __delitem__(self, tclVariableName: str) -> None:
		"""
		Unset a TCL variable.

		:param tclVariableName: Name of the TCL variable.
		"""
		self._tcl.unsetvar(tclVariableName)


@export
class OsvvmVariables(metaclass=ExtendedType, slots=True):
	"""
	A class representing OSVVM's setting variables.
	"""
	_osvvmVersion:                YearMonthVersion  #: Latest supported OSVVM version.
	_osvvmCreateVTI:                   str               #: Create derived VTI components. Not supported.

	_vhdlVersion:                 VHDLVersion       #: Default VHDL language revision.
	_toolVendor:                  str               #: Name of the tool vendor.
	_toolName:                    str               #: Name of the tool.
	_toolVersion:                 str               #: Version of the tool.

	_supportsDeferredConstants:   str               #: True, if deferred constants are supported.
	_supports2008GenericPackages: str               #: True, if VHDL-2008 generic packages are supported.
	_supports2019Interface:       str               #: True, if VHDL-2019 mode views are supported.
	_supports2019Generics:        str               #: True, if VHDL-2019 extended incomplete type generics are supported.
	_supports2019ImpureFunctions: str               #: True, if VHDL-2019 impure functions are supported.
	_supports2019FilePath:        str               #: True, if VHDL-2019 file path is supported.
	_supports2019AssertAPI:       str               #: True, if VHDL-2019 assert API is support
	_supports2019Integer64Bits:   str               #: True, if VHDL-2019 64-bit integers are supported.

	def __init__(
		self,
		osvvmVersion:                Nullable[YearMonthVersion] = None,
		vhdlVersion:                 Nullable[VHDLVersion] = None,
		toolVendor:                  Nullable[str] = None,
		toolName:                    Nullable[str] = None,
		toolVersion:                 Nullable[str] = None,
		supports2019Interface:       Nullable[str] = None,
		supports2019Generics:        Nullable[str] = None,
		supports2019ImpureFunctions: Nullable[str] = None,
		supports2019FilePath:        Nullable[str] = None,
		supports2019AssertAPI:       Nullable[str] = None,
		supports2019Integer64Bits:   Nullable[str] = None
	) -> None:
		"""
		Initialize OSVVM's setting variables.

		:param osvvmVersion:                Optional, latest supported OSVVM version.
		:param vhdlVersion:                 Optional, default VHDL language revision.
		:param toolVendor:                  Optional, name of the tool vendor.
		:param toolName:                    Optional, name of the tool.
		:param toolVersion:                 Optional, version of the tool.
		:param supports2019Interface:       Optional, VHDL-2019 mode views are supported.
		:param supports2019Generics:        Optional, VHDL-2019 extended incomplete type generics are supported.
		:param supports2019ImpureFunctions: Optional, VHDL-2019 impure functions are supported.
		:param supports2019FilePath:        Optional, VHDL-2019 file path is supported.
		:param supports2019AssertAPI:       Optional, VHDL-2019 assert API is support
		:param supports2019Integer64Bits:   Optional, VHDL-2019 64-bit integers are supported.

		.. note::

		   If not specified, the following values are used:

		   * OSVVM version = :pycode:`YearMonthVersion.Parse("2026.01")`
		   * VHDL version = :pycode:`VHDLVersion.VHDL2008`
		   * Tool vendor = :pycode:`"EDA²"`
		   * Tool name = :pycode:`"pyEDAA.ProjectModel"`
		   * Tool version = :pycode:`"0.1"`
		   * Supports VHDL-2019 interface = :pycode:`"false"`
		   * Supports VHDL-2019 generics = :pycode:`"false"`
		   * Supports VHDL-2019 impure functions = :pycode:`"false"`
		   * Supports VHDL-2019 file path = :pycode:`"false"`
		   * Supports VHDL-2019 assert API = :pycode:`"false"`
		   * Supports VHDL-2019 64-bit integers = :pycode:`"false"`
		"""
		self._osvvmVersion =                osvvmVersion                if osvvmVersion                is not None else YearMonthVersion.Parse("2026.01")
		self._osvvmCreateVTI =              "false"

		self._vhdlVersion =                 vhdlVersion                 if vhdlVersion                 is not None else VHDLVersion.VHDL2008
		self._toolVendor =                  toolVendor                  if toolVendor                  is not None else "EDA²"
		self._toolName =                    toolName                    if toolName                    is not None else "pyEDAA.ProjectModel"
		self._toolVersion =                 toolVersion                 if toolVersion                 is not None else "0.1"

		self._supportsDeferredConstants =   "true"
		self._supports2008GenericPackages = "true"
		self._supports2019Interface =       supports2019Interface       if supports2019Interface       is not None else "false"
		self._supports2019Generics =        supports2019Generics        if supports2019Generics        is not None else "false"
		self._supports2019ImpureFunctions = supports2019ImpureFunctions if supports2019ImpureFunctions is not None else "false"
		self._supports2019FilePath =        supports2019FilePath        if supports2019FilePath        is not None else "false"
		self._supports2019AssertAPI =       supports2019AssertAPI       if supports2019AssertAPI       is not None else "false"
		self._supports2019Integer64Bits =   supports2019Integer64Bits   if supports2019Integer64Bits   is not None else "false"

	@readonly
	def OSVVMVersion(self) -> YearMonthVersion:
		"""
		Read-only property to access the latest support OSVVM version (:attr:`_osvvmVersion`).

		:returns: The latest supported OSVVM version.
		"""
		return self._osvvmVersion

	@readonly
	def OSVVMCreateVTI(self) -> str:
		"""
		Read-only property to access the task deriving VTI components (:attr:`_osvvmCreateVTI`).

		:returns: The task if VTI components should be derived..
		"""
		return self._osvvmCreateVTI

	@readonly
	def VHDLVersion(self) -> VHDLVersion:
		"""
		Read-only property to access the default VHDL language revision (:attr:`_vhdlVersion`).

		:returns: The default VHDL language revision.
		"""
		return self._vhdlVersion

	@readonly
	def ToolVendor(self) -> str:
		"""
		Read-only property to access the tool vendor name (:attr:`_toolVendor`).

		:returns: The tool vendor name.
		"""
		return self._toolVendor

	@readonly
	def ToolName(self) -> str:
		"""
		Read-only property to access the tool's' name (:attr:`_toolName`).

		:returns: The tool's name.
		"""
		return self._toolName

	@readonly
	def ToolVersion(self) -> str:
		"""
		Read-only property to access the tool's version (:attr:`_toolVersion`).

		:returns: The tool's version.
		"""
		return self._toolVersion

	@readonly
	def SupportsDeferredConstants(self) -> str:
		"""
		Read-only property to access the VHDL feature flag if deferred constants are supported (:attr:`_supportsDeferredConstants`).

		:returns: The VHDL feature flag if deferred constants is supported.
		"""
		return self._supportsDeferredConstants

	@readonly
	def Supports2008GenericPackages(self) -> str:
		"""
		Read-only property to access the VHDL-2008 feature flag if generic packages are supported (:attr:`_supports2008GenericPackages`).

		:returns: The VHDL-2008 feature flag if generic packages is supported.
		"""
		return self._supports2008GenericPackages

	@readonly
	def Supports2019ImpureFunctions(self) -> str:
		"""
		Read-only property to access the VHDL-2019 feature flag if impure functions are supported (:attr:`_supports2019ImpureFunctions`).

		:returns: The VHDL-2019 feature flag if impure functions are supported.
		"""
		return self._supports2019ImpureFunctions

	@readonly
	def Supports2019Interface(self) -> str:
		"""
		Read-only property to access the VHDL-2019 feature flag if mode views (interfaces) are supported (:attr:`_supports2019Interface`).

		:returns: The VHDL-2019 feature flag if mode views are supported.
		"""
		return self._supports2019Interface

	@readonly
	def Supports2019Generics(self) -> str:
		"""
		Read-only property to access the VHDL-2019 feature flag if extended incomplete type generics are supported (:attr:`_supports2019Generics`).

		:returns: The VHDL-2019 feature flag if extended incomplete type generics are supported.
		"""
		return self._supports2019Generics

	@readonly
	def Supports2019ImpureFunctions(self) -> str:
		"""
		Read-only property to access the VHDL-2019 feature flag if impure functions are supported (:attr:`_supports2019ImpureFunctions`).

		:returns: The VHDL-2019 feature flag if impure functions are supported.
		"""
		return self._supports2019ImpureFunctions

	@readonly
	def Supports2019FilePath(self) -> str:
		"""
		Read-only property to access the VHDL-2019 feature flag if file path is supported (:attr:`_supports2019FilePath`).

		:returns: The VHDL-2019 feature flag if file path is supported.
		"""
		return self._supports2019FilePath

	@readonly
	def Supports2019AssertAPI(self) -> str:
		"""
		Read-only property to access the VHDL-2019 feature flag if assert API is supported (:attr:`_supports2019AssertAPI`).

		:returns: The VHDL-2019 feature flag if assert API is supported.
		"""
		return self._supports2019AssertAPI

	@readonly
	def Supports2019Integer64Bits(self) -> str:
		"""
		Read-only property to access the VHDL-2019 feature flag if 64-bit integers are supported (:attr:`_supports2019Integer64Bits`).

		:returns: The VHDL-2019 feature flag if 64-bit integers are supported.
		"""
		return self._supports2019Integer64Bits


@export
class OsvvmProFileProcessor(TclEnvironment):
	"""
	An OSVVM-specific TCL execution environment for ``*.pro`` files.
	"""

	def __init__(
		self,
		context:        Nullable[Context] = None,
		osvvmVariables: Nullable[OsvvmVariables] = None
	) -> None:
		"""
		Initialize an OSVVM-specific TCL execution environment.

		:param context:        The TCL execution context.
		:param osvvmVariables: OSVVM default settings.

		.. rubric:: Initialization steps:

		1. Initialize base-class.
		2. Load OSVVM default value into ``::osvvm::`` namespace variables.
		3. Overwrite predefined TCL procedures. |br|
		   Avoid harmful or disturbing actions caused by these procedures.
		4. Register Python functions as TCL procedures.
		"""
		if context is None:
			context = osvvmContext

		super().__init__(context)

		if osvvmVariables is None:
			osvvmVariables = OsvvmVariables()

		self.LoadOsvvmDefaults(osvvmVariables)
		self.OverwriteTclProcedures()
		self.RegisterTclProcedures()

	def LoadOsvvmDefaults(self, osvvmVariables: OsvvmVariables) -> None:
		"""
		Create an OSVVM namespace and declare variables with default values.

		:param osvvmVariables: OSVVM settings object.

		.. code-block:: TCL

		   namespace eval ::osvvm {
		     variable OsvvmVersion                            "<Version>"
		     variable VhdlVersion                             "<Version>"
		     variable ToolVendor                              "<ToolVendor>"
		     variable ToolName                                "<ToolName>"
		     variable ToolNameVersion                         "<ToolVersion>"
		     variable ToolSupportsDeferredConstants           "true"
		     variable ToolSupportsGenericPackages             "true"
		     variable FunctionalCoverageIntegratedInSimulator "default"
		     variable Supports2019Interface                   "false"
		     variable Supports2019Generics                    "false"
		     variable Supports2019ImpureFunctions             "false"
		     variable Supports2019FilePath                    "false"
		     variable Supports2019AssertApi                   "false"
		     variable Supports2019Integer64Bits               "false"

		     variable ClockResetVersion                       $OsvvmVersion

		     variable CreateVti                               "false"
		     variable OsvvmDevDeriveArchitectures             "false"
		   }
		"""
		match osvvmVariables.VHDLVersion:
			case VHDLVersion.VHDL2002:
				version = "2002"
			case VHDLVersion.VHDL2008:
				version = "2008"
			case VHDLVersion.VHDL2019:
				version = "2019"
			case _:
				version = "unsupported"

		code = dedent(f"""\
			namespace eval ::osvvm {{
			  variable OsvvmVersion                            "{osvvmVariables.OSVVMVersion}"
			  variable VhdlVersion                             "{version}"
			  variable ToolVendor                              "{osvvmVariables.ToolVendor}"
			  variable ToolName                                "{osvvmVariables.ToolName}"
			  variable ToolNameVersion                         "{osvvmVariables.ToolVersion}"
			  variable ToolSupportsDeferredConstants           "{osvvmVariables.SupportsDeferredConstants}"
			  variable ToolSupportsGenericPackages             "{osvvmVariables.Supports2008GenericPackages}"
			  variable FunctionalCoverageIntegratedInSimulator "default"
		    variable Supports2019Interface                   "{osvvmVariables.Supports2019Interface}"
		    variable Supports2019Generics                    "{osvvmVariables.Supports2019Generics}"
		    variable Supports2019ImpureFunctions             "{osvvmVariables.Supports2019ImpureFunctions}"
		    variable Supports2019FilePath                    "{osvvmVariables.Supports2019FilePath}"
		    variable Supports2019AssertApi                   "{osvvmVariables.Supports2019AssertAPI}"
		    variable Supports2019Integer64Bits               "{osvvmVariables.Supports2019Integer64Bits}"

			  variable ClockResetVersion                       $OsvvmVersion

			  variable CreateVti                               "{osvvmVariables.OSVVMCreateVTI}"
			  variable OsvvmDevDeriveArchitectures             "false"
			}}
			""")

		try:
			self._tcl.eval(code)
		except TclError as ex:
			raise OSVVMException(f"TCL error occurred, when initializing OSVVM variables.") from ex

	def OverwriteTclProcedures(self) -> None:
		"""
		Overwrite predefined TCL procedures.

		.. rubric:: List of overwritten procedures:

		* `puts` |rarr| :func:`~pyEDAA.OSVVM.Project.Procedures.noop`
		"""
		self.RegisterPythonFunctionAsTclProcedure(noop, "puts")

	def RegisterTclProcedures(self) -> None:
		"""
		Register Python functions as TCL procedures.

		.. rubric:: List of registered procedures:

		* ``build`` |rarr| :func:`~pyEDAA.OSVVM.Project.Procedures.build`
		* ``include`` |rarr| :func:`~pyEDAA.OSVVM.Project.Procedures.include`
		* ``library`` |rarr| :func:`~pyEDAA.OSVVM.Project.Procedures.library`
		* ``analyze`` |rarr| :func:`~pyEDAA.OSVVM.Project.Procedures.analyze`
		* ``simulate`` |rarr| :func:`~pyEDAA.OSVVM.Project.Procedures.simulate`
		* ``generic`` |rarr| :func:`~pyEDAA.OSVVM.Project.Procedures.generic`
		* ``BuildName`` |rarr| :func:`~pyEDAA.OSVVM.Project.Procedures.BuildName`
		* ``NoNullRangeWarning`` |rarr| :func:`~pyEDAA.OSVVM.Project.Procedures.NoNullRangeWarning`
		* ``TestSuite`` |rarr| :func:`~pyEDAA.OSVVM.Project.Procedures.TestSuite`
		* ``TestName`` |rarr| :func:`~pyEDAA.OSVVM.Project.Procedures.TestName`
		* ``RunTest`` |rarr| :func:`~pyEDAA.OSVVM.Project.Procedures.RunTest`
		* ``SetVHDLVersion`` |rarr| :func:`~pyEDAA.OSVVM.Project.Procedures.SetVHDLVersion`
		* ``GetVHDLVersion`` |rarr| :func:`~pyEDAA.OSVVM.Project.Procedures.GetVHDLVersion`
		* ``SetCoverageAnalyzeEnable`` |rarr| :func:`~pyEDAA.OSVVM.Project.Procedures.SetCoverageAnalyzeEnable`
		* ``SetCoverageSimulateEnable`` |rarr| :func:`~pyEDAA.OSVVM.Project.Procedures.SetCoverageSimulateEnable`
		* ``FileExists`` |rarr| :func:`~pyEDAA.OSVVM.Project.Procedures.FileExists`
		* ``DirectoryExists`` |rarr| :func:`~pyEDAA.OSVVM.Project.Procedures.DirectoryExists`
		* ``ChangeWorkingDirectory`` |rarr| :func:`~pyEDAA.OSVVM.Project.Procedures.ChangeWorkingDirectory`
		* ``FindOsvvmSettingsDirectory`` |rarr| :func:`~pyEDAA.OSVVM.Project.Procedures.FindOsvvmSettingsDirectory`
		* ``CreateOsvvmScriptSettingsPkg`` |rarr| :func:`~pyEDAA.OSVVM.Project.Procedures.CreateOsvvmScriptSettingsPkg`
		* ``ConstraintFile`` |rarr| :func:`~pyEDAA.OSVVM.Project.Procedures.ConstraintFile`
		* ``ScopeToRef`` |rarr| :func:`~pyEDAA.OSVVM.Project.Procedures.ScopeToRef`
		* ``ScopeToCell`` |rarr| :func:`~pyEDAA.OSVVM.Project.Procedures.ScopeToCell`
		* ``OpenBuildHtml`` |rarr| :func:`~pyEDAA.OSVVM.Project.Procedures.noop`
		* ``SetTranscriptType`` |rarr| :func:`~pyEDAA.OSVVM.Project.Procedures.noop`
		* ``GetTranscriptType`` |rarr| :func:`~pyEDAA.OSVVM.Project.Procedures.noop`
		* ``SetSimulatorResolution`` |rarr| :func:`~pyEDAA.OSVVM.Project.Procedures.noop`
		* ``GetSimulatorResolution`` |rarr| :func:`~pyEDAA.OSVVM.Project.Procedures.noop`
		"""
		self.RegisterPythonFunctionAsTclProcedure(build)
		self.RegisterPythonFunctionAsTclProcedure(include)
		self.RegisterPythonFunctionAsTclProcedure(library)
		self.RegisterPythonFunctionAsTclProcedure(analyze)
		self.RegisterPythonFunctionAsTclProcedure(simulate)
		self.RegisterPythonFunctionAsTclProcedure(generic)

		self.RegisterPythonFunctionAsTclProcedure(BuildName)
		self.RegisterPythonFunctionAsTclProcedure(NoNullRangeWarning)

		self.RegisterPythonFunctionAsTclProcedure(TestSuite)
		self.RegisterPythonFunctionAsTclProcedure(TestName)
		self.RegisterPythonFunctionAsTclProcedure(RunTest)

		self.RegisterPythonFunctionAsTclProcedure(SetVHDLVersion)
		self.RegisterPythonFunctionAsTclProcedure(GetVHDLVersion)
		self.RegisterPythonFunctionAsTclProcedure(SetCoverageAnalyzeEnable)
		self.RegisterPythonFunctionAsTclProcedure(SetCoverageSimulateEnable)

		self.RegisterPythonFunctionAsTclProcedure(FileExists)
		self.RegisterPythonFunctionAsTclProcedure(DirectoryExists)
		self.RegisterPythonFunctionAsTclProcedure(ChangeWorkingDirectory)

		self.RegisterPythonFunctionAsTclProcedure(FindOsvvmSettingsDirectory)
		self.RegisterPythonFunctionAsTclProcedure(CreateOsvvmScriptSettingsPkg)

		self.RegisterPythonFunctionAsTclProcedure(ConstraintFile)
		self.RegisterPythonFunctionAsTclProcedure(ScopeToRef)
		self.RegisterPythonFunctionAsTclProcedure(ScopeToCell)

		self.RegisterPythonFunctionAsTclProcedure(noop, "OpenBuildHtml")
		self.RegisterPythonFunctionAsTclProcedure(noop, "SetTranscriptType")
		self.RegisterPythonFunctionAsTclProcedure(noop, "GetTranscriptType")
		self.RegisterPythonFunctionAsTclProcedure(noop, "SetSimulatorResolution")
		self.RegisterPythonFunctionAsTclProcedure(noop, "GetSimulatorResolution")

	def LoadIncludeFile(self, path: Path) -> None:
		"""
		Load an OSVVM ``*.pro`` file for inclusion (not as a root level build, see :meth:`LoadBuildFile`).

		:param path: Path to the ``*.pro`` file.

		.. seealso::

		   * :meth:`LoadBuildFile`
		"""
		# TODO: should a context be used with _context to restore _currentDirectory?
		includeFile = self._context.IncludeFile(path)
		self.EvaluateProFile(includeFile)

	def LoadBuildFile(self, buildFile: Path, buildName: Nullable[str] = None) -> Build:
		"""
		Load an OSVVM ``*.pro`` file as build creating a new build context.

		.. rubric:: inferring the build name:

		1. From optional parameter ``buildName``.
		2. From ``*.pro`` file's filename.

		:param path: Path to the ``*.pro`` file.
		:returns:    The created build object.

		.. seealso::

		   * :meth:`LoadIncludeFile`
		"""
		if buildName is None:
			buildName = buildFile.stem

		self._context.BeginBuild(buildName)
		includeFile = self._context.IncludeFile(buildFile)
		self.EvaluateProFile(includeFile)

		# TODO: should a context be used with _context to restore _currentDirectory?
		return self._context.EndBuild()

	def LoadRegressionFile(self, regressionFile: Path, projectName: Nullable[str] = None) -> Project:
		"""
		Load a TCL file as a regression file and create a project from it.

		.. rubric:: inferring the project name:

		1. From optional parameter ``projectName``.
		2. From ``*.pro`` file's filename.

		:param regressionFile:
		:param projectName:
		:return:
		"""
		if projectName is None:
			projectName = regressionFile.stem

		self.EvaluateProFile(regressionFile)

		return self._context.ToProject(projectName)


@export
def getException(ex: Exception, context: Context) -> Exception:
	"""
	Restore Python exceptions if known by the execution context.

	:param ex:      Original exception (usually a :exc:`~tkinter.TclError`).
	:param context: The TCL execution context.
	:returns:       The original Python exception, if the context preserved an exception, otherwise the given TCLError.

	.. note::

	   When executing Python code within TCL, where TCL again is run within Python, TCL doesn't forward Python exceptions
	   through the TCL layer back into Python. Therefore, last seen Python exceptions are caught in the Python-TCL
	   interfacing procedures and preserved in the TCL execution context.

	   This helper function restores these preserved exception objects.
	"""
	if str(ex) == "":
		if (lastException := context.ClearLastException()) is not None:
			return lastException

	return ex