Coverage for pyVHDLModel/Interface.py: 97%

1# ==================================================================================================================== #

2# __ ___ _ ____ _ __ __ _ _ #

3# _ __ _ \ \ / / | | | _ \| | | \/ | ___ __| | ___| | #

4# | '_ \| | | \ \ / /| |_| | | | | | | |\/| |/ _ \ / _` |/ _ \ | #

5# | |_) | |_| |\ V / | _ | |_| | |___| | | | (_) | (_| | __/ | #

6# | .__/ \__, | \_/ |_| |_|____/|_____|_| |_|\___/ \__,_|\___|_| #

7# |_| |___/ #

8# ==================================================================================================================== #

9# Authors: #

10# Patrick Lehmann #

11# #

12# License: #

13# ==================================================================================================================== #

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.

35Interface items are used in generic, port and parameter declarations.

36"""

37from typing import Iterable, Optional as Nullable, List, Iterator, Tuple

39from pyTooling.Decorators import export, readonly

40from pyTooling.MetaClasses import ExtendedType

42from pyVHDLModel.Symbol import Symbol, SubtypeSymbol, ModeViewSymbol

43from pyVHDLModel.Base import ModelEntity, DocumentedEntityMixin, NamedEntityMixin, OptionallyNamedEntityMixin

44from pyVHDLModel.Base import MultipleNamedEntityMixin, identifiersOf

45from pyVHDLModel.Base import ExpressionUnion, Mode

46from pyVHDLModel.Object import Constant, Signal, Variable, File

47from pyVHDLModel.Subprogram import Procedure, Function

48from pyVHDLModel.Type import Type

51@export

52class ModeViewElement(ModelEntity, MultipleNamedEntityMixin, DocumentedEntityMixin):

53 """

54 Base-class for one element definition inside a mode view declaration (VHDL-2019). An element may name

55 several fields sharing the same specification (e.g. ``a, b : out;``), hence

56 :class:`~pyVHDLModel.Base.MultipleNamedEntityMixin` is inherited.

58 .. seealso::

60 * :class:`Simple mode view element <pyVHDLModel.Interface.SimpleModeViewElement>`

61 * :class:`Composite mode view element <pyVHDLModel.Interface.CompositeModeViewElement>`

62 """

64 def __init__(

65 self,

66 identifiers: Iterable[str],

67 documentation: Nullable[str] = None,

68 parent: Nullable[ModelEntity] = None

69 ) -> None:

70 """

71 Initializes a mode view element.

73 :param identifiers: A list of identifiers.

74 :param documentation: The documentation comment associated with this declaration.

75 :param parent: The parent model entity of this entity.

76 """

77 super().__init__(parent)

78 MultipleNamedEntityMixin.__init__(self, identifiers)

79 DocumentedEntityMixin.__init__(self, documentation)

81 def __str__(self) -> str:

82 """

83 Formats the mode view element as its identifiers.

85 **Format:** ``a, b``

87 :returns: The element's identifiers, comma-separated.

88 """

89 return ", ".join(self._identifiers)

92@export

93class SimpleModeViewElement(ModeViewElement):

94 """

95 A mode view element with a plain (simple) mode.

97 .. admonition:: Example

99 .. code-block:: VHDL

100

101 view MyView of RecordType is

102 a, b : out;

103 -- ^^^

104 end view;

105 """

106

107 _mode: Mode #: The element's mode.

108

109 def __init__(

110 self,

111 identifiers: Iterable[str],

112 mode: Mode,

113 documentation: Nullable[str] = None,

114 parent: Nullable[ModelEntity] = None

115 ) -> None:

116 """

117 Initializes a simple mode view element.

118

119 :param identifiers: A list of identifiers.

120 :param mode: The element's mode.

121 :param documentation: The documentation comment associated with this declaration.

122 :param parent: The parent model entity of this entity.

123 """

124 super().__init__(identifiers, documentation, parent)

125 self._mode = mode

126

127 @readonly

128 def Mode(self) -> Mode:

129 """

130 Read-only property to access the mode (:attr:`_mode`).

131

132 :returns: The mode.

133 """

134 return self._mode

135

136

137@export

138class CompositeModeViewElement(ModeViewElement):

139 """

140 A mode view element that refers to another (named) mode view for an array or record sub-element.

141 .. admonition:: Example

142

143 .. code-block:: VHDL

144

145 view OuterView of OuterRecord is

146 b : view InnerView;

147 -- ^^^^^^^^^

148 end view;

149 """

150

151 _modeViewName: ModeViewSymbol #: Reference to the mode view applied to this element.

152

153 def __init__(

154 self,

155 identifiers: Iterable[str],

156 modeViewName: ModeViewSymbol,

157 documentation: Nullable[str] = None,

158 parent: Nullable[ModelEntity] = None

159 ) -> None:

160 """

161 Initializes a composite mode view element.

162

163 :param identifiers: A list of identifiers.

164 :param modeViewName: Reference to the mode view applied to this element.

165 :param documentation: The documentation comment associated with this declaration.

166 :param parent: The parent model entity of this entity.

167 """

168 super().__init__(identifiers, documentation, parent)

169

170 self._modeViewName = modeViewName

171 modeViewName.Parent = self

172

173 @readonly

174 def ModeViewName(self) -> ModeViewSymbol:

175 """

176 Read-only property to access the mode view name (:attr:`_modeViewName`).

177

178 :returns: The mode view name.

179 """

180 return self._modeViewName

181

182

183@export

184class ModeViewDeclaration(ModelEntity, NamedEntityMixin, DocumentedEntityMixin):

185 """

