Source code for pyVHDLModel.Instantiation

# ==================================================================================================================== #
#             __     ___   _ ____  _     __  __           _      _                                                     #
#   _ __  _   \ \   / / | | |  _ \| |   |  \/  | ___   __| | ___| |                                                    #
#  | '_ \| | | \ \ / /| |_| | | | | |   | |\/| |/ _ \ / _` |/ _ \ |                                                    #
#  | |_) | |_| |\ V / |  _  | |_| | |___| |  | | (_) | (_| |  __/ |                                                    #
#  | .__/ \__, | \_/  |_| |_|____/|_____|_|  |_|\___/ \__,_|\___|_|                                                    #
#  |_|    |___/                                                                                                        #
# ==================================================================================================================== #
# Authors:                                                                                                             #
#   Patrick Lehmann                                                                                                    #
#                                                                                                                      #
# License:                                                                                                             #
# ==================================================================================================================== #
# Copyright 2017-2026 Patrick Lehmann - Boetzingen, Germany                                                            #
# Copyright 2016-2017 Patrick Lehmann - Dresden, 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                                                                                  #
# ==================================================================================================================== #
#
"""
This module contains parts of an abstract document language model for VHDL.

Instantiations of packages, procedures, functions and protected types.
"""
from __future__              import annotations

from typing                  import TYPE_CHECKING, Generator, Iterable, Optional as Nullable

from pyTooling.Decorators    import export, readonly
from pyTooling.MetaClasses   import ExtendedType

from pyVHDLModel.Exception   import PackageInstantiationNotLinkedError
from pyVHDLModel.Base        import ModelEntity
from pyVHDLModel.DesignUnit  import Package, ContextUnion
from pyVHDLModel.Association import GenericAssociationItem, GenericMapAspectMixin
from pyVHDLModel.Subprogram  import Procedure, Function, Subprogram
from pyVHDLModel.Symbol      import PackageReferenceSymbol, SubprogramReferenceSymbol, SubtypeSymbol

if TYPE_CHECKING:
	from pyVHDLModel.Visitor   import Visitor


@export
class GenericInstantiationMixin(metaclass=ExtendedType, mixin=True):
	"""
	A mixin-class for instantiations passing generic actuals.

	.. seealso::

	   * :class:`Generic entity instantiation mixin <pyVHDLModel.Instantiation.GenericEntityInstantiationMixin>`
	   * :class:`Subprogram instantiation mixin <pyVHDLModel.Instantiation.SubprogramInstantiationMixin>`
	   * :class:`Package instantiation <pyVHDLModel.Instantiation.PackageInstantiation>`
	"""
	def __init__(self) -> None:
		"""
		Initializes a generic instantiation.
		"""
		pass


@export
class GenericEntityInstantiationMixin(GenericInstantiationMixin, mixin=True):
	"""
	A mixin-class for instantiations of a design entity.
	"""
	def __init__(self) -> None:
		"""
		Initializes a generic entity instantiation.
		"""
		pass


@export
class SubprogramInstantiationMixin(GenericInstantiationMixin, GenericMapAspectMixin, mixin=True):
	"""
	A mixin-class for instantiations of a generic subprogram.

	.. seealso::

	   * :class:`Procedure instantiation <pyVHDLModel.Instantiation.ProcedureInstantiation>`
	   * :class:`Function instantiation <pyVHDLModel.Instantiation.FunctionInstantiation>`
	"""
	_subprogramReference: SubprogramReferenceSymbol  #: Reference to the instantiated generic subprogram.

	def __init__(
		self,
		subprogramReference: SubprogramReferenceSymbol,
		genericAssociationItems: Nullable[Iterable[GenericAssociationItem]] = None
	) -> None:
		"""
		Initializes a subprogram instantiation.

		:param subprogramReference:     Reference to the instantiated generic subprogram.
		:param genericAssociationItems: Optional, list of all generic associations in the generic map aspect.
		                                Default: ``None``, no generic associations.
		"""
		super().__init__()
		GenericMapAspectMixin.__init__(self, genericAssociationItems)

		self._subprogramReference = subprogramReference
		subprogramReference.Parent = self

	@readonly
	def SubprogramReference(self) -> SubprogramReferenceSymbol:
		"""
		Read-only property to access the subprogram reference (:attr:`_subprogramReference`).

		:returns: The subprogram reference.
		"""
		return self._subprogramReference



