# ==================================================================================================================== #
# __ ___ _ ____ _ __ __ _ _ #
# _ __ _ \ \ / / | | | _ \| | | \/ | ___ __| | ___| | #
# | '_ \| | | \ \ / /| |_| | | | | | | |\/| |/ _ \ / _` |/ _ \ | #
# | |_) | |_| |\ V / | _ | |_| | |___| | | | (_) | (_| | __/ | #
# | .__/ \__, | \_/ |_| |_|____/|_____|_| |_|\___/ \__,_|\___|_| #
# |_| |___/ #
# ==================================================================================================================== #
# Authors: #
# Patrick Lehmann #
# #
# License: #
# ==================================================================================================================== #
# Copyright 2026-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 #
# ==================================================================================================================== #
#
"""
This module contains parts of an abstract document language model for VHDL.
Configurations: entity aspects, binding indications, component configurations (and the structurally
identical configuration specifications), and block configurations.
"""
from __future__ import annotations
from typing import TYPE_CHECKING, ClassVar, Iterable, Union, Optional as Nullable
from pyTooling.Decorators import export, readonly
from pyTooling.MetaClasses import abstractclass
from pyVHDLModel.Base import ModelEntity, DocumentedEntityMixin, ReservedWord
from pyVHDLModel.Name import Name
from pyVHDLModel.Symbol import Symbol, EntitySymbol, ArchitectureSymbol, ConfigurationSymbol, \
ComponentInstantiationSymbol
from pyVHDLModel.Association import GenericAssociationItem, PortAssociationItem, GenericMapAspectMixin, \
PortMapAspectMixin
if TYPE_CHECKING:
from pyVHDLModel.Visitor import Visitor
@export
@abstractclass
class EntityAspect(ModelEntity):
"""
Base-class for the three forms an entity aspect can take in a binding indication: an entity
(optionally with an architecture), a configuration, or ``open``.
.. admonition:: Example
.. code-block:: VHDL
for U1 : comp use entity work.sub(behav);
-- ^^^^^^^^^^^^^^^^^^^^^^
.. seealso::
* :class:`Entity aspect entity <pyVHDLModel.Configuration.EntityAspectEntity>`
* :class:`Entity aspect configuration <pyVHDLModel.Configuration.EntityAspectConfiguration>`
* :class:`Entity aspect open <pyVHDLModel.Configuration.EntityAspectOpen>`
"""
@export
class EntityAspectEntity(EntityAspect):
"""
Represents an entity aspect naming an entity, optionally with an architecture.
.. admonition:: Example
.. code-block:: VHDL
use entity work.e_rest(rtl);
-- ^^^^^^^^^^^ <- Entity
-- ^^^ <- Architecture
"""
_entity: EntitySymbol #: Reference to the named entity.
_architecture: Nullable[ArchitectureSymbol] #: Reference to the selected architecture, or ``None`` if none was given.
def __init__(
self,
entity: EntitySymbol,
architecture: Nullable[ArchitectureSymbol] = None,
parent: Nullable[ModelEntity] = None
) -> None:
"""
Initializes an entity aspect naming an entity, optionally with an architecture.
:param entity: Reference to the named entity.
:param architecture: Optional, reference to the selected architecture. Default: ``None``, no architecture selected.
:param parent: Optional, the parent model entity of this entity. Default: ``None``, no parent.
"""
super().__init__(parent)
self._entity = entity
entity.Parent = self
self._architecture = architecture
if architecture is not None:
architecture.Parent = self
[docs]
def Visit(self, visitor: Visitor) -> None:
"""
Walk this entity aspect, its entity and its architecture (if any) with a visitor.
:param visitor: The visitor receiving the events.
"""
visitor.VisitEntityAspectEntity(self)
self._entity.Visit(visitor)
if self._architecture is not None:
visitor.VisitLeftParenthesis(self)
self._architecture.Visit(visitor)
visitor.VisitRightParenthesis(self)
visitor.DepartEntityAspectEntity(self)
@readonly
def Entity(self) -> EntitySymbol:
"""
Read-only property to access the entity (:attr:`_entity`).
:returns: The entity.
"""
return self._entity
@readonly
def Architecture(self) -> Nullable[ArchitectureSymbol]:
"""
Read-only property to access the architecture (:attr:`_architecture`).
:returns: The architecture, or ``None`` if not set.
"""
return self._architecture
@export
class EntityAspectConfiguration(EntityAspect):
"""
Represents an entity aspect naming a configuration.
.. admonition:: Example
.. code-block:: VHDL
use configuration work.cfg;
-- ^^^^^^^^ <- Configuration
"""
_configuration: ConfigurationSymbol #: Reference to the named configuration.
def __init__(self, configuration: ConfigurationSymbol, parent: Nullable[ModelEntity] = None) -> None:
"""
Initializes an entity aspect naming a configuration.
:param configuration: Reference to the named configuration.
:param parent: Optional, the parent model entity of this entity. Default: ``None``, no parent.
"""
super().__init__(parent)
self._configuration = configuration
configuration.Parent = self
[docs]
def Visit(self, visitor: Visitor) -> None:
"""
Walk this entity aspect and its configuration with a visitor.
:param visitor: The visitor receiving the events.
"""
visitor.VisitEntityAspectConfiguration(self)
self._configuration.Visit(visitor)
visitor.DepartEntityAspectConfiguration(self)
@readonly
def Configuration(self) -> ConfigurationSymbol:
"""
Read-only property to access the configuration (:attr:`_configuration`).
:returns: The configuration.
"""
return self._configuration
@export
class EntityAspectOpen(EntityAspect):
"""
Represents an open entity aspect, leaving the binding unspecified.
.. admonition:: Example
.. code-block:: VHDL
use open;
-- ^^^^ <- the aspect
"""
[docs]
def Visit(self, visitor: Visitor) -> None:
"""
Walk this open entity aspect with a visitor.
:param visitor: The visitor receiving the events.
"""
visitor.VisitEntityAspectOpen(self)
visitor.DepartEntityAspectOpen(self)
@export
class BindingIndication(ModelEntity, GenericMapAspectMixin, PortMapAspectMixin):
"""
Represents a binding indication: which design entity a component is bound to.
The entity aspect is available as :data:`EntityAspect`, together with the generic and port maps
(:attr:`~pyVHDLModel.Association.GenericMapAspectMixin.GenericAssociationItems`,
:attr:`~pyVHDLModel.Association.PortMapAspectMixin.PortAssociationItems`).
"""
_entityAspect: Nullable[EntityAspect] #: The bound design entity, or ``None`` if not given.
def __init__(
self,
entityAspect: Nullable[EntityAspect] = None,
genericAssociationItems: Nullable[Iterable[GenericAssociationItem]] = None,
portAssociationItems: Nullable[Iterable[PortAssociationItem]] = None,
parent: Nullable[ModelEntity] = None
) -> None:
"""
Initializes a binding indication.
:param entityAspect: Optional, the bound design entity. Default: ``None``, no entity aspect.
:param genericAssociationItems: Optional, list of all generic associations in the generic map aspect.
Default: ``None``, no generic associations.
:param portAssociationItems: Optional, list of all port associations in the port map aspect.
Default: ``None``, no port associations.
:param parent: Optional, the parent model entity of this entity. Default: ``None``, no parent.
"""
super().__init__(parent)
GenericMapAspectMixin.__init__(self, genericAssociationItems)
PortMapAspectMixin.__init__(self, portAssociationItems)
self._entityAspect = entityAspect
if entityAspect is not None:
entityAspect.Parent = self
[docs]
def Visit(self, visitor: Visitor) -> None:
"""
Walk this binding indication, its entity aspect and its map aspects with a visitor.
:param visitor: The visitor receiving the events.
"""
visitor.VisitBindingIndication(self)
if self._entityAspect is not None:
self._entityAspect.Visit(visitor)
self._VisitGenericMapAspect(visitor)
self._VisitPortMapAspect(visitor)
visitor.DepartBindingIndication(self)
@readonly
def EntityAspect(self) -> Nullable[EntityAspect]:
"""
Read-only property to access the entity aspect (:attr:`_entityAspect`).
:returns: The entity aspect, or ``None`` if not set.
"""
return self._entityAspect
@export
class AllInstantiationList(ModelEntity):
"""
Represents an instantiation list naming ``all`` instances of a component.
.. admonition:: Example
.. code-block:: VHDL
for all : comp use entity work.sub(behav);
-- ^^^ <- the instantiation list
"""
[docs]
def Visit(self, visitor: Visitor) -> None:
"""
Walk this ``all`` instantiation list with a visitor.
:param visitor: The visitor receiving the events.
"""
visitor.VisitAllInstantiationList(self)
visitor.DepartAllInstantiationList(self)
@export
class OthersInstantiationList(ModelEntity):
"""
Represents an instantiation list naming all instances not configured elsewhere.
.. admonition:: Example
.. code-block:: VHDL
for others : comp use entity work.sub(behav);
-- ^^^^^^ <- the instantiation list
"""
[docs]
def Visit(self, visitor: Visitor) -> None:
"""
Walk this ``others`` instantiation list with a visitor.
:param visitor: The visitor receiving the events.
"""
visitor.VisitOthersInstantiationList(self)
visitor.DepartOthersInstantiationList(self)
InstantiationListUnion = Union[list[Name], AllInstantiationList, OthersInstantiationList]
@export
class ComponentConfiguration(ModelEntity, DocumentedEntityMixin):
"""
Represents a component configuration (inside a block configuration), or - structurally identical
- a configuration specification (declared directly in an architecture's declarative part).
.. admonition:: Example
.. code-block:: VHDL
for U1 : comp use entity work.sub(behav);
-- ^^ ^^^^
-- | Component name
-- Instantiation list
"""
_END_KEYWORDS: ClassVar[tuple[ReservedWord, ...]] = (ReservedWord.For,) #: Reserved words after ``end``.
_END_KEYWORDS_OPTIONAL: ClassVar[bool] = False #: The reserved words after ``end`` are optional.
_instantiationList: InstantiationListUnion #: The instances this configuration applies to.
_componentName: ComponentInstantiationSymbol #: Reference to the component being configured.
_bindingIndication: Nullable[BindingIndication] #: The binding indication, or ``None`` if none was given.
def __init__(
self,
instantiationList: InstantiationListUnion,
componentName: ComponentInstantiationSymbol,
bindingIndication: Nullable[BindingIndication] = None,
documentation: Nullable[str] = None,
parent: Nullable[ModelEntity] = None
) -> None:
"""
Initializes a component configuration.
:param instantiationList: The instances this configuration applies to.
:param componentName: Reference to the component being configured.
:param bindingIndication: Optional, the binding indication. Default: ``None``, no binding indication.
: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__(parent)
DocumentedEntityMixin.__init__(self, documentation)
if isinstance(instantiationList, (AllInstantiationList, OthersInstantiationList)):
self._instantiationList = instantiationList
instantiationList.Parent = self
else:
self._instantiationList = list(instantiationList)
for label in self._instantiationList:
label.Parent = self
self._componentName = componentName
componentName.Parent = self
self._bindingIndication = bindingIndication
if bindingIndication is not None:
bindingIndication.Parent = self
[docs]
def Visit(self, visitor: Visitor) -> None:
"""
Walk this component configuration, its component specification and its binding indication with a visitor.
:param visitor: The visitor receiving the events.
"""
visitor.VisitComponentConfiguration(self)
visitor.VisitInstantiationList(self)
if isinstance(self._instantiationList, list):
for index, label in enumerate(self._instantiationList):
if index > 0:
visitor.VisitNameListSeparator(self)
label.Visit(visitor)
else:
self._instantiationList.Visit(visitor)
visitor.DepartInstantiationList(self)
self._componentName.Visit(visitor)
if self._bindingIndication is not None:
self._bindingIndication.Visit(visitor)
visitor.VisitEnd(self)
visitor.VisitTerminator(self)
visitor.DepartComponentConfiguration(self)
@readonly
def InstantiationList(self) -> InstantiationListUnion:
"""
Read-only property to access the instantiation list (:attr:`_instantiationList`).
:returns: The instantiation list.
"""
return self._instantiationList
@readonly
def ComponentName(self) -> ComponentInstantiationSymbol:
"""
Read-only property to access the component name (:attr:`_componentName`).
:returns: The component name.
"""
return self._componentName
@readonly
def BindingIndication(self) -> Nullable[BindingIndication]:
"""
Read-only property to access the binding indication (:attr:`_bindingIndication`).
:returns: The binding indication, or ``None`` if not set.
"""
return self._bindingIndication
@export
class BlockConfiguration(ModelEntity, DocumentedEntityMixin):
"""
Represents the configuration of one block: an architecture, a block statement or a generate body.
Nested configurations are available as :attr:`Items`.
.. admonition:: Example
.. code-block:: VHDL
for rtl
-- ^^^ <- Block
end for;
"""
_END_KEYWORDS: ClassVar[tuple[ReservedWord, ...]] = (ReservedWord.For,) #: Reserved words after ``end``.
_END_KEYWORDS_OPTIONAL: ClassVar[bool] = False #: The reserved words after ``end`` are optional.
_blockSpecification: Symbol #: The configured block.
_items: list[Union[BlockConfiguration, ComponentConfiguration]] #: Nested configurations.
def __init__(
self,
blockSpecification: Symbol,
items: Nullable[Iterable[Union[BlockConfiguration, ComponentConfiguration]]] = None,
documentation: Nullable[str] = None,
parent: Nullable[ModelEntity] = None
) -> None:
"""
Initializes a block configuration.
:param blockSpecification: The configured block.
:param items: Optional, nested configurations. Default: ``None``, no nested configurations.
: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__(parent)
DocumentedEntityMixin.__init__(self, documentation)
self._blockSpecification = blockSpecification
blockSpecification.Parent = self
self._items = itemList = []
if items is not None:
for item in items:
itemList.append(item)
item.Parent = self
[docs]
def Visit(self, visitor: Visitor) -> None:
"""
Walk this block configuration, its block specification and its nested configurations with a visitor.
:param visitor: The visitor receiving the events.
"""
visitor.VisitBlockConfiguration(self)
visitor.VisitBlockSpecification(self)
self._blockSpecification.Visit(visitor)
visitor.DepartBlockSpecification(self)
for item in self._items:
item.Visit(visitor)
visitor.VisitEnd(self)
visitor.VisitTerminator(self)
visitor.DepartBlockConfiguration(self)
@readonly
def BlockSpecification(self) -> Symbol:
"""
Read-only property to access the block specification (:attr:`_blockSpecification`).
:returns: The block specification.
"""
return self._blockSpecification
@readonly
def Items(self) -> list[Union[BlockConfiguration, ComponentConfiguration]]:
"""
Read-only property to access the items (:attr:`_items`).
:returns: List of items.
"""
return self._items