186 Represents a mode view declaration (VHDL-2019).

187

188 .. admonition:: Example

189

190 .. code-block:: VHDL

191

192 view MyView of RecordType is

193 a : out;

194 b : in;

195 end view;

196

197 .. seealso::

198

199 * :class:`Port declared with a mode view <pyVHDLModel.Interface.PortViewSignalInterfaceItem>`

200 * :class:`Parameter declared with a mode view <pyVHDLModel.Interface.ParameterViewSignalInterfaceItem>`

201 * :class:`Reference to a mode view <pyVHDLModel.Symbol.ModeViewSymbol>`

202 """

203

204 _subtype: SubtypeSymbol #: Reference to the subtype this mode view applies to.

205 _elements: List[ModeViewElement] #: List of all mode view elements, in declaration order.

206

207 def __init__(

208 self,

209 identifier: str,

210 subtype: SubtypeSymbol,

211 elements: Nullable[Iterable[ModeViewElement]] = None,

212 documentation: Nullable[str] = None,

213 parent: Nullable[ModelEntity] = None

214 ) -> None:

215 """

216 Initializes a mode view declaration (VHDL-2019).

217

218 :param identifier: The identifier of a model entity.

219 :param subtype: Reference to the subtype this mode view applies to.

220 :param elements: List of all mode view elements, in declaration order.

221 :param documentation: The documentation comment associated with this declaration.

222 :param parent: The parent model entity of this entity.

223 """

224 super().__init__(parent)

225 NamedEntityMixin.__init__(self, identifier)

226 DocumentedEntityMixin.__init__(self, documentation)

227

228 self._subtype = subtype

229 subtype.Parent = self

230

231 self._elements = []

232 if elements is not None:

233 for element in elements:

234 self._elements.append(element)

235 element.Parent = self

236

237 @readonly

238 def Subtype(self) -> SubtypeSymbol:

239 """

240 Read-only property to access the subtype (:attr:`_subtype`).

241

242 :returns: The subtype.

243 """

244 return self._subtype

245

246 @readonly

247 def Elements(self) -> List[ModeViewElement]:

248 """

249 Read-only property to access the elements (:attr:`_elements`).

250

251 :returns: List of elements.

252 """

253 return self._elements

254

255 def __str__(self) -> str:

256 """

257 Formats the mode view declaration.

258

259 **Format:** ``view myView of myRecord: a, b``

260

261 :returns: Formatted mode view declaration.

262 """

263 elements = ", ".join(str(element) for element in self._elements)

264 return f"view {self._identifier} of {self._subtype}: {elements}"

265

266

267@export

268class InterfaceItemMixin(metaclass=ExtendedType, mixin=True):

269 """

270 A mixin-class marking a declaration as an interface item.

271

272 Interface items appear in generic clauses, port clauses and parameter lists.

273

274 .. seealso::

275

276 * :class:`Generic interface item mixin <pyVHDLModel.Interface.GenericInterfaceItemMixin>`

277 * :class:`Port interface item mixin <pyVHDLModel.Interface.PortInterfaceItemMixin>`

278 * :class:`Parameter interface item mixin <pyVHDLModel.Interface.ParameterInterfaceItemMixin>`

279 * :class:`Port signal interface item <pyVHDLModel.Interface.PortSignalInterfaceItem>`

280 """

281

282 def _FormatInterfaceItem(self, mode: Nullable[Mode] = None, isModeView: bool = False) -> str:

283 """

284 Format this interface item as a single-line declaration.

285

286 Interface items are objects, so they render like one (``signal p : bit``), but an object's own

287 rendering cannot show the interface *mode* - a mode is not part of an object declaration. This

288 adds it, for the derived class's :meth:`__str__` to return.

289

290 :param mode: This item's mode, or ``None`` when it declares none.

291 :param isModeView: ``True`` if the subtype position holds a mode view (VHDL-2019), not a subtype.

292 :returns: Formatted interface item.

293 """

294 prefix = "" if mode is None or mode is Mode.Default else f"{mode!s} "

295 if isModeView:

296 prefix = "view "

297

298 return f"{self._objectKeyword} {', '.join(self._identifiers)} : {prefix}{self._subtype}"

299

300

301@export

302class InterfaceItemWithModeMixin(metaclass=ExtendedType, mixin=True):

303 """

304 A mixin-class for interface items declared with a mode.

305

306 The mode is available as :data:`Mode`.

307

308 .. seealso::

309

310 * :class:`Port interface item mixin <pyVHDLModel.Interface.PortInterfaceItemMixin>`

311 * :class:`Generic constant interface item <pyVHDLModel.Interface.GenericConstantInterfaceItem>`

312 * :class:`Port simple signal interface item <pyVHDLModel.Interface.PortSimpleSignalInterfaceItem>`

313 * :class:`Parameter constant interface item <pyVHDLModel.Interface.ParameterConstantInterfaceItem>`

314 * :class:`Parameter variable interface item <pyVHDLModel.Interface.ParameterVariableInterfaceItem>`

315 * :class:`Parameter simple signal interface item <pyVHDLModel.Interface.ParameterSimpleSignalInterfaceItem>`

316 """

317

318 _mode: Mode #: The interface item's mode.

319

320 def __init__(self, mode: Mode) -> None:

321 """

322 Initializes an interface item with mode.

323

324 :param mode: The interface item's mode.

325 """

326 self._mode = mode

327

328 @readonly

329 def Mode(self) -> Mode:

330 """

331 Read-only property to access the mode (:attr:`_mode`).

