Source code for pyVHDLModel.Object

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

Objects are constants, variables, signals and files.
"""
from __future__            import annotations

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

from pyTooling.Decorators  import export, readonly
from pyTooling.MetaClasses import ExtendedType, abstractclass
from pyTooling.Graph       import Vertex
from pyTooling.Warning     import WarningCollector

from pyVHDLModel.Base      import ModelEntity, MultipleNamedEntityMixin, DocumentedEntityMixin, ExpressionUnion, \
                                  ReservedWord
from pyVHDLModel.Exception import UnresolvedTypeMarkWarning
from pyVHDLModel.Name      import Name
from pyVHDLModel.Symbol    import Symbol, SubtypeSymbol

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


@export
@abstractclass
class Obj(ModelEntity, MultipleNamedEntityMixin, DocumentedEntityMixin):
	"""
	Base-class for all objects (constants, signals, variables and files) in VHDL.

	An object (syntax element) can define multiple objects (semantic elements) in a single declaration, thus
	:class:`~pyVHDLModel.Base.MultipleNamedEntityMixin` is inherited. All objects can be documented, thus
	:class:`~pyVHDLModel.Base.DocumentedEntityMixin` is inherited too.

	Each object references a subtype via :data:`_subtype`.

	Objects are elements in the type and object graph, thus a reference to a vertex in that graph is stored in
	:data:`_objectVertex`.

	.. seealso::

	   * :class:`Base constant <pyVHDLModel.Object.BaseConstant>`
	   * :class:`Variable <pyVHDLModel.Object.Variable>`
	   * :class:`Shared variable <pyVHDLModel.Object.SharedVariable>`
	   * :class:`Signal <pyVHDLModel.Object.Signal>`
	   * :class:`File <pyVHDLModel.Object.File>`
	"""

	_OBJECT_KEYWORD:               ClassVar[tuple[ReservedWord, ...]]         #: The reserved words introducing this object class.
	_USABLE_IN_OWN_INTERFACE_LIST: ClassVar[bool] =                     True  #: Usable by a name in its own interface list.

	_subtype:      Symbol            #: Reference to the object's subtype.
	_objectVertex: Nullable[Vertex]  #: The vertex representing this object in the design's object graph.

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

		:param identifiers:   A list of identifiers.
		:param subtype:       Reference to the object'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)
		MultipleNamedEntityMixin.__init__(self, identifiers)
		DocumentedEntityMixin.__init__(self, documentation)

		self._subtype = subtype
		subtype.Parent = self

		self._objectVertex = None

	@readonly
	def Subtype(self) -> Symbol:
		"""
		Read-only property to access the subtype (:attr:`_subtype`).

		:returns: The subtype.
		"""
		return self._subtype

	@readonly
	def ObjectVertex(self) -> Nullable[Vertex]:
		"""
		Read-only property to access the corresponding object vertex (:attr:`_objectVertex`).

		The object vertex references this Object by its value field.

		:returns: The corresponding object vertex.
		"""
		return self._objectVertex

	def Copy(self) -> Self:
		"""
		Create a copy of this object declaration.

		The copy has no parent and no object vertex. Its subtype is a copy of this declaration's subtype.

		:returns: The new object declaration.
		"""
		return self.__class__(self._identifiers, self._subtype.Copy(), self._documentation)

	def _SplitInParent(self) -> tuple[Self, ...]:
		"""
		Split this object declaration by the mutator of its parent (``SplitDeclaredItem()``).

		:returns: Tuple of declarations, one per identifier in list order, starting with this object declaration.
		"""
		return self._parent.SplitDeclaredItem(self)

	def IterateTypeMarks(
		self,
		region: DeclarativeRegionMixin
	) -> Generator[tuple[DeclarativeRegionMixin, ModelEntity, SubtypeSymbol], None, None]:
		"""
		Iterate the type marks of this object: the type mark of its subtype indication.

		:param region:  The declarative region declaring this object.
		:returns:       A generator to iterate (region, place, type mark) tuples: the object's subtype indication.
		"""
		if isinstance(self._subtype, SubtypeSymbol):
			yield region, self, self._subtype

	def DenoteBy(
		self,
		name:   Name,
		region: DeclarativeRegionMixin,
		place:  ModelEntity,
		symbol: Symbol
	) -> Nullable[ModelEntity]:
		"""
		Determine the model entity a name denoting this object denotes, as a part of a type mark: this object.

		A port or a parameter isn't usable in its own interface list (:attr:`_USABLE_IN_OWN_INTERFACE_LIST`): e.g. the
		subtype of a port can't name another port of the same port list (``i'subtype``).

		: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 object, or ``None`` if a name can't denote it here (reported as a
		                                       warning).
		:raises UnhandledCriticalWarningError: If the object is a port or parameter used in its own interface list, and no
		                                       :class:`~pyTooling.Warning.WarningCollector` collects the
		                                       :exc:`~pyVHDLModel.Exception.UnresolvedTypeMarkWarning`.
		"""
		from pyVHDLModel.Interface import InterfaceItemMixin

		if (
			not self._USABLE_IN_OWN_INTERFACE_LIST and isinstance(place, InterfaceItemMixin)
			and self._parent is place._parent
		):
			WarningCollector.Raise(UnresolvedTypeMarkWarning(
				f"Prefix '{name!s}' of type mark '{symbol._name!s}' isn't usable in its own interface list.",
				symbol=symbol,
				place=place,
				namespaces=(region._namespace, )
			))
			return None

		return self

	def __str__(self) -> str:
		"""
		Formats the object declaration.

		**Format:** ``signal s1, s2 : bit``

		:returns: Formatted object declaration.
		"""
		return f"{' '.join(self._OBJECT_KEYWORD)} {', '.join(self._identifiers)} : {self._subtype}"


@export
class WithDefaultExpressionMixin(metaclass=ExtendedType, mixin=True):
	"""
	A ``WithDefaultExpression`` is a mixin-class for all objects declarations accepting default expressions.

	The default expression is referenced by :data:`_defaultExpression`. If no default expression is present, this field
	is ``None``.

	.. seealso::

	   * :class:`Constant <pyVHDLModel.Object.Constant>`
	   * :class:`Variable <pyVHDLModel.Object.Variable>`
	   * :class:`Signal <pyVHDLModel.Object.Signal>`
	"""

	_defaultExpression: Nullable[ExpressionUnion]  #: The default value, or ``None`` if none was given.

	def __init__(self, defaultExpression: Nullable[ExpressionUnion] = None) -> None:
		"""
		Initializes an object with a default expression.

		:param defaultExpression: Optional, the default value. Default: ``None``, no default value.
		"""
		self._defaultExpression = defaultExpression
		if defaultExpression is not None:
			defaultExpression.Parent = self

	@readonly
	def DefaultExpression(self) -> Nullable[ExpressionUnion]:
		"""
		Read-only property to access the default expression (:attr:`_defaultExpression`).

		:returns: The default expression, or ``None`` if not set.
		"""
		return self._defaultExpression

	def _VisitDefaultExpression(self, visitor: Visitor) -> None:
		"""
		Walk the default expression, if any, after a variable assignment delimiter (``:=``) with a visitor.

		:param visitor: The visitor receiving the events.
		"""
		if self._defaultExpression is not None:
			visitor.VisitVariableAssignment(self)
			self._defaultExpression.Visit(visitor)


@export
@abstractclass
class BaseConstant(Obj):
	"""
	Base-class for all constants (normal and deferred constants) in VHDL.

	.. seealso::

	   * :class:`Constant <pyVHDLModel.Object.Constant>`
	   * :class:`Deferred constant <pyVHDLModel.Object.DeferredConstant>`
	"""

	_OBJECT_KEYWORD: ClassVar[tuple[ReservedWord, ...]] = (ReservedWord.Constant,)  #: The reserved words introducing this object class.


@export
class Constant(BaseConstant, WithDefaultExpressionMixin):
	"""
	Represents a constant.

	As constants (always) have a default expression, the class :class:`~pyVHDLModel.Object.WithDefaultExpressionMixin` is inherited.

	.. admonition:: Example

	   .. code-block:: VHDL

	      constant BITS : positive := 8;

	.. seealso::

	   * :class:`Generic constant interface item <pyVHDLModel.Interface.GenericConstantInterfaceItem>`
	   * :class:`Parameter constant interface item <pyVHDLModel.Interface.ParameterConstantInterfaceItem>`
	"""

	def __init__(
		self,
		identifiers: Iterable[str],
		subtype: Symbol,
		defaultExpression: Nullable[ExpressionUnion] = None,
		documentation: Nullable[str] = None,
		parent: Nullable[ModelEntity] = None
	) -> None:
		"""
		Initializes a constant.

		:param identifiers:       A list of identifiers.
		:param subtype:           Reference to the object's subtype.
		:param defaultExpression: Optional, the default value. Default: ``None``, no default value.
		: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__(identifiers, subtype, documentation, parent)
		WithDefaultExpressionMixin.__init__(self, defaultExpression)

