Source code for pyVHDLModel.Declaration

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


"""
from __future__             import annotations

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

from pyTooling.Decorators   import export, readonly
from pyTooling.Warning      import WarningCollector

from pyVHDLModel.Base       import ModelEntity, NamedEntityMixin, DocumentedEntityMixin, ReservedWord as _ReservedWord
from pyVHDLModel.Expression import BaseExpression, QualifiedExpression, FunctionCall, TypeConversion, Literal
from pyVHDLModel.Exception  import UnresolvedNameWarning, UnresolvedTypeMarkWarning
from pyVHDLModel.Name       import Name, SimpleName
from pyVHDLModel.Symbol     import PossibleReference, Symbol, SubtypeSymbol

if TYPE_CHECKING:
	from pyVHDLModel.DesignUnit import DesignUnit
	from pyVHDLModel.Regions  import DeclarativeRegionMixin
	from pyVHDLModel.Visitor  import Visitor



ExpressionUnion = Union[
	BaseExpression,
	QualifiedExpression,
	FunctionCall,
	TypeConversion,
	# ConstantOrSymbol,     TODO: ObjectSymbol
	Literal,
]


@export
@unique
class EntityClass(Enum):
	"""An ``EntityClass`` is an enumeration. It represents a VHDL language entity class (``entity``, ``label``, ...)."""

	Entity =        0   #: Entity
	Architecture =  1   #: Architecture
	Configuration = 2   #: Configuration
	Procedure =     3   #: Procedure
	Function =      4   #: Function
	Package =       5   #: Package
	Type =          6   #: Type
	Subtype =       7   #: Subtype
	Constant =      8   #: Constant
	Signal =        9   #: Signal
	Variable =      10  #: Variable
	Component =     11  #: Component
	Label =         12  #: Label
	Literal =       13  #: Literal
	Units =         14  #: Units
	Group =         15  #: Group
	File =          16  #: File
	Property =      17  #: Property
	Sequence =      18  #: Sequence
	View =          19  #: View
	Others =        20  #: Others

	__RESERVED_WORDS: ClassVar[dict[int, _ReservedWord]] = {
		0:  _ReservedWord.Entity,
		1:  _ReservedWord.Architecture,
		2:  _ReservedWord.Configuration,
		3:  _ReservedWord.Procedure,
		4:  _ReservedWord.Function,
		5:  _ReservedWord.Package,
		6:  _ReservedWord.Type,
		7:  _ReservedWord.Subtype,
		8:  _ReservedWord.Constant,
		9:  _ReservedWord.Signal,
		10: _ReservedWord.Variable,
		11: _ReservedWord.Component,
		12: _ReservedWord.Label,
		13: _ReservedWord.Literal,
		14: _ReservedWord.Units,
		15: _ReservedWord.Group,
		16: _ReservedWord.File,
		17: _ReservedWord.Property,
		18: _ReservedWord.Sequence,
		19: _ReservedWord.View
	}  #: The reserved word of each entity class, by value; ``Others`` has none.

	@readonly
	def ReservedWord(self) -> Nullable[_ReservedWord]:
		"""
		Read-only property to return the reserved word of the entity class.

		:returns: The reserved word, or ``None`` for ``EntityClass.Others``.
		"""
		return self.__RESERVED_WORDS.get(self.value, None)


@export
class Attribute(ModelEntity, NamedEntityMixin, DocumentedEntityMixin):
	"""
	Represents an attribute declaration.

	.. admonition:: Example

	   .. code-block:: VHDL

	      attribute TotalBits : natural;
	"""

	_subtype: Symbol  #: Reference to the attribute's subtype.

	def __init__(
		self,
		identifier: str,
		subtype: Symbol,
		documentation: Nullable[str] = None,
		parent: Nullable[ModelEntity] = None
	) -> None:
		"""
		Initializes an attribute declaration.

		:param identifier:    The identifier of a model entity.
		:param subtype:       Reference to the attribute's subtype.
		: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)
		NamedEntityMixin.__init__(self, identifier)
		DocumentedEntityMixin.__init__(self, documentation)

		self._subtype = subtype
		subtype.Parent = self