332

333 :returns: The mode.

334 """

335 return self._mode

336

337

338@export

339class GenericInterfaceItemMixin(InterfaceItemMixin, mixin=True):

340 """

341 A mixin-class for all items in a generic clause.

342

343 .. seealso::

344

345 * :class:`Generic constant interface item <pyVHDLModel.Interface.GenericConstantInterfaceItem>`

346 * :class:`Generic type interface item <pyVHDLModel.Interface.GenericTypeInterfaceItem>`

347 * :class:`Generic subprogram interface item <pyVHDLModel.Interface.GenericSubprogramInterfaceItem>`

348 * :class:`Generic procedure interface item <pyVHDLModel.Interface.GenericProcedureInterfaceItem>`

349 * :class:`Generic function interface item <pyVHDLModel.Interface.GenericFunctionInterfaceItem>`

350 * :class:`Generic package interface item <pyVHDLModel.Interface.GenericPackageInterfaceItem>`

351 """

352

353

354@export

355class PortInterfaceItemMixin(InterfaceItemMixin, InterfaceItemWithModeMixin, mixin=True):

356 """

357 A mixin-class for all items in a port clause.

358 """

359

360 def __init__(self, mode: Mode) -> None:

361 """

362 Initializes a port interface item.

363

364 :param mode: The interface item's mode.

365 """

366 super().__init__()

367 InterfaceItemWithModeMixin.__init__(self, mode)

368

369

370@export

371class ParameterInterfaceItemMixin(InterfaceItemMixin, mixin=True):

372 """

373 A mixin-class for all items in a subprogram's parameter list.

374

375 .. seealso::

376

377 * :class:`Parameter constant interface item <pyVHDLModel.Interface.ParameterConstantInterfaceItem>`

378 * :class:`Parameter variable interface item <pyVHDLModel.Interface.ParameterVariableInterfaceItem>`

379 * :class:`Parameter signal interface item <pyVHDLModel.Interface.ParameterSignalInterfaceItem>`

380 * :class:`Parameter file interface item <pyVHDLModel.Interface.ParameterFileInterfaceItem>`

381 """

382

383

384@export

385class GenericConstantInterfaceItem(Constant, GenericInterfaceItemMixin, InterfaceItemWithModeMixin):

386 """

387 Represents a constant in a generic clause.

388

389 .. admonition:: Example

390

391 .. code-block:: VHDL

392

393 generic (W : positive := 8);

394 -- ^ <- Identifiers

395 -- ^^^^^^^^ <- Subtype

396 -- ^ <- DefaultExpression

397 """

398 def __init__(

399 self,

400 identifiers: Iterable[str],

401 mode: Mode,

402 subtype: Symbol,

403 defaultExpression: Nullable[ExpressionUnion] = None,

404 documentation: Nullable[str] = None,

405 parent: Nullable[ModelEntity] = None

406 ) -> None:

407 """

408 Initializes a constant in a generic clause.

409

410 :param identifiers: A list of identifiers.

411 :param mode: The interface item's mode.

412 :param subtype: Reference to the object's subtype.

413 :param defaultExpression: The default value, or ``None`` if none was given.

414 :param documentation: The documentation comment associated with this declaration.

415 :param parent: The parent model entity of this entity.

416 """

417 super().__init__(identifiers, subtype, defaultExpression, documentation, parent)

418 GenericInterfaceItemMixin.__init__(self)

419 InterfaceItemWithModeMixin.__init__(self, mode)

420

421 def __str__(self) -> str:

422 """

423 Formats the generic constant.

424

425 **Format:** ``constant G : in positive``

426

427 :returns: Formatted generic constant.

428 """

429 return self._FormatInterfaceItem(self._mode)

430

431

432@export

433class GenericTypeInterfaceItem(Type, GenericInterfaceItemMixin):

434 """

435 Represents a type in a generic clause.

436

437 A generic type introduces a type name without defining the type.

438

439 .. admonition:: Example

440

441 .. code-block:: VHDL

442

443 generic (type T);

444 -- ^ <- Identifier

445 """

446 def __init__(self, identifier: str, documentation: Nullable[str] = None, parent: Nullable[ModelEntity] = None) -> None:

447 """

448 Initializes a type in a generic clause.

449

450 :param identifier: The identifier of a model entity.

451 :param documentation: The documentation comment associated with this declaration.

452 :param parent: The parent model entity of this entity.

453 """

454 super().__init__(identifier, documentation, parent)

455 GenericInterfaceItemMixin.__init__(self)

456

457

458@export

459class GenericSubprogramInterfaceItem(GenericInterfaceItemMixin):

460 """

461 Represents the base-class of subprograms in a generic clause.

462 """

463 pass

464

465

466@export

467class GenericProcedureInterfaceItem(Procedure, GenericInterfaceItemMixin):

468 """

469 Represents a procedure in a generic clause.

470

471 .. admonition:: Example

472

473 .. code-block:: VHDL

474

475 generic (procedure log(msg : string));

476 -- ^^^ <- Identifier

477 -- ^^^^^^^^^^^^ <- ParameterItems

478 """

479 def __init__(self, identifier: str, documentation: Nullable[str] = None, parent: Nullable[ModelEntity] = None) -> None:

480 """

481 Initializes a procedure in a generic clause.

482

483 :param identifier: The identifier of a model entity.

484 :param documentation: The documentation comment associated with this declaration.

485 :param parent: The parent model entity of this entity.

