Source code for pyVHDLModel.Subprogram

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

Subprograms are procedures, functions and methods.
"""
from __future__             import annotations

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

from pyTooling.Common       import getFullyQualifiedName
from pyTooling.Decorators   import export, readonly
from pyTooling.MetaClasses  import ExtendedType, abstractclass

from pyVHDLModel.Base       import ModelEntity, NamedEntityMixin, DocumentedEntityMixin, identifiersOf, ReservedWord
from pyVHDLModel.Symbol     import SubtypeSymbol
from pyVHDLModel.Type       import ProtectedType
from pyVHDLModel.Regions    import DeclarativeRegionMixin, SequentialDeclarationRegionMixin, WithGenericsMixin, \
                                   WithParametersMixin
from pyVHDLModel.Sequential import SequentialStatement, SequentialStatementsMixin

if TYPE_CHECKING:
	from pyVHDLModel.Visitor  import Visitor


@export
class SubprogramSignature(ModelEntity):
	"""
	Represents a subprogram's signature: the type marks of its parameters and of a function's return value.

	The overloads of a subprogram differ in their signature. A parameter declaring several identifiers - ``a, b : in
	natural`` - contributes its type mark once per identifier. The string form is VHDL's notation of a signature
	(IEEE Std 1076-2019, 4.5.3), as an alias declaration or attribute specification writes it:
	``[natural, natural return boolean]``.

	The parent of a signature is the subprogram declaring it (:data:`Subprogram.Signature`). The type marks stay children
	of the parameters and of the function declaring them.

	Two signatures are equal, if their parameters' type marks and their return type marks have the same normalized names
	(:data:`NormalizedParameterTypeNames`, :data:`NormalizedReturnTypeName`); the parent isn't compared. So the
	signatures of two subprograms compare by their parameter and result type profile, and a signature can be used as a
	dictionary key or set member. The names are compared as written: ``natural`` and ``std.standard.natural`` differ,
	because the model doesn't resolve type marks yet.

	.. admonition:: Example

	   .. code-block:: VHDL

	      function to_index(value : unsigned; low, high : positive) return natural;
	      --                        ^^^^^^^^              ^^^^^^^^        ^^^^^^^   <- ParameterTypes and ReturnType
	      --                                         (twice)
	"""
	_parameterTypes:               tuple[SubtypeSymbol, ...]  #: Type marks of the parameters, one per identifier.
	_returnType:                   Nullable[SubtypeSymbol]    #: Type mark of a function's return value, if a function.
	_parameterTypeNames:           tuple[str, ...]            #: Names of the parameters' type marks, as written.
	_returnTypeName:               Nullable[str]              #: Name of the return type mark, as written.
	_normalizedParameterTypeNames: tuple[str, ...]            #: Normalized names of the parameters' type marks.
	_normalizedReturnTypeName:     Nullable[str]              #: Normalized name of the return type mark.
	_hash:                         int                        #: Hash value of the parameter and result type profile.

	def __init__(
		self,
		parameterTypes: Iterable[SubtypeSymbol],
		returnType:     Nullable[SubtypeSymbol] = None,
		*,
		parent:         Nullable[Subprogram] =    None
	) -> None:
		"""
		Initializes a subprogram signature.

		:param parameterTypes: The type marks of the parameters, one per parameter identifier.
		:param returnType:     Optional, the type mark of a function's return value. Default: ``None``, a procedure.
		:param parent:         Optional, the subprogram declaring this signature. Default: ``None``.
		:raises ValueError:    If parameter 'parameterTypes' is ``None``.
		:raises TypeError:     If parameter 'parameterTypes' is not iterable.
		:raises TypeError:     If an element of parameter 'parameterTypes' is not of type
		                       :class:`~pyVHDLModel.Symbol.SubtypeSymbol`.
		:raises TypeError:     If parameter 'returnType' is not of type :class:`~pyVHDLModel.Symbol.SubtypeSymbol`.
		:raises TypeError:     If parameter 'parent' is not of type :class:`~pyVHDLModel.Subprogram.Subprogram`.
		"""
		super().__init__(parent)

		if parent is not None and not isinstance(parent, Subprogram):
			ex = TypeError("Parameter 'parent' is not of type 'Subprogram'.")
			ex.add_note(f"Got type '{getFullyQualifiedName(parent)}'.")
			raise ex

		if parameterTypes is None:
			raise ValueError("Parameter 'parameterTypes' is None.")
		elif not isinstance(parameterTypes, Iterable):
			ex = TypeError("Parameter 'parameterTypes' is not iterable.")
			ex.add_note(f"Got type '{getFullyQualifiedName(parameterTypes)}'.")
			raise ex

		types =           []
		names =           []
		normalizedNames = []
		for parameterType in parameterTypes:
			if not isinstance(parameterType, SubtypeSymbol):
				ex = TypeError("Element of parameter 'parameterTypes' is not of type 'SubtypeSymbol'.")
				ex.add_note(f"Got type '{getFullyQualifiedName(parameterType)}'.")
				raise ex

			typeMark = parameterType.TypeMark
			types.append(parameterType)
			names.append(typeMark)
			normalizedNames.append(typeMark.lower())

		if returnType is not None and not isinstance(returnType, SubtypeSymbol):
			ex = TypeError("Parameter 'returnType' is not of type 'SubtypeSymbol'.")
			ex.add_note(f"Got type '{getFullyQualifiedName(returnType)}'.")
			raise ex

		self._parameterTypes =               tuple(types)
		self._returnType =                   returnType
		self._parameterTypeNames =           tuple(names)
		self._normalizedParameterTypeNames = tuple(normalizedNames)

		if returnType is None:
			self._returnTypeName =           None
			self._normalizedReturnTypeName = None
		else:
			self._returnTypeName =           returnType.TypeMark
			self._normalizedReturnTypeName = self._returnTypeName.lower()

		self._hash = hash((self._normalizedParameterTypeNames, self._normalizedReturnTypeName))

	@readonly
	def ParameterTypes(self) -> tuple[SubtypeSymbol, ...]:
		"""
		Read-only property to access the type marks of the parameters (:attr:`_parameterTypes`).

		:returns: Tuple of the parameters' type marks, one per parameter identifier, in declaration order.
		"""
		return self._parameterTypes

	@readonly
	def ReturnType(self) -> Nullable[SubtypeSymbol]:
		"""
		Read-only property to access the type mark of a function's return value (:attr:`_returnType`).

		:returns: The return value's type mark, or ``None`` for a procedure.
		"""
		return self._returnType

	@readonly
	def ParameterTypeNames(self) -> tuple[str, ...]:
		"""
		Read-only property to access the names of the parameters' type marks, as written (:attr:`_parameterTypeNames`).

		Each name is a type mark's :data:`~pyVHDLModel.Symbol.SubtypeSymbol.TypeMark`.

		:returns: Tuple of the type marks' names, one per parameter identifier, in declaration order.
		"""
		return self._parameterTypeNames

	@readonly
	def ReturnTypeName(self) -> Nullable[str]:
		"""
		Read-only property to access the name of a function's return type mark, as written (:attr:`_returnTypeName`).

		:returns: The return type mark's name, or ``None`` for a procedure.
		"""
		return self._returnTypeName

	@readonly
	def NormalizedParameterTypeNames(self) -> tuple[str, ...]:
		"""
		Read-only property to access the normalized (lower case) names of the parameters' type marks
		(:attr:`_normalizedParameterTypeNames`).

		The names are compared by :meth:`__eq__` and hashed by :meth:`__hash__`.

		.. seealso::

		   * :term:`Normalized`

		:returns: Tuple of the type marks' normalized names, one per parameter identifier, in declaration order.
		"""
		return self._normalizedParameterTypeNames

	@readonly
	def NormalizedReturnTypeName(self) -> Nullable[str]:
		"""
		Read-only property to access the normalized (lower case) name of a function's return type mark
		(:attr:`_normalizedReturnTypeName`).

		The name is compared by :meth:`__eq__` and hashed by :meth:`__hash__`.

		.. seealso::

		   * :term:`Normalized`

		:returns: The return type mark's normalized name, or ``None`` for a procedure.
		"""
		return self._normalizedReturnTypeName

	def __eq__(self, other: Any) -> bool:
		"""
		Compare two signatures, if they are equal: same normalized names of the parameters' and the return type marks.

		:param other:      Operand to compare against.
		:returns:          ``True``, if both signatures have the same parameter and result type profile.
		:raises TypeError: If parameter ``other`` is not of type :class:`SubprogramSignature`.
		"""
		if not isinstance(other, SubprogramSignature):
			ex = TypeError("Second operand is not supported by == operator.")
			ex.add_note(f"Got type '{getFullyQualifiedName(other)}'.")
			ex.add_note("Supported types for second operand: SubprogramSignature")
			raise ex

		return (
			self._normalizedParameterTypeNames == other._normalizedParameterTypeNames and
			self._normalizedReturnTypeName == other._normalizedReturnTypeName
		)

	def __ne__(self, other: Any) -> bool:
		"""
		Compare two signatures, if they are unequal: different normalized names of the parameters' or the return type marks.

		:param other:      Operand to compare against.
		:returns:          ``True``, if both signatures have a different parameter and result type profile.
		:raises TypeError: If parameter ``other`` is not of type :class:`SubprogramSignature`.
		"""
		if not isinstance(other, SubprogramSignature):
			ex = TypeError("Second operand is not supported by != operator.")
			ex.add_note(f"Got type '{getFullyQualifiedName(other)}'.")
			ex.add_note("Supported types for second operand: SubprogramSignature")
			raise ex

		return (
			self._normalizedParameterTypeNames != other._normalizedParameterTypeNames or
			self._normalizedReturnTypeName != other._normalizedReturnTypeName
		)

	def __hash__(self) -> int:
		"""
		Return the hash of the signature over the normalized names of the parameters' and the return type marks
		(:attr:`_hash`).

		:returns: Hash value of the parameter and result type profile.
		"""
		return self._hash

	def __str__(self) -> str:
		"""
		Return the signature in VHDL's notation: the parameters' type marks, comma separated, and a function's return type
		mark, in brackets.

		:returns: The signature, e.g. ``[unsigned, positive, positive return natural]`` or ``[natural]``.
		"""
		signature = ", ".join(self._parameterTypeNames)
		if self._returnTypeName is not None:
			returnType = f"return {self._returnTypeName}"
			signature = returnType if signature == "" else f"{signature} {returnType}"

		return f"[{signature}]"


@export
@abstractclass
class Subprogram(
	ModelEntity,
	NamedEntityMixin,
	DocumentedEntityMixin,
	WithGenericsMixin,
	WithParametersMixin,
	SequentialDeclarationRegionMixin,
	SequentialStatementsMixin
):
	"""
	Represents the base-class of all subprograms: procedures and functions.

	A subprogram is a named entity (:data:`Identifier`) with an optional generic clause
	(:data:`GenericItems`), a parameter list (:data:`ParameterItems`), its own declarative part
	(:data:`DeclaredItems`) and a sequence of statements (:data:`Statements`).

	.. seealso::

	   * :class:`Procedure <pyVHDLModel.Subprogram.Procedure>`
	   * :class:`Function <pyVHDLModel.Subprogram.Function>`
	"""
	_SUBPROGRAM_KEYWORD: ClassVar[str] = "subprogram"   #: The VHDL keyword introducing this subprogram kind.
	_isPure:             bool                           #: ``True`` if the subprogram was declared pure.
	_signature:          Nullable[SubprogramSignature]  #: The kept signature, or ``None`` until computed.

	def __init__(
		self,
		identifier:      str,
		isPure:          bool,
		genericItems:    Nullable[Iterable[GenericInterfaceItemMixin]] =   None,
		parameterItems:  Nullable[Iterable[ParameterInterfaceItemMixin]] = None,
		declaredItems:   Nullable[Iterable] =                              None,
		statements:      Nullable[Iterable[SequentialStatement]] =         None,
		documentation:   Nullable[str] =                                   None,
		parent:          Nullable[ModelEntity] =                           None,
		genericGroups:   Nullable[Iterable[GenericGroup]] =                None,
		parameterGroups: Nullable[Iterable[ParameterGroup]] =              None
	) -> None:
		"""
		Initializes a subprogram.

		:param identifier:      The identifier of a model entity.
		:param isPure:          ``True`` if the subprogram was declared pure.
		:param genericItems:    Optional, list of all generics, in declaration order. Default: ``None``, no generics.
		:param parameterItems:  Optional, list of all parameters, in declaration order. Default: ``None``, no parameters.
		:param declaredItems:   Optional, list of all declared items in this sequential declaration region.
		                        Default: ``None``, no declared items.
		:param statements:      Optional, list of all sequential statements in the subprogram's body.
		                        Default: ``None``, no statements.
		:param documentation:   Optional, the documentation comment associated with this declaration.
		                        Default: ``None``, no documentation.
		:param parent:          Optional, the parent model entity of this entity. Default: ``None``, no parent.
		:param genericGroups:   Optional, list of generic groups partitioning the generics, in declaration order.
		                        Default: ``None``, one unnamed generic group.
		:param parameterGroups: Optional, list of parameter groups partitioning the parameters, in declaration order.
		                        Default: ``None``, one unnamed parameter group.
		"""
		super().__init__(parent)
		NamedEntityMixin.__init__(self, identifier)
		DocumentedEntityMixin.__init__(self, documentation)
		SequentialDeclarationRegionMixin.__init__(self, self._normalizedIdentifier, declaredItems)
		WithGenericsMixin.__init__(self, genericItems, genericGroups)
		WithParametersMixin.__init__(self, parameterItems, parameterGroups)
		SequentialStatementsMixin.__init__(self, statements)

		self._isPure =    isPure
		self._signature = None

	@ModelEntity.Parent.setter
	def Parent(self, parent: ModelEntity) -> None:
		ModelEntity.Parent.fset(self, parent)
		self._ConnectParentNamespace(parent)

	@readonly
	def IsOverloadable(self) -> bool:
		"""
		Check if this subprogram is overloadable: always, it may share its designator with other subprograms and
		enumeration literals.

		:returns: ``True``.
		"""
		return True

	@readonly
	def IsPure(self) -> bool:
		"""
		Check if the subprogram is pure (:attr:`_isPure`).

		:returns: ``True``, if the subprogram is pure.
		"""
		return self._isPure

	@readonly
	def Signature(self) -> SubprogramSignature:
		"""
		Read-only property to access the subprogram's signature (:attr:`_signature`): the type marks of its parameters,
		and of a function's return value.

		The signature is computed on the first access and kept, until a parameter is added, inserted, removed or moved.

		:returns: The signature.
		"""
		if self._signature is None:
			self._signature = SubprogramSignature(
				(item._subtype for item in self._parameterItems for _ in identifiersOf(item)),
				parent=self
			)

		return self._signature

	def _ParameterItemsChanged(self) -> None:
		"""Clear the kept signature (:attr:`_signature`), because the parameter list changed."""
		self._signature = None

	def IndexDeclaredItems(self) -> None:
		"""
		A subprogram's generics and parameters 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._IndexParameterItems()

		super().IndexDeclaredItems()

	def _Declarations(self) -> tuple[ModelEntity, ...]:
		"""
		Return all declarations of this subprogram: its generics and parameters share the declarative region.

		:returns: Tuple of declarations: the generics, the parameters, then the declared items.
		"""
		return (*self._genericItems, *self._parameterItems, *super()._Declarations())

	def _LabelRegion(self) -> Subprogram:
		"""
		Return the subprogram, whose declarative region declares the labels of its statements.

		:returns: The subprogram itself.
		"""
		return self

	def _VisitDeclarativeAndStatementPart(self, visitor: Visitor) -> None:
		"""
		Walk the declarative part and the statement part of this subprogram with a visitor.

		The reserved word ``is`` precedes the declared items, the reserved word ``begin`` the statements.

		:param visitor: The visitor receiving the events.
		"""
		visitor.VisitIs(self)
		self._VisitDeclaredItems(visitor)
		visitor.VisitBegin(self)
		self._VisitStatements(visitor)

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

		**Format:** ``procedure myProcedure(a, b)``

		:returns: Formatted subprogram declaration.
		"""
		parameters = ", ".join(name for item in self._parameterItems for name in identifiersOf(item))
		return f"{self._SUBPROGRAM_KEYWORD} {self._identifier}({parameters})"


@export
class Procedure(Subprogram):
	"""
	Represents a procedure.

	Unlike a function, a procedure returns no value. Besides its parameters, it has its own
	declarative part (:data:`DeclaredItems`) and statements (:data:`Statements`).

	.. admonition:: Example

	   .. code-block:: VHDL

	      procedure proc(signal s : in bit; variable v : out bit) is
	      --        ^^^^                                               <- Identifier
	      --             ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^       <- ParameterItems
	        variable tmp : bit;
	      --^^^^^^^^^^^^^^^^^^^                                        <- DeclaredItems
	      begin
	        tmp := s;
	      --^^^^^^^^^                                                  <- Statements
	        v := tmp;
	      end procedure;

	.. seealso::

	   * :class:`Procedure instantiation <pyVHDLModel.Instantiation.ProcedureInstantiation>`
	   * :class:`Generic procedure interface item <pyVHDLModel.Interface.GenericProcedureInterfaceItem>`
	   * :class:`Procedure method <pyVHDLModel.Subprogram.ProcedureMethod>`
	   * :class:`Function <pyVHDLModel.Subprogram.Function>`
	"""

	_END_KEYWORDS:          ClassVar[tuple[ReservedWord, ...]] = (ReservedWord.Procedure,)  #: Reserved words after ``end``.
	_END_KEYWORDS_OPTIONAL: ClassVar[bool] =                     True                       #: The reserved words after ``end`` are optional.

	_SUBPROGRAM_KEYWORD: ClassVar[str] = "procedure"  #: The VHDL keyword introducing this subprogram kind.

	def __init__(
		self,
		identifier:      str,
		genericItems:    Nullable[Iterable[GenericInterfaceItemMixin]] =   None,
		parameterItems:  Nullable[Iterable[ParameterInterfaceItemMixin]] = None,
		declaredItems:   Nullable[Iterable] =                              None,
		statements:      Nullable[Iterable[SequentialStatement]] =         None,
		documentation:   Nullable[str] =                                   None,
		parent:          Nullable[ModelEntity] =                           None,
		genericGroups:   Nullable[Iterable[GenericGroup]] =                None,
		parameterGroups: Nullable[Iterable[ParameterGroup]] =              None
	) -> None:
		"""
		Initializes a procedure.

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

