Coverage for pyVHDLModel/Symbol.py: 100%

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. 

34 

35Symbols are entity specific wrappers for names that reference VHDL language entities. 

36""" 

37from enum import Flag, auto 

38from typing import Any, Optional as Nullable, Iterable, List, Dict, Mapping 

39 

40from pyTooling.Decorators import export, readonly 

41from pyTooling.MetaClasses import ExtendedType 

42 

43from pyVHDLModel.Base import Range 

44from pyVHDLModel.Name import Name, AllName 

45 

46 

47@export 

48class PossibleReference(Flag): 

49 """ 

50 Is an enumeration, representing possible targets for a reference in a :class:`~pyVHDLModel.Symbol.Symbol`. 

51 """ 

52 

53 Unknown = 0 

54 Library = auto() #: Library 

55 Entity = auto() #: Entity 

56 Architecture = auto() #: Architecture 

57 Component = auto() #: Component 

58 Package = auto() #: Package 

59 Configuration = auto() #: Configuration 

60 Context = auto() #: Context 

61 Type = auto() #: Type 

62 Subtype = auto() #: Subtype 

63 ScalarType = auto() #: ScalarType 

64 ArrayType = auto() #: ArrayType 

65 RecordType = auto() #: RecordType 

66 RecordElement = auto() #: RecordElement 

67 AccessType = auto() #: AccessType 

68 ProtectedType = auto() #: ProtectedType 

69 FileType = auto() #: FileType 

70# Alias = auto() # TODO: Is this needed? 

71 Attribute = auto() #: Attribute 

72 TypeAttribute = auto() #: TypeAttribute 

73 ValueAttribute = auto() #: ValueAttribute 

74 SignalAttribute = auto() #: SignalAttribute 

75 RangeAttribute = auto() #: RangeAttribute 

76 ViewAttribute = auto() #: ViewAttribute 

77 Constant = auto() #: Constant 

78 Variable = auto() #: Variable 

79 Signal = auto() #: Signal 

80 File = auto() #: File 

81# Object = auto() # TODO: Is this needed? 

82 EnumLiteral = auto() #: EnumLiteral 

83 Procedure = auto() #: Procedure 

84 Function = auto() #: Function 

85 Label = auto() #: Label 

86 View = auto() #: View 

87 

88 AnyType = ScalarType | ArrayType | RecordType | ProtectedType | AccessType | FileType | Subtype #: Any possible type incl. subtypes. 

89 Object = Constant | Variable | Signal # | File #: Any object 

90 SubProgram = Procedure | Function #: Any subprogram 

91 PackageMember = AnyType | Object | SubProgram | Component #: Any member of a package 

92 SimpleNameInExpression = Constant | Variable | Signal | ScalarType | EnumLiteral | Function #: Any possible item in an expression. 

93 

94 

95# QUESTION: Why is it not a ModelEntity? 

96@export 

97class Symbol(metaclass=ExtendedType): 

98 """ 

99 Base-class for all symbol classes. 

100 """ 

101 

102 _name: Name #: The name to reference the language entity. 

103 _possibleReferences: PossibleReference #: An enumeration to filter possible references. 

104 _reference: Nullable[Any] #: The resolved language entity, otherwise ``None``. 

105 

106 def __init__(self, name: Name, possibleReferences: PossibleReference) -> None: 

107 """ 

108 Initializes a symbol. 

109 

110 :param name: The name to reference the language entity. 

111 :param possibleReferences: An enumeration to filter possible references. 

112 """ 

113 self._name = name 

114 self._possibleReferences = possibleReferences 

115 self._reference = None 

116 

117 @readonly 

118 def Name(self) -> Name: 

119 """ 

120 Read-only property to access the name (:attr:`_name`). 

121 

122 :returns: The name. 

123 """ 

124 return self._name 

125 

126 @readonly 

127 def Reference(self) -> Nullable[Any]: 

128 """ 

129 Read-only property to access the reference (:attr:`_reference`). 

130 

131 :returns: The reference, or ``None`` if not set. 

132 """ 

133 return self._reference 

134 

135 @readonly 

136 def IsResolved(self) -> bool: 

137 """ 

138 Check if the symbol is resolved, i.e. :attr:`_reference` is set. 