486 """

487 super().__init__(identifier, documentation=documentation, parent=parent)

488 GenericInterfaceItemMixin.__init__(self)

489

490

491@export

492class GenericFunctionInterfaceItem(Function, GenericInterfaceItemMixin):

493 """

494 Represents a function in a generic clause.

495

496 .. admonition:: Example

497

498 .. code-block:: VHDL

499

500 generic (function cmp(a, b : integer) return boolean);

501 -- ^^^ <- Identifier

502 -- ^^^^^^^^^^^^^^ <- ParameterItems

503 -- ^^^^^^^ <- ReturnType

504 """

505 def __init__(

506 self,

507 identifier: str,

508 returnType: SubtypeSymbol,

509 documentation: Nullable[str] = None,

510 parent: Nullable[ModelEntity] = None

511 ) -> None:

512 """

513 Initializes a function in a generic clause.

514

515 :param identifier: The identifier of a model entity.

516 :param returnType: Reference to the subtype of the function's return value.

517 :param documentation: The documentation comment associated with this declaration.

518 :param parent: The parent model entity of this entity.

519 """

520 super().__init__(identifier, returnType, documentation=documentation, parent=parent)

521 GenericInterfaceItemMixin.__init__(self)

522

523

524@export

525class InterfacePackage(ModelEntity, NamedEntityMixin, DocumentedEntityMixin):

526 """

527 Represents a package as a generic of a design unit.

528

529 An interface package parameterises a design unit with an instantiated package.

530

531 .. seealso::

532

533 * :class:`Generic package interface item <pyVHDLModel.Interface.GenericPackageInterfaceItem>`

534 """

535 def __init__(self, identifier: str, documentation: Nullable[str] = None, parent: Nullable[ModelEntity] = None) -> None:

536 """

537 Initializes a package as a generic of a design unit.

538

539 :param identifier: The identifier of a model entity.

540 :param documentation: The documentation comment associated with this declaration.

541 :param parent: The parent model entity of this entity.

542 """

543 super().__init__(parent)

544 NamedEntityMixin.__init__(self, identifier)

545 DocumentedEntityMixin.__init__(self, documentation)

546

547 def __str__(self) -> str:

548 """

549 Formats the interface package.

550

551 **Format:** ``package myPackage``

552

553 :returns: Formatted interface package.

554 """

555 return f"package {self._identifier}"

556

557

558@export

559class GenericPackageInterfaceItem(InterfacePackage, GenericInterfaceItemMixin):

560 """

561 Represents a package in a generic clause.

562

563 A generic package parameterises a design unit with an instantiated package.

564 """

565 def __init__(self, identifier: str, documentation: Nullable[str] = None, parent: Nullable[ModelEntity] = None) -> None:

566 """

567 Initializes a package in a generic clause.

568

569 :param identifier: The identifier of a model entity.

570 :param documentation: The documentation comment associated with this declaration.

571 :param parent: The parent model entity of this entity.

572 """

573 super().__init__(identifier, documentation, parent)

574 GenericInterfaceItemMixin.__init__(self)

575

576

577@export

578class PortSignalInterfaceItem(Signal, InterfaceItemMixin):

579 """

580 Represents the base-class of all signals in a port clause.

581

582 A port is declared either with a simple mode (:class:`PortSimpleSignalInterfaceItem`) or with a

583 mode view (:class:`PortViewSignalInterfaceItem`).

584

585 .. seealso::

586

587 * :class:`Port simple signal interface item <pyVHDLModel.Interface.PortSimpleSignalInterfaceItem>`

588 * :class:`Port view signal interface item <pyVHDLModel.Interface.PortViewSignalInterfaceItem>`

589 """

590

591

592@export

593class PortSimpleSignalInterfaceItem(PortSignalInterfaceItem, InterfaceItemWithModeMixin):

594 """

595 Represents a port declared with a simple mode.

596

597 The port's mode is available as :data:`Mode`, its subtype as :data:`Subtype`.

598

599 .. admonition:: Example

600

601 .. code-block:: VHDL

602

603 port (p : in bit);

604 -- ^ <- Identifiers

605 -- ^^ <- Mode

606 -- ^^^ <- Subtype

607

608 .. seealso::

609

610 * :class:`Port declared with a mode view <pyVHDLModel.Interface.PortViewSignalInterfaceItem>`

611 """

612

613 def __init__(

614 self,

615 identifiers: Iterable[str],

616 mode: Mode,

617 subtype: Symbol,

618 defaultExpression: Nullable[ExpressionUnion] = None,

619 documentation: Nullable[str] = None,

620 parent: Nullable[ModelEntity] = None

621 ) -> None:

622 """

623 Initializes a port declared with a simple mode.

624

625 :param identifiers: A list of identifiers.

626 :param mode: The interface item's mode.

627 :param subtype: Reference to the object's subtype.

628 :param defaultExpression: The default value, or ``None`` if none was given.

629 :param documentation: The documentation comment associated with this declaration.

630 :param parent: The parent model entity of this entity.

631 """

632 super().__init__(identifiers, subtype, defaultExpression, documentation, parent)

633 InterfaceItemWithModeMixin.__init__(self, mode)

634

635 def __str__(self) -> str:

636 """

637 Formats the port.

638

639 **Format:** ``signal p : in bit``

640

641 :returns: Formatted port.

642 """

643 return self._FormatInterfaceItem(self._mode)

644

645

646@export

647class PortViewSignalInterfaceItem(PortSignalInterfaceItem):

648 """

649 Represents a port declared with a mode view (VHDL-2019).

650

651 Instead of a mode, the port names a mode view (:data:`ModeViewIndication`) that assigns a mode to

652 each element of its record type.