@export
class ProcedureInstantiation(Procedure, SubprogramInstantiationMixin):
	"""
	Represents the instantiation of a generic procedure.

	.. admonition:: Example

	   .. code-block:: VHDL

	      procedure p is new gp generic map (N => 1);
	      --        ^                                   <- Identifier
	      --                 ^^                         <- GenericProcedure
	"""

	def __init__(
		self,
		identifier: str,
		subprogramReference: SubprogramReferenceSymbol,
		genericAssociationItems: Nullable[Iterable[GenericAssociationItem]] = None,
		genericItems: Nullable[Iterable] = None,
		parameterItems: Nullable[Iterable] = None,
		declaredItems: Nullable[Iterable] = None,
		statements: Nullable[Iterable] = None,
		documentation: Nullable[str] = None,
		parent: Nullable[ModelEntity] = None,
		genericGroups: Nullable[Iterable] = None,
		parameterGroups: Nullable[Iterable] = None
	) -> None:
		"""
		Initializes a procedure instantiation.

		:param identifier:              The identifier of a model entity.
		:param subprogramReference:     Reference to the instantiated generic subprogram.
		:param genericAssociationItems: Optional, list of all generic associations in the generic map aspect.
		                                Default: ``None``, no generic associations.
		:param genericItems:            Optional, list of all generics, in declaration order.
		                                Default: ``None``, no generics.
		:param parameterItems:          Optional, list of all parameters, in declaration order.
		                                Default: ``None``, no parameters.
		:param declaredItems:           Optional, list of all declared items in this sequential declaration region.
		                                Default: ``None``, no declared items.
		:param statements:              Optional, list of all sequential statements in the subprogram's body.
		                                Default: ``None``, no statements.
		:param documentation:           Optional, the documentation comment associated with this declaration.
		                                Default: ``None``, no documentation.
		:param parent:                  Optional, the parent model entity of this entity. Default: ``None``, no parent.
		:param genericGroups:           Optional, list of generic groups partitioning the generics, in declaration
		                                order. Default: ``None``, one unnamed generic group.
		:param parameterGroups:         Optional, list of parameter groups partitioning the parameters, in declaration
		                                order. Default: ``None``, one unnamed parameter group.
		"""
		super().__init__(
			identifier,
			genericItems,
			parameterItems,
			declaredItems,
			statements,
			documentation,
			parent,
			genericGroups,
			parameterGroups
		)
		SubprogramInstantiationMixin.__init__(self, subprogramReference, genericAssociationItems)