139 

140 :returns: ``True``, if the symbol is resolved. 

141 """ 

142 return self._reference is not None 

143 

144 def __bool__(self) -> bool: 

145 """ 

146 Reports whether this symbol has been resolved. 

147 

148 :returns: ``True`` if the symbol references a model entity. 

149 """ 

150 return self._reference is not None 

151 

152 def __repr__(self) -> str: 

153 """ 

154 Formats a representation of the symbol. 

155 

156 **Format:** ``SignalSymbol: 'clk' -> <signal>``, or ``... -> ?`` while unresolved 

157 

158 :returns: String representation of the symbol. 

159 """ 

160 if self._reference is not None: 

161 return f"{self.__class__.__name__}: '{self._name!s}' -> {self._reference!s}" 

162 

163 return f"{self.__class__.__name__}: '{self._name!s}' -> unresolved" 

164 

165 def __str__(self) -> str: 

166 """ 

167 Formats the symbol. 

168 

169 **Format:** the referenced model entity once resolved, else the name plus ``?`` 

170 

171 :returns: Formatted symbol. 

172 """ 

173 if self._reference is not None: 

174 return str(self._reference) 

175 

176 return f"{self._name!s}?" 

177 

178 

179@export 

180class LibraryReferenceSymbol(Symbol): 

181 """ 

182 Represents a reference (name) to a library. 

183 

184 The internal name will be a :class:`~pyVHDLModel.Name.SimpleName`. 

185 

186 .. admonition:: Example 

187 

188 .. code-block:: VHDL 

189 

190 library ieee; 

191 -- ^^^^ 

192 """ 

193 

194 def __init__(self, name: Name) -> None: 

195 """ 

196 Initializes a reference (name) to a library. 

197 

198 :param name: The name to reference the language entity. 

199 """ 

200 super().__init__(name, PossibleReference.Library) 

201 

202 @property 

203 def Library(self) -> Nullable['Library']: 

204 """ 

205 Property to access the library (:attr:`_reference`). 

206 

207 :returns: The library, or ``None`` if not set. 

208 """ 

209 return self._reference 

210 

211 @Library.setter 

212 def Library(self, value: 'Library') -> None: 

213 self._reference = value 

214 

215 

216@export 

217class PackageReferenceSymbol(Symbol): 

218 """ 

219 Represents a reference (name) to a package. 

220 

221 The internal name will be a :class:`~pyVHDLModel.Name.SelectedName`. 

222 

223 .. admonition:: Example 

224 

225 .. code-block:: VHDL 

226 

227 use ieee.numeric_std; 

228 -- ^^^^^^^^^^^^^^^^ 

229 """ 

230 

231 def __init__(self, name: Name) -> None: 

232 """ 

233 Initializes a reference (name) to a package. 

234 

235 :param name: The name to reference the language entity. 

236 """ 

237 super().__init__(name, PossibleReference.Package) 

238 

239 @property 

240 def Package(self) -> Nullable['Package']: 

241 """ 

242 Property to access the package (:attr:`_reference`). 

243 

244 :returns: The package, or ``None`` if not set. 

245 """ 

246 return self._reference 

247 

248 @Package.setter 

249 def Package(self, value: 'Package') -> None: 

250 self._reference = value 

251 

252 

253@export 

254class ModeViewSymbol(Symbol): 

255 """ 

256 Represents a reference to a mode view (VHDL-2019). 

257 

258 The referenced mode view is available as :data:`Reference` once resolved. A reference may also 

259 select the converse view. 

260 

261 .. admonition:: Example 

262 

263 Referencing a mode view: 

264 

265 .. code-block:: VHDL 

266 

267 port (p : view MasterView); 

268 -- ^^^^^^^^^^ <- Name 

269 

270 Referencing its converse: 

271 

272 .. code-block:: VHDL 

273 