653

654 .. admonition:: Example

655

656 .. code-block:: VHDL

657

658 port (p : view MyView);

659 -- ^ <- Identifiers

660 -- ^^^^^^ <- ModeViewIndication

661

662 .. seealso::

663

664 * :class:`Mode view declaration <pyVHDLModel.Interface.ModeViewDeclaration>`

665 * :class:`Port declared with a simple mode <pyVHDLModel.Interface.PortSimpleSignalInterfaceItem>`

666 """

667

668 def __init__(

669 self,

670 identifiers: Iterable[str],

671 modeViewIndication: ModeViewSymbol,

672 documentation: Nullable[str] = None,

673 parent: Nullable[ModelEntity] = None

674 ) -> None:

675 """

676 Initializes a port declared with a mode view (VHDL-2019).

677

678 :param identifiers: A list of identifiers.

679 :param modeViewIndication: Reference to the mode view applied to this port.

680 :param documentation: The documentation comment associated with this declaration.

681 :param parent: The parent model entity of this entity.

682 """

683 super().__init__(identifiers, modeViewIndication, None, documentation, parent)

684

685 @readonly

686 def ModeViewIndication(self) -> ModeViewSymbol:

687 """

688 Read-only property to access the mode view indication (:attr:`_subtype`).

689

690 :returns: The mode view indication.

691 """

692 return self._subtype

693

694 def __str__(self) -> str:

695 """

696 Formats the port declared with a mode view.

697

698 **Format:** ``signal p : view myView``

699

700 :returns: Formatted port declared with a mode view.

701 """

702 return self._FormatInterfaceItem(isModeView=True)

703

704

705@export

706class ParameterConstantInterfaceItem(Constant, ParameterInterfaceItemMixin, InterfaceItemWithModeMixin):

707 """

708 Represents a constant parameter of a subprogram.

709

710 .. admonition:: Example

711

712 .. code-block:: VHDL

713

714 function fun(constant cst : in integer) return integer;

715 -- ^^^ <- Identifiers

716 -- ^^ <- Mode

717 -- ^^^^^^^ <- Subtype

718 """

719 def __init__(

720 self,

721 identifiers: Iterable[str],

722 mode: Mode,

723 subtype: Symbol,

724 defaultExpression: Nullable[ExpressionUnion] = None,

725 documentation: Nullable[str] = None,

726 parent: Nullable[ModelEntity] = None

727 ) -> None:

728 """

729 Initializes a constant parameter of a subprogram.

730

731 :param identifiers: A list of identifiers.

732 :param mode: The interface item's mode.

733 :param subtype: Reference to the object's subtype.

734 :param defaultExpression: The default value, or ``None`` if none was given.

735 :param documentation: The documentation comment associated with this declaration.

736 :param parent: The parent model entity of this entity.

737 """

738 super().__init__(identifiers, subtype, defaultExpression, documentation, parent)

739 ParameterInterfaceItemMixin.__init__(self)

740 InterfaceItemWithModeMixin.__init__(self, mode)

741

742 def __str__(self) -> str:

743 """

744 Formats the constant parameter.

745

746 **Format:** ``constant a : in integer``

747

748 :returns: Formatted constant parameter.

749 """

750 return self._FormatInterfaceItem(self._mode)

751

752

753@export

754class ParameterVariableInterfaceItem(Variable, ParameterInterfaceItemMixin, InterfaceItemWithModeMixin):

755 """

756 Represents a variable parameter of a subprogram.

757

758 .. admonition:: Example

759

760 .. code-block:: VHDL

761

762 procedure proc(variable var : out bit);

763 -- ^^^ <- Identifiers

764 -- ^^^ <- Mode

765 -- ^^^ <- Subtype

766 """

767 def __init__(

768 self,

769 identifiers: Iterable[str],

770 mode: Mode,

771 subtype: Symbol,

772 defaultExpression: Nullable[ExpressionUnion] = None,

773 documentation: Nullable[str] = None,

774 parent: Nullable[ModelEntity] = None

775 ) -> None:

776 """

777 Initializes a variable parameter of a subprogram.

778

779 :param identifiers: A list of identifiers.

780 :param mode: The interface item's mode.

781 :param subtype: Reference to the object's subtype.

782 :param defaultExpression: The default value, or ``None`` if none was given.

783 :param documentation: The documentation comment associated with this declaration.

784 :param parent: The parent model entity of this entity.

785 """

786 super().__init__(identifiers, subtype, defaultExpression, documentation, parent)

787 ParameterInterfaceItemMixin.__init__(self)

788 InterfaceItemWithModeMixin.__init__(self, mode)

789

790 def __str__(self) -> str:

791 """

792 Formats the variable parameter.

793

794 **Format:** ``variable v : inout integer``

795

796 :returns: Formatted variable parameter.

797 """

798 return self._FormatInterfaceItem(self._mode)

799

800

801@export

802class ParameterSignalInterfaceItem(Signal, ParameterInterfaceItemMixin):

803 """

804 Represents a signal parameter of a subprogram.

805

806 .. admonition:: Example

807

808 .. code-block:: VHDL

809

810 procedure proc(signal sig : in bit);

811 -- ^^^ <- Identifiers

812 -- ^^ <- Mode

813 -- ^^^ <- Subtype

814

815 .. seealso::

816

817 * :class:`Parameter simple signal interface item <pyVHDLModel.Interface.ParameterSimpleSignalInterfaceItem>`

818 * :class:`Parameter view signal interface item <pyVHDLModel.Interface.ParameterViewSignalInterfaceItem>`