[docs] def Visit(self, visitor: Visitor) -> None: """ Walk this procedure instantiation, its generic procedure and its generic map aspect with a visitor. :param visitor: The visitor receiving the events. """ visitor.VisitProcedureInstantiation(self) self._subprogramReference.Visit(visitor) self._VisitGenericMapAspect(visitor) visitor.VisitTerminator(self) visitor.DepartProcedureInstantiation(self)
@export class FunctionInstantiation(Function, SubprogramInstantiationMixin): """ Represents the instantiation of a generic function. .. admonition:: Example .. code-block:: VHDL function f is new gf generic map (N => 1); -- ^ <- Identifier -- ^^ <- GenericFunction """ def __init__( self, identifier: str, subprogramReference: SubprogramReferenceSymbol, isPure: bool = True, genericAssociationItems: Nullable[Iterable[GenericAssociationItem]] = None, genericItems: Nullable[Iterable] = None, parameterItems: Nullable[Iterable] = None, declaredItems: Nullable[Iterable] = None, statements: Nullable[Iterable] = None, documentation: Nullable[str] = None, parent: Nullable[ModelEntity] = None, genericGroups: Nullable[Iterable] = None, parameterGroups: Nullable[Iterable] = None ) -> None: # NOTE: deliberately calls Subprogram.__init__ directly, not super().__init__() (which would # resolve to Function.__init__ and require a returnType that can never be known here - see # the class docstring above). """ Initializes a function instantiation. :param identifier: The identifier of a model entity. :param subprogramReference: Reference to the instantiated generic subprogram. :param isPure: Optional, ``True`` if the subprogram was declared pure. Default: ``True``. :param genericAssociationItems: Optional, list of all generic associations in the generic map aspect. Default: ``None``, no generic associations. :param genericItems: Optional, list of all generics, in declaration order. Default: ``None``, no generics. :param parameterItems: Optional, list of all parameters, in declaration order. Default: ``None``, no parameters. :param declaredItems: Optional, list of all declared items in this sequential declaration region. Default: ``None``, no declared items. :param statements: Optional, list of all sequential statements in the subprogram's body. Default: ``None``, no statements. :param documentation: Optional, the documentation comment associated with this declaration. Default: ``None``, no documentation. :param parent: Optional, the parent model entity of this entity. Default: ``None``, no parent. :param genericGroups: Optional, list of generic groups partitioning the generics, in declaration order. Default: ``None``, one unnamed generic group. :param parameterGroups: Optional, list of parameter groups partitioning the parameters, in declaration order. Default: ``None``, one unnamed parameter group. """ Subprogram.__init__( self, identifier, isPure, genericItems, parameterItems, declaredItems, statements, documentation, parent, genericGroups, parameterGroups ) SubprogramInstantiationMixin.__init__(self, subprogramReference, genericAssociationItems) self._returnType = None
[docs] def Visit(self, visitor: Visitor) -> None: """ Walk this function instantiation, its generic function and its generic map aspect with a visitor. :param visitor: The visitor receiving the events. """ visitor.VisitFunctionInstantiation(self) self._subprogramReference.Visit(visitor) self._VisitGenericMapAspect(visitor) visitor.VisitTerminator(self) visitor.DepartFunctionInstantiation(self)
@readonly def ReturnType(self) -> Nullable[SubtypeSymbol]: """ Read-only property to access the return type (:attr:`_returnType`). :returns: The return type, or ``None`` if not set. """ return self._returnType @export # TODO: maybe a PackageBase class is needed to share members. class PackageInstantiation(Package, GenericInstantiationMixin, GenericMapAspectMixin): """ Represents the instantiation of a generic package. .. admonition:: Example .. code-block:: VHDL package p is new gp generic map (N => 1); -- ^ <- Identifier -- ^^ <- PackageReference """ _packageReference: PackageReferenceSymbol #: Reference to the instantiated generic package. def __init__( self, identifier: str, genericPackage: PackageReferenceSymbol, contextItems: Nullable[Iterable[ContextUnion]] = None, genericAssociationItems: Nullable[Iterable[GenericAssociationItem]] = None, documentation: Nullable[str] = None, parent: Nullable[ModelEntity] = None ) -> None: """ Initializes a package instantiation. :param identifier: The identifier of a model entity. :param genericPackage: Reference to the instantiated generic package. :param contextItems: Optional, list of all context items (library, use and context clauses). Default: ``None``, no context items. :param genericAssociationItems: Optional, list of all generic associations in the generic map aspect. Default: ``None``, no generic associations. :param documentation: Optional, the documentation comment associated with this declaration. Default: ``None``, no documentation. :param parent: Optional, the parent model entity of this entity. Default: ``None``, no parent. """ super().__init__(identifier, contextItems, documentation=documentation, parent=parent) GenericEntityInstantiationMixin.__init__(self) GenericMapAspectMixin.__init__(self, genericAssociationItems) self._packageReference = genericPackage self._packageReference.Parent = self
[docs] def Visit(self, visitor: Visitor) -> None: """ Walk this package instantiation, its context clause, its generic package and its generic map aspect with a visitor. :param visitor: The visitor receiving the events. """ self._VisitContextClause(visitor) visitor.VisitPackageInstantiation(self) self._packageReference.Visit(visitor) self._VisitGenericMapAspect(visitor) visitor.VisitTerminator(self) visitor.DepartPackageInstantiation(self)
@readonly def PackageReference(self) -> PackageReferenceSymbol: """ Read-only property to access the package reference (:attr:`_packageReference`). :returns: The package reference. """ return self._packageReference
[docs] def IterateDeclarations(self) -> Generator[tuple[str, ModelEntity], None, None]: """ Iterate the declarations of the instantiated generic package a use clause can make potentially visible. :returns: A generator to iterate (normalized designator, declaration) pairs, in declaration order. :raises PackageInstantiationNotLinkedError: If this package instantiation isn't linked to its generic package. |br| Call :meth:`~pyVHDLModel.Design.LinkPackageInstances` before linking use clauses. """ if (genericPackage := self._packageReference._reference) is None: ex = PackageInstantiationNotLinkedError( f"Package instantiation '{self._identifier}' isn't linked to its generic package " f"'{self._packageReference._name}'.", instantiationName=self._identifier, genericPackageName=str(self._packageReference._name) ) ex.add_note("Call 'LinkPackageInstances()' before linking use clauses.") raise ex yield from genericPackage.IterateDeclarations()
[docs] def Instantiate(self) -> None: """ Copy the components of the generic package into this package instantiation. :raises PackageInstantiationNotLinkedError: If this package instantiation isn't linked to its generic package. """ genericPackage: Package = self._packageReference.Package if genericPackage is None: raise PackageInstantiationNotLinkedError( f"Package instantiation '{self._identifier}' isn't linked to its generic package " f"'{self._packageReference._name}'.", instantiationName=self._identifier, genericPackageName=str(self._packageReference._name) ) # TODO: components might need to be copied and derived for componentName, component in genericPackage._components.items(): self._components[componentName] = component
# FIXME: handle other package members