[docs] def Visit(self, visitor: Visitor) -> None: """ Walk this attribute declaration and its subtype with a visitor. :param visitor: The visitor receiving the events. """ visitor.VisitAttribute(self) self._subtype.Visit(visitor) visitor.VisitTerminator(self) visitor.DepartAttribute(self)
@readonly def Subtype(self) -> None: """ Read-only property to access the subtype (:attr:`_subtype`). :returns: The subtype. """ return self._subtype
[docs] def IterateTypeMarks( self, region: DeclarativeRegionMixin ) -> Generator[tuple[DeclarativeRegionMixin, ModelEntity, SubtypeSymbol], None, None]: """ Iterate the type marks of this attribute declaration: the type mark of its values. :param region: The declarative region declaring this attribute. :returns: A generator to iterate (region, place, type mark) tuples: the attribute's type mark. """ if isinstance(self._subtype, SubtypeSymbol): yield region, self, self._subtype
[docs] def __str__(self) -> str: """ Formats the attribute declaration. **Format:** ``attribute myAttribute: bit`` :returns: Formatted attribute declaration. """ return f"attribute {self._identifier}: {self._subtype}"
@export class AttributeSpecification(ModelEntity, DocumentedEntityMixin): """ Represents an attribute specification. .. admonition:: Example .. code-block:: VHDL attribute TotalBits of BusType : subtype is 32; """ _identifiers: list[Name] #: List of all names the attribute is specified for. _attribute: Name #: Reference to the specified attribute. _entityClass: EntityClass #: The entity class the named items belong to. _expression: ExpressionUnion #: The value assigned to the attribute. def __init__( self, identifiers: Iterable[Name], attribute: Name, entityClass: EntityClass, expression: ExpressionUnion, documentation: Nullable[str] = None, parent: Nullable[ModelEntity] = None ) -> None: """ Initializes an attribute specification. :param identifiers: List of all names the attribute is specified for. :param attribute: Reference to the specified attribute. :param entityClass: The entity class the named items belong to. :param expression: The value assigned to the attribute. :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._identifiers = identifierList = [] # TODO: convert to dict for identifier in identifiers: identifierList.append(identifier) identifier.Parent = self self._attribute = attribute attribute.Parent = self self._entityClass = entityClass self._expression = expression expression.Parent = self
[docs] def Visit(self, visitor: Visitor) -> None: """ Walk this attribute specification, its attribute, its entity specification and its expression with a visitor. :param visitor: The visitor receiving the events. """ visitor.VisitAttributeSpecification(self) self._attribute.Visit(visitor) visitor.VisitEntitySpecification(self) for index, name in enumerate(self._identifiers): if index > 0: visitor.VisitNameListSeparator(self) name.Visit(visitor) visitor.DepartEntitySpecification(self) visitor.VisitIs(self) self._expression.Visit(visitor) visitor.VisitTerminator(self) visitor.DepartAttributeSpecification(self)
@readonly def Identifiers(self) -> list[Name]: """ Read-only property to access the identifiers (:attr:`_identifiers`). :returns: List of identifiers. """ return self._identifiers @readonly def Attribute(self) -> Name: """ Read-only property to access the attribute (:attr:`_attribute`). :returns: The attribute. """ return self._attribute @readonly def EntityClass(self) -> EntityClass: """ Read-only property to access the entity class (:attr:`_entityClass`). :returns: The entity class. """ return self._entityClass @readonly def Expression(self) -> ExpressionUnion: """ Read-only property to access the expression (:attr:`_expression`). :returns: The expression. """ return self._expression # TODO: move somewhere else @export class Alias(ModelEntity, NamedEntityMixin, DocumentedEntityMixin): """ Represents an alias declaration. :attr:`Name` is a :class:`~pyVHDLModel.Symbol.Symbol` - like every other cross-reference in this model - rather than a bare :class:`~pyVHDLModel.Name.Name`, so it participates in the usual resolve-later mechanism (:attr:`~pyVHDLModel.Symbol.Symbol.Reference` / :attr:`~pyVHDLModel.Symbol.Symbol.IsResolved`). Unlike ``PackageReferenceSymbol`` and similar, there is no single fixed :class:`~pyVHDLModel.Symbol.PossibleReference` value that always fits: an alias without a subtype indication can refer to almost anything nameable (an object, a type, a subprogram, a literal, ...), while an alias *with* a subtype indication can - per the LRM - only ever refer to an object (a constant, variable, signal, or file); the ``possibleReferences`` passed to the ``Symbol`` should reflect whichever case applies. .. admonition:: Example .. code-block:: VHDL alias a : bit_vector(3 downto 0) is s(3 downto 0); -- ^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^ -- optional Subtype Name alias b is s; -- ^ -- Name """ _IMPLICIT_OPERATIONS: ClassVar[frozenset[str]] = frozenset(( "to_string", "to_bstring", "to_binary_string", "to_ostring", "to_octal_string", "to_hstring", "to_hex_string", "minimum", "maximum", "deallocate", "file_open", "file_close", "read", "write", "endfile", "flush" )) #: Normalized identifiers of implicitly declared operations (IEEE Std 1076-2008, 5), which aren't represented. _name: Symbol #: Reference to the name being aliased. _subtype: Nullable[SubtypeSymbol] #: Reference to the alias' subtype, or ``None`` if none was given. def __init__( self, identifier: str, name: Symbol, subtype: Nullable[SubtypeSymbol] = None, documentation: Nullable[str] = None, parent: Nullable[ModelEntity] = None ) -> None: """ Initializes an alias declaration. :param identifier: The identifier of a model entity. :param name: Reference to the name being aliased. :param subtype: Optional, reference to the alias' subtype. Default: ``None``, no subtype 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) NamedEntityMixin.__init__(self, identifier) DocumentedEntityMixin.__init__(self, documentation) self._name = name name.Parent = self self._subtype = subtype if subtype is not None: subtype.Parent = self
[docs] def Visit(self, visitor: Visitor) -> None: """ Walk this alias declaration, its subtype (if any) and its name with a visitor. :param visitor: The visitor receiving the events. """ visitor.VisitAlias(self) if self._subtype is not None: self._subtype.Visit(visitor) visitor.VisitIs(self) self._name.Visit(visitor) visitor.VisitTerminator(self) visitor.DepartAlias(self)
@readonly def Name(self) -> Symbol: """ Read-only property to access the name (:attr:`_name`). :returns: The name. """ return self._name @readonly def Subtype(self) -> Nullable[SubtypeSymbol]: """ Read-only property to access the subtype (:attr:`_subtype`). :returns: The subtype, or ``None`` if not set. """ return self._subtype @readonly def IsOverloadable(self) -> bool: """ Check if this alias is overloadable: it has no subtype indication, and its name may denote a subprogram or an enumeration literal. The resolved name (:attr:`~pyVHDLModel.Symbol.Symbol.Reference`) decides, else the name's possible references, e.g. ``alias To_SLV is To_StdLogicVector [std_ulogic_vector return std_logic_vector];``. :returns: ``True``, if this alias is overloadable. """ if self._subtype is not None: return False elif (reference := self._name._reference) is not None: return reference.IsOverloadable overloadables = PossibleReference.SubProgram | PossibleReference.EnumLiteral return (self._name._possibleReferences & overloadables) != PossibleReference.Unknown
[docs] def IterateTypeMarks( self, region: DeclarativeRegionMixin ) -> Generator[tuple[DeclarativeRegionMixin, ModelEntity, SubtypeSymbol], None, None]: """ Iterate the type marks of this alias: the type mark of its subtype indication, if it has one. :param region: The declarative region declaring this alias. :returns: A generator to iterate (region, place, type mark) tuples: the alias' subtype indication, if given. """ if self._subtype is not None: yield region, self, self._subtype
[docs] def ResolveReferences(self, designUnit: DesignUnit, region: DeclarativeRegionMixin) -> None: """ Resolve the name of this alias, if it has no subtype indication, then its type marks. The name is resolved, if it's a simple name or an expanded name ``lib.pkg.item`` (:attr:`~pyVHDLModel.Name.Name.IsExpandedName`) and denotes a declaration, which isn't overloadable, e.g. a type or an object (:meth:`~pyVHDLModel.Regions.DeclarativeRegionMixin.LookupName`); the alias isn't overloadable then (:attr:`IsOverloadable`). The name of an implicitly declared operation (:attr:`_IMPLICIT_OPERATIONS`, an operator symbol) isn't looked up, as the model doesn't represent these. :param designUnit: The design unit containing this declaration. :param region: The declarative region declaring this declaration. :raises UnhandledCriticalWarningError: If the name can't be resolved, and no :class:`~pyTooling.Warning.WarningCollector` collects the :exc:`~pyVHDLModel.Exception.UnresolvedNameWarning`. :raises UnhandledCriticalWarningError: If a type mark can't be resolved, and no :class:`~pyTooling.Warning.WarningCollector` collects the :exc:`~pyVHDLModel.Exception.UnresolvedTypeMarkWarning`. """ if self._subtype is None: name = self._name._name isImplicit = name._normalizedIdentifier in self._IMPLICIT_OPERATIONS or name.IsOperatorSymbol if (isinstance(name, SimpleName) or name.IsExpandedName) and not isImplicit: self._name._reference = None aliased = region.LookupName(self, self._name, name, UnresolvedNameWarning) if len(aliased) > 0 and not aliased[0].IsOverloadable: self._name._reference = aliased[0] super().ResolveReferences(designUnit, region)
[docs] def ResetReferences(self, designUnit: DesignUnit, region: DeclarativeRegionMixin) -> None: """ Reset the reference of this alias' name, if it has no subtype indication, and the references of its type marks. :param designUnit: The design unit containing this declaration. :param region: The declarative region declaring this declaration. """ if self._subtype is None: self._name._reference = None super().ResetReferences(designUnit, region)
[docs] def DenoteBy( self, name: Name, region: DeclarativeRegionMixin, place: ModelEntity, symbol: Symbol ) -> Nullable[ModelEntity]: """ Determine the model entity a name denoting this alias denotes, as a part of a type mark. The type mark is an attribute name like ``al'subtype``. An alias with a subtype indication denotes itself, an object alias; otherwise, the declaration its name references says what it denotes (e.g. an object or a type). :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: The denoted model entity, or ``None`` if it can't be resolved (reported as a warning). :raises UnhandledCriticalWarningError: If the alias' name isn't resolved, and no :class:`~pyTooling.Warning.WarningCollector` collects the :exc:`~pyVHDLModel.Exception.UnresolvedTypeMarkWarning`. :raises UnhandledCriticalWarningError: If the declaration the alias' name references can't be denoted, and no :class:`~pyTooling.Warning.WarningCollector` collects the :exc:`~pyVHDLModel.Exception.UnresolvedTypeMarkWarning`. """ if self._subtype is not None: return self elif (reference := self._name._reference) is None: WarningCollector.Raise(UnresolvedTypeMarkWarning( f"Name of prefix '{name!s}' of type mark '{symbol._name!s}' isn't resolved.", symbol=symbol, place=place, namespaces=(region._namespace, ) )) return None return reference.DenoteBy(name, region, place, symbol)
[docs] def __str__(self) -> str: """ Formats the alias declaration. **Format:** ``alias myAlias : bit is target``, or without the subtype when none was given :returns: Formatted alias declaration. """ subtype = f" : {self._subtype}" if self._subtype is not None else "" return f"alias {self._identifier}{subtype} is {self._name}"