819 """

820

821

822@export

823class ParameterSimpleSignalInterfaceItem(ParameterSignalInterfaceItem, InterfaceItemWithModeMixin):

824 """

825 Represents a signal parameter declared with a simple mode.

826

827 The parameter's mode is available as :data:`Mode`, its subtype as :data:`Subtype`.

828

829 .. admonition:: Example

830

831 .. code-block:: VHDL

832

833 procedure proc(signal sig : in bit);

834 -- ^^^ <- Identifiers

835 -- ^^ <- Mode

836 -- ^^^ <- Subtype

837 """

838

839 def __init__(

840 self,

841 identifiers: Iterable[str],

842 mode: Mode,

843 subtype: Symbol,

844 defaultExpression: Nullable[ExpressionUnion] = None,

845 documentation: Nullable[str] = None,

846 parent: Nullable[ModelEntity] = None

847 ) -> None:

848 """

849 Initializes a signal parameter declared with a simple mode.

850

851 :param identifiers: A list of identifiers.

852 :param mode: The interface item's mode.

853 :param subtype: Reference to the object's subtype.

854 :param defaultExpression: The default value, or ``None`` if none was given.

855 :param documentation: The documentation comment associated with this declaration.

856 :param parent: The parent model entity of this entity.

857 """

858 super().__init__(identifiers, subtype, defaultExpression, documentation, parent)

859 ParameterInterfaceItemMixin.__init__(self)

860 InterfaceItemWithModeMixin.__init__(self, mode)

861

862 def __str__(self) -> str:

863 """

864 Formats the signal parameter.

865

866 **Format:** ``signal s : in bit``

867

868 :returns: Formatted signal parameter.

869 """

870 return self._FormatInterfaceItem(self._mode)

871

872

873@export

874class ParameterViewSignalInterfaceItem(ParameterSignalInterfaceItem):

875 """

876 Represents a signal parameter declared with a mode view (VHDL-2019).

877

878 Instead of a mode, the parameter names a mode view (:data:`ModeViewIndication`) that assigns a mode

879 to each element of its record type.

880

881 .. admonition:: Example

882

883 .. code-block:: VHDL

884

885 procedure proc(signal sig : view MasterView);

886 -- ^^^ <- Identifiers

887 -- ^^^^^^^^^^ <- ModeViewIndication

888

889 .. seealso::

890

891 * :class:`Mode view declaration <pyVHDLModel.Interface.ModeViewDeclaration>`

892 * :class:`Parameter declared with a simple mode <pyVHDLModel.Interface.ParameterSimpleSignalInterfaceItem>`

893 """

894

895 def __init__(

896 self,

897 identifiers: Iterable[str],

898 modeViewIndication: ModeViewSymbol,

899 documentation: Nullable[str] = None,

900 parent: Nullable[ModelEntity] = None

901 ) -> None:

902 """

903 Initializes a signal parameter declared with a mode view (VHDL-2019).

904

905 :param identifiers: A list of identifiers.

906 :param modeViewIndication: Reference to the mode view applied to this parameter.

907 :param documentation: The documentation comment associated with this declaration.

908 :param parent: The parent model entity of this entity.

909 """

910 super().__init__(identifiers, modeViewIndication, None, documentation, parent)

911 ParameterInterfaceItemMixin.__init__(self)

912

913 @readonly

914 def ModeViewIndication(self) -> ModeViewSymbol:

915 """

916 Read-only property to access the mode view indication (:attr:`_subtype`).

917

918 :returns: The mode view indication.

919 """

920 return self._subtype

921

922 def __str__(self) -> str:

923 """

924 Formats the signal parameter declared with a mode view.

925

926 **Format:** ``signal s : view myView``

927

928 :returns: Formatted signal parameter declared with a mode view.

929 """

930 return self._FormatInterfaceItem(isModeView=True)

931

932

933@export

934class ParameterFileInterfaceItem(File, ParameterInterfaceItemMixin):

935 """

936 Represents a file parameter of a subprogram.

937

938 .. admonition:: Example

939

940 .. code-block:: VHDL

941

942 procedure proc(file fil : text_file);

943 -- ^^^ <- Identifiers

944 -- ^^^^^^^^^ <- Subtype

945 """

946 def __init__(

947 self,

948 identifiers: Iterable[str],

949 subtype: Symbol,

950 documentation: Nullable[str] = None,

951 parent: Nullable[ModelEntity] = None

952 ) -> None:

953 """

954 Initializes a file parameter of a subprogram.

955

956 :param identifiers: A list of identifiers.

957 :param subtype: Reference to the object's subtype.

958 :param documentation: The documentation comment associated with this declaration.

959 :param parent: The parent model entity of this entity.

960 """

961 super().__init__(identifiers, subtype, documentation, parent)

962 ParameterInterfaceItemMixin.__init__(self)

963

964 def __str__(self) -> str:

965 """

966 Formats the file parameter.

967

968 **Format:** ``file f : text``

969

970 :returns: Formatted file parameter.

971 """

972 return self._FormatInterfaceItem()

973

974

975@export

976class WithGenericsMixin(metaclass=ExtendedType, mixin=True):

977 """

978 A mixin-class for language constructs with a generic clause.

979

980 .. seealso::

981

982 * :class:`Package <pyVHDLModel.DesignUnit.Package>`

983 * :class:`Entity <pyVHDLModel.DesignUnit.Entity>`

984 * :class:`Generic group <pyVHDLModel.Interface.GenericGroup>`