[docs] def Copy(self) -> Self: """ Create a copy of this constant. The copy has no parent and no object vertex. Its subtype and default expression are copies of this constant's subtype and default expression. :returns: The new constant. """ defaultExpression = None if self._defaultExpression is None else self._defaultExpression.Copy() return self.__class__(self._identifiers, self._subtype.Copy(), defaultExpression, self._documentation)
[docs] def Visit(self, visitor: Visitor) -> None: """ Walk this constant declaration, its subtype and its default expression with a visitor. :param visitor: The visitor receiving the events. """ visitor.VisitConstant(self) self._subtype.Visit(visitor) self._VisitDefaultExpression(visitor) visitor.VisitTerminator(self) visitor.DepartConstant(self)
@export class DeferredConstant(BaseConstant): """ Represents a deferred constant. Deferred constants are forward declarations for a (complete) constant declaration, thus it contains a field :data:`_constantReference` to the complete constant declaration. .. admonition:: Example .. code-block:: VHDL constant BITS : positive; """ _constantReference: Nullable[Constant] #: The full declaration, or ``None`` if unlinked. def __init__( self, identifiers: Iterable[str], subtype: Symbol, documentation: Nullable[str] = None, parent: Nullable[ModelEntity] = None ) -> None: """ Initializes a deferred constant. :param identifiers: A list of identifiers. :param subtype: Reference to the object'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__(identifiers, subtype, documentation, parent) self._constantReference = None
[docs] def Visit(self, visitor: Visitor) -> None: """ Walk this deferred constant declaration, its subtype with a visitor. :param visitor: The visitor receiving the events. """ visitor.VisitDeferredConstant(self) self._subtype.Visit(visitor) visitor.VisitTerminator(self) visitor.DepartDeferredConstant(self)
@readonly def ConstantReference(self) -> Nullable[Constant]: """ Read-only property to access the constant reference (:attr:`_constantReference`). :returns: The constant reference, or ``None`` if not set. """ return self._constantReference
[docs] def Copy(self) -> Self: """ Create a copy of this deferred constant. The copy has no parent and no object vertex. Its subtype is a copy of this deferred constant's subtype; the full constant declaration, if linked, is the same. :returns: The new deferred constant. """ copy = self.__class__(self._identifiers, self._subtype.Copy(), self._documentation) copy._constantReference = self._constantReference return copy
@export class Variable(Obj, WithDefaultExpressionMixin): """ Represents a variable. As variables might have a default expression, the class :class:`~pyVHDLModel.Object.WithDefaultExpressionMixin` is inherited. .. admonition:: Example .. code-block:: VHDL variable result : natural := 0; .. seealso:: * :class:`Parameter variable interface item <pyVHDLModel.Interface.ParameterVariableInterfaceItem>` """ _OBJECT_KEYWORD: ClassVar[tuple[ReservedWord, ...]] = (ReservedWord.Variable,) #: The reserved words introducing this object class. def __init__( self, identifiers: Iterable[str], subtype: Symbol, defaultExpression: Nullable[ExpressionUnion] = None, documentation: Nullable[str] = None, parent: Nullable[ModelEntity] = None ) -> None: """ Initializes a variable. :param identifiers: A list of identifiers. :param subtype: Reference to the object's subtype. :param defaultExpression: Optional, the default value. Default: ``None``, no default value. :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__(identifiers, subtype, documentation, parent) WithDefaultExpressionMixin.__init__(self, defaultExpression)
[docs] def Copy(self) -> Self: """ Create a copy of this variable. The copy has no parent and no object vertex. Its subtype and default expression are copies of this variable's subtype and default expression. :returns: The new variable. """ defaultExpression = None if self._defaultExpression is None else self._defaultExpression.Copy() return self.__class__(self._identifiers, self._subtype.Copy(), defaultExpression, self._documentation)
[docs] def Visit(self, visitor: Visitor) -> None: """ Walk this variable declaration, its subtype and its default expression with a visitor. :param visitor: The visitor receiving the events. """ visitor.VisitVariable(self) self._subtype.Visit(visitor) self._VisitDefaultExpression(visitor) visitor.VisitTerminator(self) visitor.DepartVariable(self)
@export class SharedVariable(Obj): """ Represents a shared variable. .. todo:: Shared variable object not implemented. """ _OBJECT_KEYWORD: ClassVar[tuple[ReservedWord, ...]] = (ReservedWord.Shared, ReservedWord.Variable) #: The reserved words introducing this object class.
[docs] def Visit(self, visitor: Visitor) -> None: """ Walk this shared variable declaration, its subtype with a visitor. :param visitor: The visitor receiving the events. """ visitor.VisitSharedVariable(self) self._subtype.Visit(visitor) visitor.VisitTerminator(self) visitor.DepartSharedVariable(self)
@export class Signal(Obj, WithDefaultExpressionMixin): """ Represents a signal. As signals might have a default expression, the class :class:`~pyVHDLModel.Object.WithDefaultExpressionMixin` is inherited. .. admonition:: Example .. code-block:: VHDL signal counter : unsigned(7 downto 0) := '0'; .. seealso:: * :class:`Port signal interface item <pyVHDLModel.Interface.PortSignalInterfaceItem>` * :class:`Parameter signal interface item <pyVHDLModel.Interface.ParameterSignalInterfaceItem>` """ _OBJECT_KEYWORD: ClassVar[tuple[ReservedWord, ...]] = (ReservedWord.Signal,) #: The reserved words introducing this object class. def __init__( self, identifiers: Iterable[str], subtype: Symbol, defaultExpression: Nullable[ExpressionUnion] = None, documentation: Nullable[str] = None, parent: Nullable[ModelEntity] = None ) -> None: """ Initializes a signal. :param identifiers: A list of identifiers. :param subtype: Reference to the object's subtype. :param defaultExpression: Optional, the default value. Default: ``None``, no default value. :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__(identifiers, subtype, documentation, parent) WithDefaultExpressionMixin.__init__(self, defaultExpression)
[docs] def Copy(self) -> Self: """ Create a copy of this signal. The copy has no parent and no object vertex. Its subtype and default expression are copies of this signal's subtype and default expression. :returns: The new signal. """ defaultExpression = None if self._defaultExpression is None else self._defaultExpression.Copy() return self.__class__(self._identifiers, self._subtype.Copy(), defaultExpression, self._documentation)
[docs] def Visit(self, visitor: Visitor) -> None: """ Walk this signal declaration, its subtype and its default expression with a visitor. :param visitor: The visitor receiving the events. """ visitor.VisitSignal(self) self._subtype.Visit(visitor) self._VisitDefaultExpression(visitor) visitor.VisitTerminator(self) visitor.DepartSignal(self)
@export class File(Obj): """ Represents a file. .. todo:: File object not implemented. .. seealso:: * :class:`Parameter file interface item <pyVHDLModel.Interface.ParameterFileInterfaceItem>` """ _OBJECT_KEYWORD: ClassVar[tuple[ReservedWord, ...]] = (ReservedWord.File,) #: The reserved words introducing this object class.
[docs] def Visit(self, visitor: Visitor) -> None: """ Walk this file declaration, its subtype with a visitor. :param visitor: The visitor receiving the events. """ visitor.VisitFile(self) self._subtype.Visit(visitor) visitor.VisitTerminator(self) visitor.DepartFile(self)