Source code for pyVHDLModel.DesignUnit

# ==================================================================================================================== #
#             __     ___   _ ____  _     __  __           _      _                                                     #
#   _ __  _   \ \   / / | | |  _ \| |   |  \/  | ___   __| | ___| |                                                    #
#  | '_ \| | | \ \ / /| |_| | | | | |   | |\/| |/ _ \ / _` |/ _ \ |                                                    #
#  | |_) | |_| |\ 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.

Design units are contexts, entities, architectures, packages and their bodies as well as configurations.
"""
from __future__                import annotations

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

from pyTooling.Common          import getFullyQualifiedName, getTypeName
from pyTooling.Decorators      import export, readonly
from pyTooling.MetaClasses     import ExtendedType, abstractmethod, abstractclass
from pyTooling.Graph           import Vertex

from pyVHDLModel.Common        import AllowBlackboxMixin
from pyVHDLModel.Exception     import AlreadyInDesignError, NotAChildError
from pyVHDLModel.Base          import ModelEntity, NamedEntityMixin, MultipleNamedEntityMixin, DocumentedEntityMixin, \
                                      normalizedIdentifiersOf, ReservedWord
from pyVHDLModel.Name          import Name
from pyVHDLModel.Namespace     import Namespace
from pyVHDLModel.Regions       import DeclarativeRegionMixin, ConcurrentDeclarationRegionMixin, WithGenericsMixin, \
                                      WithPortsMixin, WithoutStatementsMixin
from pyVHDLModel.Symbol        import Symbol, PackageSymbol, EntitySymbol, LibraryReferenceSymbol
from pyVHDLModel.Interface     import GenericInterfaceItemMixin, PortInterfaceItemMixin, GenericGroup, PortGroup
from pyVHDLModel.Object        import DeferredConstant
from pyVHDLModel.Type          import AnonymousType, Subtype
from pyVHDLModel.Concurrent    import ConcurrentStatement, ConcurrentStatementsMixin
from pyVHDLModel.Configuration import BlockConfiguration

if TYPE_CHECKING:
	from pyVHDLModel.Visitor     import Visitor


@export
@abstractclass
class Reference(ModelEntity):
	"""
	A base-class for all references.

	.. seealso::

	   * :class:`Library clause <pyVHDLModel.DesignUnit.LibraryClause>`
	   * :class:`Use clause <pyVHDLModel.DesignUnit.UseClause>`
	   * :class:`Context reference <pyVHDLModel.DesignUnit.ContextReference>`
	"""

	_symbols:       list[Symbol]  #: List of all symbols referenced by this clause.

	def __init__(self, symbols: Iterable[Symbol], parent: Nullable[ModelEntity] = None) -> None:
		"""
		Initializes a reference by taking a list of symbols and a parent reference.

		:param symbols: A list of symbols this reference references to.
		:param parent:  Optional, reference to the logical parent in the model hierarchy. Default: ``None``, no parent.
		"""
		super().__init__(parent)

		self._symbols = list(symbols)

	@readonly
	def Symbols(self) -> list[Symbol]:
		"""
		Read-only property to access the symbols this reference references to (:attr:`_symbols`).

		:returns: A list of symbols.
		"""
		return self._symbols

	def _VisitSymbols(self, visitor: Visitor) -> None:
		"""
		Walk the referenced symbols, separated by commas, with a visitor.

		:param visitor: The visitor receiving the events.
		"""
		for index, symbol in enumerate(self._symbols):
			if index > 0:
				visitor.VisitNameListSeparator(self)

			symbol.Visit(visitor)


@export
class LibraryClause(Reference):
	"""
	Represents a library clause.

	.. admonition:: Example

	   .. code-block:: VHDL

	      library std, ieee;
	"""

	@readonly
	def Symbols(self) -> list[LibraryReferenceSymbol]:
		"""
		Read-only property to access the symbols this library clause references to (:attr:`_symbols`).

		:returns: A list of library reference symbols.
		"""
		return self._symbols

[docs] def __contains__(self, libraryIdentifier: str) -> bool: """ Check if this library clause names a library. :param libraryIdentifier: The normalized identifier of the library. :returns: ``True``, if one of the clause's library names is the library. """ return any(symbol._name._normalizedIdentifier == libraryIdentifier for symbol in self._symbols)
[docs] def Visit(self, visitor: Visitor) -> None: """ Walk this library clause and its library names with a visitor. :param visitor: The visitor receiving the events. """ visitor.VisitLibraryClause(self) self._VisitSymbols(visitor) visitor.VisitTerminator(self) visitor.DepartLibraryClause(self)
@export class UseClause(Reference): """ Represents a use clause. .. admonition:: Example .. code-block:: VHDL use std.text_io.all, ieee.numeric_std.all; """
[docs] def ResetReferences(self, designUnit: DesignUnit, region: DeclarativeRegionMixin) -> None: """ Reset the references of this use clause's symbols, which :meth:`~pyVHDLModel.Design.Analyze` linked. :param designUnit: The design unit containing this declaration. :param region: The declarative region declaring this declaration. """ super().ResetReferences(designUnit, region) for symbol in self._symbols: symbol._reference = None
[docs] def Visit(self, visitor: Visitor) -> None: """ Walk this use clause and its selected names with a visitor. :param visitor: The visitor receiving the events. """ visitor.VisitUseClause(self) self._VisitSymbols(visitor) visitor.VisitTerminator(self) visitor.DepartUseClause(self)
@export class ContextReference(Reference): """ Represents a context reference. .. hint:: It's called *context reference* not *context clause* by the LRM. .. admonition:: Example .. code-block:: VHDL context ieee.ieee_std_context; """
[docs] def Visit(self, visitor: Visitor) -> None: """ Walk this context reference and its context names with a visitor. :param visitor: The visitor receiving the events. """ visitor.VisitContextReference(self) self._VisitSymbols(visitor) visitor.VisitTerminator(self) visitor.DepartContextReference(self)
ContextUnion = Union[ LibraryClause, UseClause, ContextReference ] @export class DesignUnitWithContextMixin(metaclass=ExtendedType, mixin=True): """ A mixin-class for all design units with a context. .. seealso:: * :class:`Package <pyVHDLModel.DesignUnit.Package>` * :class:`Package body <pyVHDLModel.DesignUnit.PackageBody>` * :class:`Entity <pyVHDLModel.DesignUnit.Entity>` * :class:`Architecture <pyVHDLModel.DesignUnit.Architecture>` * :class:`Configuration <pyVHDLModel.DesignUnit.Configuration>` """ @export @abstractclass class DesignUnit(ModelEntity, NamedEntityMixin, DocumentedEntityMixin): """ A base-class for all design units. When a design unit is formatted, an unknown part - a library that is not set, or an entity with no known architecture - is rendered as ``?``. .. seealso:: * :class:`Primary design units <pyVHDLModel.DesignUnit.PrimaryUnit>` * :class:`Context <pyVHDLModel.DesignUnit.Context>` * :class:`Entity <pyVHDLModel.DesignUnit.Entity>` * :class:`Package <pyVHDLModel.DesignUnit.Package>` * :class:`Configuration <pyVHDLModel.DesignUnit.Configuration>` * :class:`Secondary design units <pyVHDLModel.DesignUnit.SecondaryUnit>` * :class:`Architecture <pyVHDLModel.DesignUnit.Architecture>` * :class:`Package body <pyVHDLModel.DesignUnit.PackageBody>` """ _CONTINUES_PARENT_REGION: ClassVar[bool] = False #: ``True`` if it continues its parent's declarative region. _IMPLICIT_LIBRARIES: ClassVar[tuple[str, ...]] = ("work", "std") #: Library names visible without a library clause. _document: Document #: The VHDL library, the design unit was analyzed into. # Either written as statements before (e.g. entity, architecture, package, ...), or as statements inside (context) _contextItems: list[ContextUnion] #: List of all context items (library, use and context clauses). _libraryReferences: list[LibraryClause] #: List of library clauses. _packageReferences: list[UseClause] #: List of use clauses. _contextReferences: list[ContextReference] #: List of context clauses. _referencedLibraries: dict[str, Library] #: Referenced libraries based on explicit library clauses or implicit inheritance _referencedPackages: dict[str, dict[str, Package]] #: Referenced packages based on explicit use clauses or implicit inheritance _referencedContexts: dict[str, Context] #: Referenced contexts based on explicit context references or implicit inheritance _dependencyVertex: Vertex #: Reference to the vertex in the dependency graph representing the design unit. |br| This reference is set by :meth:`~pyVHDLModel.Design.CreateDependencyGraph`. _hierarchyVertex: Vertex #: The vertex in the hierarchy graph def __init__(self, identifier: str, contextItems: Nullable[Iterable[ContextUnion]] = None, documentation: Nullable[str] = None, parent: Nullable[ModelEntity] = None) -> None: """ Initializes a design unit. :param identifier: Identifier (name) of the design unit. :param contextItems: Optional, a sequence of library, use or context clauses. Default: ``None``, no context items. :param documentation: Optional, associated documentation of the design unit. Default: ``None``, no documentation. :param parent: Optional, reference to the logical parent in the model hierarchy. Default: ``None``, no parent. :raises TypeError: If an element of parameter 'contextItems' is not of type :class:`LibraryClause`, :class:`UseClause` or :class:`ContextReference`. """ super().__init__(parent) NamedEntityMixin.__init__(self, identifier) DocumentedEntityMixin.__init__(self, documentation) self._document = None self._contextItems = contextItemList = [] self._libraryReferences = libraryReferences = [] self._packageReferences = packageReferences = [] self._contextReferences = contextReferences = [] if contextItems is not None: for item in contextItems: if isinstance(item, UseClause): packageReferences.append(item) elif isinstance(item, LibraryClause): libraryReferences.append(item) elif isinstance(item, ContextReference): contextReferences.append(item) else: ex = TypeError( "Element of parameter 'contextItems' is not of type 'LibraryClause', 'UseClause' or 'ContextReference'." ) ex.add_note(f"Got type '{getFullyQualifiedName(item)}'.") raise ex contextItemList.append(item) item.Parent = self self._referencedLibraries = {} self._referencedPackages = {} self._referencedContexts = {} self._dependencyVertex = None self._hierarchyVertex = None @property def Document(self) -> Document: """ Property to access the document (:attr:`_document`). :returns: The document. """ return self._document @Document.setter def Document(self, document: Document) -> None: self._document = document @property def Library(self) -> Library: """ Property to access the library (:attr:`_parent`). :returns: The library. """ return self._parent @Library.setter def Library(self, library: Library) -> None: self._parent = library @readonly def ContextItems(self) -> list[ContextUnion]: """ Read-only property to access the sequence of all context items comprising library, use and context clauses (:attr:`_contextItems`). :returns: Sequence of context items. """ return self._contextItems @readonly def ContextReferences(self) -> list[ContextReference]: """ Read-only property to access the sequence of context clauses (:attr:`_contextReferences`). :returns: Sequence of context clauses. """ return self._contextReferences @readonly def LibraryReferences(self) -> list[LibraryClause]: """ Read-only property to access the sequence of library clauses (:attr:`_libraryReferences`). :returns: Sequence of library clauses. """ return self._libraryReferences def _VisitContextClause(self, visitor: Visitor) -> None: """ Walk the context clause, i.e. the context items preceding the design unit, with a visitor. The context clause is reported, even if it has no context items. :param visitor: The visitor receiving the events. """ visitor.VisitContextClause(self) for item in self._contextItems: item.Visit(visitor) visitor.DepartContextClause(self) @readonly def PackageReferences(self) -> list[UseClause]: """ Read-only property to access the sequence of use clauses (:attr:`_packageReferences`). :returns: Sequence of use clauses. """ return self._packageReferences def AddContextItem(self, contextItem: ContextUnion) -> None: """ Add a context item at the end of the context clause. The context item's parent is set to this design unit. A library clause is also added to :data:`LibraryReferences`, a use clause to :data:`PackageReferences` and a context reference to :data:`ContextReferences`, in the order of :data:`ContextItems`. A context item may repeat an earlier one. :param contextItem: The library clause, use clause or context reference to add. :raises ValueError: If parameter 'contextItem' is ``None``. :raises TypeError: If parameter 'contextItem' is not of type :class:`LibraryClause`, :class:`UseClause` or :class:`ContextReference`. :raises AlreadyInDesignError: If parameter 'contextItem' already has a parent. .. attention:: The mutator doesn't update what :meth:`~pyVHDLModel.Design.Analyze` derived from the context items: the referenced libraries, packages and contexts (:data:`ReferencedLibraries`, :data:`ReferencedPackages`, :data:`ReferencedContexts`), the namespace entries of a use clause, the edges of the dependency graph, and the references of the symbols. A design changed after its analysis needs a new analysis. .. seealso:: :meth:`InsertContextItem` |rarr| Insert a context item at a position of the context clause. :meth:`RemoveContextItem` |rarr| Remove a context item from the context clause. """ self.InsertContextItem(len(self._contextItems), contextItem) def InsertContextItem(self, index: int, contextItem: ContextUnion) -> None: """ Insert a context item at a position of the context clause. The context item's parent is set to this design unit. A library clause is also added to :data:`LibraryReferences`, a use clause to :data:`PackageReferences` and a context reference to :data:`ContextReferences`, in the order of :data:`ContextItems`. A context item may repeat an earlier one. :param index: Position, from ``0`` (first) to the number of context items (append). A negative index counts from the end, as for :meth:`list.insert`: ``-1`` inserts before the last context item. :param contextItem: The library clause, use clause or context reference to insert. :raises ValueError: If parameter 'index' is ``None``. :raises TypeError: If parameter 'index' is not of type :class:`int`. :raises ValueError: If parameter 'index' is out of range. :raises ValueError: If parameter 'contextItem' is ``None``. :raises TypeError: If parameter 'contextItem' is not of type :class:`LibraryClause`, :class:`UseClause` or :class:`ContextReference`. :raises AlreadyInDesignError: If parameter 'contextItem' already has a parent. .. attention:: The mutator doesn't update what :meth:`~pyVHDLModel.Design.Analyze` derived from the context items: the referenced libraries, packages and contexts (:data:`ReferencedLibraries`, :data:`ReferencedPackages`, :data:`ReferencedContexts`), the namespace entries of a use clause, the edges of the dependency graph, and the references of the symbols. A design changed after its analysis needs a new analysis. .. seealso:: :meth:`AddContextItem` |rarr| Add a context item at the end of the context clause. :meth:`RemoveContextItem` |rarr| Remove a context item from the context clause. """ count = len(self._contextItems) if index is None: raise ValueError("Parameter 'index' is None.") elif not isinstance(index, int): ex = TypeError("Parameter 'index' is not of type 'int'.") ex.add_note(f"Got type '{getFullyQualifiedName(index)}'.") raise ex elif not (-count <= index <= count): ex = ValueError(f"Parameter 'index' is out of range {-count}..{count}.") ex.add_note(f"Got value '{index}'.") raise ex if contextItem is None: raise ValueError("Parameter 'contextItem' is None.") elif not isinstance(contextItem, (LibraryClause, UseClause, ContextReference)): ex = TypeError("Parameter 'contextItem' is not of type 'LibraryClause', 'UseClause' or 'ContextReference'.") ex.add_note(f"Got type '{getFullyQualifiedName(contextItem)}'.") raise ex elif contextItem._parent is not None: ex = AlreadyInDesignError( f"{getTypeName(contextItem)} already has a parent.", element=contextItem, parent=contextItem._parent ) ex.add_note(f"Remove it from its {getTypeName(contextItem._parent)} first.") raise ex if isinstance(contextItem, LibraryClause): references = self._libraryReferences referenceType = LibraryClause elif isinstance(contextItem, UseClause): references = self._packageReferences referenceType = UseClause else: references = self._contextReferences referenceType = ContextReference position = index if index >= 0 else count + index referenceIndex = sum(1 for item in self._contextItems[:position] if isinstance(item, referenceType)) self._contextItems.insert(position, contextItem) references.insert(referenceIndex, contextItem) contextItem.Parent = self def RemoveContextItem(self, contextItem: ContextUnion) -> None: """ Remove a context item from the context clause. The context item is detached: its parent is cleared, and it's removed from :data:`ContextItems` and from :data:`LibraryReferences`, :data:`PackageReferences` or :data:`ContextReferences`. The context item itself is unchanged and can be added to another design unit, or inserted at another position. :param contextItem: The library clause, use clause or context reference to remove. :raises ValueError: If parameter 'contextItem' is ``None``. :raises TypeError: If parameter 'contextItem' is not of type :class:`LibraryClause`, :class:`UseClause` or :class:`ContextReference`. :raises NotAChildError: If parameter 'contextItem' is not a context item of this design unit. .. attention:: The mutator doesn't update what :meth:`~pyVHDLModel.Design.Analyze` derived from the context items: the referenced libraries, packages and contexts (:data:`ReferencedLibraries`, :data:`ReferencedPackages`, :data:`ReferencedContexts`), the namespace entries of a use clause, the edges of the dependency graph, and the references of the symbols. A design changed after its analysis needs a new analysis. .. seealso:: :meth:`AddContextItem` |rarr| Add a context item at the end of the context clause. :meth:`InsertContextItem` |rarr| Insert a context item at a position of the context clause. """ if contextItem is None: raise ValueError("Parameter 'contextItem' is None.") elif not isinstance(contextItem, (LibraryClause, UseClause, ContextReference)): ex = TypeError("Parameter 'contextItem' is not of type 'LibraryClause', 'UseClause' or 'ContextReference'.") ex.add_note(f"Got type '{getFullyQualifiedName(contextItem)}'.") raise ex for index, item in enumerate(self._contextItems): if item is contextItem: break else: raise NotAChildError( f"{getTypeName(contextItem)} is not a context item of this {getTypeName(self)}.", element=contextItem, parent=self ) if isinstance(contextItem, LibraryClause): references = self._libraryReferences elif isinstance(contextItem, UseClause): references = self._packageReferences else: references = self._contextReferences del self._contextItems[index] references.remove(contextItem) contextItem._parent = None @readonly def ReferencedLibraries(self) -> dict[str, Library]: """ Read-only property to access the referenced libraries (:attr:`_referencedLibraries`). :returns: Dictionary of referenced libraries, indexed by normalized identifier. """ return self._referencedLibraries @readonly def ReferencedPackages(self) -> dict[str, Package]: """ Read-only property to access the referenced packages (:attr:`_referencedPackages`). :returns: Dictionary of referenced packages, indexed by normalized identifier. """ return self._referencedPackages @readonly def ReferencedContexts(self) -> dict[str, Context]: """ Read-only property to access the referenced contexts (:attr:`_referencedContexts`). :returns: Dictionary of referenced contexts, indexed by normalized identifier. """ return self._referencedContexts @readonly def DependencyVertex(self) -> Vertex: """ Read-only property to access the corresponding dependency vertex (:attr:`_dependencyVertex`). The dependency vertex references this design unit by its value field. :returns: The corresponding dependency vertex. """ return self._dependencyVertex @readonly def HierarchyVertex(self) -> Vertex: """ Read-only property to access the corresponding hierarchy vertex (:attr:`_hierarchyVertex`). The hierarchy vertex references this design unit by its value field. :returns: The corresponding hierarchy vertex. """ return self._hierarchyVertex def IsLibraryVisible(self, libraryIdentifier: str) -> bool: """ Check if the logical name of a library is visible in this design unit. The name ``work`` is implicitly visible, the name ``std`` too, except in a context declaration. Every other name needs a library clause, also the real name of the working library. The library clause is searched in this design unit's context clause, in the context clause of its primary unit, and in the contexts these reference, also in nested ones. The design unit must be in a library of a design. :param libraryIdentifier: The normalized identifier of the library. :returns: ``True``, if the library's name is visible. """ if libraryIdentifier in self._IMPLICIT_LIBRARIES: return True libraries = self._parent._parent._libraries designUnits = list(self._ContextClauseUnits()) for unit in designUnits: for libraryReference in unit._libraryReferences: if libraryIdentifier in libraryReference: return True for contextReference in unit._contextReferences: for symbol in contextReference._symbols: prefixIdentifier = symbol._name._prefix._normalizedIdentifier library = unit._parent if prefixIdentifier == "work" else libraries.get(prefixIdentifier) if library is not None: context = library._contexts.get(symbol._name._normalizedIdentifier) if context is not None and context not in designUnits: designUnits.append(context) return False def _ContextClauseUnits(self) -> tuple[DesignUnit, ...]: """ Return the design units whose context clause applies to this design unit. :returns: Tuple of this design unit. """ return (self, ) @abstractmethod def __str__(self) -> str: """ Formats the design unit. Every concrete design unit renders itself, so this base-class provides no implementation. :returns: Formatted design unit. """ @export @abstractclass class PrimaryUnit(DesignUnit): """ A base-class for all primary design units. .. seealso:: * :class:`Context <pyVHDLModel.DesignUnit.Context>` * :class:`Package <pyVHDLModel.DesignUnit.Package>` * :class:`Entity <pyVHDLModel.DesignUnit.Entity>` * :class:`Configuration <pyVHDLModel.DesignUnit.Configuration>` * :class:`PSL primary unit <pyVHDLModel.PSLModel.PSLPrimaryUnit>` (PSL is not supported) """ @export @abstractclass class SecondaryUnit(DesignUnit): """ A base-class for all secondary design units. .. seealso:: * :class:`Package body <pyVHDLModel.DesignUnit.PackageBody>` * :class:`Architecture <pyVHDLModel.DesignUnit.Architecture>` """ @export class Context(PrimaryUnit): """ Represents a context declaration. A context contains a generic list of all its items (library clauses, use clauses and context references) in :data:`_contextItems`. Furthermore, when a context gets initialized, the item kinds get separated into individual lists: * :class:`~pyVHDLModel.DesignUnit.LibraryClause` |rarr| :data:`_libraryReferences` * :class:`~pyVHDLModel.DesignUnit.UseClause` |rarr| :data:`_packageReferences` * :class:`~pyVHDLModel.DesignUnit.ContextReference` |rarr| :data:`_contextReferences` When :meth:`pyVHDLModel.Design.LinkContexts` got called, these lists were processed and the fields: * :data:`_referencedLibraries` (:pycode:`dict[libName, Library]`) * :data:`_referencedPackages` (:pycode:`dict[libName, [pkgName, Package]]`) * :data:`_referencedContexts` (:pycode:`dict[libName, [ctxName, Context]]`) are populated. The declarations the use clauses make potentially visible are imported into :data:`_namespace`. .. admonition:: Example .. code-block:: VHDL context ctx is -- ... end context; .. seealso:: * :class:`Library clause <pyVHDLModel.DesignUnit.LibraryClause>` * :class:`Use clause <pyVHDLModel.DesignUnit.UseClause>` """ _END_KEYWORDS: ClassVar[tuple[ReservedWord, ...]] = (ReservedWord.Context,) #: Reserved words after ``end``. _END_KEYWORDS_OPTIONAL: ClassVar[bool] = True #: The reserved words after ``end`` are optional. _IMPLICIT_LIBRARIES: ClassVar[tuple[str, ...]] = ("work", ) #: No ``std``: a context declaration has no implicit library clause (13.2). _namespace: Namespace #: The namespace of the declarations imported by this context's use clauses. def __init__(self, identifier: str, references: Nullable[Iterable[ContextUnion]] = None, documentation: Nullable[str] = None, parent: Nullable[ModelEntity] = None) -> None: """ Initializes a context declaration. :param identifier: The identifier of a model entity. :param references: Optional, all context items, in declaration order. Default: ``None``, no context items. :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. :raises TypeError: If an element of parameter 'references' is not of type :class:`LibraryClause`, :class:`UseClause` or :class:`ContextReference`. """ super().__init__(identifier, None, documentation, parent) self._namespace = Namespace(self._normalizedIdentifier) if references is not None: for reference in references: if isinstance(reference, LibraryClause): self._libraryReferences.append(reference) elif isinstance(reference, UseClause): self._packageReferences.append(reference) elif isinstance(reference, ContextReference): self._contextReferences.append(reference) else: ex = TypeError( "Element of parameter 'references' is not of type 'LibraryClause', 'UseClause' or 'ContextReference'." ) ex.add_note(f"Got type '{getFullyQualifiedName(reference)}'.") raise ex self._contextItems.append(reference) reference.Parent = self
[docs] def Visit(self, visitor: Visitor) -> None: """ Walk this context declaration and its context items with a visitor. A context declaration has no context clause: its context items are walked inside the declaration. :param visitor: The visitor receiving the events. """ visitor.VisitContext(self) for item in self._contextItems: item.Visit(visitor) visitor.VisitEnd(self) visitor.VisitTerminator(self) visitor.DepartContext(self)
[docs] def __str__(self) -> str: """ Formats the context declaration. **Format:** ``Context: mylib.myContext`` :returns: Formatted context declaration. """ lib = self._parent._identifier if self._parent is not None else "?" return f"Context: {lib}.{self._identifier}"
@export class Package( PrimaryUnit, DesignUnitWithContextMixin, WithGenericsMixin, ConcurrentDeclarationRegionMixin, WithoutStatementsMixin, AllowBlackboxMixin ): """ Represents a package declaration. .. admonition:: Example .. code-block:: VHDL package pkg is -- ... end package; .. seealso:: * :class:`Package instantiation <pyVHDLModel.Instantiation.PackageInstantiation>` * :class:`Predefined package <pyVHDLModel.Predefined.PredefinedPackage>` * :class:`Package body implementing it <pyVHDLModel.DesignUnit.PackageBody>` """ _END_KEYWORDS: ClassVar[tuple[ReservedWord, ...]] = (ReservedWord.Package,) #: Reserved words after ``end``. _END_KEYWORDS_OPTIONAL: ClassVar[bool] = True #: The reserved words after ``end`` are optional. _packageBody: Nullable[PackageBody] #: The corresponding package body, or ``None`` if none was analyzed. _deferredConstants: dict[str, DeferredConstant] #: Deferred constants, indexed by name. def __init__( self, identifier: str, contextItems: Nullable[Iterable[ContextUnion]] = None, genericItems: Nullable[Iterable[GenericInterfaceItemMixin]] = None, declaredItems: Nullable[Iterable] = None, documentation: Nullable[str] = None, allowBlackbox: Nullable[bool] = None, parent: Nullable[ModelEntity] = None, genericGroups: Nullable[Iterable[GenericGroup]] = None ) -> None: """ Initialize a package. :param identifier: Name of the VHDL package. :param contextItems: Optional, list of all context items (library, use and context clauses). Default: ``None``, no context items. :param genericItems: Optional, list of all generics, in declaration order. Default: ``None``, no generics. :param declaredItems: Optional, list of all declared items in this concurrent declaration region. Default: ``None``, no declared items. :param documentation: Optional, associated documentation of the design unit. Default: ``None``, no documentation. :param allowBlackbox: Optional, specify if blackboxes are allowed in this design. Default: ``None``, inherited from the parent. :param parent: Optional, the parent model entity (library) of this VHDL package. Default: ``None``, no parent. :param genericGroups: Optional, list of generic groups partitioning the generics, in declaration order. Default: ``None``, one unnamed generic group. """ super().__init__(identifier, contextItems, documentation, parent) DesignUnitWithContextMixin.__init__(self) ConcurrentDeclarationRegionMixin.__init__( self, self._normalizedIdentifier, declaredItems, self._CONTINUES_PARENT_REGION ) WithGenericsMixin.__init__(self, genericItems, genericGroups) AllowBlackboxMixin.__init__(self, allowBlackbox) self._packageBody = None self._deferredConstants = {} self._components = {} @readonly def PackageBody(self) -> Nullable[PackageBody]: """ Read-only property to access the package body (:attr:`_packageBody`). :returns: The package body, or ``None`` if not set. """ return self._packageBody @readonly def DeclaredItems(self) -> list: """ Read-only property to access the declared items (:attr:`_declaredItems`). :returns: List of declared items. """ return self._declaredItems @readonly def DeferredConstants(self) -> dict[str, DeferredConstant]: """ Read-only property to access the deferred constants (:attr:`_deferredConstants`). :returns: Dictionary of deferred constants, indexed by normalized identifier. """ return self._deferredConstants @readonly def Components(self) -> dict[str, Component]: """ Read-only property to access the components (:attr:`_components`). :returns: Dictionary of components, indexed by normalized identifier. """ return self._components
[docs] def IterateDeclarations(self) -> Generator[tuple[str, ModelEntity], None, None]: """ Iterate the declarations of this package a use clause can make potentially visible. A declared item contributes its normalized identifiers; an enumerated type its enumeration literals too, a physical type its units. An incomplete type is completed by its full type declaration, so it's skipped. :returns: A generator to iterate (normalized designator, declaration) pairs, in declaration order. """ for item in self._declaredItems: if isinstance(item, AnonymousType): continue elif isinstance(item, (NamedEntityMixin, MultipleNamedEntityMixin)): for normalizedIdentifier in normalizedIdentifiersOf(item): yield normalizedIdentifier, item yield from item.IterateImplicitDeclarations()
[docs] def IterateMemberDeclarations(self, memberIdentifier: str) -> Generator[tuple[str, ModelEntity], None, None]: """ Iterate the declarations of this package a use clause naming one package member makes potentially visible. These are the declarations of the package with the member's identifier, e.g. all overloads of a subprogram. A type brings its enumeration literals or physical units along (IEEE Std 1076-2008, 12.4), a subtype those of its base type: the known base type, else the type its type marks lead to, followed by simple names in the package. :param memberIdentifier: The normalized (lower case) identifier of the package member. :returns: A generator to iterate (normalized designator, declaration) pairs, in declaration order. """ for normalizedIdentifier, declaration in self.IterateDeclarations(): if normalizedIdentifier == memberIdentifier: yield normalizedIdentifier, declaration # A subtype's base type: known for a predefined subtype, else follow the type marks by simple names. baseType = declaration while isinstance(baseType, Subtype): if baseType._baseType is not None: baseType = baseType._baseType elif (typeMark := baseType._type._name)._prefix is None: result = baseType._parent._namespace.Lookup(typeMark._normalizedIdentifier, baseType) baseType = result._declarations[0] if len(result._declarations) == 1 else None else: baseType = None if baseType is not None: yield from baseType.IterateImplicitDeclarations()
[docs] def DenoteBy( self, name: Name, region: DeclarativeRegionMixin, place: ModelEntity, symbol: Symbol ) -> Nullable[ModelEntity]: """ Return this package, the model entity a name in a type mark denotes. :param name: The name denoting this declaration, a part of the type mark. :param region: The declarative region containing the type mark. :param place: The declaration containing the type mark. :param symbol: The type mark. :returns: This package. """ return self
[docs] def _IndexOtherDeclaredItem(self, item) -> None: if isinstance(item, DeferredConstant): for normalizedIdentifier in item.NormalizedIdentifiers: self._deferredConstants[normalizedIdentifier] = item elif isinstance(item, Component): self._components[item._normalizedIdentifier] = item else: super()._IndexOtherDeclaredItem(item)
[docs] def _UnindexOtherDeclaredItem(self, item: ModelEntity) -> None: """ Remove a declared item, which a concurrent declaration region doesn't handle itself. A deferred constant is removed from :attr:`_deferredConstants`. An entry referring to another deferred constant of the same identifier (a duplicate declaration) is kept: :meth:`RemoveDeclaredItem` indexes the region again. :param item: The declared item. """ if isinstance(item, DeferredConstant): for normalizedIdentifier in item._normalizedIdentifiers: if self._deferredConstants.get(normalizedIdentifier) is item: del self._deferredConstants[normalizedIdentifier] else: super()._UnindexOtherDeclaredItem(item)
[docs] def _SharedRegions(self) -> tuple[ConcurrentDeclarationRegionMixin, ...]: """ Return the other language constructs forming one declarative region with this package. :returns: Tuple of the package body, if linked (:attr:`_packageBody`). """ return () if self._packageBody is None else (self._packageBody, )
[docs] def Visit(self, visitor: Visitor) -> None: """ Walk this package declaration, its context clause, its generic clause and its declared items with a visitor. :param visitor: The visitor receiving the events. """ self._VisitContextClause(visitor) visitor.VisitPackage(self) self._VisitGenericClause(visitor) self._VisitDeclaredItems(visitor) visitor.VisitEnd(self) visitor.VisitTerminator(self) visitor.DepartPackage(self)
[docs] def __str__(self) -> str: """ Formats the package declaration. **Format:** ``Package: 'mylib.myPackage'`` :returns: Formatted package declaration. """ lib = self._parent._identifier if self._parent is not None else "?" return f"Package: '{lib}.{self._identifier}'"
[docs] def __repr__(self) -> str: """ Formats a representation of the package declaration. **Format:** ``mylib.myPackage`` :returns: String representation of the package declaration. """ lib = self._parent._identifier if self._parent is not None else "?" return f"{lib}.{self._identifier}"
[docs] def IndexDeclaredItems(self) -> None: """ A generic package's generics share the declarative region of its declarative part. :raises UnhandledCriticalWarningError: If an identifier is declared twice in a declarative region and no :class:`~pyTooling.Warning.WarningCollector` collects the :exc:`~pyVHDLModel.Exception.DuplicateDeclarationWarning`. """ self._deferredConstants.clear() self._IndexGenericItems() super().IndexDeclaredItems()
[docs] def _Declarations(self) -> tuple[ModelEntity, ...]: """ Return all declarations of this package: its generics share the declarative region. :returns: Tuple of declarations: the generics, then the declared items. """ return (*self._genericItems, *super()._Declarations())
@export class PackageBody(SecondaryUnit, DesignUnitWithContextMixin, ConcurrentDeclarationRegionMixin, WithoutStatementsMixin): """ Represents a package body declaration. .. admonition:: Example .. code-block:: VHDL package body pkg is -- ... end package body; .. seealso:: * :class:`Predefined package body <pyVHDLModel.Predefined.PredefinedPackageBody>` * :class:`Package it implements <pyVHDLModel.DesignUnit.Package>` """ _END_KEYWORDS: ClassVar[tuple[ReservedWord, ...]] = (ReservedWord.Package, ReservedWord.Body) #: Reserved words after ``end``. _END_KEYWORDS_OPTIONAL: ClassVar[bool] = True #: The reserved words after ``end`` are optional. _CONTINUES_PARENT_REGION: ClassVar[bool] = True #: A package body continues its package's declarative region. _package: PackageSymbol #: Reference to the package this body implements. def __init__( self, packageSymbol: PackageSymbol, contextItems: Nullable[Iterable[ContextUnion]] = None, declaredItems: Nullable[Iterable] = None, documentation: Nullable[str] = None, parent: Nullable[ModelEntity] = None ) -> None: """ Initializes a package body declaration. :param packageSymbol: Reference to the package this body implements. :param contextItems: Optional, list of all context items (library, use and context clauses). Default: ``None``, no context items. :param declaredItems: Optional, list of all declared items in this concurrent declaration region. Default: ``None``, no declared items. :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__(packageSymbol.Name.Identifier, contextItems, documentation, parent) DesignUnitWithContextMixin.__init__(self) ConcurrentDeclarationRegionMixin.__init__( self, self._normalizedIdentifier, declaredItems, self._CONTINUES_PARENT_REGION ) self._package = packageSymbol packageSymbol.Parent = self @readonly def Package(self) -> PackageSymbol: """ Read-only property to access the package (:attr:`_package`). :returns: The package. """ return self._package @readonly def DeclaredItems(self) -> list: """ Read-only property to access the declared items (:attr:`_declaredItems`). :returns: List of declared items. """ return self._declaredItems def LinkDeclaredItemsToPackage(self) -> None: pass
[docs] def _SharedRegions(self) -> tuple[ConcurrentDeclarationRegionMixin, ...]: """ Return the other language constructs forming one declarative region with this package body. :returns: Tuple of the package, if linked. """ package = self._package.Package return () if package is None else (package, )
[docs] def _ContextClauseUnits(self) -> tuple[DesignUnit, ...]: """ Return the design units whose context clause applies to this package body. :returns: Tuple of this package body and its package, if linked. """ package = self._package.Package return (self, ) if package is None else (self, package)
[docs] def Visit(self, visitor: Visitor) -> None: """ Walk this package body, its context clause and its declared items with a visitor. :param visitor: The visitor receiving the events. """ self._VisitContextClause(visitor) visitor.VisitPackageBody(self) self._VisitDeclaredItems(visitor) visitor.VisitEnd(self) visitor.VisitTerminator(self) visitor.DepartPackageBody(self)
[docs] def __str__(self) -> str: """ Formats the package body declaration. **Format:** ``Package Body: mylib.myPackage(body)`` :returns: Formatted package body declaration. """ lib = self._parent._identifier if self._parent is not None else "?" return f"Package Body: {lib}.{self._identifier}(body)"
[docs] def __repr__(self) -> str: """ Formats a representation of the package body declaration. **Format:** ``mylib.myPackage(body)`` :returns: String representation of the package body declaration. """ lib = self._parent._identifier if self._parent is not None else "?" return f"{lib}.{self._identifier}(body)"
@export class Entity(PrimaryUnit, DesignUnitWithContextMixin, WithGenericsMixin, WithPortsMixin, ConcurrentDeclarationRegionMixin, ConcurrentStatementsMixin, AllowBlackboxMixin): """ Represents an entity declaration. .. admonition:: Example .. code-block:: VHDL entity ent is -- ... end entity; .. seealso:: * :class:`Architecture implementing it <pyVHDLModel.DesignUnit.Architecture>` * :class:`Component declaring the same interface <pyVHDLModel.DesignUnit.Component>` * :class:`Configuration binding it <pyVHDLModel.DesignUnit.Configuration>` """ _END_KEYWORDS: ClassVar[tuple[ReservedWord, ...]] = (ReservedWord.Entity,) #: Reserved words after ``end``. _END_KEYWORDS_OPTIONAL: ClassVar[bool] = True #: The reserved words after ``end`` are optional. _architectures: dict[str, Architecture] #: Dictionary of all architectures of this entity, indexed by name. def __init__( self, identifier: str, contextItems: Nullable[Iterable[ContextUnion]] = None, genericItems: Nullable[Iterable[GenericInterfaceItemMixin]] = None, portItems: Nullable[Iterable[PortInterfaceItemMixin]] = None, declaredItems: Nullable[Iterable] = None, statements: Nullable[Iterable[ConcurrentStatement]] = None, documentation: Nullable[str] = None, allowBlackbox: Nullable[bool] = None, parent: Nullable[ModelEntity] = None, genericGroups: Nullable[Iterable[GenericGroup]] = None, portGroups: Nullable[Iterable[PortGroup]] = None ) -> None: """ Initializes an entity declaration. :param identifier: The identifier of a model entity. :param contextItems: Optional, list of all context items (library, use and context clauses). Default: ``None``, no context items. :param genericItems: Optional, list of all generics, in declaration order. Default: ``None``, no generics. :param portItems: Optional, list of all ports, in declaration order. Default: ``None``, no ports. :param declaredItems: Optional, list of all declared items in this concurrent declaration region. Default: ``None``, no declared items. :param statements: Optional, list of all concurrent statements in this construct. Default: ``None``, no statements. :param documentation: Optional, the documentation comment associated with this declaration. Default: ``None``, no documentation. :param allowBlackbox: Optional, allow blackboxes for components in language entity. Default: ``None``, inherited from the parent. :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 portGroups: Optional, list of port groups partitioning the ports, in declaration order. Default: ``None``, one unnamed port group. """ super().__init__(identifier, contextItems, documentation, parent) DesignUnitWithContextMixin.__init__(self) ConcurrentDeclarationRegionMixin.__init__( self, self._normalizedIdentifier, declaredItems, self._CONTINUES_PARENT_REGION ) WithGenericsMixin.__init__(self, genericItems, genericGroups) WithPortsMixin.__init__(self, portItems, portGroups) ConcurrentStatementsMixin.__init__(self, statements) AllowBlackboxMixin.__init__(self, allowBlackbox) self._architectures = {} @readonly def Architectures(self) -> dict[str, Architecture]: """ Read-only property to access the architectures (:attr:`_architectures`). :returns: Dictionary of architectures, indexed by normalized identifier. """ return self._architectures
[docs] def Visit(self, visitor: Visitor) -> None: """ Walk this entity, its context clause, its interface, its declared items and its statements with a visitor. :param visitor: The visitor receiving the events. """ self._VisitContextClause(visitor) visitor.VisitEntity(self) self._VisitGenericClause(visitor) self._VisitPortClause(visitor) self._VisitDeclaredItems(visitor) visitor.VisitBegin(self) self._VisitStatements(visitor) visitor.VisitEnd(self) visitor.VisitTerminator(self) visitor.DepartEntity(self)
[docs] def __str__(self) -> str: """ Formats the entity declaration. **Format:** ``Entity: 'mylib.myEntity(rtl, sim)'`` The parenthesis lists the known architectures, or ``?`` if there are none. :returns: Formatted entity declaration. """ lib = self._parent._identifier if self._parent is not None else "?" archs = ', '.join(self._architectures.keys()) if self._architectures else "?" return f"Entity: '{lib}.{self._identifier}({archs})'"
[docs] def __repr__(self) -> str: """ Formats a representation of the entity declaration. **Format:** ``mylib.myEntity(rtl, sim)`` :returns: String representation of the entity declaration. """ lib = self._parent._identifier if self._parent is not None else "?" archs = ', '.join(self._architectures.keys()) if self._architectures else "?" return f"{lib}.{self._identifier}({archs})"
[docs] def IndexDeclaredItems(self) -> None: """ An entity's generics and ports share the declarative region of its declarative part. :raises UnhandledCriticalWarningError: If an identifier is declared twice in a declarative region and no :class:`~pyTooling.Warning.WarningCollector` collects the :exc:`~pyVHDLModel.Exception.DuplicateDeclarationWarning`. """ self._IndexGenericItems() self._IndexPortItems() super().IndexDeclaredItems()
[docs] def _Declarations(self) -> tuple[ModelEntity, ...]: """ Return all declarations of this entity: its generics and ports share the declarative region. :returns: Tuple of declarations: the generics, the ports, then the declared items. """ return (*self._genericItems, *self._portItems, *super()._Declarations())
[docs] def _SharedRegions(self) -> tuple[ConcurrentDeclarationRegionMixin, ...]: """ Return the other language constructs forming one declarative region with this entity. :returns: Tuple of the linked architectures (:attr:`_architectures`). """ return tuple(self._architectures.values())
@export class Architecture(SecondaryUnit, DesignUnitWithContextMixin, ConcurrentDeclarationRegionMixin, ConcurrentStatementsMixin, AllowBlackboxMixin): """ Represents an architecture declaration. .. admonition:: Example .. code-block:: VHDL architecture rtl of ent is -- ... begin -- ... end architecture; .. seealso:: * :class:`Entity it implements <pyVHDLModel.DesignUnit.Entity>` """ _END_KEYWORDS: ClassVar[tuple[ReservedWord, ...]] = (ReservedWord.Architecture,) #: Reserved words after ``end``. _END_KEYWORDS_OPTIONAL: ClassVar[bool] = True #: The reserved words after ``end`` are optional. _CONTINUES_PARENT_REGION: ClassVar[bool] = True #: An architecture continues its entity's declarative region. _entity: EntitySymbol #: Reference to the entity this architecture implements. def __init__( self, identifier: str, entity: EntitySymbol, contextItems: Nullable[Iterable[ContextUnion]] = None, declaredItems: Nullable[Iterable] = None, statements: Iterable[ConcurrentStatement] = None, documentation: Nullable[str] = None, allowBlackbox: Nullable[bool] = None, parent: Nullable[ModelEntity] = None ) -> None: """ Initializes an architecture declaration. :param identifier: The identifier of a model entity. :param entity: Reference to the entity this architecture implements. :param contextItems: Optional, list of all context items (library, use and context clauses). Default: ``None``, no context items. :param declaredItems: Optional, list of all declared items in this concurrent declaration region. Default: ``None``, no declared items. :param statements: Optional, list of all concurrent statements in this construct. Default: ``None``, no statements. :param documentation: Optional, the documentation comment associated with this declaration. Default: ``None``, no documentation. :param allowBlackbox: Optional, allow blackboxes for components in language entity. Default: ``None``, inherited from the parent. :param parent: Optional, the parent model entity of this entity. Default: ``None``, no parent. """ super().__init__(identifier, contextItems, documentation, parent) DesignUnitWithContextMixin.__init__(self) ConcurrentDeclarationRegionMixin.__init__( self, self._normalizedIdentifier, declaredItems, self._CONTINUES_PARENT_REGION ) ConcurrentStatementsMixin.__init__(self, statements) AllowBlackboxMixin.__init__(self, allowBlackbox) self._entity = entity entity.Parent = self @readonly def Entity(self) -> EntitySymbol: # FIXME: change to entitySymbol, offer entity directly, but raise exception if not resolved. """ Read-only property to access the entity (:attr:`_entity`). :returns: The entity. """ return self._entity
[docs] def Visit(self, visitor: Visitor) -> None: """ Walk this architecture, its context clause, its entity, its declared items and its statements with a visitor. :param visitor: The visitor receiving the events. """ self._VisitContextClause(visitor) visitor.VisitArchitecture(self) self._entity.Visit(visitor) visitor.VisitIs(self) self._VisitDeclaredItems(visitor) visitor.VisitBegin(self) self._VisitStatements(visitor) visitor.VisitEnd(self) visitor.VisitTerminator(self) visitor.DepartArchitecture(self)
[docs] def __str__(self) -> str: """ Formats the architecture declaration. **Format:** ``Architecture: mylib.myEntity(rtl)`` :returns: Formatted architecture declaration. """ lib = self._parent._identifier if self._parent is not None else "?" ent = self._entity._name._identifier if self._entity is not None else "?" return f"Architecture: {lib}.{ent}({self._identifier})"
[docs] def __repr__(self) -> str: """ Formats a representation of the architecture declaration. **Format:** ``mylib.myEntity(rtl)`` :returns: String representation of the architecture declaration. """ lib = self._parent._identifier if self._parent is not None else "?" ent = self._entity._name._identifier if self._entity is not None else "?" return f"{lib}.{ent}({self._identifier})"
[docs] def _SharedRegions(self) -> tuple[ConcurrentDeclarationRegionMixin, ...]: """ Return the other language constructs forming one declarative region with this architecture. :returns: Tuple of the entity, if linked. """ entity = self._entity.Entity return () if entity is None else (entity, )
[docs] def _ContextClauseUnits(self) -> tuple[DesignUnit, ...]: """ Return the design units whose context clause applies to this architecture. :returns: Tuple of this architecture and its entity, if linked. """ entity = self._entity.Entity return (self, ) if entity is None else (self, entity)
@export class Component( ModelEntity, NamedEntityMixin, DocumentedEntityMixin, WithGenericsMixin, WithPortsMixin, DeclarativeRegionMixin, WithoutStatementsMixin, AllowBlackboxMixin ): """ Represents a component declaration. A component declaration is a declarative region (IEEE Std 1076-2008, 12.1): its generics and ports share one namespace, nested in the namespace of the declarative region declaring the component. A component has no declarative part, so it has no declared items and no mutators for them. .. admonition:: Example .. code-block:: VHDL component ent is -- ... end component; .. seealso:: * :class:`Entity it may be bound to <pyVHDLModel.DesignUnit.Entity>` * :class:`Component configuration <pyVHDLModel.Configuration.ComponentConfiguration>` """ _END_KEYWORDS: ClassVar[tuple[ReservedWord, ...]] = (ReservedWord.Component,) #: Reserved words after ``end``. _END_KEYWORDS_OPTIONAL: ClassVar[bool] = False #: The reserved words after ``end`` are optional. _isBlackbox: Nullable[bool] #: Component is a blackbox. _entity: Nullable[Entity] #: Linked entity, or ``None`` if unresolved. _namespace: Namespace #: The namespace of this component's declarative region. def __init__( self, identifier: str, genericItems: Nullable[Iterable[GenericInterfaceItemMixin]] = None, portItems: Nullable[Iterable[PortInterfaceItemMixin]] = None, documentation: Nullable[str] = None, allowBlackbox: Nullable[bool] = None, parent: Nullable[ModelEntity] = None, genericGroups: Nullable[Iterable[GenericGroup]] = None, portGroups: Nullable[Iterable[PortGroup]] = None ) -> None: """ Initializes a component declaration. :param identifier: The identifier of a model entity. :param genericItems: Optional, list of all generics of this component, in declaration order. Default: ``None``, no generics. :param portItems: Optional, list of all ports of this component, in declaration order. Default: ``None``, no ports. :param documentation: Optional, the documentation comment associated with this declaration. Default: ``None``, no documentation. :param allowBlackbox: Optional, allow blackboxes for components in language entity. Default: ``None``, inherited from the parent. :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 portGroups: Optional, list of port groups partitioning the ports, in declaration order. Default: ``None``, one unnamed port group. """ super().__init__(parent) NamedEntityMixin.__init__(self, identifier) DocumentedEntityMixin.__init__(self, documentation) DeclarativeRegionMixin.__init__(self) self._namespace = Namespace(self._normalizedIdentifier) WithGenericsMixin.__init__(self, genericItems, genericGroups) WithPortsMixin.__init__(self, portItems, portGroups) AllowBlackboxMixin.__init__(self, allowBlackbox) self._isBlackbox = None self._entity = None @ModelEntity.Parent.setter def Parent(self, parent: ModelEntity) -> None: ModelEntity.Parent.fset(self, parent) self._ConnectParentNamespace(parent)
[docs] def Visit(self, visitor: Visitor) -> None: """ Walk this component declaration, its generic clause and its port clause with a visitor. :param visitor: The visitor receiving the events. """ visitor.VisitComponent(self) self._VisitGenericClause(visitor) self._VisitPortClause(visitor) visitor.VisitEnd(self) visitor.VisitTerminator(self) visitor.DepartComponent(self)
[docs] def IndexDeclaredItems(self) -> None: """ Index the generics and ports of this component in its namespace. :raises UnhandledCriticalWarningError: If an identifier is declared twice in the component and no :class:`~pyTooling.Warning.WarningCollector` collects the :exc:`~pyVHDLModel.Exception.DuplicateDeclarationWarning`. """ self._IndexGenericItems() self._IndexPortItems() self._areDeclaredItemsIndexed = True
[docs] def _Declarations(self) -> tuple[ModelEntity, ...]: """ Return all declarations of this component. :returns: Tuple of declarations: the generics, then the ports. """ return (*self._genericItems, *self._portItems)
@readonly def IsBlackbox(self) -> Nullable[bool]: """ Check if the component is a blackbox (:attr:`_isBlackbox`). If components were not linked to matching entities, this property returns ``None``. :returns: ``True``, if the component is a blackbox; ``False``, if it is not; ``None``, if components were not linked to entities yet. """ return self._isBlackbox @property def Entity(self) -> Nullable[Entity]: """ Property to access the entity (:attr:`_entity`). :returns: The entity, or ``None`` if not set. """ return self._entity @Entity.setter def Entity(self, value: Entity) -> None: self._entity = value self._isBlackbox = False
[docs] def __str__(self) -> str: """ Formats the component declaration. **Format:** ``Component: myComponent`` :returns: Formatted component declaration. """ return f"Component: {self._identifier}"
[docs] def __repr__(self) -> str: """ Formats a representation of the component declaration. **Format:** ``mylib.myPackage:myComponent`` :returns: String representation of the component declaration. """ return f"{self._parent!r}:{self._identifier}"
@export class Configuration(PrimaryUnit, DesignUnitWithContextMixin): """ Represents a configuration declaration. .. admonition:: Example .. code-block:: VHDL configuration cfg of ent is for rtl -- ... end for; end configuration; .. seealso:: * :class:`Entity it configures <pyVHDLModel.DesignUnit.Entity>` * :class:`Block configuration <pyVHDLModel.Configuration.BlockConfiguration>` """ _END_KEYWORDS: ClassVar[tuple[ReservedWord, ...]] = (ReservedWord.Configuration,) #: Reserved words after ``end``. _END_KEYWORDS_OPTIONAL: ClassVar[bool] = True #: The reserved words after ``end`` are optional. _entity: EntitySymbol #: Reference to the entity this configuration configures. _blockConfiguration: BlockConfiguration #: The configuration of the entity's architecture. _namespace: Namespace #: The namespace of this configuration's declarative region. def __init__( self, identifier: str, entity: EntitySymbol, blockConfiguration: BlockConfiguration, contextItems: Nullable[Iterable[ContextUnion]] = None, documentation: Nullable[str] = None, parent: Nullable[ModelEntity] = None ) -> None: """ Initializes a configuration declaration. :param identifier: The identifier of a model entity. :param entity: Reference to the entity this configuration configures. :param blockConfiguration: The configuration of the entity's architecture. :param contextItems: Optional, list of all context items (library, use and context clauses). Default: ``None``, no context items. :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, parent) DesignUnitWithContextMixin.__init__(self) self._namespace = Namespace(self._normalizedIdentifier) self._entity = entity entity.Parent = self self._blockConfiguration = blockConfiguration blockConfiguration.Parent = self @readonly def Entity(self) -> EntitySymbol: """ Read-only property to access the entity (:attr:`_entity`). :returns: The entity. """ return self._entity @readonly def BlockConfiguration(self) -> BlockConfiguration: """ Read-only property to access the block configuration (:attr:`_blockConfiguration`). :returns: The block configuration. """ return self._blockConfiguration
[docs] def Visit(self, visitor: Visitor) -> None: """ Walk this configuration, its context clause, its entity and its block configuration with a visitor. :param visitor: The visitor receiving the events. """ self._VisitContextClause(visitor) visitor.VisitConfiguration(self) self._entity.Visit(visitor) visitor.VisitIs(self) self._blockConfiguration.Visit(visitor) visitor.VisitEnd(self) visitor.VisitTerminator(self) visitor.DepartConfiguration(self)
[docs] def __str__(self) -> str: """ Formats the configuration declaration. **Format:** ``Configuration: mylib.myConfiguration`` :returns: Formatted configuration declaration. """ lib = self._parent._identifier if self._parent is not None else "?" return f"Configuration: {lib}.{self._identifier}"
[docs] def __repr__(self) -> str: """ Formats a representation of the configuration declaration. **Format:** ``mylib.myConfiguration`` :returns: String representation of the configuration declaration. """ lib = self._parent._identifier if self._parent is not None else "?" return f"{lib}.{self._identifier}"