985 """

986 _genericItems: List[GenericInterfaceItemMixin] #: List of all generics, in declaration order.

987

988 def __init__(

989 self,

990 genericItems: Nullable[Iterable[GenericInterfaceItemMixin]] = None,

991 ) -> None:

992 """

993 Initializes a language construct with a generic clause.

994

995 :param genericItems: List of all generics, in declaration order.

996 """

997 self._genericItems = []

998 if genericItems is not None:

999 for item in genericItems:

1000 self._genericItems.append(item)

1001 item.Parent = self

1002

1003 @readonly

1004 def GenericItems(self) -> List[GenericInterfaceItemMixin]:

1005 """

1006 Read-only property to access the generic items (:attr:`_genericItems`).

1007

1008 :returns: List of generic items.

1009 """

1010 return self._genericItems

1011

1012 @readonly

1013 def GenericCount(self) -> int:

1014 """

1015 Read-only property to return the number of generics in :attr:`_genericItems`.

1016

1017 :returns: The generic count.

1018 """

1019 return len(self._genericItems)

1020

1021

1022@export

1023class WithPortsMixin(metaclass=ExtendedType, mixin=True):

1024 """

1025 A mixin-class for language constructs with a port clause.

1026

1027 .. seealso::

1028

1029 * :class:`Concurrent block statement <pyVHDLModel.Concurrent.ConcurrentBlockStatement>`

1030 * :class:`Entity <pyVHDLModel.DesignUnit.Entity>`

1031 * :class:`Port group <pyVHDLModel.Interface.PortGroup>`

1032 """

1033 _portItems: List[PortInterfaceItemMixin] #: List of all ports, in declaration order.

1034

1035 def __init__(

1036 self,

1037 portItems: Nullable[Iterable[PortInterfaceItemMixin]] = None,

1038 ) -> None:

1039 """

1040 Initializes a language construct with a port clause.

1041

1042 :param portItems: List of all ports, in declaration order.

1043 """

1044 self._portItems = []

1045 if portItems is not None:

1046 for item in portItems:

1047 self._portItems.append(item)

1048 item.Parent = self

1049

1050 @readonly

1051 def PortItems(self) -> List[PortInterfaceItemMixin]:

1052 """

1053 Read-only property to access the port items (:attr:`_portItems`).

1054

1055 :returns: List of port items.

1056 """

1057 return self._portItems

1058

1059 @readonly

1060 def PortCount(self) -> int:

1061 """

1062 Read-only property to return the number of ports in :attr:`_portItems`.

1063

1064 :returns: The port count.

1065 """

1066 return len(self._portItems)

1067

1068

1069@export

1070class WithParametersMixin(metaclass=ExtendedType, mixin=True):

1071 """

1072 A mixin-class for language constructs with a parameter list.

1073

1074 .. seealso::

1075

1076 * :class:`Parameter group <pyVHDLModel.Interface.ParameterGroup>`

1077 """

1078 _parameterItems: List[ParameterInterfaceItemMixin] #: List of all parameters, in declaration order.

1079

1080 def __init__(

1081 self,

1082 parameterItems: Nullable[Iterable[ParameterInterfaceItemMixin]] = None,

1083 ) -> None:

1084 """

1085 Initializes a language construct with a parameter list.

1086

1087 :param parameterItems: List of all parameters, in declaration order.

1088 """

1089 self._parameterItems = []

1090 if parameterItems is not None: 1090 ↛ exitline 1090 didn't return from function '__init__' because the condition on line 1090 was always true

1091 for item in parameterItems:

1092 self._parameterItems.append(item)

1093 item.Parent = self

1094

1095 @readonly

1096 def ParameterItems(self) -> List[ParameterInterfaceItemMixin]:

1097 """

1098 Read-only property to access the parameter items (:attr:`_parameterItems`).

1099

1100 :returns: List of parameter items.

1101 """

1102 return self._parameterItems

1103

1104 @readonly

1105 def ParameterCount(self) -> int:

1106 """

1107 Read-only property to return the number of parameters in :attr:`_parameterItems`.

1108

1109 :returns: The parameter count.

1110 """

1111 return len(self._parameterItems)

1112

1113

1114@export

1115class InterfaceGroup(ModelEntity, OptionallyNamedEntityMixin, DocumentedEntityMixin):

1116 """

1117 Represents a group of interface items sharing one clause.

1118

1119 The group may be named (:data:`Identifier`), which is optional.

1120

1121 .. seealso::

1122

1123 * :class:`Generic group <pyVHDLModel.Interface.GenericGroup>`

1124 * :class:`Port group <pyVHDLModel.Interface.PortGroup>`

1125 * :class:`Parameter group <pyVHDLModel.Interface.ParameterGroup>`

1126 """

1127 def __init__(

1128 self,

1129 name: Nullable[str] = None,

1130 documentation: Nullable[str] = None,

1131 parent: Nullable[ModelEntity] = None

1132 ) -> None:

1133 """

1134 Initializes a group of interface items sharing one clause.

1135

1136 :param name: The group's name.

1137 :param documentation: The documentation comment associated with this declaration.

1138 :param parent: The parent model entity of this entity.

1139 """

1140 super().__init__(parent)

1141 OptionallyNamedEntityMixin.__init__(self, name)

1142 DocumentedEntityMixin.__init__(self, documentation)

1143

1144

1145@export

1146class GenericGroup(InterfaceGroup, WithGenericsMixin):

1147 """

1148 Represents the generic clause of a design unit.

1149

1150 The generics are available as :data:`GenericItems`.

1151

1152 .. seealso::

1153

1154 * :class:`Port clause <pyVHDLModel.Interface.PortGroup>`

