Coverage for pyVHDLModel/Object.py: 100%
67 statements
« prev ^ index » next coverage.py v7.16.0, created at 2026-09-11 23:50 +0000
1# ==================================================================================================================== #
2# __ ___ _ ____ _ __ __ _ _ #
3# _ __ _ \ \ / / | | | _ \| | | \/ | ___ __| | ___| | #
4# | '_ \| | | \ \ / /| |_| | | | | | | |\/| |/ _ \ / _` |/ _ \ | #
5# | |_) | |_| |\ V / | _ | |_| | |___| | | | (_) | (_| | __/ | #
6# | .__/ \__, | \_/ |_| |_|____/|_____|_| |_|\___/ \__,_|\___|_| #
7# |_| |___/ #
8# ==================================================================================================================== #
9# Authors: #
10# Patrick Lehmann #
11# #
12# License: #
13# ==================================================================================================================== #
14# Copyright 2017-2026 Patrick Lehmann - Boetzingen, Germany #
15# Copyright 2016-2017 Patrick Lehmann - Dresden, Germany #
16# #
17# Licensed under the Apache License, Version 2.0 (the "License"); #
18# you may not use this file except in compliance with the License. #
19# You may obtain a copy of the License at #
20# #
21# http://www.apache.org/licenses/LICENSE-2.0 #
22# #
23# Unless required by applicable law or agreed to in writing, software #
24# distributed under the License is distributed on an "AS IS" BASIS, #
25# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. #
26# See the License for the specific language governing permissions and #
27# limitations under the License. #
28# #
29# SPDX-License-Identifier: Apache-2.0 #
30# ==================================================================================================================== #
31#
32"""
33This module contains parts of an abstract document language model for VHDL.
35Objects are constants, variables, signals and files.
36"""
37from typing import ClassVar, Iterable, Optional as Nullable
39from pyTooling.Decorators import export, readonly
40from pyTooling.MetaClasses import ExtendedType
41from pyTooling.Graph import Vertex
43from pyVHDLModel.Base import ModelEntity, MultipleNamedEntityMixin, DocumentedEntityMixin, ExpressionUnion
44from pyVHDLModel.Symbol import Symbol
47@export
48class Obj(ModelEntity, MultipleNamedEntityMixin, DocumentedEntityMixin):
49 """
50 Base-class for all objects (constants, signals, variables and files) in VHDL.
52 An object (syntax element) can define multiple objects (semantic elements) in a single declaration, thus
53 :class:`~pyVHDLModel.Base.MultipleNamedEntityMixin` is inherited. All objects can be documented, thus
54 :class:`~pyVHDLModel.Base.DocumentedEntityMixin` is inherited too.
56 Each object references a subtype via :data:`_subtype`.
58 Objects are elements in the type and object graph, thus a reference to a vertex in that graph is stored in
59 :data:`__objectVertex`.
61 .. seealso::
63 * :class:`Base constant <pyVHDLModel.Object.BaseConstant>`
64 * :class:`Variable <pyVHDLModel.Object.Variable>`
65 * :class:`Shared variable <pyVHDLModel.Object.SharedVariable>`
66 * :class:`Signal <pyVHDLModel.Object.Signal>`
67 * :class:`File <pyVHDLModel.Object.File>`
68 """
70 _objectKeyword: ClassVar[str] = "object" #: The VHDL keyword introducing this object class.
72 _subtype: Symbol #: Reference to the object's subtype.
73 _objectVertex: Nullable[Vertex] #: The vertex representing this object in the design's object graph.
75 def __init__(self, identifiers: Iterable[str], subtype: Symbol, documentation: Nullable[str] = None, parent: Nullable[ModelEntity] = None) -> None:
76 """
77 Initializes an object.
79 :param identifiers: A list of identifiers.
80 :param subtype: Reference to the object's subtype.
81 :param documentation: The documentation comment associated with this declaration.
82 :param parent: The parent model entity of this entity.
83 """
84 super().__init__(parent)
85 MultipleNamedEntityMixin.__init__(self, identifiers)
86 DocumentedEntityMixin.__init__(self, documentation)
88 self._subtype = subtype
89 subtype.Parent = self
91 self._objectVertex = None
93 @readonly
94 def Subtype(self) -> Symbol:
95 """
96 Read-only property to access the subtype (:attr:`_subtype`).
98 :returns: The subtype.
99 """
100 return self._subtype
102 @readonly
103 def ObjectVertex(self) -> Nullable[Vertex]:
104 """
105 Read-only property to access the corresponding object vertex (:attr:`_objectVertex`).
107 The object vertex references this Object by its value field.
109 :returns: The corresponding object vertex.
110 """
111 return self._objectVertex
113 def __str__(self) -> str:
114 """
115 Formats the object declaration.
117 **Format:** ``signal s1, s2 : bit``
119 :returns: Formatted object declaration.
120 """
121 return f"{self._objectKeyword} {', '.join(self._identifiers)} : {self._subtype}"
124@export
125class WithDefaultExpressionMixin(metaclass=ExtendedType, mixin=True):
126 """
127 A ``WithDefaultExpression`` is a mixin-class for all objects declarations accepting default expressions.
129 The default expression is referenced by :data:`__defaultExpression`. If no default expression is present, this field
130 is ``None``.
132 .. seealso::
134 * :class:`Constant <pyVHDLModel.Object.Constant>`
135 * :class:`Variable <pyVHDLModel.Object.Variable>`
136 * :class:`Signal <pyVHDLModel.Object.Signal>`
137 """
139 _defaultExpression: Nullable[ExpressionUnion] #: The default value, or ``None`` if none was given.
141 def __init__(self, defaultExpression: Nullable[ExpressionUnion] = None) -> None:
142 """
143 Initializes an object with a default expression.
145 :param defaultExpression: The default value, or ``None`` if none was given.
146 """
147 self._defaultExpression = defaultExpression
148 if defaultExpression is not None:
149 defaultExpression.Parent = self
151 @readonly
152 def DefaultExpression(self) -> Nullable[ExpressionUnion]:
153 """
154 Read-only property to access the default expression (:attr:`_defaultExpression`).
156 :returns: The default expression, or ``None`` if not set.
157 """
158 return self._defaultExpression
161@export
162class BaseConstant(Obj):
163 """
164 Base-class for all constants (normal and deferred constants) in VHDL.
166 .. seealso::
168 * :class:`Constant <pyVHDLModel.Object.Constant>`
169 * :class:`Deferred constant <pyVHDLModel.Object.DeferredConstant>`
170 """
172 _objectKeyword: ClassVar[str] = "constant"
175@export
176class Constant(BaseConstant, WithDefaultExpressionMixin):
177 """
178 Represents a constant.
180 As constants (always) have a default expression, the class :class:`~pyVHDLModel.Object.WithDefaultExpressionMixin` is inherited.
182 .. admonition:: Example
184 .. code-block:: VHDL
186 constant BITS : positive := 8;
188 .. seealso::
190 * :class:`Generic constant interface item <pyVHDLModel.Interface.GenericConstantInterfaceItem>`
191 * :class:`Parameter constant interface item <pyVHDLModel.Interface.ParameterConstantInterfaceItem>`
192 """
194 def __init__(
195 self,
196 identifiers: Iterable[str],
197 subtype: Symbol,
198 defaultExpression: Nullable[ExpressionUnion] = None,
199 documentation: Nullable[str] = None,
200 parent: Nullable[ModelEntity] = None
201 ) -> None:
202 """
203 Initializes a constant.
205 :param identifiers: A list of identifiers.
206 :param subtype: Reference to the object's subtype.
207 :param defaultExpression: The default value, or ``None`` if none was given.
208 :param documentation: The documentation comment associated with this declaration.
209 :param parent: The parent model entity of this entity.
210 """
211 super().__init__(identifiers, subtype, documentation, parent)
212 WithDefaultExpressionMixin.__init__(self, defaultExpression)
215@export
216class DeferredConstant(BaseConstant):
217 """
218 Represents a deferred constant.
220 Deferred constants are forward declarations for a (complete) constant declaration, thus it contains a
221 field :data:`__constantReference` to the complete constant declaration.
223 .. admonition:: Example
225 .. code-block:: VHDL
227 constant BITS : positive;
228 """
229 _constantReference: Nullable[Constant] #: The full declaration, or ``None`` if unlinked.
231 def __init__(
232 self,
233 identifiers: Iterable[str],
234 subtype: Symbol,
235 documentation: Nullable[str] = None,
236 parent: Nullable[ModelEntity] = None
237 ) -> None:
238 """
239 Initializes a deferred constant.
241 :param identifiers: A list of identifiers.
242 :param subtype: Reference to the object's subtype.
243 :param documentation: The documentation comment associated with this declaration.
244 :param parent: The parent model entity of this entity.
245 """
246 super().__init__(identifiers, subtype, documentation, parent)
248 self._constantReference = None
250 @readonly
251 def ConstantReference(self) -> Nullable[Constant]:
252 """
253 Read-only property to access the constant reference (:attr:`_constantReference`).
255 :returns: The constant reference, or ``None`` if not set.
256 """
257 return self._constantReference
260@export
261class Variable(Obj, WithDefaultExpressionMixin):
262 """
263 Represents a variable.
265 As variables might have a default expression, the class :class:`~pyVHDLModel.Object.WithDefaultExpressionMixin` is inherited.
267 .. admonition:: Example
269 .. code-block:: VHDL
271 variable result : natural := 0;
273 .. seealso::
275 * :class:`Parameter variable interface item <pyVHDLModel.Interface.ParameterVariableInterfaceItem>`
276 """
278 _objectKeyword: ClassVar[str] = "variable"
280 def __init__(
281 self,
282 identifiers: Iterable[str],
283 subtype: Symbol,
284 defaultExpression: Nullable[ExpressionUnion] = None,
285 documentation: Nullable[str] = None,
286 parent: Nullable[ModelEntity] = None
287 ) -> None:
288 """
289 Initializes a variable.
291 :param identifiers: A list of identifiers.
292 :param subtype: Reference to the object's subtype.
293 :param defaultExpression: The default value, or ``None`` if none was given.
294 :param documentation: The documentation comment associated with this declaration.
295 :param parent: The parent model entity of this entity.
296 """
297 super().__init__(identifiers, subtype, documentation, parent)
298 WithDefaultExpressionMixin.__init__(self, defaultExpression)
301@export
302class SharedVariable(Obj):
303 """
304 Represents a shared variable.
306 .. todo:: Shared variable object not implemented.
307 """
309 _objectKeyword: ClassVar[str] = "shared variable"
313@export
314class Signal(Obj, WithDefaultExpressionMixin):
315 """
316 Represents a signal.
318 As signals might have a default expression, the class :class:`~pyVHDLModel.Object.WithDefaultExpressionMixin` is inherited.
320 .. admonition:: Example
322 .. code-block:: VHDL
324 signal counter : unsigned(7 downto 0) := '0';
326 .. seealso::
328 * :class:`Port signal interface item <pyVHDLModel.Interface.PortSignalInterfaceItem>`
329 * :class:`Parameter signal interface item <pyVHDLModel.Interface.ParameterSignalInterfaceItem>`
330 """
332 _objectKeyword: ClassVar[str] = "signal"
334 def __init__(
335 self,
336 identifiers: Iterable[str],
337 subtype: Symbol,
338 defaultExpression: Nullable[ExpressionUnion] = None,
339 documentation: Nullable[str] = None,
340 parent: Nullable[ModelEntity] = None
341 ) -> None:
342 """
343 Initializes a signal.
345 :param identifiers: A list of identifiers.
346 :param subtype: Reference to the object's subtype.
347 :param defaultExpression: The default value, or ``None`` if none was given.
348 :param documentation: The documentation comment associated with this declaration.
349 :param parent: The parent model entity of this entity.
350 """
351 super().__init__(identifiers, subtype, documentation, parent)
352 WithDefaultExpressionMixin.__init__(self, defaultExpression)
355@export
356class File(Obj):
357 """
358 Represents a file.
360 .. todo:: File object not implemented.
362 .. seealso::
364 * :class:`Parameter file interface item <pyVHDLModel.Interface.ParameterFileInterfaceItem>`
365 """
367 _objectKeyword: ClassVar[str] = "file"