[docs] def Visit(self, visitor: Visitor) -> None: """ Walk this procedure, its generic clause, its parameters, its declared items and its statements with a visitor. :param visitor: The visitor receiving the events. """ visitor.VisitProcedure(self) self._VisitGenericClause(visitor) self._VisitFormalParameterList(visitor) self._VisitDeclarativeAndStatementPart(visitor) visitor.VisitEnd(self) visitor.VisitTerminator(self) visitor.DepartProcedure(self)
@export class Function(Subprogram): """ Represents a function. A function returns a value of its return type (:data:`ReturnType`) and is either pure or impure (:data:`IsPure`). Besides its parameters, it has its own declarative part (:data:`DeclaredItems`) and statements (:data:`Statements`). .. admonition:: Example .. code-block:: VHDL function fun(constant c : in positive) return integer is -- ^^^ <- Identifier -- ^^^^^^^^^^^^^^^^^^^^^^^^ <- ParameterItems -- ^^^^^^^ <- ReturnType variable tmp : integer; --^^^^^^^^^^^^^^^^^^^^^^^ <- DeclaredItems begin tmp := c; --^^^^^^^^^ <- Statements return tmp; end function; .. seealso:: * :class:`Function instantiation <pyVHDLModel.Instantiation.FunctionInstantiation>` * :class:`Generic function interface item <pyVHDLModel.Interface.GenericFunctionInterfaceItem>` * :class:`Function method <pyVHDLModel.Subprogram.FunctionMethod>` * :class:`Procedure <pyVHDLModel.Subprogram.Procedure>` """ _END_KEYWORDS: ClassVar[tuple[ReservedWord, ...]] = (ReservedWord.Function,) #: Reserved words after ``end``. _END_KEYWORDS_OPTIONAL: ClassVar[bool] = True #: The reserved words after ``end`` are optional. _SUBPROGRAM_KEYWORD: ClassVar[str] = "function" #: The VHDL keyword introducing this subprogram kind. _returnType: SubtypeSymbol #: Reference to the subtype of the function's return value. def __init__( self, identifier: str, returnType: SubtypeSymbol, isPure: bool = True, genericItems: Nullable[Iterable[GenericInterfaceItemMixin]] = None, parameterItems: Nullable[Iterable[ParameterInterfaceItemMixin]] = None, declaredItems: Nullable[Iterable] = None, statements: Nullable[Iterable[SequentialStatement]] = None, documentation: Nullable[str] = None, parent: Nullable[ModelEntity] = None, genericGroups: Nullable[Iterable[GenericGroup]] = None, parameterGroups: Nullable[Iterable[ParameterGroup]] = None ) -> None: """ Initializes a function. :param identifier: The identifier of a model entity. :param returnType: Reference to the subtype of the function's return value. :param isPure: Optional, ``True`` if the subprogram was declared pure. Default: ``True``. :param genericItems: Optional, list of all generics, in declaration order. Default: ``None``, no generics. :param parameterItems: Optional, list of all parameters, in declaration order. Default: ``None``, no parameters. :param declaredItems: Optional, list of all declared items in this sequential declaration region. Default: ``None``, no declared items. :param statements: Optional, list of all sequential statements in the subprogram's body. Default: ``None``, no statements. :param documentation: Optional, the documentation comment associated with this declaration. Default: ``None``, no documentation. :param parent: Optional, the parent model entity of this entity. Default: ``None``, no parent. :param genericGroups: Optional, list of generic groups partitioning the generics, in declaration order. Default: ``None``, one unnamed generic group. :param parameterGroups: Optional, list of parameter groups partitioning the parameters, in declaration order. Default: ``None``, one unnamed parameter group. """ super().__init__( identifier, isPure, genericItems, parameterItems, declaredItems, statements, documentation, parent, genericGroups, parameterGroups ) self._returnType = returnType returnType.Parent = self
[docs] def Visit(self, visitor: Visitor) -> None: """ Walk this function, its generic clause, its parameters, its return type, its declared items and its statements with a visitor. :param visitor: The visitor receiving the events. """ visitor.VisitFunction(self) self._VisitGenericClause(visitor) self._VisitFormalParameterList(visitor) visitor.VisitReturn(self) self._returnType.Visit(visitor) self._VisitDeclarativeAndStatementPart(visitor) visitor.VisitEnd(self) visitor.VisitTerminator(self) visitor.DepartFunction(self)
[docs] def IterateTypeMarks( self, region: DeclarativeRegionMixin ) -> Generator[tuple[DeclarativeRegionMixin, ModelEntity, SubtypeSymbol], None, None]: """ Iterate the type marks of this function: its return type. The return type is looked up in the function's own region, before the function's declared items: at its first declared item, or at the function itself. The function's parameters are declarations of its own region. :param region: The declarative region declaring this function. :returns: A generator to iterate (region, place, type mark) tuples: the return type. """ place = self._declaredItems[0] if len(self._declaredItems) > 0 else self yield self, place, self._returnType
@readonly def ReturnType(self) -> SubtypeSymbol: """ Read-only property to access the return type (:attr:`_returnType`). :returns: The return type. """ return self._returnType @readonly def Signature(self) -> SubprogramSignature: """ Read-only property to access the function's signature (:attr:`_signature`): the type marks of its parameters and of its return value. The signature is computed on the first access and kept, until a parameter is added, inserted, removed or moved. :returns: The signature. """ if self._signature is None: self._signature = SubprogramSignature( (item._subtype for item in self._parameterItems for _ in identifiersOf(item)), self._returnType, parent=self ) return self._signature @export class MethodMixin(metaclass=ExtendedType, mixin=True): """ A ``Method`` is a mixin class for all subprograms in a protected type. .. seealso:: * :class:`Procedure method <pyVHDLModel.Subprogram.ProcedureMethod>` * :class:`Function method <pyVHDLModel.Subprogram.FunctionMethod>` """ _protectedType: ProtectedType #: Reference to the protected type this method belongs to. def __init__(self, protectedType: Nullable[ProtectedType] = None) -> None: """ Initializes a method. :param protectedType: Optional, reference to the protected type this method belongs to. Default: ``None``. """ self._protectedType = protectedType if protectedType is not None: protectedType.Parent = self @readonly def ProtectedType(self) -> ProtectedType: """ Read-only property to access the protected type (:attr:`_protectedType`). :returns: The protected type. """ return self._protectedType @export class ProcedureMethod(Procedure, MethodMixin): """ Represents a procedure declared as a method of a protected type. The protected type is available as :data:`ProtectedType`. .. seealso:: * :class:`Protected type <pyVHDLModel.Type.ProtectedType>` """ def __init__( self, identifier: str, genericItems: Nullable[Iterable[GenericInterfaceItemMixin]] = None, parameterItems: Nullable[Iterable[ParameterInterfaceItemMixin]] = None, declaredItems: Nullable[Iterable] = None, statements: Nullable[Iterable[SequentialStatement]] = None, documentation: Nullable[str] = None, protectedType: Nullable[ProtectedType] = None, parent: Nullable[ModelEntity] = None, genericGroups: Nullable[Iterable[GenericGroup]] = None, parameterGroups: Nullable[Iterable[ParameterGroup]] = None ) -> None: """ Initializes a procedure declared as a method of a protected type. :param identifier: The identifier of a model entity. :param genericItems: Optional, list of all generics, in declaration order. Default: ``None``, no generics. :param parameterItems: Optional, list of all parameters, in declaration order. Default: ``None``, no parameters. :param declaredItems: Optional, list of all declared items in this sequential declaration region. Default: ``None``, no declared items. :param statements: Optional, list of all sequential statements in the subprogram's body. Default: ``None``, no statements. :param documentation: Optional, the documentation comment associated with this declaration. Default: ``None``, no documentation. :param protectedType: Optional, reference to the protected type this method belongs to. Default: ``None``. :param parent: Optional, the parent model entity of this entity. Default: ``None``, no parent. :param genericGroups: Optional, list of generic groups partitioning the generics, in declaration order. Default: ``None``, one unnamed generic group. :param parameterGroups: Optional, list of parameter groups partitioning the parameters, in declaration order. Default: ``None``, one unnamed parameter group. """ super().__init__( identifier, genericItems, parameterItems, declaredItems, statements, documentation, parent, genericGroups, parameterGroups ) MethodMixin.__init__(self, protectedType) @export class FunctionMethod(Function, MethodMixin): """ Represents a function declared as a method of a protected type. The protected type is available as :data:`ProtectedType`. .. seealso:: * :class:`Protected type <pyVHDLModel.Type.ProtectedType>` """ def __init__( self, identifier: str, returnType: SubtypeSymbol, isPure: bool = True, genericItems: Nullable[Iterable[GenericInterfaceItemMixin]] = None, parameterItems: Nullable[Iterable[ParameterInterfaceItemMixin]] = None, declaredItems: Nullable[Iterable] = None, statements: Nullable[Iterable[SequentialStatement]] = None, documentation: Nullable[str] = None, protectedType: Nullable[ProtectedType] = None, parent: Nullable[ModelEntity] = None, genericGroups: Nullable[Iterable[GenericGroup]] = None, parameterGroups: Nullable[Iterable[ParameterGroup]] = None ) -> None: """ Initializes a function declared as a method of a protected type. :param identifier: The identifier of a model entity. :param returnType: Reference to the subtype of the function's return value. :param isPure: Optional, ``True`` if the subprogram was declared pure. Default: ``True``. :param genericItems: Optional, list of all generics, in declaration order. Default: ``None``, no generics. :param parameterItems: Optional, list of all parameters, in declaration order. Default: ``None``, no parameters. :param declaredItems: Optional, list of all declared items in this sequential declaration region. Default: ``None``, no declared items. :param statements: Optional, list of all sequential statements in the subprogram's body. Default: ``None``, no statements. :param documentation: Optional, the documentation comment associated with this declaration. Default: ``None``, no documentation. :param protectedType: Optional, reference to the protected type this method belongs to. Default: ``None``. :param parent: Optional, the parent model entity of this entity. Default: ``None``, no parent. :param genericGroups: Optional, list of generic groups partitioning the generics, in declaration order. Default: ``None``, one unnamed generic group. :param parameterGroups: Optional, list of parameter groups partitioning the parameters, in declaration order. Default: ``None``, one unnamed parameter group. """ super().__init__( identifier, returnType, isPure, genericItems, parameterItems, declaredItems, statements, documentation, parent, genericGroups, parameterGroups ) MethodMixin.__init__(self, protectedType)