1155 * :class:`Parameter list <pyVHDLModel.Interface.ParameterGroup>`

1156 """

1157 def __init__(

1158 self,

1159 genericItems: Iterable[GenericInterfaceItemMixin],

1160 name: Nullable[str] = None,

1161 documentation: Nullable[str] = None,

1162 parent: Nullable[ModelEntity] = None

1163 ) -> None:

1164 """

1165 Initializes a generic group.

1166

1167 :param genericItems: List of all generics, in declaration order.

1168 :param name: The group's name.

1169 :param documentation: The documentation comment associated with this declaration.

1170 :param parent: The parent model entity of this entity.

1171 """

1172 super().__init__(name, documentation, parent)

1173 WithGenericsMixin.__init__(self, genericItems)

1174

1175 def __len__(self) -> int:

1176 """

1177 Returns the number of generics in this group.

1178

1179 :returns: Number of generics.

1180 """

1181 return len(self._genericItems)

1182

1183 def __iter__(self) -> Iterator[GenericInterfaceItemMixin]:

1184 """

1185 Iterates the generics in this group.

1186

1187 :returns: An iterator over the group's generics.

1188 """

1189 return iter(self._genericItems)

1190

1191 def __str__(self) -> str:

1192 """

1193 Formats the generic group.

1194

1195 **Format:** ``GenericGroup: myGroup (2): WIDTH, DEPTH``

1196

1197 :returns: Formatted generic group.

1198 """

1199 names = ", ".join(name for item in self._genericItems for name in identifiersOf(item))

1200 return f"GenericGroup: {self._identifier} ({len(self._genericItems)}): {names}"

1201

1202

1203@export

1204class PortGroup(InterfaceGroup, WithPortsMixin):

1205 """

1206 Represents the port clause of a design unit.

1207

1208 The ports are available as :data:`PortItems`.

1209

1210 .. seealso::

1211

1212 * :class:`Generic clause <pyVHDLModel.Interface.GenericGroup>`

1213 * :class:`Parameter list <pyVHDLModel.Interface.ParameterGroup>`

1214 """

1215 def __init__(

1216 self,

1217 portItems: Iterable[PortInterfaceItemMixin],

1218 name: Nullable[str] = None,

1219 documentation: Nullable[str] = None,

1220 parent: Nullable[ModelEntity] = None

1221 ) -> None:

1222 """

1223 Initializes a port group.

1224

1225 :param portItems: List of all ports, in declaration order.

1226 :param name: The group's name.

1227 :param documentation: The documentation comment associated with this declaration.

1228 :param parent: The parent model entity of this entity.

1229 """

1230 super().__init__(name, documentation, parent)

1231 WithPortsMixin.__init__(self, portItems)

1232

1233 def __len__(self) -> int:

1234 """

1235 Returns the number of ports in this group.

1236

1237 :returns: Number of ports.

1238 """

1239 return len(self._portItems)

1240

1241 def __iter__(self) -> Iterator[PortInterfaceItemMixin]:

1242 """

1243 Iterates the ports in this group.

1244

1245 :returns: An iterator over the group's ports.

1246 """

1247 return iter(self._portItems)

1248

1249 def __str__(self) -> str:

1250 """

1251 Formats the port group.

1252

1253 **Format:** ``PortGroup: myGroup (2): clock, reset``

1254

1255 :returns: Formatted port group.

1256 """

1257 names = ", ".join(name for item in self._portItems for name in identifiersOf(item))

1258 return f"PortGroup: {self._identifier} ({len(self._portItems)}): {names}"

1259

1260

1261@export

1262class ParameterGroup(InterfaceGroup, WithParametersMixin):

1263 """

1264 Represents the parameter list of a subprogram.

1265

1266 The parameters are available as :data:`ParameterItems`.

1267

1268 .. seealso::

1269

1270 * :class:`Generic clause <pyVHDLModel.Interface.GenericGroup>`

1271 * :class:`Port clause <pyVHDLModel.Interface.PortGroup>`

1272 """

1273 def __init__(

1274 self,

1275 parameterItems: Iterable[ParameterInterfaceItemMixin],

1276 name: Nullable[str] = None,

1277 documentation: Nullable[str] = None,

1278 parent: Nullable[ModelEntity] = None

1279 ) -> None:

1280 """

1281 Initializes a parameter group.

1282

1283 :param parameterItems: List of all parameters, in declaration order.

1284 :param name: The group's name.

1285 :param documentation: The documentation comment associated with this declaration.

1286 :param parent: The parent model entity of this entity.

1287 """

1288 super().__init__(name, documentation, parent)

1289 WithParametersMixin.__init__(self, parameterItems)

1290

1291 def __len__(self) -> int:

1292 """

1293 Returns the number of parameters in this group.

1294

1295 :returns: Number of parameters.

1296 """

1297 return len(self._parameterItems)

1298

1299 def __iter__(self) -> Iterator[ParameterInterfaceItemMixin]:

1300 """

1301 Iterates the parameters in this group.

1302

1303 :returns: An iterator over the group's parameters.

1304 """

1305 return iter(self._parameterItems)

1306

1307 def __str__(self) -> str:

1308 """

1309 Formats the parameter group.

1310

1311 **Format:** ``ParameterGroup: myGroup (2): a, b``

1312

1313 :returns: Formatted parameter group.

1314 """

1315 names = ", ".join(name for item in self._parameterItems for name in identifiersOf(item))

1316 return f"ParameterGroup: {self._identifier} ({len(self._parameterItems)}): {names}"