274 port (p : view MasterView'converse); 

275 -- ^^^^^^^^^^^^^^^^^^^ <- Name 

276 """ 

277 

278 def __init__(self, name: Name) -> None: 

279 """ 

280 Initializes a reference to a mode view (VHDL-2019). 

281 

282 :param name: The name to reference the language entity. 

283 """ 

284 super().__init__(name, PossibleReference.View) 

285 

286 @property 

287 def ModeView(self) -> Nullable['ModeViewDeclaration']: 

288 """ 

289 Property to access the mode view (:attr:`_reference`). 

290 

291 :returns: The mode view, or ``None`` if not set. 

292 """ 

293 return self._reference 

294 

295 @ModeView.setter 

296 def ModeView(self, value: 'ModeViewDeclaration') -> None: 

297 self._reference = value 

298 

299 

300@export 

301class SubprogramReferenceSymbol(Symbol): 

302 """ 

303 Represents a reference to a subprogram. 

304 

305 The referenced subprogram is available as :data:`Reference` once resolved. 

306 

307 .. admonition:: Example 

308 

309 .. code-block:: VHDL 

310 

311 function f is new gen_fun generic map (N => 1); 

312 -- ^^^^^^^ <- Name 

313 """ 

314 

315 def __init__(self, name: Name) -> None: 

316 """ 

317 Initializes a reference to a subprogram. 

318 

319 :param name: The name to reference the language entity. 

320 """ 

321 super().__init__(name, PossibleReference.SubProgram) 

322 

323 @property 

324 def Subprogram(self) -> Nullable['Subprogram']: 

325 """ 

326 Property to access the subprogram (:attr:`_reference`). 

327 

328 :returns: The subprogram, or ``None`` if not set. 

329 """ 

330 return self._reference 

331 

332 @Subprogram.setter 

333 def Subprogram(self, value: 'Subprogram') -> None: 

334 self._reference = value 

335 

336 

337@export 

338class ConfigurationSymbol(Symbol): 

339 """ 

340 Represents a reference to a configuration. 

341 

342 The referenced configuration is available as :data:`Reference` once resolved. 

343 

344 .. admonition:: Example 

345 

346 .. code-block:: VHDL 

347 

348 for U1 : comp use configuration work.cfg; 

349 -- ^^^^^^^^ <- Name 

350 """ 

351 

352 def __init__(self, name: Name) -> None: 

353 """ 

354 Initializes a reference to a configuration. 

355 

356 :param name: The name to reference the language entity. 

357 """ 

358 super().__init__(name, PossibleReference.Configuration) 

359 

360 @property 

361 def Configuration(self) -> Nullable['Configuration']: 

362 """ 

363 Property to access the configuration (:attr:`_reference`). 

364 

365 :returns: The configuration, or ``None`` if not set. 

366 """ 

367 return self._reference 

368 

369 @Configuration.setter 

370 def Configuration(self, value: 'Configuration') -> None: 

371 self._reference = value 

372 

373 

374@export 

375class VariableSymbol(Symbol): 

376 """ 

377 Represents a reference (name) to a variable, e.g. the target of a variable assignment. 

378 

379 .. admonition:: Example 

380 

381 .. code-block:: VHDL 

382 

383 v := '1'; 

384 --^ 

385 """ 

386 

387 def __init__(self, name: Name) -> None: 

388 """ 

389 Initializes a variable symbol. 

390 

391 :param name: The name to reference the language entity. 

392 """ 

393 super().__init__(name, PossibleReference.Variable) 

394 

395 @property 

396 def Variable(self) -> Nullable['Variable']: 

397 """ 

398 Property to access the variable (:attr:`_reference`). 

399 

400 :returns: The variable, or ``None`` if not set. 

401 """ 

402 return self._reference 

403 

404 @Variable.setter 

405 def Variable(self, value: 'Variable') -> None: 

406 self._reference = value 

407 

408 

409@export 

410class SignalSymbol(Symbol): 

411 """ 

412 Represents a reference (name) to a signal, e.g. the target of a signal assignment. 

413 

414 .. admonition:: Example 

415 

416 .. code-block:: VHDL 

417 

418 s <= '1'; 

419 --^ 

420 """ 

421 

422 def __init__(self, name: Name) -> None: 

423 """ 

424 Initializes a signal symbol. 

425 

426 :param name: The name to reference the language entity. 

427 """ 

428 super().__init__(name, PossibleReference.Signal) 

429 

430 @property 

431 def Signal(self) -> Nullable['Signal']: 

432 """ 

433 Property to access the signal (:attr:`_reference`). 

434 

435 :returns: The signal, or ``None`` if not set. 

436 """ 

437 return self._reference 

438 

439 @Signal.setter 

440 def Signal(self, value: 'Signal') -> None: 

441 self._reference = value 

442 

443 

444@export 

445class ContextReferenceSymbol(Symbol): 

446 """ 

447 Represents a reference (name) to a context. 

448 

449 The internal name will be a :class:`~pyVHDLModel.Name.SelectedName`. 

450 

451 .. admonition:: Example 

452 

453 .. code-block:: VHDL 

454 

455 context ieee.ieee_std_context; 

456 -- ^^^^^^^^^^^^^^^^^^^^^ 

457 """ 

458 

459 def __init__(self, name: Name) -> None: 

460 """ 

461 Initializes a reference (name) to a context. 

462 

463 :param name: The name to reference the language entity. 

464 """ 

465 super().__init__(name, PossibleReference.Context) 

466 

467 @property 

468 def Context(self) -> 'Context': 

469 """ 

470 Property to access the context (:attr:`_reference`). 

471 

472 :returns: The context. 

473 """ 

474 return self._reference 

475 

476 @Context.setter 

477 def Context(self, value: 'Context') -> None: 

478 self._reference = value 

479 

480 

481@export 

482class PackageMemberReferenceSymbol(Symbol): 

483 """ 

484 Represents a reference (name) to a package member. 

485 

486 The internal name will be a :class:`~pyVHDLModel.Name.SelectedName`. 

487 

488 .. admonition:: Example 

489 

490 .. code-block:: VHDL 

491 

492 use ieee.numeric_std.unsigned; 

493 -- ^^^^^^^^^^^^^^^^^^^^^^^^^ 

494 """ 

495 

496 def __init__(self, name: Name) -> None: 

497 """ 

498 Initializes a reference (name) to a package member. 

499 

500 :param name: The name to reference the language entity. 

501 """ 

502 super().__init__(name, PossibleReference.PackageMember) 

503 

504 @property 

505 def Member(self) -> Nullable['Package']: # TODO: typehint 

506 """ 

507 Property to access the member (:attr:`_reference`). 

508 

509 :returns: The member, or ``None`` if not set. 

510 """ 

511 return self._reference 

512 

513 @Member.setter 

514 def Member(self, value: 'Package') -> None: # TODO: typehint 

515 self._reference = value 

516 

517 

518@export 

519class AllPackageMembersReferenceSymbol(Symbol): 

520 """ 

521 Represents a reference (name) to all package members. 

522 

523 The internal name will be a :class:`~pyVHDLModel.Name.AllName`. 

524 

525 .. admonition:: Example 

526 

527 .. code-block:: VHDL 

528 

529 use ieee.numeric_std.all; 

530 -- ^^^^^^^^^^^^^^^^^^^^ 

531 """ 

532 

533 def __init__(self, name: AllName) -> None: 

534 """ 

535 Initializes a reference (name) to all package members. 

536 

537 :param name: The name to reference the language entity. 

538 """ 

539 super().__init__(name, PossibleReference.PackageMember) 

540 

541 @property 

542 def Members(self) -> 'Package': # TODO: typehint 

543 """ 

544 Property to access the members (:attr:`_reference`). 

545 

546 :returns: The members. 

547 """ 

548 return self._reference 

549 

550 @Members.setter 

551 def Members(self, value: 'Package') -> None: # TODO: typehint 

552 self._reference = value 

553 

554 

555@export 

556class EntityInstantiationSymbol(Symbol): 

557 """ 

558 Represents a reference (name) to an entity in a direct entity instantiation. 

559 

560 The internal name will be a :class:`~pyVHDLModel.Name.SimpleName` or :class:`~pyVHDLModel.Name.SelectedName`. 

561 

562 .. admonition:: Example 

563 

564 .. code-block:: VHDL 

565 

566 inst : entity work.Counter; 

567 -- ^^^^^^^^^^^^ 

568 """ 

569 

570 def __init__(self, name: Name) -> None: 

571 """ 

572 Initializes a reference (name) to an entity in a direct entity instantiation. 

573 

574 :param name: The name to reference the language entity. 

575 """ 

576 super().__init__(name, PossibleReference.Entity) 

577 

578 @property 

579 def Entity(self) -> 'Entity': 

580 """ 

581 Property to access the entity (:attr:`_reference`). 

582 

583 :returns: The entity. 

584 """ 

585 return self._reference 

586 

587 @Entity.setter 

588 def Entity(self, value: 'Entity') -> None: 

589 self._reference = value 

590 

591 

592@export 

593class ComponentInstantiationSymbol(Symbol): 

594 """ 

595 Represents a reference (name) to an entity in a component instantiation. 

596 

597 The internal name will be a :class:`~pyVHDLModel.Name.SimpleName` or :class:`~pyVHDLModel.Name.SelectedName`. 

598 

599 .. admonition:: Example 

600 

601 .. code-block:: VHDL 

602 

603 inst : component Counter; 

604 -- ^^^^^^^ 

605 """ 

606 

607 def __init__(self, name: Name) -> None: 

608 """ 

609 Initializes a reference (name) to an entity in a component instantiation. 

610 

611 :param name: The name to reference the language entity. 

612 """ 

613 super().__init__(name, PossibleReference.Component) 

614 

615 @property 

616 def Component(self) -> 'Component': 

617 """ 

618 Property to access the component (:attr:`_reference`). 

619 

620 :returns: The component. 

621 """ 

622 return self._reference 

623 

624 @Component.setter 

625 def Component(self, value: 'Component') -> None: 

626 self._reference = value 

627 

628 

629@export 

630class ConfigurationInstantiationSymbol(Symbol): 

631 """ 

632 Represents a reference (name) to an entity in a configuration instantiation. 

633 

634 The internal name will be a :class:`~pyVHDLModel.Name.SimpleName` or :class:`~pyVHDLModel.Name.SelectedName`. 

635 

636 .. admonition:: Example 

637 

638 .. code-block:: VHDL 

639 

640 inst : configuration Counter; 

641 -- ^^^^^^^ 

642 """ 

643 

644 def __init__(self, name: Name) -> None: 

645 """ 

646 Initializes a reference (name) to an entity in a configuration instantiation. 

647 

648 :param name: The name to reference the language entity. 

649 """ 

650 super().__init__(name, PossibleReference.Configuration) 

651 

652 @property 

653 def Configuration(self) -> 'Configuration': 

654 """ 

655 Property to access the configuration (:attr:`_reference`). 

656 

657 :returns: The configuration. 

658 """ 

659 return self._reference 

660 

661 @Configuration.setter 

662 def Configuration(self, value: 'Configuration') -> None: 

663 self._reference = value 

664 

665 

666@export 

667class EntitySymbol(Symbol): 

668 """ 

669 Represents a reference (name) to an entity in an architecture declaration. 

670 

671 The internal name will be a :class:`~pyVHDLModel.Name.SimpleName` or :class:`~pyVHDLModel.Name.SelectedName`. 

672 

673 .. admonition:: Example 

674 

675 .. code-block:: VHDL 

676 

677 architecture rtl of Counter is 

678 -- ^^^^^^^ 

679 begin 

680 end architecture; 

681 """ 

682 

683 def __init__(self, name: Name) -> None: 

684 """ 

685 Initializes a reference (name) to an entity in an architecture declaration. 

686 

687 :param name: The name to reference the language entity. 

688 """ 

689 super().__init__(name, PossibleReference.Entity) 

690 

691 @property 

692 def Entity(self) -> 'Entity': 

693 """ 

694 Property to access the entity (:attr:`_reference`). 

695 

696 :returns: The entity. 

697 """ 

698 return self._reference 

699 

700 @Entity.setter 

701 def Entity(self, value: 'Entity') -> None: 

702 self._reference = value 

703 

704 

705@export 

706class ArchitectureSymbol(Symbol): 

707 """An entity reference in an entity instantiation with architecture name.""" 

708 

709 def __init__(self, name: Name) -> None: 

710 """ 

711 Initializes an architecture symbol. 

712 

713 :param name: The name to reference the language entity. 

714 """ 

715 super().__init__(name, PossibleReference.Architecture) 

716 

717 @property 

718 def Architecture(self) -> 'Architecture': 

719 """ 

720 Property to access the architecture (:attr:`_reference`). 

721 

722 :returns: The architecture. 

723 """ 

724 return self._reference 

725 

726 @Architecture.setter 

727 def Architecture(self, value: 'Architecture') -> None: 

728 self._reference = value 

729 

730 

731@export 

732class PackageSymbol(Symbol): 

733 """ 

734 Represents a reference (name) to a package in a package body declaration. 

735 

736 The internal name will be a :class:`~pyVHDLModel.Name.SimpleName` or :class:`~pyVHDLModel.Name.SelectedName`. 

737 

738 .. admonition:: Example 

739 

740 .. code-block:: VHDL 

741 

742 package body Utilities is 

743 -- ^^^^^^^^^ 

744 end package body; 

745 """ 

746 

747 def __init__(self, name: Name) -> None: 

748 """ 

749 Initializes a reference (name) to a package in a package body declaration. 

750 

751 :param name: The name to reference the language entity. 

752 """ 

753 super().__init__(name, PossibleReference.Package) 

754 

755 @property 

756 def Package(self) -> 'Package': 

757 """ 

758 Property to access the package (:attr:`_reference`). 

759 

760 :returns: The package. 

761 """ 

762 return self._reference 

763 

764 @Package.setter 

765 def Package(self, value: 'Package') -> None: 

766 self._reference = value 

767 

768 

769@export 

770class RecordElementSymbol(Symbol): 

771 """ 

772 Represents a reference to a record element. 

773 

774 The referenced language entity is available as :data:`Reference` once resolved. 

775 

776 .. admonition:: Example 

777 

778 .. code-block:: VHDL 

779 

780 r := (a => '1', b => '0'); 

781 -- ^ <- Name 

782 """ 

783 def __init__(self, name: Name) -> None: 

784 """ 

785 Initializes a reference to a record element. 

786 

787 :param name: The name to reference the language entity. 

788 """ 

789 super().__init__(name, PossibleReference.RecordElement) 

790 

791 

792@export 

793class RangeAttributeSymbol(Symbol): 

794 """A symbol referencing a range attribute, e.g. ``vector'range``.""" 

795 

796 def __init__(self, name: Name) -> None: 

797 """ 

798 Initialize a range attribute symbol. 

799 

800 :param name: The attribute name referencing the range. 

801 """ 

802 super().__init__(name, PossibleReference.RangeAttribute) 

803 

804 

805@export 

806class SubtypeSymbol(Symbol): 

807 """ 

808 Represents the base-class of all references to a type or subtype. 

809 

810 The referenced language entity is available as :data:`Reference` once resolved. 

811 

812 .. seealso:: 

813 

814 * :class:`Simple subtype symbol <pyVHDLModel.Symbol.SimpleSubtypeSymbol>` 

815 * :class:`Constrained scalar subtype symbol <pyVHDLModel.Symbol.ConstrainedScalarSubtypeSymbol>` 

816 * :class:`Constrained composite subtype symbol <pyVHDLModel.Symbol.ConstrainedCompositeSubtypeSymbol>` 

817 """ 

818 def __init__(self, name: Name) -> None: 

819 """ 

820 Initializes a subtype symbol. 

821 

822 :param name: The name to reference the language entity. 

823 """ 

824 super().__init__(name, PossibleReference.Type | PossibleReference.Subtype) 

825 

826 @property 

827 def Subtype(self) -> 'Subtype': 

828 """ 

829 Property to access the subtype (:attr:`_reference`). 

830 

831 :returns: The subtype. 

832 """ 

833 return self._reference 

834 

835 @Subtype.setter 

836 def Subtype(self, value: 'Subtype') -> None: 

837 self._reference = value 

838 

839 

840@export 

841class SimpleSubtypeSymbol(SubtypeSymbol): 

842 """ 

843 Represents a reference to a type or subtype by its type mark. 

844 

845 The referenced language entity is available as :data:`Reference` once resolved. 

846 

847 .. admonition:: Example 

848 

849 .. code-block:: VHDL 

850 

851 signal s : bit := '0'; 

852 -- ^^^ <- Name 

853 """ 

854 pass 

855 

856 

857@export 

858class Constraint(metaclass=ExtendedType, mixin=True): 

859 """ 

860 A mixin-class for symbols carrying a constraint. 

861 

862 .. seealso:: 

863 

864 * :class:`Scalar constraint <pyVHDLModel.Symbol.ScalarConstraint>` 

865 * :class:`Array constraint <pyVHDLModel.Symbol.ArrayConstraint>` 

866 * :class:`Record constraint <pyVHDLModel.Symbol.RecordConstraint>` 

867 """ 

868 pass 

869 

870 

871@export 

872class ScalarConstraint(Constraint, mixin=True): 

873 """ 

874 A mixin-class for a scalar constraint: a range. 

875 

876 The range is available as :data:`Constraint`. 

877 

878 .. seealso:: 

879 

880 * :class:`Constrained scalar subtype symbol <pyVHDLModel.Symbol.ConstrainedScalarSubtypeSymbol>` 

881 """ 

882 _constraint: Range #: The range constraining the scalar subtype. 

883 

884 def __init__(self, constraint: Range) -> None: 

885 """ 

886 Initializes a scalar constraint. 

887 

888 :param constraint: The range constraining the scalar subtype. 

889 """ 

890 self._constraint = constraint 

891 

892 @readonly 

893 def Constraint(self) -> Range: 

894 """ 

895 Read-only property to access the scalar type's range constraint (:attr:`_constraint`). 

896 

897 :returns: The constraint of the scalar subtype. 

898 """ 

899 return self._constraint 

900 

901 

902@export 

903class ConstrainedScalarSubtypeSymbol(SubtypeSymbol, ScalarConstraint): 

904 """ 

905 Represents a reference to a scalar subtype narrowed by a range. 

906 

907 The referenced language entity is available as :data:`Reference` once resolved. The range is 

908 mandatory: a type mark without a range constraint is a :class:`~pyVHDLModel.Symbol.SimpleSubtypeSymbol`. 

909 

910 .. admonition:: Example 

911 

912 .. code-block:: VHDL 

913 

914 for i in integer range 0 to 3 loop 

915 -- ^^^^^^^ <- Name 

916 -- ^^^^^^ <- Constraint 

917 

918 A range constraint written as a range attribute is a :class:`~pyVHDLModel.Base.RangeFromName` 

919 referring to a :class:`~pyVHDLModel.Symbol.RangeAttributeSymbol`: 

920 

921 .. code-block:: VHDL 

922 

923 subtype index is natural range vector'range; 

924 -- ^^^^^^^ <- Name 

925 -- ^^^^^^^^^^^^ <- Constraint 

926 """ 

927 

928 def __init__(self, name: Name, constraint: Range) -> None: 

929 """ 

930 Initializes a reference to a scalar subtype narrowed by a range. 

931 

932 :param name: The name to reference the language entity. 

933 :param constraint: The range constraining the scalar subtype. 

934 """ 

935 super().__init__(name) 

936 ScalarConstraint.__init__(self, constraint) 

937 

938 

939@export 

940class ArrayConstraint(Constraint, mixin=True): 

941 """ 

942 A mixin-class for an array constraint: one range per dimension. 

943 

944 The ranges are available as :data:`Constraints`. 

945 

946 .. seealso:: 

947 

948 * :class:`Constrained array subtype symbol <pyVHDLModel.Symbol.ConstrainedArraySubtypeSymbol>` 

949 """ 

950 _constraints: List[Range] #: List of all index ranges, one per dimension. 

951 

952 def __init__(self, constraints: Iterable[Range]) -> None: 

953 """ 

954 Initializes an array constraint. 

955 

956 :param constraints: List of all index ranges, one per dimension. 

957 """ 

958 self._constraints = [constraint for constraint in constraints] 

959 

960 @readonly 

961 def Constraints(self) -> List[Range]: 

962 """ 

963 Read-only property to access the constraints (:attr:`_constraints`). 

964 

965 :returns: List of constraints. 

966 """ 

967 return self._constraints 

968 

969 

970@export 

971class RecordConstraint(Constraint, mixin=True): 

972 """ 

973 A mixin-class for a record constraint: one constraint per element. 

974 

975 The constraints are available as :data:`Constraints`. 

976 

977 .. seealso:: 

978 

979 * :class:`Constrained record subtype symbol <pyVHDLModel.Symbol.ConstrainedRecordSubtypeSymbol>` 

980 """ 

981 _constraints: Dict[RecordElementSymbol, Range] #: Dictionary of the constraint per constrained record element. 

982 

983 def __init__(self, constraints: Mapping[RecordElementSymbol, Range]) -> None: 

984 """ 

985 Initializes a record constraint. 

986 

987 :param constraints: Dictionary of the constraint per constrained record element. 

988 """ 

989 self._constraints = {key: value for key, value in constraints.items()} 

990 

991 @readonly 

992 def Constraints(self) -> Dict[RecordElementSymbol, Range]: 

993 """ 

994 Read-only property to access the constraints (:attr:`_constraints`). 

995 

996 :returns: Dictionary of constraints. 

997 """ 

998 return self._constraints 

999 

1000 

1001@export 

1002class ConstrainedCompositeSubtypeSymbol(SubtypeSymbol): 

1003 """ 

1004 Represents the base-class of references to constrained composite subtypes. 

1005 

1006 The referenced language entity is available as :data:`Reference` once resolved. 

1007 

1008 .. seealso:: 

1009 

1010 * :class:`Constrained array subtype symbol <pyVHDLModel.Symbol.ConstrainedArraySubtypeSymbol>` 

1011 * :class:`Constrained record subtype symbol <pyVHDLModel.Symbol.ConstrainedRecordSubtypeSymbol>` 

1012 """ 

1013 pass 

1014 

1015 

1016@export 

1017class ConstrainedArraySubtypeSymbol(ConstrainedCompositeSubtypeSymbol, ArrayConstraint): 

1018 """ 

1019 Represents a reference to an array subtype narrowed by index ranges. 

1020 

1021 The referenced language entity is available as :data:`Reference` once resolved. 

1022 

1023 .. admonition:: Example 

1024 

1025 .. code-block:: VHDL 

1026 

1027 signal v : bit_vector(7 downto 0); 

1028 -- ^^^^^^^^^^ <- Name 

1029 -- ^^^^^^^^^^ <- Constraints 

1030 """ 

1031 _constraints: List #: List of all index ranges, one per dimension. 

1032 

1033 def __init__(self, name: Name, constraints: Iterable) -> None: 

1034 """ 

1035 Initializes a reference to an array subtype narrowed by index ranges. 

1036 

1037 :param name: The name to reference the language entity. 

1038 :param constraints: List of all index ranges, one per dimension. 

1039 """ 

1040 super().__init__(name) 

1041 ArrayConstraint.__init__(self, constraints) 

1042 

1043 

1044@export 

1045class ConstrainedRecordSubtypeSymbol(ConstrainedCompositeSubtypeSymbol, RecordConstraint): 

1046 """ 

1047 Represents a reference to a record subtype with constrained elements. 

1048 

1049 The referenced language entity is available as :data:`Reference` once resolved. 

1050 """ 

1051 _constraints: Dict[RecordElementSymbol, Any] #: Dictionary of the constraint per constrained record element. 

1052 

1053 def __init__(self, name: Name, constraints: Mapping) -> None: 

1054 """ 

1055 Initializes a reference to a record subtype with constrained elements. 

1056 

1057 :param name: The name to reference the language entity. 

1058 :param constraints: Dictionary of the constraint per constrained record element. 

1059 """ 

1060 super().__init__(name) 

1061 RecordConstraint.__init__(self, constraints) 

1062 

1063 

1064@export 

1065class SimpleObjectOrFunctionCallSymbol(Symbol): 

1066 """ 

1067 Represents a reference that is either an object or a parameterless function call. 

1068 

1069 Which of the two it is cannot be decided before the name is resolved. The referenced language 

1070 entity is available as :data:`Reference` once resolved. 

1071 """ 

1072 def __init__(self, name: Name) -> None: 

1073 """ 

1074 Initializes a reference that is either an object or a parameterless function call. 

1075 

1076 :param name: The name to reference the language entity. 

1077 """ 

1078 super().__init__(name, PossibleReference.SimpleNameInExpression)