pyGHDL.dom.DesignUnit

This module contains all DOM classes for VHDL’s design units (context, architecture, package, package body, context and configuration.

Classes


Classes

class pyGHDL.dom.DesignUnit.LibraryClause(libraryNode, symbols)[source]

This class implements a pyGHDL.dom object derived from pyVHDLModel.DesignUnit.LibraryClause.

Represents a library clause.

Example

library std, ieee;

Inheritance

Inheritance diagram of LibraryClause

Parameters:
  • libraryNode (Iir)

  • symbols (Iterable[Symbol])

__init__(libraryNode, symbols)[source]

Initializes a library clause.

Parameters:
  • libraryNode (Iir) – The IIR node of the library clause.

  • symbols (Iterable[Symbol]) – A list of symbols this reference references to.

Return type:

None

_iirNode: Iir

The IIR node in libghdl’s tree this DOM object was translated from.

_position: Position

The IIR node’s position in the source file, resolved on first access and then cached.

DenoteBy(name, region, place, symbol)

Determine the model entity a name denoting this declaration denotes, as a part of a type mark (Name.Denote).

A declaration, which a name in a type mark can denote, overrides this method and returns itself: an object, an alias, a type or subtype, a record element, a package. Any other declaration (e.g. a subprogram) is reported.

Parameters:
  • name (Name) – The name denoting this declaration, a part of the type mark.

  • region (DeclarativeRegionMixin) – The declarative region containing the type mark.

  • place (ModelEntity) – The declaration containing the type mark.

  • symbol (Symbol) – The type mark.

Return type:

ModelEntity | None

Returns:

None, as a name in a type mark can’t denote this declaration (reported as a warning).

Raises:

UnhandledCriticalWarningError – Always, if no WarningCollector collects the UnresolvedTypeMarkWarning.

GetAncestor(type)

Return the closest ancestor of the given type found by walking the parent chain upwards.

Iterates the parent chain - starting at this model entity - upwards (toward the root of the model) until an ancestor of the requested type is found.

Parameters:

type (Type) – Class (type) of the ancestor to find.

Return type:

ModelEntity

Returns:

The closest ancestor of the requested type.

Raises:

AncestorNotFoundError – If the root of the model is reached without finding an ancestor of the requested type.

classmethod GetMethodsWithAttributes(predicate=None)

Return the class’ methods that carry at least one matching attribute.

Parameters:

predicate (type[TAttr] | Iterable[type[TAttr]] | None) – Optional, an attribute class, an iterable of attribute classes, or None to accept every attribute.

Return type:

dict[Callable[..., Any], tuple[Attribute, ...]]

Returns:

Dictionary of methods and the matching attributes attached to them.

Raises:
  • ValueError – If an element of parameter ‘predicate’ is not a sub-class of Attribute.

  • ValueError – If parameter ‘predicate’ is neither an attribute class nor an iterable of those.

property IsOverloadable: bool

Check if this model entity is an overloadable declaration: it may share its designator with other overloadable declarations.

Subprograms, enumeration literals and aliases, which may denote one of them, are overloadable; they override this property.

Returns:

True, if this model entity is an overloadable declaration.

IterateImplicitDeclarations()

Iterate the declarations this declaration implies.

An enumerated type implies its enumeration literals, a physical type its units; they override this method.

Return type:

Generator[tuple[str, ModelEntity]]

Returns:

A generator to iterate (normalized designator, declaration) pairs, in declaration order: none.

IterateTypeMarks(region)

Iterate the type marks of this declaration, each with the region and the place to look it up.

The place of a type mark is the declaration containing it. Declarations with type marks override this method, e.g. an object yields the type mark of its subtype indication, an array type its index and element subtypes.

Parameters:

region (DeclarativeRegionMixin) – The declarative region declaring this declaration.

Return type:

Generator[tuple[DeclarativeRegionMixin, ModelEntity, SubtypeSymbol]]

Returns:

A generator to iterate (region, place, type mark) tuples, in declaration order: none.

property Parent: ModelEntity

Property to access the model entity’s parent element reference in a logical hierarchy (_parent).

Returns:

Reference to the parent entity.

property Position: Position

Cached read-only property to access an IIR’s position in source code (_position).

If _position is None, resolve the position object from _iirNode

Returns:

The IIR’s position in the source file.

ResetReferences(designUnit, region)

Reset the references ResolveReferences() derived: the references of this declaration’s type marks.

A use clause, an alias and a subtype extend this method.

Parameters:
  • designUnit (DesignUnit) – The design unit containing this declaration.

  • region (DeclarativeRegionMixin) – The declarative region declaring this declaration.

Return type:

None

ResolveReferences(designUnit, region)

Resolve the references of this declaration: its type marks (IterateTypeMarks()).

Each type mark is resolved at its place by the region it is looked up in (ResolveTypeMark()). An incomplete type, an alias and a subtype extend this method.

Parameters:
  • designUnit (DesignUnit) – The design unit containing this declaration.

  • region (DeclarativeRegionMixin) – The declarative region declaring this declaration.

Raises:

UnhandledCriticalWarningError – If a type mark can’t be resolved, and no WarningCollector collects the UnresolvedTypeMarkWarning.

Return type:

None

property Symbols: list[LibraryReferenceSymbol]

Read-only property to access the symbols this library clause references to (_symbols).

Returns:

A list of library reference symbols.

Visit(visitor)[source]

Walk this library clause and its library names with a visitor.

Parameters:

visitor (Visitor) – The visitor receiving the events.

Return type:

None

_VisitSymbols(visitor)

Walk the referenced symbols, separated by commas, with a visitor.

Parameters:

visitor (Visitor) – The visitor receiving the events.

Return type:

None

__contains__(libraryIdentifier)[source]

Check if this library clause names a library.

Parameters:

libraryIdentifier (str) – The normalized identifier of the library.

Return type:

bool

Returns:

True, if one of the clause’s library names is the library.

__getstate__()

Return the object’s state for pickling, collecting every slot of the class hierarchy.

Return type:

dict[str, Any]

Returns:

Dictionary of slot names and their values.

Raises:

ExtendedTypeError – If a slot was never assigned, so it has no value to serialize.

__new__(**kwargs)
__setstate__(state)

Restore the object’s state from unpickling, requiring exactly the slots of the class hierarchy.

Parameters:

state (dict[str, Any]) – Dictionary of slot names and their values.

Raises:

ExtendedTypeError – If the given state misses a slot or carries an unexpected one.

Return type:

None

_parent: ModelEntity

Reference to a parent entity in the logical model hierarchy.

_symbols: list[Symbol]

List of all symbols referenced by this clause.

class pyGHDL.dom.DesignUnit.UseClause(useNode, symbols)[source]

This class implements a pyGHDL.dom object derived from pyVHDLModel.DesignUnit.UseClause.

Represents a use clause.

Example

use std.text_io.all, ieee.numeric_std.all;

Inheritance

Inheritance diagram of UseClause

Parameters:
__init__(useNode, symbols)[source]

Initializes a use clause.

Parameters:
  • useNode (Iir) – The IIR node of the use clause.

  • symbols (Iterable[Symbol]) – A list of symbols this reference references to.

Return type:

None

classmethod parse(useNode)[source]

Translates the IIR node of the use clause to an UseClause.

Parameters:

useNode (Iir) – The IIR node of the use clause.

Returns:

The translated use clause.

_iirNode: Iir

The IIR node in libghdl’s tree this DOM object was translated from.

_position: Position

The IIR node’s position in the source file, resolved on first access and then cached.

DenoteBy(name, region, place, symbol)

Determine the model entity a name denoting this declaration denotes, as a part of a type mark (Name.Denote).

A declaration, which a name in a type mark can denote, overrides this method and returns itself: an object, an alias, a type or subtype, a record element, a package. Any other declaration (e.g. a subprogram) is reported.

Parameters:
  • name (Name) – The name denoting this declaration, a part of the type mark.

  • region (DeclarativeRegionMixin) – The declarative region containing the type mark.

  • place (ModelEntity) – The declaration containing the type mark.

  • symbol (Symbol) – The type mark.

Return type:

ModelEntity | None

Returns:

None, as a name in a type mark can’t denote this declaration (reported as a warning).

Raises:

UnhandledCriticalWarningError – Always, if no WarningCollector collects the UnresolvedTypeMarkWarning.

GetAncestor(type)

Return the closest ancestor of the given type found by walking the parent chain upwards.

Iterates the parent chain - starting at this model entity - upwards (toward the root of the model) until an ancestor of the requested type is found.

Parameters:

type (Type) – Class (type) of the ancestor to find.

Return type:

ModelEntity

Returns:

The closest ancestor of the requested type.

Raises:

AncestorNotFoundError – If the root of the model is reached without finding an ancestor of the requested type.

classmethod GetMethodsWithAttributes(predicate=None)

Return the class’ methods that carry at least one matching attribute.

Parameters:

predicate (type[TAttr] | Iterable[type[TAttr]] | None) – Optional, an attribute class, an iterable of attribute classes, or None to accept every attribute.

Return type:

dict[Callable[..., Any], tuple[Attribute, ...]]

Returns:

Dictionary of methods and the matching attributes attached to them.

Raises:
  • ValueError – If an element of parameter ‘predicate’ is not a sub-class of Attribute.

  • ValueError – If parameter ‘predicate’ is neither an attribute class nor an iterable of those.

property IsOverloadable: bool

Check if this model entity is an overloadable declaration: it may share its designator with other overloadable declarations.

Subprograms, enumeration literals and aliases, which may denote one of them, are overloadable; they override this property.

Returns:

True, if this model entity is an overloadable declaration.

IterateImplicitDeclarations()

Iterate the declarations this declaration implies.

An enumerated type implies its enumeration literals, a physical type its units; they override this method.

Return type:

Generator[tuple[str, ModelEntity]]

Returns:

A generator to iterate (normalized designator, declaration) pairs, in declaration order: none.

IterateTypeMarks(region)

Iterate the type marks of this declaration, each with the region and the place to look it up.

The place of a type mark is the declaration containing it. Declarations with type marks override this method, e.g. an object yields the type mark of its subtype indication, an array type its index and element subtypes.

Parameters:

region (DeclarativeRegionMixin) – The declarative region declaring this declaration.

Return type:

Generator[tuple[DeclarativeRegionMixin, ModelEntity, SubtypeSymbol]]

Returns:

A generator to iterate (region, place, type mark) tuples, in declaration order: none.

property Parent: ModelEntity

Property to access the model entity’s parent element reference in a logical hierarchy (_parent).

Returns:

Reference to the parent entity.

property Position: Position

Cached read-only property to access an IIR’s position in source code (_position).

If _position is None, resolve the position object from _iirNode

Returns:

The IIR’s position in the source file.

ResetReferences(designUnit, region)[source]

Reset the references of this use clause’s symbols, which Analyze() linked.

Parameters:
  • designUnit (DesignUnit) – The design unit containing this declaration.

  • region (DeclarativeRegionMixin) – The declarative region declaring this declaration.

Return type:

None

ResolveReferences(designUnit, region)

Resolve the references of this declaration: its type marks (IterateTypeMarks()).

Each type mark is resolved at its place by the region it is looked up in (ResolveTypeMark()). An incomplete type, an alias and a subtype extend this method.

Parameters:
  • designUnit (DesignUnit) – The design unit containing this declaration.

  • region (DeclarativeRegionMixin) – The declarative region declaring this declaration.

Raises:

UnhandledCriticalWarningError – If a type mark can’t be resolved, and no WarningCollector collects the UnresolvedTypeMarkWarning.

Return type:

None

property Symbols: list[Symbol]

Read-only property to access the symbols this reference references to (_symbols).

Returns:

A list of symbols.

Visit(visitor)[source]

Walk this use clause and its selected names with a visitor.

Parameters:

visitor (Visitor) – The visitor receiving the events.

Return type:

None

_VisitSymbols(visitor)

Walk the referenced symbols, separated by commas, with a visitor.

Parameters:

visitor (Visitor) – The visitor receiving the events.

Return type:

None

__getstate__()

Return the object’s state for pickling, collecting every slot of the class hierarchy.

Return type:

dict[str, Any]

Returns:

Dictionary of slot names and their values.

Raises:

ExtendedTypeError – If a slot was never assigned, so it has no value to serialize.

__new__(**kwargs)
__setstate__(state)

Restore the object’s state from unpickling, requiring exactly the slots of the class hierarchy.

Parameters:

state (dict[str, Any]) – Dictionary of slot names and their values.

Raises:

ExtendedTypeError – If the given state misses a slot or carries an unexpected one.

Return type:

None

_parent: ModelEntity

Reference to a parent entity in the logical model hierarchy.

_symbols: list[Symbol]

List of all symbols referenced by this clause.

class pyGHDL.dom.DesignUnit.ContextReference(contextNode, symbols)[source]

This class implements a pyGHDL.dom object derived from pyVHDLModel.DesignUnit.ContextReference.

Represents a context reference.

Hint

It’s called context reference not context clause by the LRM.

Example

context ieee.ieee_std_context;

Inheritance

Inheritance diagram of ContextReference

Parameters:
  • contextNode (Iir)

  • symbols (Iterable[Symbol])

__init__(contextNode, symbols)[source]

Initializes a context reference.

Parameters:
  • contextNode (Iir) – The IIR node of the context reference.

  • symbols (Iterable[Symbol]) – A list of symbols this reference references to.

Return type:

None

classmethod parse(contextNode)[source]

Translates the IIR node of the context to a ContextReference.

Parameters:

contextNode (Iir) – The IIR node of the context.

Returns:

The translated context.

_iirNode: Iir

The IIR node in libghdl’s tree this DOM object was translated from.

_position: Position

The IIR node’s position in the source file, resolved on first access and then cached.

DenoteBy(name, region, place, symbol)

Determine the model entity a name denoting this declaration denotes, as a part of a type mark (Name.Denote).

A declaration, which a name in a type mark can denote, overrides this method and returns itself: an object, an alias, a type or subtype, a record element, a package. Any other declaration (e.g. a subprogram) is reported.

Parameters:
  • name (Name) – The name denoting this declaration, a part of the type mark.

  • region (DeclarativeRegionMixin) – The declarative region containing the type mark.

  • place (ModelEntity) – The declaration containing the type mark.

  • symbol (Symbol) – The type mark.

Return type:

ModelEntity | None

Returns:

None, as a name in a type mark can’t denote this declaration (reported as a warning).

Raises:

UnhandledCriticalWarningError – Always, if no WarningCollector collects the UnresolvedTypeMarkWarning.

GetAncestor(type)

Return the closest ancestor of the given type found by walking the parent chain upwards.

Iterates the parent chain - starting at this model entity - upwards (toward the root of the model) until an ancestor of the requested type is found.

Parameters:

type (Type) – Class (type) of the ancestor to find.

Return type:

ModelEntity

Returns:

The closest ancestor of the requested type.

Raises:

AncestorNotFoundError – If the root of the model is reached without finding an ancestor of the requested type.

classmethod GetMethodsWithAttributes(predicate=None)

Return the class’ methods that carry at least one matching attribute.

Parameters:

predicate (type[TAttr] | Iterable[type[TAttr]] | None) – Optional, an attribute class, an iterable of attribute classes, or None to accept every attribute.

Return type:

dict[Callable[..., Any], tuple[Attribute, ...]]

Returns:

Dictionary of methods and the matching attributes attached to them.

Raises:
  • ValueError – If an element of parameter ‘predicate’ is not a sub-class of Attribute.

  • ValueError – If parameter ‘predicate’ is neither an attribute class nor an iterable of those.

property IsOverloadable: bool

Check if this model entity is an overloadable declaration: it may share its designator with other overloadable declarations.

Subprograms, enumeration literals and aliases, which may denote one of them, are overloadable; they override this property.

Returns:

True, if this model entity is an overloadable declaration.

IterateImplicitDeclarations()

Iterate the declarations this declaration implies.

An enumerated type implies its enumeration literals, a physical type its units; they override this method.

Return type:

Generator[tuple[str, ModelEntity]]

Returns:

A generator to iterate (normalized designator, declaration) pairs, in declaration order: none.

IterateTypeMarks(region)

Iterate the type marks of this declaration, each with the region and the place to look it up.

The place of a type mark is the declaration containing it. Declarations with type marks override this method, e.g. an object yields the type mark of its subtype indication, an array type its index and element subtypes.

Parameters:

region (DeclarativeRegionMixin) – The declarative region declaring this declaration.

Return type:

Generator[tuple[DeclarativeRegionMixin, ModelEntity, SubtypeSymbol]]

Returns:

A generator to iterate (region, place, type mark) tuples, in declaration order: none.

property Parent: ModelEntity

Property to access the model entity’s parent element reference in a logical hierarchy (_parent).

Returns:

Reference to the parent entity.

property Position: Position

Cached read-only property to access an IIR’s position in source code (_position).

If _position is None, resolve the position object from _iirNode

Returns:

The IIR’s position in the source file.

ResetReferences(designUnit, region)

Reset the references ResolveReferences() derived: the references of this declaration’s type marks.

A use clause, an alias and a subtype extend this method.

Parameters:
  • designUnit (DesignUnit) – The design unit containing this declaration.

  • region (DeclarativeRegionMixin) – The declarative region declaring this declaration.

Return type:

None

ResolveReferences(designUnit, region)

Resolve the references of this declaration: its type marks (IterateTypeMarks()).

Each type mark is resolved at its place by the region it is looked up in (ResolveTypeMark()). An incomplete type, an alias and a subtype extend this method.

Parameters:
  • designUnit (DesignUnit) – The design unit containing this declaration.

  • region (DeclarativeRegionMixin) – The declarative region declaring this declaration.

Raises:

UnhandledCriticalWarningError – If a type mark can’t be resolved, and no WarningCollector collects the UnresolvedTypeMarkWarning.

Return type:

None

property Symbols: list[Symbol]

Read-only property to access the symbols this reference references to (_symbols).

Returns:

A list of symbols.

Visit(visitor)[source]

Walk this context reference and its context names with a visitor.

Parameters:

visitor (Visitor) – The visitor receiving the events.

Return type:

None

_VisitSymbols(visitor)

Walk the referenced symbols, separated by commas, with a visitor.

Parameters:

visitor (Visitor) – The visitor receiving the events.

Return type:

None

__getstate__()

Return the object’s state for pickling, collecting every slot of the class hierarchy.

Return type:

dict[str, Any]

Returns:

Dictionary of slot names and their values.

Raises:

ExtendedTypeError – If a slot was never assigned, so it has no value to serialize.

__new__(**kwargs)
__setstate__(state)

Restore the object’s state from unpickling, requiring exactly the slots of the class hierarchy.

Parameters:

state (dict[str, Any]) – Dictionary of slot names and their values.

Raises:

ExtendedTypeError – If the given state misses a slot or carries an unexpected one.

Return type:

None

_parent: ModelEntity

Reference to a parent entity in the logical model hierarchy.

_symbols: list[Symbol]

List of all symbols referenced by this clause.

class pyGHDL.dom.DesignUnit.Entity(node, identifier, contextItems=None, genericItems=None, portItems=None, declaredItems=None, statements=None, documentation=None)[source]

This class implements a pyGHDL.dom object derived from pyVHDLModel.DesignUnit.Entity.

Represents an entity declaration.

Example

entity ent is
  -- ...
end entity;

Inheritance

Inheritance diagram of Entity

Parameters:
  • node (Iir)

  • identifier (str)

  • contextItems (Iterable[VHDLModel_ContextUnion])

  • genericItems (Iterable[GenericInterfaceItemMixin])

  • portItems (Iterable[PortInterfaceItemMixin])

  • declaredItems (Iterable)

  • statements (Iterable[ConcurrentStatement])

  • documentation (str)

__init__(node, identifier, contextItems=None, genericItems=None, portItems=None, declaredItems=None, statements=None, documentation=None)[source]

Initializes an entity declaration.

Parameters:
  • node (Iir) – The IIR node this object was translated from.

  • identifier (str) – The entity’s identifier.

  • contextItems (Iterable[LibraryClause | UseClause | ContextReference]) – Optional, list of all context items (library, use and context clauses).

  • genericItems (Iterable[GenericInterfaceItemMixin]) – Optional, list of all generics, in declaration order.

  • portItems (Iterable[PortInterfaceItemMixin]) – Optional, list of all ports, in declaration order.

  • declaredItems (Iterable) – Optional, list of all declared items in this concurrent declaration region.

  • statements (Iterable[ConcurrentStatement]) – Optional, list of all concurrent statements in this construct.

  • documentation (str) – Optional, the documentation comment associated with this declaration.

Return type:

None

classmethod parse(entityNode, contextItems)[source]

Translates the IIR node of the entity declaration to an Entity.

Parameters:
Returns:

The translated entity declaration.

_iirNode

The IIR node in libghdl’s tree this DOM object was translated from.

_position

The IIR node’s position in the source file, resolved on first access and then cached.

AddContextItem(contextItem)

Add a context item at the end of the context clause.

The context item’s parent is set to this design unit. A library clause is also added to LibraryReferences, a use clause to PackageReferences and a context reference to ContextReferences, in the order of ContextItems. A context item may repeat an earlier one.

Parameters:

contextItem (LibraryClause | UseClause | ContextReference) – The library clause, use clause or context reference to add.

Raises:
Return type:

None

Attention

The mutator doesn’t update what Analyze() derived from the context items: the referenced libraries, packages and contexts (ReferencedLibraries, ReferencedPackages, ReferencedContexts), the namespace entries of a use clause, the edges of the dependency graph, and the references of the symbols. A design changed after its analysis needs a new analysis.

See also

InsertContextItem()

→ Insert a context item at a position of the context clause.

RemoveContextItem()

→ Remove a context item from the context clause.

AddDeclaredItem(declaredItem)

Add a declared item at the end of the declarative region.

The declared item’s parent is set to this declarative region. If the region is indexed, its identifiers are added to the region’s namespace and to the lookup table matching its kind.

Parameters:

declaredItem (ModelEntity) – The declared item to add.

Raises:
  • ValueError – If parameter ‘declaredItem’ is None.

  • TypeError – If parameter ‘declaredItem’ is not a declaration allowed in this declarative region.

  • AlreadyInDesignError – If parameter ‘declaredItem’ already has a parent.

  • DuplicateDeclarationError – If an existing declaration of the declarative region shares an identifier with the declared item.

Return type:

None

See also

InsertDeclaredItem()

→ Insert a declared item at a position of the declarative region.

RemoveDeclaredItem()

→ Remove a declared item from the declarative region.

AddGenericItem(genericItem, group=None)

Add a generic at the end of the generic clause, or at the end of a generic group.

The generic’s parent is set to this language construct, and its identifiers are added to the language construct’s namespace, if it has one. Without a generic group, the generic joins the last generic group, or forms a new unnamed generic group if there are no generics.

Parameters:
  • genericItem (GenericInterfaceItemMixin) – The generic to add.

  • group (GenericGroup | None) – Optional, the generic group of this language construct to add the generic to, at its end. Default: None, the end of the generic clause.

Raises:
  • ValueError – If parameter ‘genericItem’ is None.

  • TypeError – If parameter ‘genericItem’ is not of type GenericInterfaceItemMixin.

  • AlreadyInDesignError – If parameter ‘genericItem’ already has a parent.

  • TypeError – If parameter ‘group’ is not of type GenericGroup.

  • NotAChildError – If parameter ‘group’ is not a generic group of this language construct.

  • DuplicateGenericError – If an existing declaration of the language construct shares an identifier with the generic.

Return type:

None

See also

InsertGenericItem()

→ Insert a generic at a position of the generic clause.

RemoveGenericItem()

→ Remove a generic from the generic clause.

AddPortItem(portItem, group=None)

Add a port at the end of the port clause, or at the end of a port group.

The port’s parent is set to this language construct, and its identifiers are added to the language construct’s namespace, if it has one. Without a port group, the port joins the last port group, or forms a new unnamed port group if there are no ports.

Parameters:
  • portItem (PortSignalInterfaceItem) – The port to add.

  • group (PortGroup | None) – Optional, the port group of this language construct to add the port to, at its end. Default: None, the end of the port clause.

Raises:
  • ValueError – If parameter ‘portItem’ is None.

  • TypeError – If parameter ‘portItem’ is not of type PortSignalInterfaceItem.

  • AlreadyInDesignError – If parameter ‘portItem’ already has a parent.

  • TypeError – If parameter ‘group’ is not of type PortGroup.

  • NotAChildError – If parameter ‘group’ is not a port group of this language construct.

  • DuplicatePortError – If an existing declaration of the language construct shares an identifier with the port.

Return type:

None

See also

InsertPortItem()

→ Insert a port at a position of the port clause.

RemovePortItem()

→ Remove a port from the port clause.

AddStatement(statement)

Add a concurrent statement at the end of this construct.

The statement’s parent is set to this construct. If the statements are indexed, an instantiation, a block or a generate statement is added to the lookup table matching its kind.

Parameters:

statement (ConcurrentStatement) – The concurrent statement to add.

Raises:
  • ValueError – If parameter ‘statement’ is None.

  • TypeError – If parameter ‘statement’ is not of type ConcurrentStatement.

  • AlreadyInDesignError – If parameter ‘statement’ already has a parent.

  • DuplicateLabelError – If the declarative region already declares the statement’s label.

Return type:

None

See also

InsertStatement()

→ Insert a concurrent statement at a position of this construct.

RemoveStatement()

→ Remove a concurrent statement from this construct.

property AllowBlackbox: bool

Property to return whether a design supports blackboxes, inherited from the parent if not set locally (_allowBlackbox).

Algorithm

  1. If allow blackbox property is locally set, return the local value,

  2. Otherwise, return allow blackbox value from parent object.

Returns:

True, if blackboxes are allowed.

Raises:

AllowBlackboxNotSetError – If neither a local value is set nor a parent object is available to inherit the value from.

Setter accepts:

bool | None

property Architectures: dict[str, Architecture]

Read-only property to access the architectures (_architectures).

Returns:

Dictionary of architectures, indexed by normalized identifier.

property Components: dict[str, Any]

Read-only property to access the components (_components).

Returns:

Dictionary of components, indexed by normalized identifier.

property Constants: dict[str, Constant]

Read-only property to access the constants (_constants).

Returns:

Dictionary of constants, indexed by normalized identifier.

property ContextItems: list[LibraryClause | UseClause | ContextReference]

Read-only property to access the sequence of all context items comprising library, use and context clauses (_contextItems).

Returns:

Sequence of context items.

property ContextReferences: list[ContextReference]

Read-only property to access the sequence of context clauses (_contextReferences).

Returns:

Sequence of context clauses.

property DeclaredItems: list

Read-only property to access the declared items (_declaredItems).

Returns:

List of declared items.

DenoteBy(name, region, place, symbol)

Determine the model entity a name denoting this declaration denotes, as a part of a type mark (Name.Denote).

A declaration, which a name in a type mark can denote, overrides this method and returns itself: an object, an alias, a type or subtype, a record element, a package. Any other declaration (e.g. a subprogram) is reported.

Parameters:
  • name (Name) – The name denoting this declaration, a part of the type mark.

  • region (DeclarativeRegionMixin) – The declarative region containing the type mark.

  • place (ModelEntity) – The declaration containing the type mark.

  • symbol (Symbol) – The type mark.

Return type:

ModelEntity | None

Returns:

None, as a name in a type mark can’t denote this declaration (reported as a warning).

Raises:

UnhandledCriticalWarningError – Always, if no WarningCollector collects the UnresolvedTypeMarkWarning.

property DependencyVertex: Vertex

Read-only property to access the corresponding dependency vertex (_dependencyVertex).

The dependency vertex references this design unit by its value field.

Returns:

The corresponding dependency vertex.

property Document: Document

Property to access the document (_document).

Returns:

The document.

property Documentation: str | None

Read-only property to access the model entity’s documentation (_documentation).

Returns:

Associated documentation of a model entity.

property Files: dict[str, File]

Read-only property to access the files (_files).

Returns:

Dictionary of files, indexed by normalized identifier.

property Functions: dict[str, list[Function]]

Read-only property to access the functions (_functions).

Returns:

Dictionary of functions, indexed by normalized identifier; each entry is a list of overloads.

property GenericCount: int

Read-only property to return the number of generics declared by _genericItems.

A generic constant item with several identifiers (generic (A, B : natural)) declares several generics.

Returns:

The number of generics.

property GenericGroups: list[GenericGroup]

Read-only property to access the generic groups (_genericGroups).

The generic groups partition the generic clause: concatenated in order, they list every generic exactly once, in declaration order.

Returns:

List of generic groups, in declaration order.

property GenericItems: list[GenericInterfaceItemMixin]

Read-only property to access the generic items (_genericItems).

Returns:

List of generic items.

GetAncestor(type)

Return the closest ancestor of the given type found by walking the parent chain upwards.

Iterates the parent chain - starting at this model entity - upwards (toward the root of the model) until an ancestor of the requested type is found.

Parameters:

type (Type) – Class (type) of the ancestor to find.

Return type:

ModelEntity

Returns:

The closest ancestor of the requested type.

Raises:

AncestorNotFoundError – If the root of the model is reached without finding an ancestor of the requested type.

GetIdentifier(normalizedIdentifier)

Return the identifier as declared, for the model entity’s normalized identifier.

Parameters:

normalizedIdentifier (str) – The model entity’s normalized (lower case) identifier.

Return type:

str

Returns:

The identifier in its declared spelling.

classmethod GetMethodsWithAttributes(predicate=None)

Return the class’ methods that carry at least one matching attribute.

Parameters:

predicate (type[TAttr] | Iterable[type[TAttr]] | None) – Optional, an attribute class, an iterable of attribute classes, or None to accept every attribute.

Return type:

dict[Callable[..., Any], tuple[Attribute, ...]]

Returns:

Dictionary of methods and the matching attributes attached to them.

Raises:
  • ValueError – If an element of parameter ‘predicate’ is not a sub-class of Attribute.

  • ValueError – If parameter ‘predicate’ is neither an attribute class nor an iterable of those.

property HierarchyVertex: Vertex

Read-only property to access the corresponding hierarchy vertex (_hierarchyVertex).

The hierarchy vertex references this design unit by its value field.

Returns:

The corresponding hierarchy vertex.

property Identifier: str

Read-only property to access the model entity’s identifier (_identifier).

Returns:

Name of a model entity.

IndexDeclaredItems()[source]

An entity’s generics and ports share the declarative region of its declarative part.

Raises:

UnhandledCriticalWarningError – If an identifier is declared twice in a declarative region and no WarningCollector collects the DuplicateDeclarationWarning.

Return type:

None

IndexStatements()

Index the instantiations, blocks and generate statements of this construct, and the statements nested in them.

Both lookup tables (_instantiations, _hierarchy) are cleared first, so indexing again yields the same lookup tables. Afterwards, the statement mutators (e.g. InsertStatement()) keep them up to date.

Return type:

None

InsertContextItem(index, contextItem)

Insert a context item at a position of the context clause.

The context item’s parent is set to this design unit. A library clause is also added to LibraryReferences, a use clause to PackageReferences and a context reference to ContextReferences, in the order of ContextItems. A context item may repeat an earlier one.

Parameters:
  • index (int) – Position, from 0 (first) to the number of context items (append). A negative index counts from the end, as for list.insert(): -1 inserts before the last context item.

  • contextItem (LibraryClause | UseClause | ContextReference) – The library clause, use clause or context reference to insert.

Raises:
Return type:

None

Attention

The mutator doesn’t update what Analyze() derived from the context items: the referenced libraries, packages and contexts (ReferencedLibraries, ReferencedPackages, ReferencedContexts), the namespace entries of a use clause, the edges of the dependency graph, and the references of the symbols. A design changed after its analysis needs a new analysis.

See also

AddContextItem()

→ Add a context item at the end of the context clause.

RemoveContextItem()

→ Remove a context item from the context clause.

InsertDeclaredItem(index, declaredItem)

Insert a declared item at a position of the declarative region.

The declared item’s parent is set to this declarative region. If the region is indexed, its identifiers are added to the region’s namespace and to the lookup table matching its kind.

An identifier is declared once per declarative region: interface items and declared items count, including those of the language construct sharing the declarative region (an entity and its architecture, a package and its body). Subprograms are overloadable: a subprogram may share its identifier with other subprograms. A protected type body may share its identifier with its protected type, a full type with its incomplete type declaration, and a constant with its deferred constant. Items imported into the namespace (e.g. by a use clause) are hidden.

Parameters:
  • index (int) – Position, from 0 (first) to the number of declared items (append). A negative index counts from the end, as for list.insert(): -1 inserts before the last declared item.

  • declaredItem (ModelEntity) – The declared item to insert.

Raises:
  • ValueError – If parameter ‘index’ is None.

  • TypeError – If parameter ‘index’ is not of type int.

  • ValueError – If parameter ‘index’ is out of range.

  • ValueError – If parameter ‘declaredItem’ is None.

  • TypeError – If parameter ‘declaredItem’ is not a declaration allowed in this declarative region.

  • AlreadyInDesignError – If parameter ‘declaredItem’ already has a parent.

  • DuplicateDeclarationError – If an existing declaration of the declarative region shares an identifier with the declared item.

Return type:

None

See also

AddDeclaredItem()

→ Add a declared item at the end of the declarative region.

InsertDeclaredItemBefore()

→ Insert a declared item before another declared item.

InsertDeclaredItemAfter()

→ Insert a declared item after another declared item.

RemoveDeclaredItem()

→ Remove a declared item from the declarative region.

MoveDeclaredItem()

→ Move a declared item to a position of the declarative region.

InsertDeclaredItemAfter(declaredItem, after)

Insert a declared item after another declared item.

The declared item’s parent is set to this declarative region. If the region is indexed, its identifiers are added to the region’s namespace and to the lookup table matching its kind.

Parameters:
  • declaredItem (ModelEntity) – The declared item to insert.

  • after (ModelEntity) – The declared item of this declarative region to insert after.

Raises:
  • ValueError – If parameter ‘declaredItem’ is None.

  • TypeError – If parameter ‘declaredItem’ is not a declaration allowed in this declarative region.

  • AlreadyInDesignError – If parameter ‘declaredItem’ already has a parent.

  • ValueError – If parameter ‘after’ is None.

  • TypeError – If parameter ‘after’ is not of type ModelEntity.

  • NotAChildError – If parameter ‘after’ is not a declared item of this declarative region.

  • DuplicateDeclarationError – If an existing declaration of the declarative region shares an identifier with the declared item.

Return type:

None

See also

InsertDeclaredItem()

→ Insert a declared item at a position of the declarative region.

InsertDeclaredItemBefore()

→ Insert a declared item before another declared item.

InsertDeclaredItemBefore(declaredItem, before)

Insert a declared item before another declared item.

The declared item’s parent is set to this declarative region. If the region is indexed, its identifiers are added to the region’s namespace and to the lookup table matching its kind.

Parameters:
  • declaredItem (ModelEntity) – The declared item to insert.

  • before (ModelEntity) – The declared item of this declarative region to insert before.

Raises:
  • ValueError – If parameter ‘declaredItem’ is None.

  • TypeError – If parameter ‘declaredItem’ is not a declaration allowed in this declarative region.

  • AlreadyInDesignError – If parameter ‘declaredItem’ already has a parent.

  • ValueError – If parameter ‘before’ is None.

  • TypeError – If parameter ‘before’ is not of type ModelEntity.

  • NotAChildError – If parameter ‘before’ is not a declared item of this declarative region.

  • DuplicateDeclarationError – If an existing declaration of the declarative region shares an identifier with the declared item.

Return type:

None

See also

InsertDeclaredItem()

→ Insert a declared item at a position of the declarative region.

InsertDeclaredItemAfter()

→ Insert a declared item after another declared item.

InsertGenericItem(index, genericItem, group=None)

Insert a generic at a position of the generic clause.

The generic’s parent is set to this language construct, and its identifiers are added to the language construct’s namespace, if it has one.

Without a generic group, the generic joins the generic group of the generic before index; at index 0, the generic group of the first generic. If there are no generics, the generic forms a new unnamed generic group. A generic group given must contain index or end at it, so the generic groups stay contiguous.

Parameters:
  • index (int) – Position, from 0 (first) to the length of GenericItems (append). A negative index counts from the end, as for list.insert(): -1 inserts before the last generic.

  • genericItem (GenericInterfaceItemMixin) – The generic to insert.

  • group (GenericGroup | None) – Optional, the generic group of this language construct to insert the generic into. Default: None, the generic group of the generic before index.

Raises:
  • ValueError – If parameter ‘index’ is None.

  • TypeError – If parameter ‘index’ is not of type int.

  • ValueError – If parameter ‘index’ is out of range.

  • ValueError – If parameter ‘genericItem’ is None.

  • TypeError – If parameter ‘genericItem’ is not of type GenericInterfaceItemMixin.

  • AlreadyInDesignError – If parameter ‘genericItem’ already has a parent.

  • TypeError – If parameter ‘group’ is not of type GenericGroup.

  • NotAChildError – If parameter ‘group’ is not a generic group of this language construct.

  • ValueError – If parameter ‘group’ neither contains nor ends at parameter ‘index’.

  • DuplicateGenericError – If an existing declaration of the language construct shares an identifier with the generic.

Return type:

None

See also

AddGenericItem()

→ Add a generic at the end of the generic clause.

RemoveGenericItem()

→ Remove a generic from the generic clause.

MoveGenericItem()

→ Move a generic to a position of the generic clause.

InsertPortItem(index, portItem, group=None)

Insert a port at a position of the port clause.

The port’s parent is set to this language construct, and its identifiers are added to the language construct’s namespace, if it has one.

Without a port group, the port joins the port group of the port before index; at index 0, the port group of the first port. If there are no ports, the port forms a new unnamed port group. A port group given must contain index or end at it, so the port groups stay contiguous.

Parameters:
  • index (int) – Position, from 0 (first) to the length of PortItems (append). A negative index counts from the end, as for list.insert(): -1 inserts before the last port.

  • portItem (PortSignalInterfaceItem) – The port to insert.

  • group (PortGroup | None) – Optional, the port group of this language construct to insert the port into. Default: None, the port group of the port before index.

Raises:
  • ValueError – If parameter ‘index’ is None.

  • TypeError – If parameter ‘index’ is not of type int.

  • ValueError – If parameter ‘index’ is out of range.

  • ValueError – If parameter ‘portItem’ is None.

  • TypeError – If parameter ‘portItem’ is not of type PortSignalInterfaceItem.

  • AlreadyInDesignError – If parameter ‘portItem’ already has a parent.

  • TypeError – If parameter ‘group’ is not of type PortGroup.

  • NotAChildError – If parameter ‘group’ is not a port group of this language construct.

  • ValueError – If parameter ‘group’ neither contains nor ends at parameter ‘index’.

  • DuplicatePortError – If an existing declaration of the language construct shares an identifier with the port.

Return type:

None

See also

AddPortItem()

→ Add a port at the end of the port clause.

RemovePortItem()

→ Remove a port from the port clause.

MovePortItem()

→ Move a port to a position of the port clause.

InsertStatement(index, statement)

Insert a concurrent statement at a position of this construct.

The statement’s parent is set to this construct: a process, block or generate statement connects its namespace to this construct’s namespace. If the statements are indexed (IndexStatements()), an instantiation, a block or a generate statement is added to the lookup table matching its kind, and the statements nested in it are indexed.

A statement label is declared in the declarative region of this construct: it may neither repeat another statement’s label, nor an identifier declared in the region, including the region an entity shares with its architectures. An unlabeled statement declares nothing.

Parameters:
  • index (int) – Position, from 0 (first) to the number of statements (append). A negative index counts from the end, as for list.insert(): -1 inserts before the last statement.

  • statement (ConcurrentStatement) – The concurrent statement to insert.

Raises:
  • ValueError – If parameter ‘index’ is None.

  • TypeError – If parameter ‘index’ is not of type int.

  • ValueError – If parameter ‘index’ is out of range.

  • ValueError – If parameter ‘statement’ is None.

  • TypeError – If parameter ‘statement’ is not of type ConcurrentStatement.

  • AlreadyInDesignError – If parameter ‘statement’ already has a parent.

  • DuplicateLabelError – If the declarative region already declares the statement’s label.

Return type:

None

See also

AddStatement()

→ Add a concurrent statement at the end of this construct.

InsertStatementBefore()

→ Insert a concurrent statement before another statement.

InsertStatementAfter()

→ Insert a concurrent statement after another statement.

RemoveStatement()

→ Remove a concurrent statement from this construct.

MoveStatement()

→ Move a concurrent statement to a position of this construct.

InsertStatementAfter(statement, after)

Insert a concurrent statement after another statement of this construct.

The statement’s parent is set to this construct. If the statements are indexed, an instantiation, a block or a generate statement is added to the lookup table matching its kind.

Parameters:
Raises:
  • ValueError – If parameter ‘statement’ is None.

  • TypeError – If parameter ‘statement’ is not of type ConcurrentStatement.

  • AlreadyInDesignError – If parameter ‘statement’ already has a parent.

  • ValueError – If parameter ‘after’ is None.

  • TypeError – If parameter ‘after’ is not of type ModelEntity.

  • NotAChildError – If parameter ‘after’ is not a statement of this construct.

  • DuplicateLabelError – If the declarative region already declares the statement’s label.

Return type:

None

See also

InsertStatement()

→ Insert a concurrent statement at a position of this construct.

InsertStatementBefore()

→ Insert a concurrent statement before another statement.

InsertStatementBefore(statement, before)

Insert a concurrent statement before another statement of this construct.

The statement’s parent is set to this construct. If the statements are indexed, an instantiation, a block or a generate statement is added to the lookup table matching its kind.

Parameters:
Raises:
  • ValueError – If parameter ‘statement’ is None.

  • TypeError – If parameter ‘statement’ is not of type ConcurrentStatement.

  • AlreadyInDesignError – If parameter ‘statement’ already has a parent.

  • ValueError – If parameter ‘before’ is None.

  • TypeError – If parameter ‘before’ is not of type ModelEntity.

  • NotAChildError – If parameter ‘before’ is not a statement of this construct.

  • DuplicateLabelError – If the declarative region already declares the statement’s label.

Return type:

None

See also

InsertStatement()

→ Insert a concurrent statement at a position of this construct.

InsertStatementAfter()

→ Insert a concurrent statement after another statement.

IsLibraryVisible(libraryIdentifier)

Check if the logical name of a library is visible in this design unit.

The name work is implicitly visible, the name std too, except in a context declaration. Every other name needs a library clause, also the real name of the working library. The library clause is searched in this design unit’s context clause, in the context clause of its primary unit, and in the contexts these reference, also in nested ones. The design unit must be in a library of a design.

Parameters:

libraryIdentifier (str) – The normalized identifier of the library.

Return type:

bool

Returns:

True, if the library’s name is visible.

property IsOverloadable: bool

Check if this model entity is an overloadable declaration: it may share its designator with other overloadable declarations.

Subprograms, enumeration literals and aliases, which may denote one of them, are overloadable; they override this property.

Returns:

True, if this model entity is an overloadable declaration.

IterateDeclarationRegions()

Iterate this declarative region and all declarative regions nested in it.

Nested regions are declarations (e.g. subprograms, generic subprograms, protected types, packages) and concurrent statements (blocks, processes, generate statements and their branches), each followed by the regions nested in it.

Return type:

Generator[DeclarativeRegionMixin]

Returns:

A generator to iterate the declarative regions, this region first.

IterateImplicitDeclarations()

Iterate the declarations this declaration implies.

An enumerated type implies its enumeration literals, a physical type its units; they override this method.

Return type:

Generator[tuple[str, ModelEntity]]

Returns:

A generator to iterate (normalized designator, declaration) pairs, in declaration order: none.

IterateSingleGenericDeclarations(predicate=None)

Iterate all generics per declared identifier, in declaration order.

A generic constant yields one single declaration per identifier: generic (A, B : positive) yields two. A generic type, subprogram or package declares exactly one identifier and is yielded itself.

Parameters:

predicate (Callable[[SingleGenericDeclarationMixin | GenericInterfaceItemMixin], bool] | None) – Optional, filter function to select the yielded generics. Default: all.

Return type:

Generator[SingleGenericDeclarationMixin | GenericInterfaceItemMixin]

Returns:

A generator to iterate all (selected) generics.

IterateSinglePortDeclarations(predicate=None)

Iterate all ports per declared identifier, in declaration order.

A port yields one single declaration per identifier: port (a, b : in bit) yields two.

Parameters:

predicate (Callable[[SinglePortDeclarationMixin], bool] | None) – Optional, filter function to select the yielded ports. Default: all.

Return type:

Generator[SinglePortDeclarationMixin]

Returns:

A generator to iterate all (selected) ports.

IterateTypeMarks(region)

Iterate the type marks of this declaration, each with the region and the place to look it up.

The place of a type mark is the declaration containing it. Declarations with type marks override this method, e.g. an object yields the type mark of its subtype indication, an array type its index and element subtypes.

Parameters:

region (DeclarativeRegionMixin) – The declarative region declaring this declaration.

Return type:

Generator[tuple[DeclarativeRegionMixin, ModelEntity, SubtypeSymbol]]

Returns:

A generator to iterate (region, place, type mark) tuples, in declaration order: none.

property Library: Library

Property to access the library (_parent).

Returns:

The library.

property LibraryReferences: list[LibraryClause]

Read-only property to access the sequence of library clauses (_libraryReferences).

Returns:

Sequence of library clauses.

LookupName(place, symbol, name, warningType)

Look up the declarations a simple name or an expanded name denotes at a place in this region.

A simple name is looked up at the place (Lookup()). An expanded name pkg.T or lib.pkg.T resolves its prefix: pkg to a package visible at the place, else to an enclosing declarative region of that name (e.g. the package or entity containing the place); lib.pkg by the library (work or a library whose name is visible in the design unit containing the place, IsLibraryVisible()) and the package’s name. Then the suffix is searched among the declarations of the package or region (FindDeclarations()).

A failure is reported as a warning of the given type, whose label names the kind of name in the message (e.g. Type mark); then no declaration is returned. A name, which is a part of the symbol’s name (e.g. the prefix s of the type mark s'subtype), is reported as a prefix of the symbol’s name.

Parameters:
  • place (ModelEntity) – The declaration containing the name.

  • symbol (Symbol) – The symbol containing the name.

  • name (Name) – The simple name or expanded name: the symbol’s name or a part of it.

  • warningType (type[UnresolvedNameWarning]) – The warning class reporting a failure.

Return type:

tuple[ModelEntity, ...]

Returns:

Tuple of the directly visible declarations, empty if none is.

Raises:

UnhandledCriticalWarningError – If the name isn’t visible, is ambiguous, or has a prefix, which isn’t a visible package or an enclosing region, and no WarningCollector collects the warning.

MoveDeclaredItem(declaredItem, index)

Move a declared item to a position of the declarative region.

The declared item stays a declared item of this declarative region: only the order of the declared items changes.

If the region is indexed, the lookup tables and the namespace follow the new order: a list of overloads (e.g. in Functions) follows the declaration order, and the namespace refers to the overload declared last. If another declaration shares an identifier with the declared item (e.g. a duplicate declaration read by a parser), the region is indexed again (IndexDeclaredItems()) after the move.

Parameters:
  • declaredItem (ModelEntity) – The declared item to move.

  • index (int) – Position of the declared item after the move, from 0 (first) to the number of declared items minus one (last). A negative index counts from the end, as for a list index: -1 moves the declared item to the end.

Raises:
  • ValueError – If parameter ‘declaredItem’ is None.

  • TypeError – If parameter ‘declaredItem’ is not of type ModelEntity.

  • NotAChildError – If parameter ‘declaredItem’ is not a declared item of this declarative region.

  • ValueError – If parameter ‘index’ is None.

  • TypeError – If parameter ‘index’ is not of type int.

  • ValueError – If parameter ‘index’ is out of range.

Return type:

None

See also

MoveDeclaredItemBefore()

→ Move a declared item before another declared item.

MoveDeclaredItemAfter()

→ Move a declared item after another declared item.

InsertDeclaredItem()

→ Insert a declared item at a position of the declarative region.

RemoveDeclaredItem()

→ Remove a declared item from the declarative region.

MoveDeclaredItemAfter(declaredItem, after)

Move a declared item after another declared item.

The declared item stays a declared item of this declarative region: only the order of the declared items changes, as for MoveDeclaredItem(). Moving a declared item after itself keeps it in place.

Parameters:
  • declaredItem (ModelEntity) – The declared item to move.

  • after (ModelEntity) – The declared item of this declarative region to move after.

Raises:
  • ValueError – If parameter ‘declaredItem’ is None.

  • TypeError – If parameter ‘declaredItem’ is not of type ModelEntity.

  • NotAChildError – If parameter ‘declaredItem’ is not a declared item of this declarative region.

  • ValueError – If parameter ‘after’ is None.

  • TypeError – If parameter ‘after’ is not of type ModelEntity.

  • NotAChildError – If parameter ‘after’ is not a declared item of this declarative region.

Return type:

None

See also

MoveDeclaredItem()

→ Move a declared item to a position of the declarative region.

MoveDeclaredItemBefore()

→ Move a declared item before another declared item.

MoveDeclaredItemBefore(declaredItem, before)

Move a declared item before another declared item.

The declared item stays a declared item of this declarative region: only the order of the declared items changes, as for MoveDeclaredItem(). Moving a declared item before itself keeps it in place.

Parameters:
  • declaredItem (ModelEntity) – The declared item to move.

  • before (ModelEntity) – The declared item of this declarative region to move before.

Raises:
  • ValueError – If parameter ‘declaredItem’ is None.

  • TypeError – If parameter ‘declaredItem’ is not of type ModelEntity.

  • NotAChildError – If parameter ‘declaredItem’ is not a declared item of this declarative region.

  • ValueError – If parameter ‘before’ is None.

  • TypeError – If parameter ‘before’ is not of type ModelEntity.

  • NotAChildError – If parameter ‘before’ is not a declared item of this declarative region.

Return type:

None

See also

MoveDeclaredItem()

→ Move a declared item to a position of the declarative region.

MoveDeclaredItemAfter()

→ Move a declared item after another declared item.

MoveGenericItem(genericItem, index)

Move a generic to a position of the generic clause.

The generic stays a generic of this language construct: only the order of the generic clause changes. A generic subprogram is an overload: if the language construct’s namespace is indexed, it refers to the overload declared last afterwards.

The generic leaves its generic group, like RemoveGenericItem(), and joins a generic group, like InsertGenericItem() without a generic group: the generic group of the generic before its new position; at index 0, the generic group of the first generic. A move to the generic’s current position changes nothing.

Parameters:
  • genericItem (GenericInterfaceItemMixin) – The generic to move.

  • index (int) – Position of the generic after the move, from 0 (first) to the length of GenericItems minus one (last). A negative index counts from the end, as for a list index: -1 moves the generic to the end.

Raises:
  • ValueError – If parameter ‘genericItem’ is None.

  • TypeError – If parameter ‘genericItem’ is not of type GenericInterfaceItemMixin.

  • NotAChildError – If parameter ‘genericItem’ is not a generic of this language construct.

  • ValueError – If parameter ‘index’ is None.

  • TypeError – If parameter ‘index’ is not of type int.

  • ValueError – If parameter ‘index’ is out of range.

  • NotInNamespaceError – If the namespace is indexed, and the identifier of a generic subprogram refers to an element, which is no overload, e.g. a duplicate declaration.

Return type:

None

See also

InsertGenericItem()

→ Insert a generic at a position of the generic clause.

RemoveGenericItem()

→ Remove a generic from the generic clause.

MovePortItem(portItem, index)

Move a port to a position of the port clause.

The port stays a port of this language construct: only the order of the port clause changes. The port leaves its port group, like RemovePortItem(), and joins a port group, like InsertPortItem() without a port group: the port group of the port before its new position; at index 0, the port group of the first port. A move to the port’s current position changes nothing.

Parameters:
  • portItem (PortSignalInterfaceItem) – The port to move.

  • index (int) – Position of the port after the move, from 0 (first) to the length of PortItems minus one (last). A negative index counts from the end, as for a list index: -1 moves the port to the end.

Raises:
  • ValueError – If parameter ‘portItem’ is None.

  • TypeError – If parameter ‘portItem’ is not of type PortSignalInterfaceItem.

  • NotAChildError – If parameter ‘portItem’ is not a port of this language construct.

  • ValueError – If parameter ‘index’ is None.

  • TypeError – If parameter ‘index’ is not of type int.

  • ValueError – If parameter ‘index’ is out of range.

Return type:

None

See also

InsertPortItem()

→ Insert a port at a position of the port clause.

RemovePortItem()

→ Remove a port from the port clause.

MoveStatement(statement, index)

Move a concurrent statement to a position of this construct.

The statement stays a statement of this construct: only the order of the statements changes. If the statements are indexed (IndexStatements()), the lookup tables are unchanged.

Parameters:
  • statement (ConcurrentStatement) – The concurrent statement to move.

  • index (int) – Position of the statement after the move, from 0 (first) to the number of statements minus one (last). A negative index counts from the end, as for a list index: -1 moves the statement to the end.

Raises:
  • ValueError – If parameter ‘statement’ is None.

  • TypeError – If parameter ‘statement’ is not of type ModelEntity.

  • NotAChildError – If parameter ‘statement’ is not a statement of this construct.

  • ValueError – If parameter ‘index’ is None.

  • TypeError – If parameter ‘index’ is not of type int.

  • ValueError – If parameter ‘index’ is out of range.

Return type:

None

See also

MoveStatementBefore()

→ Move a concurrent statement before another statement.

MoveStatementAfter()

→ Move a concurrent statement after another statement.

InsertStatement()

→ Insert a concurrent statement at a position of this construct.

RemoveStatement()

→ Remove a concurrent statement from this construct.

MoveStatementAfter(statement, after)

Move a concurrent statement after another statement of this construct.

The statement stays a statement of this construct: only the order of the statements changes, as for MoveStatement(). Moving a statement after itself keeps it in place.

Parameters:
Raises:
  • ValueError – If parameter ‘statement’ is None.

  • TypeError – If parameter ‘statement’ is not of type ModelEntity.

  • NotAChildError – If parameter ‘statement’ is not a statement of this construct.

  • ValueError – If parameter ‘after’ is None.

  • TypeError – If parameter ‘after’ is not of type ModelEntity.

  • NotAChildError – If parameter ‘after’ is not a statement of this construct.

Return type:

None

See also

MoveStatement()

→ Move a concurrent statement to a position of this construct.

MoveStatementBefore()

→ Move a concurrent statement before another statement.

MoveStatementBefore(statement, before)

Move a concurrent statement before another statement of this construct.

The statement stays a statement of this construct: only the order of the statements changes, as for MoveStatement(). Moving a statement before itself keeps it in place.

Parameters:
Raises:
  • ValueError – If parameter ‘statement’ is None.

  • TypeError – If parameter ‘statement’ is not of type ModelEntity.

  • NotAChildError – If parameter ‘statement’ is not a statement of this construct.

  • ValueError – If parameter ‘before’ is None.

  • TypeError – If parameter ‘before’ is not of type ModelEntity.

  • NotAChildError – If parameter ‘before’ is not a statement of this construct.

Return type:

None

See also

MoveStatement()

→ Move a concurrent statement to a position of this construct.

MoveStatementAfter()

→ Move a concurrent statement after another statement.

property NormalizedIdentifier: str

Read-only property to access the model entity’s normalized identifier (_normalizedIdentifier).

See also

Returns:

Normalized name of a model entity.

property PackageReferences: list[UseClause]

Read-only property to access the sequence of use clauses (_packageReferences).

Returns:

Sequence of use clauses.

property Parent: ModelEntity

Property to access the model entity’s parent element reference in a logical hierarchy (_parent).

Returns:

Reference to the parent entity.

property PortCount: int

Read-only property to return the number of ports declared by _portItems.

A port item with several identifiers (port (a, b : in bit)) declares several ports.

Returns:

The number of ports.

property PortGroups: list[PortGroup]

Read-only property to access the port groups (_portGroups).

The port groups partition the port clause: concatenated in order, they list every port exactly once, in declaration order.

Returns:

List of port groups, in declaration order.

property PortItems: list[PortInterfaceItemMixin]

Read-only property to access the port items (_portItems).

Returns:

List of port items.

property Position: Position

Cached read-only property to access an IIR’s position in source code (_position).

If _position is None, resolve the position object from _iirNode

Returns:

The IIR’s position in the source file.

Precedes(item, anchor, inclusive)

Check if an item precedes an anchor in this declarative region.

An item, which isn’t a declaration of this region (e.g. a use clause of the context clause), precedes every anchor.

Parameters:
  • item (ModelEntity | None) – The item in declaration order, or None for the implicit use clause.

  • anchor (ModelEntity) – A declaration of this region, e.g. the one containing the place of a lookup.

  • inclusive (bool) – True, if the anchor precedes itself, i.e. the place is nested inside the anchor.

Return type:

bool

Returns:

True, if the item precedes the anchor.

property Procedures: dict[str, list[Procedure]]

Read-only property to access the procedures (_procedures).

Returns:

Dictionary of procedures, indexed by normalized identifier; each entry is a list of overloads.

property ReferencedContexts: dict[str, Context]

Read-only property to access the referenced contexts (_referencedContexts).

Returns:

Dictionary of referenced contexts, indexed by normalized identifier.

property ReferencedLibraries: dict[str, Library]

Read-only property to access the referenced libraries (_referencedLibraries).

Returns:

Dictionary of referenced libraries, indexed by normalized identifier.

property ReferencedPackages: dict[str, Package]

Read-only property to access the referenced packages (_referencedPackages).

Returns:

Dictionary of referenced packages, indexed by normalized identifier.

RemoveContextItem(contextItem)

Remove a context item from the context clause.

The context item is detached: its parent is cleared, and it’s removed from ContextItems and from LibraryReferences, PackageReferences or ContextReferences. The context item itself is unchanged and can be added to another design unit, or inserted at another position.

Parameters:

contextItem (LibraryClause | UseClause | ContextReference) – The library clause, use clause or context reference to remove.

Raises:
Return type:

None

Attention

The mutator doesn’t update what Analyze() derived from the context items: the referenced libraries, packages and contexts (ReferencedLibraries, ReferencedPackages, ReferencedContexts), the namespace entries of a use clause, the edges of the dependency graph, and the references of the symbols. A design changed after its analysis needs a new analysis.

See also

AddContextItem()

→ Add a context item at the end of the context clause.

InsertContextItem()

→ Insert a context item at a position of the context clause.

RemoveDeclaredItem(declaredItem)

Remove a declared item from the declarative region.

The declared item is detached: its parent is cleared. If the region is indexed, the declared item’s identifiers are removed from the region’s namespace and from the lookup table matching its kind first; they are checked before anything is changed. The declared item itself is unchanged and can be added to another declarative region, or inserted at another position.

The namespace refers to the overload declared last: removing it, the namespace refers to the remaining overload declared last. If another declaration shares an identifier with the declared item (e.g. a duplicate declaration read by a parser), the region is indexed again (IndexDeclaredItems()) after the removal.

Parameters:

declaredItem (ModelEntity) – The declared item to remove.

Raises:
  • ValueError – If parameter ‘declaredItem’ is None.

  • TypeError – If parameter ‘declaredItem’ is not of type ModelEntity.

  • NotAChildError – If parameter ‘declaredItem’ is not a declared item of this declarative region.

  • NotInNamespaceError – If the region is indexed, and an identifier of the declared item isn’t declared in its namespace.

  • NotInNamespaceError – If the region is indexed, and an identifier of the declared item refers to another declaration, e.g. a duplicate declaration.

Return type:

None

See also

AddDeclaredItem()

→ Add a declared item at the end of the declarative region.

InsertDeclaredItem()

→ Insert a declared item at a position of the declarative region.

MoveDeclaredItem()

→ Move a declared item to a position of the declarative region.

RemoveGenericItem(genericItem)

Remove a generic from the generic clause.

The generic is detached: its parent and generic group are cleared and its identifiers are removed from the language construct’s namespace, if it has one. A generic group, which becomes empty, is removed from GenericGroups and its parent is cleared. The generic itself is unchanged and can be added to another language construct, or inserted at another position.

Parameters:

genericItem (GenericInterfaceItemMixin) – The generic to remove.

Raises:
  • ValueError – If parameter ‘genericItem’ is None.

  • TypeError – If parameter ‘genericItem’ is not of type GenericInterfaceItemMixin.

  • NotAChildError – If parameter ‘genericItem’ is not a generic of this language construct.

  • NotInNamespaceError – If the namespace is indexed, and an identifier of the generic isn’t declared in it.

  • NotInNamespaceError – If the namespace is indexed, and an identifier of the generic refers to another element, e.g. a duplicate declaration.

Return type:

None

See also

AddGenericItem()

→ Add a generic at the end of the generic clause.

InsertGenericItem()

→ Insert a generic at a position of the generic clause.

MoveGenericItem()

→ Move a generic to a position of the generic clause.

RemovePortItem(portItem)

Remove a port from the port clause.

The port is detached: its parent and port group are cleared and its identifiers are removed from the language construct’s namespace, if it has one. A port group, which becomes empty, is removed from PortGroups and its parent is cleared. The port itself is unchanged and can be added to another language construct, or inserted at another position.

Parameters:

portItem (PortSignalInterfaceItem) – The port to remove.

Raises:
  • ValueError – If parameter ‘portItem’ is None.

  • TypeError – If parameter ‘portItem’ is not of type PortSignalInterfaceItem.

  • NotAChildError – If parameter ‘portItem’ is not a port of this language construct.

  • NotInNamespaceError – If the namespace is indexed, and an identifier of the port isn’t declared in it.

  • NotInNamespaceError – If the namespace is indexed, and an identifier of the port refers to another element, e.g. a duplicate declaration.

Return type:

None

See also

AddPortItem()

→ Add a port at the end of the port clause.

InsertPortItem()

→ Insert a port at a position of the port clause.

MovePortItem()

→ Move a port to a position of the port clause.

RemoveStatement(statement)

Remove a concurrent statement from this construct.

The statement is detached: its parent is cleared. If the statements are indexed, an instantiation, a block or a generate statement is removed from its lookup table. The statement itself is unchanged and can be added to another construct, or inserted at another position. A removed process, block or generate statement keeps the link of its namespace to this construct’s namespace.

Parameters:

statement (ConcurrentStatement) – The concurrent statement to remove.

Raises:
  • ValueError – If parameter ‘statement’ is None.

  • TypeError – If parameter ‘statement’ is not of type ModelEntity.

  • NotAChildError – If parameter ‘statement’ is not a statement of this construct.

Return type:

None

See also

AddStatement()

→ Add a concurrent statement at the end of this construct.

InsertStatement()

→ Insert a concurrent statement at a position of this construct.

MoveStatement()

→ Move a concurrent statement to a position of this construct.

ResetReferences(designUnit, region)

Reset the references ResolveReferences() derived: the references of this declaration’s type marks.

A use clause, an alias and a subtype extend this method.

Parameters:
  • designUnit (DesignUnit) – The design unit containing this declaration.

  • region (DeclarativeRegionMixin) – The declarative region declaring this declaration.

Return type:

None

ResolveReferences(designUnit, region)

Resolve the references of this declaration: its type marks (IterateTypeMarks()).

Each type mark is resolved at its place by the region it is looked up in (ResolveTypeMark()). An incomplete type, an alias and a subtype extend this method.

Parameters:
  • designUnit (DesignUnit) – The design unit containing this declaration.

  • region (DeclarativeRegionMixin) – The declarative region declaring this declaration.

Raises:

UnhandledCriticalWarningError – If a type mark can’t be resolved, and no WarningCollector collects the UnresolvedTypeMarkWarning.

Return type:

None

ResolveTypeMark(place, symbol)

Resolve a type mark at its place in this region and set the symbol’s reference.

Algorithm

  1. Clear the symbol’s reference.

  2. Look up the type mark’s name (LookupName()).

  3. An alias of a type is replaced by the type its name references.

  4. If the declaration is a type, a subtype or a generic type, it becomes the symbol’s reference. A full type, which follows the place in the same region, is visible by its incomplete type declaration only to an access type.

An attribute name denoting a type (e.g. s'subtype, A'element) is resolved part by part (Denote()); the type it denotes becomes the symbol’s reference.

Parameters:
Raises:

UnhandledCriticalWarningError – If the type mark isn’t visible, is ambiguous, has a prefix, which isn’t a visible package, denotes no type, or denotes an incomplete type outside of an access type, and no WarningCollector collects the UnresolvedTypeMarkWarning.

Return type:

None

property SharedVariables: dict[str, SharedVariable]

Read-only property to access the shared variables (_sharedVariables).

Returns:

Dictionary of shared variables, indexed by normalized identifier.

property Signals: dict[str, Signal]

Read-only property to access the signals (_signals).

Returns:

Dictionary of signals, indexed by normalized identifier.

SplitDeclaredItem(declaredItem)

Split a declared item with an identifier list into one declaration per identifier.

The declared item keeps its first identifier. For every other identifier, a new declaration is created by its Copy() and inserted right after it, in list order; its parent is set to this declarative region. If the region is indexed, the namespace and lookup table entries of the other identifiers refer to the new declarations; they are checked before anything is changed. A declared item declaring one identifier is unchanged.

Parameters:

declaredItem (ModelEntity) – The declared item to split.

Return type:

tuple[ModelEntity, ...]

Returns:

Tuple of declarations, one per identifier in list order, starting with the split declared item.

Raises:
  • ValueError – If parameter ‘declaredItem’ is None.

  • TypeError – If parameter ‘declaredItem’ is not of type ModelEntity.

  • NotAChildError – If parameter ‘declaredItem’ is not a declared item of this declarative region.

  • NotInNamespaceError – If the region is indexed, and an identifier of the declared item refers to another declaration, e.g. a duplicate declaration.

See also

Split()

→ Split a declaration with an identifier list.

RemoveDeclaredItem()

→ Remove a declared item from the declarative region.

SplitGenericItem(genericItem)

Split a generic with an identifier list into one generic per identifier.

The generic keeps its first identifier. For every other identifier, a new generic is created by its Copy() and inserted right after it, in list order, in the generic clause and in the generic’s generic group; its parent is set to this language construct. If the language construct has a namespace, the entries of the other identifiers refer to the new generics. A generic declaring one identifier is unchanged.

Parameters:

genericItem (GenericInterfaceItemMixin) – The generic to split.

Return type:

tuple[GenericInterfaceItemMixin, ...]

Returns:

Tuple of generics, one per identifier in list order, starting with the split generic.

Raises:
  • ValueError – If parameter ‘genericItem’ is None.

  • TypeError – If parameter ‘genericItem’ is not of type GenericInterfaceItemMixin.

  • NotAChildError – If parameter ‘genericItem’ is not a generic of this language construct.

  • NotInNamespaceError – If the namespace is indexed, and an identifier of the generic refers to another element, e.g. a duplicate declaration.

See also

Split()

→ Split a declaration with an identifier list.

RemoveGenericItem()

→ Remove a generic from the generic clause.

SplitPortItem(portItem)

Split a port with an identifier list into one port per identifier.

The port keeps its first identifier. For every other identifier, a new port is created by its Copy() and inserted right after it, in list order, in the port clause and in the port’s port group; its parent is set to this language construct. If the language construct has a namespace, the entries of the other identifiers refer to the new ports. A port declaring one identifier is unchanged.

Parameters:

portItem (PortSignalInterfaceItem) – The port to split.

Return type:

tuple[PortSignalInterfaceItem, ...]

Returns:

Tuple of ports, one per identifier in list order, starting with the split port.

Raises:
  • ValueError – If parameter ‘portItem’ is None.

  • TypeError – If parameter ‘portItem’ is not of type PortSignalInterfaceItem.

  • NotAChildError – If parameter ‘portItem’ is not a port of this language construct.

  • NotInNamespaceError – If the namespace is indexed, and an identifier of the port refers to another element, e.g. a duplicate declaration.

See also

Split()

→ Split a declaration with an identifier list.

RemovePortItem()

→ Remove a port from the port clause.

property Statements: list[ConcurrentStatement]

Read-only property to access the statements (_statements).

Returns:

List of statements.

property Subtypes: dict[str, Subtype]

Read-only property to access the subtypes (_subtypes).

Returns:

Dictionary of subtypes, indexed by normalized identifier.

property Types: dict[str, FullType]

Read-only property to access the types (_types).

Returns:

Dictionary of types, indexed by normalized identifier.

Visit(visitor)[source]

Walk this entity, its context clause, its interface, its declared items and its statements with a visitor.

Parameters:

visitor (Visitor) – The visitor receiving the events.

Return type:

None

_AddOverloadToNamespace(item)

Add a function or procedure to the namespace, if it’s the overload declared last.

The namespace keeps one entry per identifier: the overload declared last, as after IndexDeclaredItems(), which adds interface items first, then declared items (_Declarations()).

Parameters:

item (NamedEntityMixin | MultipleNamedEntityMixin) – The function or procedure, already an interface item or declared item of this region.

Return type:

None

_AddToGenericGroup(position, genericItem)

Add a generic to the generic group of the generic before position.

At position 0, the generic joins the generic group of the first generic. If there are no generic groups, the generic forms a new unnamed generic group.

Parameters:
  • position (int) – Position of the generic in the generic clause, from 0 (first) to the length of GenericItems (last).

  • genericItem (GenericInterfaceItemMixin) – The generic to add, which isn’t in a generic group.

Return type:

None

_AddToNamespace(element)

Add an element’s identifiers to this region’s namespace.

Nothing is added to a region not indexed yet: IndexDeclaredItems() adds the element later. A generic subprogram is an overload (_AddOverloadToNamespace()).

Parameters:

element (NamedEntityMixin | MultipleNamedEntityMixin) – The named element to add, e.g. an interface item.

Return type:

None

_AddToPortGroup(position, portItem)

Add a port to the port group of the port before position; at position 0, the port group of the first port.

If there are no port groups, the port forms a new unnamed port group.

Parameters:
  • position (int) – Position of the port in the port clause, from 0 (first) to the length of PortItems (last).

  • portItem (PortSignalInterfaceItem) – The port to add, which isn’t in a port group.

Return type:

None

_CONTINUES_PARENT_REGION = False

True if it continues its parent’s declarative region.

_ClashingDeclarations(item)

Return the declarations sharing an identifier with the given item, which may not share it.

The declarations (_Declarations()) and the labeled statements (_Labels()) of this declarative region and of the language constructs sharing it (_SharedRegions()) are searched: a statement label is declared implicitly. Items imported into the namespace (e.g. by a use clause) are no declarations.

Parameters:

item (ModelEntity) – The new declaration, or the new labeled statement.

Return type:

tuple[ModelEntity, ...]

Returns:

Tuple of clashing declarations, interface items first, then declared items in declaration order, then labeled statements.

_ConnectParentNamespace(parent)

Connect this region’s namespace to the namespace of the enclosing declarative region.

A declaration of this region then hides a same-named declaration of the enclosing region. A parent, which isn’t a declarative region (e.g. a subprogram of an interface list), has no namespace to connect to.

Parameters:

parent (ModelEntity) – The new parent of this region.

Return type:

None

_ContextClauseUnits()

Return the design units whose context clause applies to this design unit.

Return type:

tuple[DesignUnit, ...]

Returns:

Tuple of this design unit.

_DECLARED_ITEM_TYPES = (<class 'pyVHDLModel.Type.BaseType'>, <class 'pyVHDLModel.Subprogram.Subprogram'>, <class 'pyVHDLModel.DesignUnit.Package'>, <class 'pyVHDLModel.DesignUnit.PackageBody'>, <class 'pyVHDLModel.Object.Constant'>, <class 'pyVHDLModel.Object.Signal'>, <class 'pyVHDLModel.Object.SharedVariable'>, <class 'pyVHDLModel.Object.File'>, <class 'pyVHDLModel.Declaration.Alias'>, <class 'pyVHDLModel.DesignUnit.Component'>, <class 'pyVHDLModel.Declaration.Attribute'>, <class 'pyVHDLModel.Declaration.AttributeSpecification'>, <class 'pyVHDLModel.Configuration.ComponentConfiguration'>, <class 'pyVHDLModel.Interface.ModeViewDeclaration'>, <class 'pyVHDLModel.DesignUnit.UseClause'>, <class 'pyVHDLModel.PSLModel.PSLEntity'>)

Accepted classes of declared items (pyVHDLModel).

_Declarations()[source]

Return all declarations of this entity: its generics and ports share the declarative region.

Return type:

tuple[ModelEntity, ...]

Returns:

Tuple of declarations: the generics, the ports, then the declared items.

_DeclaredItemsSharingIdentifiers(declaredItem)

Return the other declared items of this region sharing an identifier with the given declared item.

Parameters:

declaredItem (ModelEntity) – The declared item.

Return type:

list[ModelEntity]

Returns:

List of declared items, in declaration order.

_END_KEYWORDS: ClassVar[tuple[ReservedWord, ...]] = (ReservedWord.Entity,)

Reserved words after end.

_END_KEYWORDS_OPTIONAL: ClassVar[bool] = True

The reserved words after end are optional.

_IMPLICIT_LIBRARIES = ('work', 'std')

Library names visible without a library clause.

_IndexDeclaredItem(item)

Add a declared item to the namespace and to the lookup table matching its kind.

Parameters:

item (ModelEntity) – The declared item.

Return type:

None

_IndexGenericItems()

Add the generics to the host’s namespace; a generic subprogram is an overload.

Return type:

None

_IndexOtherDeclaredItem(item)

Hook for declared items the region doesn’t handle itself. Derived classes may override it.

An alias, an attribute declaration and a package (also a package instantiation) declared in the region are added to the namespace, without a lookup table.

Parameters:

item (ModelEntity) – The declared item.

Return type:

None

_IndexOverload(item)

Add an inserted function or procedure to its lookup table and to the namespace.

The list of overloads follows the declaration order. The namespace is updated by _AddOverloadToNamespace().

Parameters:

item (NamedEntityMixin | MultipleNamedEntityMixin) – The inserted function or procedure.

Return type:

None

_IndexPortItems()

Add the ports to the host’s namespace.

Return type:

None

_IndexStatement(statement)

Add an instantiation, a block or a generate statement to its lookup table, and index the statements nested in it.

Parameters:

statement (ConcurrentStatement) – The concurrent statement of this construct.

Return type:

None

_IterateStatementRegions()

Iterate the declarative regions of the concurrent statements, each followed by the regions nested in it.

Blocks, processes and for-generate statements are declarative regions; an if-generate statement has one per branch, a case-generate statement one per alternative.

Return type:

Generator[DeclarativeRegionMixin]

Returns:

A generator to iterate the declarative regions, in statement order.

_Labels()

Return the labeled statements, whose labels are declared in this construct’s declarative region.

A statement nested in a block or generate statement is declared in that statement’s declarative region.

Return type:

tuple[ConcurrentStatement, ...]

Returns:

Tuple of labeled statements, in statement order.

_MayShareIdentifier(item, existing)

Check if two declarations may share an identifier in one declarative region.

Subprograms are overloadable. A protected type body completes its protected type, a full type completes its incomplete type, and a constant completes its deferred constant.

Parameters:
Return type:

bool

Returns:

True, if both declarations may share an identifier.

_RemoveDeclaredItemEntries(lookupTable, item)

Remove a declared item’s entries from a lookup table and from the namespace.

Every identifier is checked before anything is removed.

Parameters:
Raises:
  • NotInNamespaceError – If an identifier of the declared item isn’t declared in the namespace.

  • NotInNamespaceError – If an identifier of the declared item refers to another element, e.g. a duplicate declaration.

Return type:

None

_RemoveDeclaredItemsFromNamespace()

Remove all declared items of this region from its namespace.

Interface items of this region and items imported from elsewhere (e.g. by a use clause) are kept.

Return type:

None

_RemoveFromGenericGroup(genericItem)

Remove a generic from its generic group and clear the generic’s group.

A generic group, which becomes empty, is removed from GenericGroups and its parent is cleared.

Parameters:

genericItem (GenericInterfaceItemMixin) – The generic to remove from its generic group.

Return type:

None

_RemoveFromNamespace(element)

Remove an element’s identifiers from this region’s namespace.

Nothing is removed from a region not indexed yet, as its namespace doesn’t contain the element. A generic subprogram is an overload (_RemoveOverloadFromNamespace()).

Parameters:

element (NamedEntityMixin | MultipleNamedEntityMixin) – The named element to remove, e.g. an interface item.

Raises:
  • NotInNamespaceError – If the region is indexed, and an identifier of the element isn’t declared in the namespace.

  • NotInNamespaceError – If the region is indexed, and an identifier of the element refers to another element, e.g. a duplicate declaration.

Return type:

None

_RemoveFromPortGroup(portItem)

Remove a port from its port group and clear the port’s group.

A port group, which becomes empty, is removed from PortGroups and its parent is cleared.

Parameters:

portItem (PortSignalInterfaceItem) – The port to remove from its port group.

Return type:

None

_RemoveOverloadFromNamespace(item)

Remove a function or procedure from the namespace.

Removing the overload the namespace refers to, the namespace refers to the remaining overload declared last (_Declarations()), or the identifier is removed, if no overload remains. Removing another overload leaves the namespace unchanged. The namespace is checked before it’s changed.

Parameters:

item (NamedEntityMixin | MultipleNamedEntityMixin) – The function or procedure, still an interface item or declared item of this region.

Raises:
  • NotInNamespaceError – If the identifier isn’t declared in the namespace.

  • NotInNamespaceError – If the identifier refers to an element, which is no overload, e.g. a duplicate declaration.

Return type:

None

_SharedRegions()[source]

Return the other language constructs forming one declarative region with this entity.

Return type:

tuple[ConcurrentDeclarationRegionMixin, ...]

Returns:

Tuple of the linked architectures (_architectures).

_UnindexDeclaredItem(item)

Remove a declared item from the namespace and from the lookup table matching its kind.

Parameters:

item (ModelEntity) – The declared item.

Return type:

None

_UnindexOtherDeclaredItem(item)

Hook to remove declared items the region doesn’t handle itself. Derived classes may override it.

An alias, an attribute declaration and a package are removed from the namespace.

Parameters:

item (ModelEntity) – The declared item.

Raises:

NotInNamespaceError – If the item is an alias, an attribute declaration or a package, which isn’t declared in the namespace.

Return type:

None

_UnindexOverload(item)

Remove a function or procedure from its lookup table and from the namespace.

The namespace is updated first, by _RemoveOverloadFromNamespace().

Parameters:

item (NamedEntityMixin | MultipleNamedEntityMixin) – The function or procedure to remove, still a declared item of this region.

Raises:
  • NotInNamespaceError – If the identifier isn’t declared in the namespace.

  • NotInNamespaceError – If the identifier refers to an element, which is no overload, e.g. a duplicate declaration.

Return type:

None

_UnindexStatement(statement)

Remove an instantiation, a block or a generate statement from its lookup table.

Parameters:

statement (ConcurrentStatement) – The concurrent statement of this construct.

Return type:

None

_VisitContextClause(visitor)

Walk the context clause, i.e. the context items preceding the design unit, with a visitor.

The context clause is reported, even if it has no context items.

Parameters:

visitor (Visitor) – The visitor receiving the events.

Return type:

None

_VisitDeclaredItems(visitor)

Walk the declared items in declaration order with a visitor.

Parameters:

visitor (Visitor) – The visitor receiving the events.

Return type:

None

_VisitGenericClause(visitor)

Walk the generic clause, if there are generics, with a visitor.

The generics are separated by semicolons.

Parameters:

visitor (Visitor) – The visitor receiving the events.

Return type:

None

_VisitPortClause(visitor)

Walk the port clause, if there are ports, with a visitor.

The ports are separated by semicolons.

Parameters:

visitor (Visitor) – The visitor receiving the events.

Return type:

None

_VisitStatements(visitor)

Walk the concurrent statements in statement order with a visitor.

Parameters:

visitor (Visitor) – The visitor receiving the events.

Return type:

None

__getstate__()

Return the object’s state for pickling, collecting every slot of the class hierarchy.

Return type:

dict[str, Any]

Returns:

Dictionary of slot names and their values.

Raises:

ExtendedTypeError – If a slot was never assigned, so it has no value to serialize.

__new__(**kwargs)
__repr__()[source]

Formats a representation of the entity declaration.

Format: mylib.myEntity(rtl, sim)

Return type:

str

Returns:

String representation of the entity declaration.

__setstate__(state)

Restore the object’s state from unpickling, requiring exactly the slots of the class hierarchy.

Parameters:

state (dict[str, Any]) – Dictionary of slot names and their values.

Raises:

ExtendedTypeError – If the given state misses a slot or carries an unexpected one.

Return type:

None

__str__()[source]

Formats the entity declaration.

Format: Entity: 'mylib.myEntity(rtl, sim)'

The parenthesis lists the known architectures, or ? if there are none.

Return type:

str

Returns:

Formatted entity declaration.

_allowBlackbox

Allow blackboxes for components; None inherits the parent’s setting.

_architectures: dict[str, Architecture]

Dictionary of all architectures of this entity, indexed by name.

_areDeclaredItemsIndexed

True if IndexDeclaredItems() filled the namespace.

_areStatementsIndexed

True if IndexStatements() filled _instantiations and _hierarchy.

_components

Dictionary of all components declared in this concurrent declaration region.

_constants

Dictionary of all constants declared in this concurrent declaration region.

_contextItems

List of all context items (library, use and context clauses).

_contextReferences

List of context clauses.

_declaredItems

List of all declared items in this concurrent declaration region.

_dependencyVertex

Reference to the vertex in the dependency graph representing the design unit.
This reference is set by CreateDependencyGraph().

_document

The VHDL library, the design unit was analyzed into.

_documentation

The associated documentation of a model entity.

_files

Dictionary of all files declared in this concurrent declaration region.

_functions

Dictionary of all functions declared in this concurrent declaration region, indexed by name; each entry is a list of overloads.

_genericGroups

List of all generic groups, in declaration order.

_genericItems

List of all generics, in declaration order.

_hierarchy

All elements creating a hierarchy level (blocks and generates), in declaration order.

_hierarchyVertex

The vertex in the hierarchy graph

_identifier

The identifier of a model entity.

_instantiations

All instantiations, indexed by label.

_libraryReferences

List of library clauses.

_namespace

The namespace of this concurrent declaration region.

_normalizedIdentifier

The normalized (lower case) identifier of a model entity.

_packageReferences

List of use clauses.

_parent

Reference to a parent entity in the logical model hierarchy.

_portGroups

List of all port groups, in declaration order.

_portItems

List of all ports, in declaration order.

_procedures

Dictionary of all procedures declared in this concurrent declaration region, indexed by name; each entry is a list of overloads.

_referencedContexts

Referenced contexts based on explicit context references or implicit inheritance

_referencedLibraries

Referenced libraries based on explicit library clauses or implicit inheritance

_referencedPackages

Referenced packages based on explicit use clauses or implicit inheritance

_sharedVariables

Dictionary of all shared variables declared in this concurrent declaration region.

_signals

Dictionary of all signals declared in this concurrent declaration region.

_statements

List of all concurrent statements in this construct.

_subtypes

Dictionary of all subtypes declared in this concurrent declaration region.

_types

Dictionary of all types declared in this concurrent declaration region.

class pyGHDL.dom.DesignUnit.Architecture(node, identifier, entity, contextItems=None, declaredItems=None, statements=None, documentation=None)[source]

This class implements a pyGHDL.dom object derived from pyVHDLModel.DesignUnit.Architecture.

Represents an architecture declaration.

Example

architecture rtl of ent is
  -- ...
begin
  -- ...
end architecture;

Inheritance

Inheritance diagram of Architecture

Parameters:
  • node (Iir)

  • identifier (str)

  • entity (EntitySymbol)

  • contextItems (Iterable[VHDLModel_ContextUnion])

  • declaredItems (Iterable)

  • statements (Iterable[ConcurrentStatement])

  • documentation (str)

__init__(node, identifier, entity, contextItems=None, declaredItems=None, statements=None, documentation=None)[source]

Initializes an architecture declaration.

Parameters:
  • node (Iir) – The IIR node this object was translated from.

  • identifier (str) – The architecture’s identifier.

  • entity (EntitySymbol) – Reference to the entity this architecture implements.

  • contextItems (Iterable[LibraryClause | UseClause | ContextReference]) – Optional, list of all context items (library, use and context clauses).

  • declaredItems (Iterable) – Optional, list of all declared items in this concurrent declaration region.

  • statements (Iterable[ConcurrentStatement]) – Optional, list of all concurrent statements in this construct.

  • documentation (str) – Optional, the documentation comment associated with this declaration.

Return type:

None

classmethod parse(architectureNode, contextItems)[source]

Translates the IIR node of the architecture body to an Architecture.

Parameters:
Returns:

The translated architecture body.

_iirNode

The IIR node in libghdl’s tree this DOM object was translated from.

_position

The IIR node’s position in the source file, resolved on first access and then cached.

AddContextItem(contextItem)

Add a context item at the end of the context clause.

The context item’s parent is set to this design unit. A library clause is also added to LibraryReferences, a use clause to PackageReferences and a context reference to ContextReferences, in the order of ContextItems. A context item may repeat an earlier one.

Parameters:

contextItem (LibraryClause | UseClause | ContextReference) – The library clause, use clause or context reference to add.

Raises:
Return type:

None

Attention

The mutator doesn’t update what Analyze() derived from the context items: the referenced libraries, packages and contexts (ReferencedLibraries, ReferencedPackages, ReferencedContexts), the namespace entries of a use clause, the edges of the dependency graph, and the references of the symbols. A design changed after its analysis needs a new analysis.

See also

InsertContextItem()

→ Insert a context item at a position of the context clause.

RemoveContextItem()

→ Remove a context item from the context clause.

AddDeclaredItem(declaredItem)

Add a declared item at the end of the declarative region.

The declared item’s parent is set to this declarative region. If the region is indexed, its identifiers are added to the region’s namespace and to the lookup table matching its kind.

Parameters:

declaredItem (ModelEntity) – The declared item to add.

Raises:
  • ValueError – If parameter ‘declaredItem’ is None.

  • TypeError – If parameter ‘declaredItem’ is not a declaration allowed in this declarative region.

  • AlreadyInDesignError – If parameter ‘declaredItem’ already has a parent.

  • DuplicateDeclarationError – If an existing declaration of the declarative region shares an identifier with the declared item.

Return type:

None

See also

InsertDeclaredItem()

→ Insert a declared item at a position of the declarative region.

RemoveDeclaredItem()

→ Remove a declared item from the declarative region.

AddStatement(statement)

Add a concurrent statement at the end of this construct.

The statement’s parent is set to this construct. If the statements are indexed, an instantiation, a block or a generate statement is added to the lookup table matching its kind.

Parameters:

statement (ConcurrentStatement) – The concurrent statement to add.

Raises:
  • ValueError – If parameter ‘statement’ is None.

  • TypeError – If parameter ‘statement’ is not of type ConcurrentStatement.

  • AlreadyInDesignError – If parameter ‘statement’ already has a parent.

  • DuplicateLabelError – If the declarative region already declares the statement’s label.

Return type:

None

See also

InsertStatement()

→ Insert a concurrent statement at a position of this construct.

RemoveStatement()

→ Remove a concurrent statement from this construct.

property AllowBlackbox: bool

Property to return whether a design supports blackboxes, inherited from the parent if not set locally (_allowBlackbox).

Algorithm

  1. If allow blackbox property is locally set, return the local value,

  2. Otherwise, return allow blackbox value from parent object.

Returns:

True, if blackboxes are allowed.

Raises:

AllowBlackboxNotSetError – If neither a local value is set nor a parent object is available to inherit the value from.

Setter accepts:

bool | None

property Components: dict[str, Any]

Read-only property to access the components (_components).

Returns:

Dictionary of components, indexed by normalized identifier.

property Constants: dict[str, Constant]

Read-only property to access the constants (_constants).

Returns:

Dictionary of constants, indexed by normalized identifier.

property ContextItems: list[LibraryClause | UseClause | ContextReference]

Read-only property to access the sequence of all context items comprising library, use and context clauses (_contextItems).

Returns:

Sequence of context items.

property ContextReferences: list[ContextReference]

Read-only property to access the sequence of context clauses (_contextReferences).

Returns:

Sequence of context clauses.

property DeclaredItems: list

Read-only property to access the declared items (_declaredItems).

Returns:

List of declared items.

DenoteBy(name, region, place, symbol)

Determine the model entity a name denoting this declaration denotes, as a part of a type mark (Name.Denote).

A declaration, which a name in a type mark can denote, overrides this method and returns itself: an object, an alias, a type or subtype, a record element, a package. Any other declaration (e.g. a subprogram) is reported.

Parameters:
  • name (Name) – The name denoting this declaration, a part of the type mark.

  • region (DeclarativeRegionMixin) – The declarative region containing the type mark.

  • place (ModelEntity) – The declaration containing the type mark.

  • symbol (Symbol) – The type mark.

Return type:

ModelEntity | None

Returns:

None, as a name in a type mark can’t denote this declaration (reported as a warning).

Raises:

UnhandledCriticalWarningError – Always, if no WarningCollector collects the UnresolvedTypeMarkWarning.

property DependencyVertex: Vertex

Read-only property to access the corresponding dependency vertex (_dependencyVertex).

The dependency vertex references this design unit by its value field.

Returns:

The corresponding dependency vertex.

property Document: Document

Property to access the document (_document).

Returns:

The document.

property Documentation: str | None

Read-only property to access the model entity’s documentation (_documentation).

Returns:

Associated documentation of a model entity.

property Entity: EntitySymbol

Read-only property to access the entity (_entity).

Returns:

The entity.

property Files: dict[str, File]

Read-only property to access the files (_files).

Returns:

Dictionary of files, indexed by normalized identifier.

property Functions: dict[str, list[Function]]

Read-only property to access the functions (_functions).

Returns:

Dictionary of functions, indexed by normalized identifier; each entry is a list of overloads.

GetAncestor(type)

Return the closest ancestor of the given type found by walking the parent chain upwards.

Iterates the parent chain - starting at this model entity - upwards (toward the root of the model) until an ancestor of the requested type is found.

Parameters:

type (Type) – Class (type) of the ancestor to find.

Return type:

ModelEntity

Returns:

The closest ancestor of the requested type.

Raises:

AncestorNotFoundError – If the root of the model is reached without finding an ancestor of the requested type.

GetIdentifier(normalizedIdentifier)

Return the identifier as declared, for the model entity’s normalized identifier.

Parameters:

normalizedIdentifier (str) – The model entity’s normalized (lower case) identifier.

Return type:

str

Returns:

The identifier in its declared spelling.

classmethod GetMethodsWithAttributes(predicate=None)

Return the class’ methods that carry at least one matching attribute.

Parameters:

predicate (type[TAttr] | Iterable[type[TAttr]] | None) – Optional, an attribute class, an iterable of attribute classes, or None to accept every attribute.

Return type:

dict[Callable[..., Any], tuple[Attribute, ...]]

Returns:

Dictionary of methods and the matching attributes attached to them.

Raises:
  • ValueError – If an element of parameter ‘predicate’ is not a sub-class of Attribute.

  • ValueError – If parameter ‘predicate’ is neither an attribute class nor an iterable of those.

property HierarchyVertex: Vertex

Read-only property to access the corresponding hierarchy vertex (_hierarchyVertex).

The hierarchy vertex references this design unit by its value field.

Returns:

The corresponding hierarchy vertex.

property Identifier: str

Read-only property to access the model entity’s identifier (_identifier).

Returns:

Name of a model entity.

IndexDeclaredItems()

Index declared items listed in the concurrent declaration region.

Algorithm

  1. Clear all lookup tables and remove all declared items from _namespace. Interface items and imported items stay in the namespace.

  2. Iterate all declared items:

Indexing again yields the same lookup tables and namespace.

See also

pyVHDLModel.Design.IndexPackages()

Iterate all packages in the design and index declared items.

pyVHDLModel.Library.IndexPackages()

Iterate all packages in the library and index declared items.

pyVHDLModel.DesignUnit.Package._IndexOtherDeclaredItem()

Index the deferred constants and components of a package.

Raises:

UnhandledCriticalWarningError – If an identifier is declared twice in a declarative region and no WarningCollector collects the DuplicateDeclarationWarning.

Return type:

None

IndexStatements()

Index the instantiations, blocks and generate statements of this construct, and the statements nested in them.

Both lookup tables (_instantiations, _hierarchy) are cleared first, so indexing again yields the same lookup tables. Afterwards, the statement mutators (e.g. InsertStatement()) keep them up to date.

Return type:

None

InsertContextItem(index, contextItem)

Insert a context item at a position of the context clause.

The context item’s parent is set to this design unit. A library clause is also added to LibraryReferences, a use clause to PackageReferences and a context reference to ContextReferences, in the order of ContextItems. A context item may repeat an earlier one.

Parameters:
  • index (int) – Position, from 0 (first) to the number of context items (append). A negative index counts from the end, as for list.insert(): -1 inserts before the last context item.

  • contextItem (LibraryClause | UseClause | ContextReference) – The library clause, use clause or context reference to insert.

Raises:
Return type:

None

Attention

The mutator doesn’t update what Analyze() derived from the context items: the referenced libraries, packages and contexts (ReferencedLibraries, ReferencedPackages, ReferencedContexts), the namespace entries of a use clause, the edges of the dependency graph, and the references of the symbols. A design changed after its analysis needs a new analysis.

See also

AddContextItem()

→ Add a context item at the end of the context clause.

RemoveContextItem()

→ Remove a context item from the context clause.

InsertDeclaredItem(index, declaredItem)

Insert a declared item at a position of the declarative region.

The declared item’s parent is set to this declarative region. If the region is indexed, its identifiers are added to the region’s namespace and to the lookup table matching its kind.

An identifier is declared once per declarative region: interface items and declared items count, including those of the language construct sharing the declarative region (an entity and its architecture, a package and its body). Subprograms are overloadable: a subprogram may share its identifier with other subprograms. A protected type body may share its identifier with its protected type, a full type with its incomplete type declaration, and a constant with its deferred constant. Items imported into the namespace (e.g. by a use clause) are hidden.

Parameters:
  • index (int) – Position, from 0 (first) to the number of declared items (append). A negative index counts from the end, as for list.insert(): -1 inserts before the last declared item.

  • declaredItem (ModelEntity) – The declared item to insert.

Raises:
  • ValueError – If parameter ‘index’ is None.

  • TypeError – If parameter ‘index’ is not of type int.

  • ValueError – If parameter ‘index’ is out of range.

  • ValueError – If parameter ‘declaredItem’ is None.

  • TypeError – If parameter ‘declaredItem’ is not a declaration allowed in this declarative region.

  • AlreadyInDesignError – If parameter ‘declaredItem’ already has a parent.

  • DuplicateDeclarationError – If an existing declaration of the declarative region shares an identifier with the declared item.

Return type:

None

See also

AddDeclaredItem()

→ Add a declared item at the end of the declarative region.

InsertDeclaredItemBefore()

→ Insert a declared item before another declared item.

InsertDeclaredItemAfter()

→ Insert a declared item after another declared item.

RemoveDeclaredItem()

→ Remove a declared item from the declarative region.

MoveDeclaredItem()

→ Move a declared item to a position of the declarative region.

InsertDeclaredItemAfter(declaredItem, after)

Insert a declared item after another declared item.

The declared item’s parent is set to this declarative region. If the region is indexed, its identifiers are added to the region’s namespace and to the lookup table matching its kind.

Parameters:
  • declaredItem (ModelEntity) – The declared item to insert.

  • after (ModelEntity) – The declared item of this declarative region to insert after.

Raises:
  • ValueError – If parameter ‘declaredItem’ is None.

  • TypeError – If parameter ‘declaredItem’ is not a declaration allowed in this declarative region.

  • AlreadyInDesignError – If parameter ‘declaredItem’ already has a parent.

  • ValueError – If parameter ‘after’ is None.

  • TypeError – If parameter ‘after’ is not of type ModelEntity.

  • NotAChildError – If parameter ‘after’ is not a declared item of this declarative region.

  • DuplicateDeclarationError – If an existing declaration of the declarative region shares an identifier with the declared item.

Return type:

None

See also

InsertDeclaredItem()

→ Insert a declared item at a position of the declarative region.

InsertDeclaredItemBefore()

→ Insert a declared item before another declared item.

InsertDeclaredItemBefore(declaredItem, before)

Insert a declared item before another declared item.

The declared item’s parent is set to this declarative region. If the region is indexed, its identifiers are added to the region’s namespace and to the lookup table matching its kind.

Parameters:
  • declaredItem (ModelEntity) – The declared item to insert.

  • before (ModelEntity) – The declared item of this declarative region to insert before.

Raises:
  • ValueError – If parameter ‘declaredItem’ is None.

  • TypeError – If parameter ‘declaredItem’ is not a declaration allowed in this declarative region.

  • AlreadyInDesignError – If parameter ‘declaredItem’ already has a parent.

  • ValueError – If parameter ‘before’ is None.

  • TypeError – If parameter ‘before’ is not of type ModelEntity.

  • NotAChildError – If parameter ‘before’ is not a declared item of this declarative region.

  • DuplicateDeclarationError – If an existing declaration of the declarative region shares an identifier with the declared item.

Return type:

None

See also

InsertDeclaredItem()

→ Insert a declared item at a position of the declarative region.

InsertDeclaredItemAfter()

→ Insert a declared item after another declared item.

InsertStatement(index, statement)

Insert a concurrent statement at a position of this construct.

The statement’s parent is set to this construct: a process, block or generate statement connects its namespace to this construct’s namespace. If the statements are indexed (IndexStatements()), an instantiation, a block or a generate statement is added to the lookup table matching its kind, and the statements nested in it are indexed.

A statement label is declared in the declarative region of this construct: it may neither repeat another statement’s label, nor an identifier declared in the region, including the region an entity shares with its architectures. An unlabeled statement declares nothing.

Parameters:
  • index (int) – Position, from 0 (first) to the number of statements (append). A negative index counts from the end, as for list.insert(): -1 inserts before the last statement.

  • statement (ConcurrentStatement) – The concurrent statement to insert.

Raises:
  • ValueError – If parameter ‘index’ is None.

  • TypeError – If parameter ‘index’ is not of type int.

  • ValueError – If parameter ‘index’ is out of range.

  • ValueError – If parameter ‘statement’ is None.

  • TypeError – If parameter ‘statement’ is not of type ConcurrentStatement.

  • AlreadyInDesignError – If parameter ‘statement’ already has a parent.

  • DuplicateLabelError – If the declarative region already declares the statement’s label.

Return type:

None

See also

AddStatement()

→ Add a concurrent statement at the end of this construct.

InsertStatementBefore()

→ Insert a concurrent statement before another statement.

InsertStatementAfter()

→ Insert a concurrent statement after another statement.

RemoveStatement()

→ Remove a concurrent statement from this construct.

MoveStatement()

→ Move a concurrent statement to a position of this construct.

InsertStatementAfter(statement, after)

Insert a concurrent statement after another statement of this construct.

The statement’s parent is set to this construct. If the statements are indexed, an instantiation, a block or a generate statement is added to the lookup table matching its kind.

Parameters:
Raises:
  • ValueError – If parameter ‘statement’ is None.

  • TypeError – If parameter ‘statement’ is not of type ConcurrentStatement.

  • AlreadyInDesignError – If parameter ‘statement’ already has a parent.

  • ValueError – If parameter ‘after’ is None.

  • TypeError – If parameter ‘after’ is not of type ModelEntity.

  • NotAChildError – If parameter ‘after’ is not a statement of this construct.

  • DuplicateLabelError – If the declarative region already declares the statement’s label.

Return type:

None

See also

InsertStatement()

→ Insert a concurrent statement at a position of this construct.

InsertStatementBefore()

→ Insert a concurrent statement before another statement.

InsertStatementBefore(statement, before)

Insert a concurrent statement before another statement of this construct.

The statement’s parent is set to this construct. If the statements are indexed, an instantiation, a block or a generate statement is added to the lookup table matching its kind.

Parameters:
Raises:
  • ValueError – If parameter ‘statement’ is None.

  • TypeError – If parameter ‘statement’ is not of type ConcurrentStatement.

  • AlreadyInDesignError – If parameter ‘statement’ already has a parent.

  • ValueError – If parameter ‘before’ is None.

  • TypeError – If parameter ‘before’ is not of type ModelEntity.

  • NotAChildError – If parameter ‘before’ is not a statement of this construct.

  • DuplicateLabelError – If the declarative region already declares the statement’s label.

Return type:

None

See also

InsertStatement()

→ Insert a concurrent statement at a position of this construct.

InsertStatementAfter()

→ Insert a concurrent statement after another statement.

IsLibraryVisible(libraryIdentifier)

Check if the logical name of a library is visible in this design unit.

The name work is implicitly visible, the name std too, except in a context declaration. Every other name needs a library clause, also the real name of the working library. The library clause is searched in this design unit’s context clause, in the context clause of its primary unit, and in the contexts these reference, also in nested ones. The design unit must be in a library of a design.

Parameters:

libraryIdentifier (str) – The normalized identifier of the library.

Return type:

bool

Returns:

True, if the library’s name is visible.

property IsOverloadable: bool

Check if this model entity is an overloadable declaration: it may share its designator with other overloadable declarations.

Subprograms, enumeration literals and aliases, which may denote one of them, are overloadable; they override this property.

Returns:

True, if this model entity is an overloadable declaration.

IterateDeclarationRegions()

Iterate this declarative region and all declarative regions nested in it.

Nested regions are declarations (e.g. subprograms, generic subprograms, protected types, packages) and concurrent statements (blocks, processes, generate statements and their branches), each followed by the regions nested in it.

Return type:

Generator[DeclarativeRegionMixin]

Returns:

A generator to iterate the declarative regions, this region first.

IterateImplicitDeclarations()

Iterate the declarations this declaration implies.

An enumerated type implies its enumeration literals, a physical type its units; they override this method.

Return type:

Generator[tuple[str, ModelEntity]]

Returns:

A generator to iterate (normalized designator, declaration) pairs, in declaration order: none.

IterateTypeMarks(region)

Iterate the type marks of this declaration, each with the region and the place to look it up.

The place of a type mark is the declaration containing it. Declarations with type marks override this method, e.g. an object yields the type mark of its subtype indication, an array type its index and element subtypes.

Parameters:

region (DeclarativeRegionMixin) – The declarative region declaring this declaration.

Return type:

Generator[tuple[DeclarativeRegionMixin, ModelEntity, SubtypeSymbol]]

Returns:

A generator to iterate (region, place, type mark) tuples, in declaration order: none.

property Library: Library

Property to access the library (_parent).

Returns:

The library.

property LibraryReferences: list[LibraryClause]

Read-only property to access the sequence of library clauses (_libraryReferences).

Returns:

Sequence of library clauses.

LookupName(place, symbol, name, warningType)

Look up the declarations a simple name or an expanded name denotes at a place in this region.

A simple name is looked up at the place (Lookup()). An expanded name pkg.T or lib.pkg.T resolves its prefix: pkg to a package visible at the place, else to an enclosing declarative region of that name (e.g. the package or entity containing the place); lib.pkg by the library (work or a library whose name is visible in the design unit containing the place, IsLibraryVisible()) and the package’s name. Then the suffix is searched among the declarations of the package or region (FindDeclarations()).

A failure is reported as a warning of the given type, whose label names the kind of name in the message (e.g. Type mark); then no declaration is returned. A name, which is a part of the symbol’s name (e.g. the prefix s of the type mark s'subtype), is reported as a prefix of the symbol’s name.

Parameters:
  • place (ModelEntity) – The declaration containing the name.

  • symbol (Symbol) – The symbol containing the name.

  • name (Name) – The simple name or expanded name: the symbol’s name or a part of it.

  • warningType (type[UnresolvedNameWarning]) – The warning class reporting a failure.

Return type:

tuple[ModelEntity, ...]

Returns:

Tuple of the directly visible declarations, empty if none is.

Raises:

UnhandledCriticalWarningError – If the name isn’t visible, is ambiguous, or has a prefix, which isn’t a visible package or an enclosing region, and no WarningCollector collects the warning.

MoveDeclaredItem(declaredItem, index)

Move a declared item to a position of the declarative region.

The declared item stays a declared item of this declarative region: only the order of the declared items changes.

If the region is indexed, the lookup tables and the namespace follow the new order: a list of overloads (e.g. in Functions) follows the declaration order, and the namespace refers to the overload declared last. If another declaration shares an identifier with the declared item (e.g. a duplicate declaration read by a parser), the region is indexed again (IndexDeclaredItems()) after the move.

Parameters:
  • declaredItem (ModelEntity) – The declared item to move.

  • index (int) – Position of the declared item after the move, from 0 (first) to the number of declared items minus one (last). A negative index counts from the end, as for a list index: -1 moves the declared item to the end.

Raises:
  • ValueError – If parameter ‘declaredItem’ is None.

  • TypeError – If parameter ‘declaredItem’ is not of type ModelEntity.

  • NotAChildError – If parameter ‘declaredItem’ is not a declared item of this declarative region.

  • ValueError – If parameter ‘index’ is None.

  • TypeError – If parameter ‘index’ is not of type int.

  • ValueError – If parameter ‘index’ is out of range.

Return type:

None

See also

MoveDeclaredItemBefore()

→ Move a declared item before another declared item.

MoveDeclaredItemAfter()

→ Move a declared item after another declared item.

InsertDeclaredItem()

→ Insert a declared item at a position of the declarative region.

RemoveDeclaredItem()

→ Remove a declared item from the declarative region.

MoveDeclaredItemAfter(declaredItem, after)

Move a declared item after another declared item.

The declared item stays a declared item of this declarative region: only the order of the declared items changes, as for MoveDeclaredItem(). Moving a declared item after itself keeps it in place.

Parameters:
  • declaredItem (ModelEntity) – The declared item to move.

  • after (ModelEntity) – The declared item of this declarative region to move after.

Raises:
  • ValueError – If parameter ‘declaredItem’ is None.

  • TypeError – If parameter ‘declaredItem’ is not of type ModelEntity.

  • NotAChildError – If parameter ‘declaredItem’ is not a declared item of this declarative region.

  • ValueError – If parameter ‘after’ is None.

  • TypeError – If parameter ‘after’ is not of type ModelEntity.

  • NotAChildError – If parameter ‘after’ is not a declared item of this declarative region.

Return type:

None

See also

MoveDeclaredItem()

→ Move a declared item to a position of the declarative region.

MoveDeclaredItemBefore()

→ Move a declared item before another declared item.

MoveDeclaredItemBefore(declaredItem, before)

Move a declared item before another declared item.

The declared item stays a declared item of this declarative region: only the order of the declared items changes, as for MoveDeclaredItem(). Moving a declared item before itself keeps it in place.

Parameters:
  • declaredItem (ModelEntity) – The declared item to move.

  • before (ModelEntity) – The declared item of this declarative region to move before.

Raises:
  • ValueError – If parameter ‘declaredItem’ is None.

  • TypeError – If parameter ‘declaredItem’ is not of type ModelEntity.

  • NotAChildError – If parameter ‘declaredItem’ is not a declared item of this declarative region.

  • ValueError – If parameter ‘before’ is None.

  • TypeError – If parameter ‘before’ is not of type ModelEntity.

  • NotAChildError – If parameter ‘before’ is not a declared item of this declarative region.

Return type:

None

See also

MoveDeclaredItem()

→ Move a declared item to a position of the declarative region.

MoveDeclaredItemAfter()

→ Move a declared item after another declared item.

MoveStatement(statement, index)

Move a concurrent statement to a position of this construct.

The statement stays a statement of this construct: only the order of the statements changes. If the statements are indexed (IndexStatements()), the lookup tables are unchanged.

Parameters:
  • statement (ConcurrentStatement) – The concurrent statement to move.

  • index (int) – Position of the statement after the move, from 0 (first) to the number of statements minus one (last). A negative index counts from the end, as for a list index: -1 moves the statement to the end.

Raises:
  • ValueError – If parameter ‘statement’ is None.

  • TypeError – If parameter ‘statement’ is not of type ModelEntity.

  • NotAChildError – If parameter ‘statement’ is not a statement of this construct.

  • ValueError – If parameter ‘index’ is None.

  • TypeError – If parameter ‘index’ is not of type int.

  • ValueError – If parameter ‘index’ is out of range.

Return type:

None

See also

MoveStatementBefore()

→ Move a concurrent statement before another statement.

MoveStatementAfter()

→ Move a concurrent statement after another statement.

InsertStatement()

→ Insert a concurrent statement at a position of this construct.

RemoveStatement()

→ Remove a concurrent statement from this construct.

MoveStatementAfter(statement, after)

Move a concurrent statement after another statement of this construct.

The statement stays a statement of this construct: only the order of the statements changes, as for MoveStatement(). Moving a statement after itself keeps it in place.

Parameters:
Raises:
  • ValueError – If parameter ‘statement’ is None.

  • TypeError – If parameter ‘statement’ is not of type ModelEntity.

  • NotAChildError – If parameter ‘statement’ is not a statement of this construct.

  • ValueError – If parameter ‘after’ is None.

  • TypeError – If parameter ‘after’ is not of type ModelEntity.

  • NotAChildError – If parameter ‘after’ is not a statement of this construct.

Return type:

None

See also

MoveStatement()

→ Move a concurrent statement to a position of this construct.

MoveStatementBefore()

→ Move a concurrent statement before another statement.

MoveStatementBefore(statement, before)

Move a concurrent statement before another statement of this construct.

The statement stays a statement of this construct: only the order of the statements changes, as for MoveStatement(). Moving a statement before itself keeps it in place.

Parameters:
Raises:
  • ValueError – If parameter ‘statement’ is None.

  • TypeError – If parameter ‘statement’ is not of type ModelEntity.

  • NotAChildError – If parameter ‘statement’ is not a statement of this construct.

  • ValueError – If parameter ‘before’ is None.

  • TypeError – If parameter ‘before’ is not of type ModelEntity.

  • NotAChildError – If parameter ‘before’ is not a statement of this construct.

Return type:

None

See also

MoveStatement()

→ Move a concurrent statement to a position of this construct.

MoveStatementAfter()

→ Move a concurrent statement after another statement.

property NormalizedIdentifier: str

Read-only property to access the model entity’s normalized identifier (_normalizedIdentifier).

See also

Returns:

Normalized name of a model entity.

property PackageReferences: list[UseClause]

Read-only property to access the sequence of use clauses (_packageReferences).

Returns:

Sequence of use clauses.

property Parent: ModelEntity

Property to access the model entity’s parent element reference in a logical hierarchy (_parent).

Returns:

Reference to the parent entity.

property Position: Position

Cached read-only property to access an IIR’s position in source code (_position).

If _position is None, resolve the position object from _iirNode

Returns:

The IIR’s position in the source file.

Precedes(item, anchor, inclusive)

Check if an item precedes an anchor in this declarative region.

An item, which isn’t a declaration of this region (e.g. a use clause of the context clause), precedes every anchor.

Parameters:
  • item (ModelEntity | None) – The item in declaration order, or None for the implicit use clause.

  • anchor (ModelEntity) – A declaration of this region, e.g. the one containing the place of a lookup.

  • inclusive (bool) – True, if the anchor precedes itself, i.e. the place is nested inside the anchor.

Return type:

bool

Returns:

True, if the item precedes the anchor.

property Procedures: dict[str, list[Procedure]]

Read-only property to access the procedures (_procedures).

Returns:

Dictionary of procedures, indexed by normalized identifier; each entry is a list of overloads.

property ReferencedContexts: dict[str, Context]

Read-only property to access the referenced contexts (_referencedContexts).

Returns:

Dictionary of referenced contexts, indexed by normalized identifier.

property ReferencedLibraries: dict[str, Library]

Read-only property to access the referenced libraries (_referencedLibraries).

Returns:

Dictionary of referenced libraries, indexed by normalized identifier.

property ReferencedPackages: dict[str, Package]

Read-only property to access the referenced packages (_referencedPackages).

Returns:

Dictionary of referenced packages, indexed by normalized identifier.

RemoveContextItem(contextItem)

Remove a context item from the context clause.

The context item is detached: its parent is cleared, and it’s removed from ContextItems and from LibraryReferences, PackageReferences or ContextReferences. The context item itself is unchanged and can be added to another design unit, or inserted at another position.

Parameters:

contextItem (LibraryClause | UseClause | ContextReference) – The library clause, use clause or context reference to remove.

Raises:
Return type:

None

Attention

The mutator doesn’t update what Analyze() derived from the context items: the referenced libraries, packages and contexts (ReferencedLibraries, ReferencedPackages, ReferencedContexts), the namespace entries of a use clause, the edges of the dependency graph, and the references of the symbols. A design changed after its analysis needs a new analysis.

See also

AddContextItem()

→ Add a context item at the end of the context clause.

InsertContextItem()

→ Insert a context item at a position of the context clause.

RemoveDeclaredItem(declaredItem)

Remove a declared item from the declarative region.

The declared item is detached: its parent is cleared. If the region is indexed, the declared item’s identifiers are removed from the region’s namespace and from the lookup table matching its kind first; they are checked before anything is changed. The declared item itself is unchanged and can be added to another declarative region, or inserted at another position.

The namespace refers to the overload declared last: removing it, the namespace refers to the remaining overload declared last. If another declaration shares an identifier with the declared item (e.g. a duplicate declaration read by a parser), the region is indexed again (IndexDeclaredItems()) after the removal.

Parameters:

declaredItem (ModelEntity) – The declared item to remove.

Raises:
  • ValueError – If parameter ‘declaredItem’ is None.

  • TypeError – If parameter ‘declaredItem’ is not of type ModelEntity.

  • NotAChildError – If parameter ‘declaredItem’ is not a declared item of this declarative region.

  • NotInNamespaceError – If the region is indexed, and an identifier of the declared item isn’t declared in its namespace.

  • NotInNamespaceError – If the region is indexed, and an identifier of the declared item refers to another declaration, e.g. a duplicate declaration.

Return type:

None

See also

AddDeclaredItem()

→ Add a declared item at the end of the declarative region.

InsertDeclaredItem()

→ Insert a declared item at a position of the declarative region.

MoveDeclaredItem()

→ Move a declared item to a position of the declarative region.

RemoveStatement(statement)

Remove a concurrent statement from this construct.

The statement is detached: its parent is cleared. If the statements are indexed, an instantiation, a block or a generate statement is removed from its lookup table. The statement itself is unchanged and can be added to another construct, or inserted at another position. A removed process, block or generate statement keeps the link of its namespace to this construct’s namespace.

Parameters:

statement (ConcurrentStatement) – The concurrent statement to remove.

Raises:
  • ValueError – If parameter ‘statement’ is None.

  • TypeError – If parameter ‘statement’ is not of type ModelEntity.

  • NotAChildError – If parameter ‘statement’ is not a statement of this construct.

Return type:

None

See also

AddStatement()

→ Add a concurrent statement at the end of this construct.

InsertStatement()

→ Insert a concurrent statement at a position of this construct.

MoveStatement()

→ Move a concurrent statement to a position of this construct.

ResetReferences(designUnit, region)

Reset the references ResolveReferences() derived: the references of this declaration’s type marks.

A use clause, an alias and a subtype extend this method.

Parameters:
  • designUnit (DesignUnit) – The design unit containing this declaration.

  • region (DeclarativeRegionMixin) – The declarative region declaring this declaration.

Return type:

None

ResolveReferences(designUnit, region)

Resolve the references of this declaration: its type marks (IterateTypeMarks()).

Each type mark is resolved at its place by the region it is looked up in (ResolveTypeMark()). An incomplete type, an alias and a subtype extend this method.

Parameters:
  • designUnit (DesignUnit) – The design unit containing this declaration.

  • region (DeclarativeRegionMixin) – The declarative region declaring this declaration.

Raises:

UnhandledCriticalWarningError – If a type mark can’t be resolved, and no WarningCollector collects the UnresolvedTypeMarkWarning.

Return type:

None

ResolveTypeMark(place, symbol)

Resolve a type mark at its place in this region and set the symbol’s reference.

Algorithm

  1. Clear the symbol’s reference.

  2. Look up the type mark’s name (LookupName()).

  3. An alias of a type is replaced by the type its name references.

  4. If the declaration is a type, a subtype or a generic type, it becomes the symbol’s reference. A full type, which follows the place in the same region, is visible by its incomplete type declaration only to an access type.

An attribute name denoting a type (e.g. s'subtype, A'element) is resolved part by part (Denote()); the type it denotes becomes the symbol’s reference.

Parameters:
Raises:

UnhandledCriticalWarningError – If the type mark isn’t visible, is ambiguous, has a prefix, which isn’t a visible package, denotes no type, or denotes an incomplete type outside of an access type, and no WarningCollector collects the UnresolvedTypeMarkWarning.

Return type:

None

property SharedVariables: dict[str, SharedVariable]

Read-only property to access the shared variables (_sharedVariables).

Returns:

Dictionary of shared variables, indexed by normalized identifier.

property Signals: dict[str, Signal]

Read-only property to access the signals (_signals).

Returns:

Dictionary of signals, indexed by normalized identifier.

SplitDeclaredItem(declaredItem)

Split a declared item with an identifier list into one declaration per identifier.

The declared item keeps its first identifier. For every other identifier, a new declaration is created by its Copy() and inserted right after it, in list order; its parent is set to this declarative region. If the region is indexed, the namespace and lookup table entries of the other identifiers refer to the new declarations; they are checked before anything is changed. A declared item declaring one identifier is unchanged.

Parameters:

declaredItem (ModelEntity) – The declared item to split.

Return type:

tuple[ModelEntity, ...]

Returns:

Tuple of declarations, one per identifier in list order, starting with the split declared item.

Raises:
  • ValueError – If parameter ‘declaredItem’ is None.

  • TypeError – If parameter ‘declaredItem’ is not of type ModelEntity.

  • NotAChildError – If parameter ‘declaredItem’ is not a declared item of this declarative region.

  • NotInNamespaceError – If the region is indexed, and an identifier of the declared item refers to another declaration, e.g. a duplicate declaration.

See also

Split()

→ Split a declaration with an identifier list.

RemoveDeclaredItem()

→ Remove a declared item from the declarative region.

property Statements: list[ConcurrentStatement]

Read-only property to access the statements (_statements).

Returns:

List of statements.

property Subtypes: dict[str, Subtype]

Read-only property to access the subtypes (_subtypes).

Returns:

Dictionary of subtypes, indexed by normalized identifier.

property Types: dict[str, FullType]

Read-only property to access the types (_types).

Returns:

Dictionary of types, indexed by normalized identifier.

Visit(visitor)[source]

Walk this architecture, its context clause, its entity, its declared items and its statements with a visitor.

Parameters:

visitor (Visitor) – The visitor receiving the events.

Return type:

None

_AddOverloadToNamespace(item)

Add a function or procedure to the namespace, if it’s the overload declared last.

The namespace keeps one entry per identifier: the overload declared last, as after IndexDeclaredItems(), which adds interface items first, then declared items (_Declarations()).

Parameters:

item (NamedEntityMixin | MultipleNamedEntityMixin) – The function or procedure, already an interface item or declared item of this region.

Return type:

None

_AddToNamespace(element)

Add an element’s identifiers to this region’s namespace.

Nothing is added to a region not indexed yet: IndexDeclaredItems() adds the element later. A generic subprogram is an overload (_AddOverloadToNamespace()).

Parameters:

element (NamedEntityMixin | MultipleNamedEntityMixin) – The named element to add, e.g. an interface item.

Return type:

None

_CONTINUES_PARENT_REGION: ClassVar[bool] = True

An architecture continues its entity’s declarative region.

_ClashingDeclarations(item)

Return the declarations sharing an identifier with the given item, which may not share it.

The declarations (_Declarations()) and the labeled statements (_Labels()) of this declarative region and of the language constructs sharing it (_SharedRegions()) are searched: a statement label is declared implicitly. Items imported into the namespace (e.g. by a use clause) are no declarations.

Parameters:

item (ModelEntity) – The new declaration, or the new labeled statement.

Return type:

tuple[ModelEntity, ...]

Returns:

Tuple of clashing declarations, interface items first, then declared items in declaration order, then labeled statements.

_ConnectParentNamespace(parent)

Connect this region’s namespace to the namespace of the enclosing declarative region.

A declaration of this region then hides a same-named declaration of the enclosing region. A parent, which isn’t a declarative region (e.g. a subprogram of an interface list), has no namespace to connect to.

Parameters:

parent (ModelEntity) – The new parent of this region.

Return type:

None

_ContextClauseUnits()[source]

Return the design units whose context clause applies to this architecture.

Return type:

tuple[DesignUnit, ...]

Returns:

Tuple of this architecture and its entity, if linked.

_DECLARED_ITEM_TYPES = (<class 'pyVHDLModel.Type.BaseType'>, <class 'pyVHDLModel.Subprogram.Subprogram'>, <class 'pyVHDLModel.DesignUnit.Package'>, <class 'pyVHDLModel.DesignUnit.PackageBody'>, <class 'pyVHDLModel.Object.Constant'>, <class 'pyVHDLModel.Object.Signal'>, <class 'pyVHDLModel.Object.SharedVariable'>, <class 'pyVHDLModel.Object.File'>, <class 'pyVHDLModel.Declaration.Alias'>, <class 'pyVHDLModel.DesignUnit.Component'>, <class 'pyVHDLModel.Declaration.Attribute'>, <class 'pyVHDLModel.Declaration.AttributeSpecification'>, <class 'pyVHDLModel.Configuration.ComponentConfiguration'>, <class 'pyVHDLModel.Interface.ModeViewDeclaration'>, <class 'pyVHDLModel.DesignUnit.UseClause'>, <class 'pyVHDLModel.PSLModel.PSLEntity'>)

Accepted classes of declared items (pyVHDLModel).

_Declarations()

Return all declarations of this declarative region.

A host class with interface items extends the list by its interface items, listed first.

Return type:

tuple[ModelEntity, ...]

Returns:

Tuple of declarations: the declared items, in declaration order.

_DeclaredItemsSharingIdentifiers(declaredItem)

Return the other declared items of this region sharing an identifier with the given declared item.

Parameters:

declaredItem (ModelEntity) – The declared item.

Return type:

list[ModelEntity]

Returns:

List of declared items, in declaration order.

_END_KEYWORDS: ClassVar[tuple[ReservedWord, ...]] = (ReservedWord.Architecture,)

Reserved words after end.

_END_KEYWORDS_OPTIONAL: ClassVar[bool] = True

The reserved words after end are optional.

_IMPLICIT_LIBRARIES = ('work', 'std')

Library names visible without a library clause.

_IndexDeclaredItem(item)

Add a declared item to the namespace and to the lookup table matching its kind.

Parameters:

item (ModelEntity) – The declared item.

Return type:

None

_IndexOtherDeclaredItem(item)

Hook for declared items the region doesn’t handle itself. Derived classes may override it.

An alias, an attribute declaration and a package (also a package instantiation) declared in the region are added to the namespace, without a lookup table.

Parameters:

item (ModelEntity) – The declared item.

Return type:

None

_IndexOverload(item)

Add an inserted function or procedure to its lookup table and to the namespace.

The list of overloads follows the declaration order. The namespace is updated by _AddOverloadToNamespace().

Parameters:

item (NamedEntityMixin | MultipleNamedEntityMixin) – The inserted function or procedure.

Return type:

None

_IndexStatement(statement)

Add an instantiation, a block or a generate statement to its lookup table, and index the statements nested in it.

Parameters:

statement (ConcurrentStatement) – The concurrent statement of this construct.

Return type:

None

_IterateStatementRegions()

Iterate the declarative regions of the concurrent statements, each followed by the regions nested in it.

Blocks, processes and for-generate statements are declarative regions; an if-generate statement has one per branch, a case-generate statement one per alternative.

Return type:

Generator[DeclarativeRegionMixin]

Returns:

A generator to iterate the declarative regions, in statement order.

_Labels()

Return the labeled statements, whose labels are declared in this construct’s declarative region.

A statement nested in a block or generate statement is declared in that statement’s declarative region.

Return type:

tuple[ConcurrentStatement, ...]

Returns:

Tuple of labeled statements, in statement order.

_MayShareIdentifier(item, existing)

Check if two declarations may share an identifier in one declarative region.

Subprograms are overloadable. A protected type body completes its protected type, a full type completes its incomplete type, and a constant completes its deferred constant.

Parameters:
Return type:

bool

Returns:

True, if both declarations may share an identifier.

_RemoveDeclaredItemEntries(lookupTable, item)

Remove a declared item’s entries from a lookup table and from the namespace.

Every identifier is checked before anything is removed.

Parameters:
Raises:
  • NotInNamespaceError – If an identifier of the declared item isn’t declared in the namespace.

  • NotInNamespaceError – If an identifier of the declared item refers to another element, e.g. a duplicate declaration.

Return type:

None

_RemoveDeclaredItemsFromNamespace()

Remove all declared items of this region from its namespace.

Interface items of this region and items imported from elsewhere (e.g. by a use clause) are kept.

Return type:

None

_RemoveFromNamespace(element)

Remove an element’s identifiers from this region’s namespace.

Nothing is removed from a region not indexed yet, as its namespace doesn’t contain the element. A generic subprogram is an overload (_RemoveOverloadFromNamespace()).

Parameters:

element (NamedEntityMixin | MultipleNamedEntityMixin) – The named element to remove, e.g. an interface item.

Raises:
  • NotInNamespaceError – If the region is indexed, and an identifier of the element isn’t declared in the namespace.

  • NotInNamespaceError – If the region is indexed, and an identifier of the element refers to another element, e.g. a duplicate declaration.

Return type:

None

_RemoveOverloadFromNamespace(item)

Remove a function or procedure from the namespace.

Removing the overload the namespace refers to, the namespace refers to the remaining overload declared last (_Declarations()), or the identifier is removed, if no overload remains. Removing another overload leaves the namespace unchanged. The namespace is checked before it’s changed.

Parameters:

item (NamedEntityMixin | MultipleNamedEntityMixin) – The function or procedure, still an interface item or declared item of this region.

Raises:
  • NotInNamespaceError – If the identifier isn’t declared in the namespace.

  • NotInNamespaceError – If the identifier refers to an element, which is no overload, e.g. a duplicate declaration.

Return type:

None

_SharedRegions()[source]

Return the other language constructs forming one declarative region with this architecture.

Return type:

tuple[ConcurrentDeclarationRegionMixin, ...]

Returns:

Tuple of the entity, if linked.

_UnindexDeclaredItem(item)

Remove a declared item from the namespace and from the lookup table matching its kind.

Parameters:

item (ModelEntity) – The declared item.

Return type:

None

_UnindexOtherDeclaredItem(item)

Hook to remove declared items the region doesn’t handle itself. Derived classes may override it.

An alias, an attribute declaration and a package are removed from the namespace.

Parameters:

item (ModelEntity) – The declared item.

Raises:

NotInNamespaceError – If the item is an alias, an attribute declaration or a package, which isn’t declared in the namespace.

Return type:

None

_UnindexOverload(item)

Remove a function or procedure from its lookup table and from the namespace.

The namespace is updated first, by _RemoveOverloadFromNamespace().

Parameters:

item (NamedEntityMixin | MultipleNamedEntityMixin) – The function or procedure to remove, still a declared item of this region.

Raises:
  • NotInNamespaceError – If the identifier isn’t declared in the namespace.

  • NotInNamespaceError – If the identifier refers to an element, which is no overload, e.g. a duplicate declaration.

Return type:

None

_UnindexStatement(statement)

Remove an instantiation, a block or a generate statement from its lookup table.

Parameters:

statement (ConcurrentStatement) – The concurrent statement of this construct.

Return type:

None

_VisitContextClause(visitor)

Walk the context clause, i.e. the context items preceding the design unit, with a visitor.

The context clause is reported, even if it has no context items.

Parameters:

visitor (Visitor) – The visitor receiving the events.

Return type:

None

_VisitDeclaredItems(visitor)

Walk the declared items in declaration order with a visitor.

Parameters:

visitor (Visitor) – The visitor receiving the events.

Return type:

None

_VisitStatements(visitor)

Walk the concurrent statements in statement order with a visitor.

Parameters:

visitor (Visitor) – The visitor receiving the events.

Return type:

None

__getstate__()

Return the object’s state for pickling, collecting every slot of the class hierarchy.

Return type:

dict[str, Any]

Returns:

Dictionary of slot names and their values.

Raises:

ExtendedTypeError – If a slot was never assigned, so it has no value to serialize.

__new__(**kwargs)
__repr__()[source]

Formats a representation of the architecture declaration.

Format: mylib.myEntity(rtl)

Return type:

str

Returns:

String representation of the architecture declaration.

__setstate__(state)

Restore the object’s state from unpickling, requiring exactly the slots of the class hierarchy.

Parameters:

state (dict[str, Any]) – Dictionary of slot names and their values.

Raises:

ExtendedTypeError – If the given state misses a slot or carries an unexpected one.

Return type:

None

__str__()[source]

Formats the architecture declaration.

Format: Architecture: mylib.myEntity(rtl)

Return type:

str

Returns:

Formatted architecture declaration.

_allowBlackbox

Allow blackboxes for components; None inherits the parent’s setting.

_areDeclaredItemsIndexed

True if IndexDeclaredItems() filled the namespace.

_areStatementsIndexed

True if IndexStatements() filled _instantiations and _hierarchy.

_components

Dictionary of all components declared in this concurrent declaration region.

_constants

Dictionary of all constants declared in this concurrent declaration region.

_contextItems

List of all context items (library, use and context clauses).

_contextReferences

List of context clauses.

_declaredItems

List of all declared items in this concurrent declaration region.

_dependencyVertex

Reference to the vertex in the dependency graph representing the design unit.
This reference is set by CreateDependencyGraph().

_document

The VHDL library, the design unit was analyzed into.

_documentation

The associated documentation of a model entity.

_entity: EntitySymbol

Reference to the entity this architecture implements.

_files

Dictionary of all files declared in this concurrent declaration region.

_functions

Dictionary of all functions declared in this concurrent declaration region, indexed by name; each entry is a list of overloads.

_hierarchy

All elements creating a hierarchy level (blocks and generates), in declaration order.

_hierarchyVertex

The vertex in the hierarchy graph

_identifier

The identifier of a model entity.

_instantiations

All instantiations, indexed by label.

_libraryReferences

List of library clauses.

_namespace

The namespace of this concurrent declaration region.

_normalizedIdentifier

The normalized (lower case) identifier of a model entity.

_packageReferences

List of use clauses.

_parent

Reference to a parent entity in the logical model hierarchy.

_procedures

Dictionary of all procedures declared in this concurrent declaration region, indexed by name; each entry is a list of overloads.

_referencedContexts

Referenced contexts based on explicit context references or implicit inheritance

_referencedLibraries

Referenced libraries based on explicit library clauses or implicit inheritance

_referencedPackages

Referenced packages based on explicit use clauses or implicit inheritance

_sharedVariables

Dictionary of all shared variables declared in this concurrent declaration region.

_signals

Dictionary of all signals declared in this concurrent declaration region.

_statements

List of all concurrent statements in this construct.

_subtypes

Dictionary of all subtypes declared in this concurrent declaration region.

_types

Dictionary of all types declared in this concurrent declaration region.

class pyGHDL.dom.DesignUnit.Component(node, identifier, genericItems=None, portItems=None, documentation=None)[source]

This class implements a pyGHDL.dom object derived from pyVHDLModel.DesignUnit.Component.

Represents a component declaration.

A component declaration is a declarative region (IEEE Std 1076-2008, 12.1): its generics and ports share one namespace, nested in the namespace of the declarative region declaring the component. A component has no declarative part, so it has no declared items and no mutators for them.

Example

component ent is
  -- ...
end component;

Inheritance

Inheritance diagram of Component

Parameters:
  • node (Iir)

  • identifier (str)

  • genericItems (Iterable[GenericInterfaceItemMixin])

  • portItems (Iterable[PortInterfaceItemMixin])

  • documentation (str)

__init__(node, identifier, genericItems=None, portItems=None, documentation=None)[source]

Initializes a component declaration.

Parameters:
  • node (Iir) – The IIR node this object was translated from.

  • identifier (str) – The component’s identifier.

  • genericItems (Iterable[GenericInterfaceItemMixin]) – Optional, list of all generics of this component, in declaration order.

  • portItems (Iterable[PortInterfaceItemMixin]) – Optional, list of all ports of this component, in declaration order.

  • documentation (str) – Optional, the documentation comment associated with this declaration.

Return type:

None

classmethod parse(componentNode)[source]

Translates the IIR node of the component declaration to a Component.

Parameters:

componentNode (Iir) – The IIR node of the component declaration.

Returns:

The translated component declaration.

_iirNode: Iir

The IIR node in libghdl’s tree this DOM object was translated from.

_position: Position

The IIR node’s position in the source file, resolved on first access and then cached.

AddGenericItem(genericItem, group=None)

Add a generic at the end of the generic clause, or at the end of a generic group.

The generic’s parent is set to this language construct, and its identifiers are added to the language construct’s namespace, if it has one. Without a generic group, the generic joins the last generic group, or forms a new unnamed generic group if there are no generics.

Parameters:
  • genericItem (GenericInterfaceItemMixin) – The generic to add.

  • group (GenericGroup | None) – Optional, the generic group of this language construct to add the generic to, at its end. Default: None, the end of the generic clause.

Raises:
  • ValueError – If parameter ‘genericItem’ is None.

  • TypeError – If parameter ‘genericItem’ is not of type GenericInterfaceItemMixin.

  • AlreadyInDesignError – If parameter ‘genericItem’ already has a parent.

  • TypeError – If parameter ‘group’ is not of type GenericGroup.

  • NotAChildError – If parameter ‘group’ is not a generic group of this language construct.

  • DuplicateGenericError – If an existing declaration of the language construct shares an identifier with the generic.

Return type:

None

See also

InsertGenericItem()

→ Insert a generic at a position of the generic clause.

RemoveGenericItem()

→ Remove a generic from the generic clause.

AddPortItem(portItem, group=None)

Add a port at the end of the port clause, or at the end of a port group.

The port’s parent is set to this language construct, and its identifiers are added to the language construct’s namespace, if it has one. Without a port group, the port joins the last port group, or forms a new unnamed port group if there are no ports.

Parameters:
  • portItem (PortSignalInterfaceItem) – The port to add.

  • group (PortGroup | None) – Optional, the port group of this language construct to add the port to, at its end. Default: None, the end of the port clause.

Raises:
  • ValueError – If parameter ‘portItem’ is None.

  • TypeError – If parameter ‘portItem’ is not of type PortSignalInterfaceItem.

  • AlreadyInDesignError – If parameter ‘portItem’ already has a parent.

  • TypeError – If parameter ‘group’ is not of type PortGroup.

  • NotAChildError – If parameter ‘group’ is not a port group of this language construct.

  • DuplicatePortError – If an existing declaration of the language construct shares an identifier with the port.

Return type:

None

See also

InsertPortItem()

→ Insert a port at a position of the port clause.

RemovePortItem()

→ Remove a port from the port clause.

property AllowBlackbox: bool

Property to return whether a design supports blackboxes, inherited from the parent if not set locally (_allowBlackbox).

Algorithm

  1. If allow blackbox property is locally set, return the local value,

  2. Otherwise, return allow blackbox value from parent object.

Returns:

True, if blackboxes are allowed.

Raises:

AllowBlackboxNotSetError – If neither a local value is set nor a parent object is available to inherit the value from.

Setter accepts:

bool | None

DenoteBy(name, region, place, symbol)

Determine the model entity a name denoting this declaration denotes, as a part of a type mark (Name.Denote).

A declaration, which a name in a type mark can denote, overrides this method and returns itself: an object, an alias, a type or subtype, a record element, a package. Any other declaration (e.g. a subprogram) is reported.

Parameters:
  • name (Name) – The name denoting this declaration, a part of the type mark.

  • region (DeclarativeRegionMixin) – The declarative region containing the type mark.

  • place (ModelEntity) – The declaration containing the type mark.

  • symbol (Symbol) – The type mark.

Return type:

ModelEntity | None

Returns:

None, as a name in a type mark can’t denote this declaration (reported as a warning).

Raises:

UnhandledCriticalWarningError – Always, if no WarningCollector collects the UnresolvedTypeMarkWarning.

property Documentation: str | None

Read-only property to access the model entity’s documentation (_documentation).

Returns:

Associated documentation of a model entity.

property Entity: Entity | None

Property to access the entity (_entity).

Returns:

The entity, or None if not set.

Setter accepts:

Entity

property GenericCount: int

Read-only property to return the number of generics declared by _genericItems.

A generic constant item with several identifiers (generic (A, B : natural)) declares several generics.

Returns:

The number of generics.

property GenericGroups: list[GenericGroup]

Read-only property to access the generic groups (_genericGroups).

The generic groups partition the generic clause: concatenated in order, they list every generic exactly once, in declaration order.

Returns:

List of generic groups, in declaration order.

property GenericItems: list[GenericInterfaceItemMixin]

Read-only property to access the generic items (_genericItems).

Returns:

List of generic items.

GetAncestor(type)

Return the closest ancestor of the given type found by walking the parent chain upwards.

Iterates the parent chain - starting at this model entity - upwards (toward the root of the model) until an ancestor of the requested type is found.

Parameters:

type (Type) – Class (type) of the ancestor to find.

Return type:

ModelEntity

Returns:

The closest ancestor of the requested type.

Raises:

AncestorNotFoundError – If the root of the model is reached without finding an ancestor of the requested type.

GetIdentifier(normalizedIdentifier)

Return the identifier as declared, for the model entity’s normalized identifier.

Parameters:

normalizedIdentifier (str) – The model entity’s normalized (lower case) identifier.

Return type:

str

Returns:

The identifier in its declared spelling.

classmethod GetMethodsWithAttributes(predicate=None)

Return the class’ methods that carry at least one matching attribute.

Parameters:

predicate (type[TAttr] | Iterable[type[TAttr]] | None) – Optional, an attribute class, an iterable of attribute classes, or None to accept every attribute.

Return type:

dict[Callable[..., Any], tuple[Attribute, ...]]

Returns:

Dictionary of methods and the matching attributes attached to them.

Raises:
  • ValueError – If an element of parameter ‘predicate’ is not a sub-class of Attribute.

  • ValueError – If parameter ‘predicate’ is neither an attribute class nor an iterable of those.

property Identifier: str

Read-only property to access the model entity’s identifier (_identifier).

Returns:

Name of a model entity.

IndexDeclaredItems()[source]

Index the generics and ports of this component in its namespace.

Raises:

UnhandledCriticalWarningError – If an identifier is declared twice in the component and no WarningCollector collects the DuplicateDeclarationWarning.

Return type:

None

InsertGenericItem(index, genericItem, group=None)

Insert a generic at a position of the generic clause.

The generic’s parent is set to this language construct, and its identifiers are added to the language construct’s namespace, if it has one.

Without a generic group, the generic joins the generic group of the generic before index; at index 0, the generic group of the first generic. If there are no generics, the generic forms a new unnamed generic group. A generic group given must contain index or end at it, so the generic groups stay contiguous.

Parameters:
  • index (int) – Position, from 0 (first) to the length of GenericItems (append). A negative index counts from the end, as for list.insert(): -1 inserts before the last generic.

  • genericItem (GenericInterfaceItemMixin) – The generic to insert.

  • group (GenericGroup | None) – Optional, the generic group of this language construct to insert the generic into. Default: None, the generic group of the generic before index.

Raises:
  • ValueError – If parameter ‘index’ is None.

  • TypeError – If parameter ‘index’ is not of type int.

  • ValueError – If parameter ‘index’ is out of range.

  • ValueError – If parameter ‘genericItem’ is None.

  • TypeError – If parameter ‘genericItem’ is not of type GenericInterfaceItemMixin.

  • AlreadyInDesignError – If parameter ‘genericItem’ already has a parent.

  • TypeError – If parameter ‘group’ is not of type GenericGroup.

  • NotAChildError – If parameter ‘group’ is not a generic group of this language construct.

  • ValueError – If parameter ‘group’ neither contains nor ends at parameter ‘index’.

  • DuplicateGenericError – If an existing declaration of the language construct shares an identifier with the generic.

Return type:

None

See also

AddGenericItem()

→ Add a generic at the end of the generic clause.

RemoveGenericItem()

→ Remove a generic from the generic clause.

MoveGenericItem()

→ Move a generic to a position of the generic clause.

InsertPortItem(index, portItem, group=None)

Insert a port at a position of the port clause.

The port’s parent is set to this language construct, and its identifiers are added to the language construct’s namespace, if it has one.

Without a port group, the port joins the port group of the port before index; at index 0, the port group of the first port. If there are no ports, the port forms a new unnamed port group. A port group given must contain index or end at it, so the port groups stay contiguous.

Parameters:
  • index (int) – Position, from 0 (first) to the length of PortItems (append). A negative index counts from the end, as for list.insert(): -1 inserts before the last port.

  • portItem (PortSignalInterfaceItem) – The port to insert.

  • group (PortGroup | None) – Optional, the port group of this language construct to insert the port into. Default: None, the port group of the port before index.

Raises:
  • ValueError – If parameter ‘index’ is None.

  • TypeError – If parameter ‘index’ is not of type int.

  • ValueError – If parameter ‘index’ is out of range.

  • ValueError – If parameter ‘portItem’ is None.

  • TypeError – If parameter ‘portItem’ is not of type PortSignalInterfaceItem.

  • AlreadyInDesignError – If parameter ‘portItem’ already has a parent.

  • TypeError – If parameter ‘group’ is not of type PortGroup.

  • NotAChildError – If parameter ‘group’ is not a port group of this language construct.

  • ValueError – If parameter ‘group’ neither contains nor ends at parameter ‘index’.

  • DuplicatePortError – If an existing declaration of the language construct shares an identifier with the port.

Return type:

None

See also

AddPortItem()

→ Add a port at the end of the port clause.

RemovePortItem()

→ Remove a port from the port clause.

MovePortItem()

→ Move a port to a position of the port clause.

property IsBlackbox: bool | None

Check if the component is a blackbox (_isBlackbox).

If components were not linked to matching entities, this property returns None.

Returns:

True, if the component is a blackbox; False, if it is not; None, if components were not linked to entities yet.

property IsOverloadable: bool

Check if this model entity is an overloadable declaration: it may share its designator with other overloadable declarations.

Subprograms, enumeration literals and aliases, which may denote one of them, are overloadable; they override this property.

Returns:

True, if this model entity is an overloadable declaration.

IterateDeclarationRegions()

Iterate this declarative region and all declarative regions nested in it.

Nested regions are declarations (e.g. subprograms, generic subprograms, protected types, packages) and concurrent statements (blocks, processes, generate statements and their branches), each followed by the regions nested in it.

Return type:

Generator[DeclarativeRegionMixin]

Returns:

A generator to iterate the declarative regions, this region first.

IterateImplicitDeclarations()

Iterate the declarations this declaration implies.

An enumerated type implies its enumeration literals, a physical type its units; they override this method.

Return type:

Generator[tuple[str, ModelEntity]]

Returns:

A generator to iterate (normalized designator, declaration) pairs, in declaration order: none.

IterateSingleGenericDeclarations(predicate=None)

Iterate all generics per declared identifier, in declaration order.

A generic constant yields one single declaration per identifier: generic (A, B : positive) yields two. A generic type, subprogram or package declares exactly one identifier and is yielded itself.

Parameters:

predicate (Callable[[SingleGenericDeclarationMixin | GenericInterfaceItemMixin], bool] | None) – Optional, filter function to select the yielded generics. Default: all.

Return type:

Generator[SingleGenericDeclarationMixin | GenericInterfaceItemMixin]

Returns:

A generator to iterate all (selected) generics.

IterateSinglePortDeclarations(predicate=None)

Iterate all ports per declared identifier, in declaration order.

A port yields one single declaration per identifier: port (a, b : in bit) yields two.

Parameters:

predicate (Callable[[SinglePortDeclarationMixin], bool] | None) – Optional, filter function to select the yielded ports. Default: all.

Return type:

Generator[SinglePortDeclarationMixin]

Returns:

A generator to iterate all (selected) ports.

IterateTypeMarks(region)

Iterate the type marks of this declaration, each with the region and the place to look it up.

The place of a type mark is the declaration containing it. Declarations with type marks override this method, e.g. an object yields the type mark of its subtype indication, an array type its index and element subtypes.

Parameters:

region (DeclarativeRegionMixin) – The declarative region declaring this declaration.

Return type:

Generator[tuple[DeclarativeRegionMixin, ModelEntity, SubtypeSymbol]]

Returns:

A generator to iterate (region, place, type mark) tuples, in declaration order: none.

LookupName(place, symbol, name, warningType)

Look up the declarations a simple name or an expanded name denotes at a place in this region.

A simple name is looked up at the place (Lookup()). An expanded name pkg.T or lib.pkg.T resolves its prefix: pkg to a package visible at the place, else to an enclosing declarative region of that name (e.g. the package or entity containing the place); lib.pkg by the library (work or a library whose name is visible in the design unit containing the place, IsLibraryVisible()) and the package’s name. Then the suffix is searched among the declarations of the package or region (FindDeclarations()).

A failure is reported as a warning of the given type, whose label names the kind of name in the message (e.g. Type mark); then no declaration is returned. A name, which is a part of the symbol’s name (e.g. the prefix s of the type mark s'subtype), is reported as a prefix of the symbol’s name.

Parameters:
  • place (ModelEntity) – The declaration containing the name.

  • symbol (Symbol) – The symbol containing the name.

  • name (Name) – The simple name or expanded name: the symbol’s name or a part of it.

  • warningType (type[UnresolvedNameWarning]) – The warning class reporting a failure.

Return type:

tuple[ModelEntity, ...]

Returns:

Tuple of the directly visible declarations, empty if none is.

Raises:

UnhandledCriticalWarningError – If the name isn’t visible, is ambiguous, or has a prefix, which isn’t a visible package or an enclosing region, and no WarningCollector collects the warning.

MoveGenericItem(genericItem, index)

Move a generic to a position of the generic clause.

The generic stays a generic of this language construct: only the order of the generic clause changes. A generic subprogram is an overload: if the language construct’s namespace is indexed, it refers to the overload declared last afterwards.

The generic leaves its generic group, like RemoveGenericItem(), and joins a generic group, like InsertGenericItem() without a generic group: the generic group of the generic before its new position; at index 0, the generic group of the first generic. A move to the generic’s current position changes nothing.

Parameters:
  • genericItem (GenericInterfaceItemMixin) – The generic to move.

  • index (int) – Position of the generic after the move, from 0 (first) to the length of GenericItems minus one (last). A negative index counts from the end, as for a list index: -1 moves the generic to the end.

Raises:
  • ValueError – If parameter ‘genericItem’ is None.

  • TypeError – If parameter ‘genericItem’ is not of type GenericInterfaceItemMixin.

  • NotAChildError – If parameter ‘genericItem’ is not a generic of this language construct.

  • ValueError – If parameter ‘index’ is None.

  • TypeError – If parameter ‘index’ is not of type int.

  • ValueError – If parameter ‘index’ is out of range.

  • NotInNamespaceError – If the namespace is indexed, and the identifier of a generic subprogram refers to an element, which is no overload, e.g. a duplicate declaration.

Return type:

None

See also

InsertGenericItem()

→ Insert a generic at a position of the generic clause.

RemoveGenericItem()

→ Remove a generic from the generic clause.

MovePortItem(portItem, index)

Move a port to a position of the port clause.

The port stays a port of this language construct: only the order of the port clause changes. The port leaves its port group, like RemovePortItem(), and joins a port group, like InsertPortItem() without a port group: the port group of the port before its new position; at index 0, the port group of the first port. A move to the port’s current position changes nothing.

Parameters:
  • portItem (PortSignalInterfaceItem) – The port to move.

  • index (int) – Position of the port after the move, from 0 (first) to the length of PortItems minus one (last). A negative index counts from the end, as for a list index: -1 moves the port to the end.

Raises:
  • ValueError – If parameter ‘portItem’ is None.

  • TypeError – If parameter ‘portItem’ is not of type PortSignalInterfaceItem.

  • NotAChildError – If parameter ‘portItem’ is not a port of this language construct.

  • ValueError – If parameter ‘index’ is None.

  • TypeError – If parameter ‘index’ is not of type int.

  • ValueError – If parameter ‘index’ is out of range.

Return type:

None

See also

InsertPortItem()

→ Insert a port at a position of the port clause.

RemovePortItem()

→ Remove a port from the port clause.

property NormalizedIdentifier: str

Read-only property to access the model entity’s normalized identifier (_normalizedIdentifier).

See also

Returns:

Normalized name of a model entity.

property Parent: ModelEntity

Property to access the model entity’s parent element reference in a logical hierarchy (_parent).

Returns:

Reference to the parent entity.

property PortCount: int

Read-only property to return the number of ports declared by _portItems.

A port item with several identifiers (port (a, b : in bit)) declares several ports.

Returns:

The number of ports.

property PortGroups: list[PortGroup]

Read-only property to access the port groups (_portGroups).

The port groups partition the port clause: concatenated in order, they list every port exactly once, in declaration order.

Returns:

List of port groups, in declaration order.

property PortItems: list[PortInterfaceItemMixin]

Read-only property to access the port items (_portItems).

Returns:

List of port items.

property Position: Position

Cached read-only property to access an IIR’s position in source code (_position).

If _position is None, resolve the position object from _iirNode

Returns:

The IIR’s position in the source file.

Precedes(item, anchor, inclusive)

Check if an item precedes an anchor in this declarative region.

An item, which isn’t a declaration of this region (e.g. a use clause of the context clause), precedes every anchor.

Parameters:
  • item (ModelEntity | None) – The item in declaration order, or None for the implicit use clause.

  • anchor (ModelEntity) – A declaration of this region, e.g. the one containing the place of a lookup.

  • inclusive (bool) – True, if the anchor precedes itself, i.e. the place is nested inside the anchor.

Return type:

bool

Returns:

True, if the item precedes the anchor.

RemoveGenericItem(genericItem)

Remove a generic from the generic clause.

The generic is detached: its parent and generic group are cleared and its identifiers are removed from the language construct’s namespace, if it has one. A generic group, which becomes empty, is removed from GenericGroups and its parent is cleared. The generic itself is unchanged and can be added to another language construct, or inserted at another position.

Parameters:

genericItem (GenericInterfaceItemMixin) – The generic to remove.

Raises:
  • ValueError – If parameter ‘genericItem’ is None.

  • TypeError – If parameter ‘genericItem’ is not of type GenericInterfaceItemMixin.

  • NotAChildError – If parameter ‘genericItem’ is not a generic of this language construct.

  • NotInNamespaceError – If the namespace is indexed, and an identifier of the generic isn’t declared in it.

  • NotInNamespaceError – If the namespace is indexed, and an identifier of the generic refers to another element, e.g. a duplicate declaration.

Return type:

None

See also

AddGenericItem()

→ Add a generic at the end of the generic clause.

InsertGenericItem()

→ Insert a generic at a position of the generic clause.

MoveGenericItem()

→ Move a generic to a position of the generic clause.

RemovePortItem(portItem)

Remove a port from the port clause.

The port is detached: its parent and port group are cleared and its identifiers are removed from the language construct’s namespace, if it has one. A port group, which becomes empty, is removed from PortGroups and its parent is cleared. The port itself is unchanged and can be added to another language construct, or inserted at another position.

Parameters:

portItem (PortSignalInterfaceItem) – The port to remove.

Raises:
  • ValueError – If parameter ‘portItem’ is None.

  • TypeError – If parameter ‘portItem’ is not of type PortSignalInterfaceItem.

  • NotAChildError – If parameter ‘portItem’ is not a port of this language construct.

  • NotInNamespaceError – If the namespace is indexed, and an identifier of the port isn’t declared in it.

  • NotInNamespaceError – If the namespace is indexed, and an identifier of the port refers to another element, e.g. a duplicate declaration.

Return type:

None

See also

AddPortItem()

→ Add a port at the end of the port clause.

InsertPortItem()

→ Insert a port at a position of the port clause.

MovePortItem()

→ Move a port to a position of the port clause.

ResetReferences(designUnit, region)

Reset the references ResolveReferences() derived: the references of this declaration’s type marks.

A use clause, an alias and a subtype extend this method.

Parameters:
  • designUnit (DesignUnit) – The design unit containing this declaration.

  • region (DeclarativeRegionMixin) – The declarative region declaring this declaration.

Return type:

None

ResolveReferences(designUnit, region)

Resolve the references of this declaration: its type marks (IterateTypeMarks()).

Each type mark is resolved at its place by the region it is looked up in (ResolveTypeMark()). An incomplete type, an alias and a subtype extend this method.

Parameters:
  • designUnit (DesignUnit) – The design unit containing this declaration.

  • region (DeclarativeRegionMixin) – The declarative region declaring this declaration.

Raises:

UnhandledCriticalWarningError – If a type mark can’t be resolved, and no WarningCollector collects the UnresolvedTypeMarkWarning.

Return type:

None

ResolveTypeMark(place, symbol)

Resolve a type mark at its place in this region and set the symbol’s reference.

Algorithm

  1. Clear the symbol’s reference.

  2. Look up the type mark’s name (LookupName()).

  3. An alias of a type is replaced by the type its name references.

  4. If the declaration is a type, a subtype or a generic type, it becomes the symbol’s reference. A full type, which follows the place in the same region, is visible by its incomplete type declaration only to an access type.

An attribute name denoting a type (e.g. s'subtype, A'element) is resolved part by part (Denote()); the type it denotes becomes the symbol’s reference.

Parameters:
Raises:

UnhandledCriticalWarningError – If the type mark isn’t visible, is ambiguous, has a prefix, which isn’t a visible package, denotes no type, or denotes an incomplete type outside of an access type, and no WarningCollector collects the UnresolvedTypeMarkWarning.

Return type:

None

SplitGenericItem(genericItem)

Split a generic with an identifier list into one generic per identifier.

The generic keeps its first identifier. For every other identifier, a new generic is created by its Copy() and inserted right after it, in list order, in the generic clause and in the generic’s generic group; its parent is set to this language construct. If the language construct has a namespace, the entries of the other identifiers refer to the new generics. A generic declaring one identifier is unchanged.

Parameters:

genericItem (GenericInterfaceItemMixin) – The generic to split.

Return type:

tuple[GenericInterfaceItemMixin, ...]

Returns:

Tuple of generics, one per identifier in list order, starting with the split generic.

Raises:
  • ValueError – If parameter ‘genericItem’ is None.

  • TypeError – If parameter ‘genericItem’ is not of type GenericInterfaceItemMixin.

  • NotAChildError – If parameter ‘genericItem’ is not a generic of this language construct.

  • NotInNamespaceError – If the namespace is indexed, and an identifier of the generic refers to another element, e.g. a duplicate declaration.

See also

Split()

→ Split a declaration with an identifier list.

RemoveGenericItem()

→ Remove a generic from the generic clause.

SplitPortItem(portItem)

Split a port with an identifier list into one port per identifier.

The port keeps its first identifier. For every other identifier, a new port is created by its Copy() and inserted right after it, in list order, in the port clause and in the port’s port group; its parent is set to this language construct. If the language construct has a namespace, the entries of the other identifiers refer to the new ports. A port declaring one identifier is unchanged.

Parameters:

portItem (PortSignalInterfaceItem) – The port to split.

Return type:

tuple[PortSignalInterfaceItem, ...]

Returns:

Tuple of ports, one per identifier in list order, starting with the split port.

Raises:
  • ValueError – If parameter ‘portItem’ is None.

  • TypeError – If parameter ‘portItem’ is not of type PortSignalInterfaceItem.

  • NotAChildError – If parameter ‘portItem’ is not a port of this language construct.

  • NotInNamespaceError – If the namespace is indexed, and an identifier of the port refers to another element, e.g. a duplicate declaration.

See also

Split()

→ Split a declaration with an identifier list.

RemovePortItem()

→ Remove a port from the port clause.

Visit(visitor)[source]

Walk this component declaration, its generic clause and its port clause with a visitor.

Parameters:

visitor (Visitor) – The visitor receiving the events.

Return type:

None

_AddOverloadToNamespace(item)

Add a function or procedure to the namespace, if it’s the overload declared last.

The namespace keeps one entry per identifier: the overload declared last, as after IndexDeclaredItems(), which adds interface items first, then declared items (_Declarations()).

Parameters:

item (NamedEntityMixin | MultipleNamedEntityMixin) – The function or procedure, already an interface item or declared item of this region.

Return type:

None

_AddToGenericGroup(position, genericItem)

Add a generic to the generic group of the generic before position.

At position 0, the generic joins the generic group of the first generic. If there are no generic groups, the generic forms a new unnamed generic group.

Parameters:
  • position (int) – Position of the generic in the generic clause, from 0 (first) to the length of GenericItems (last).

  • genericItem (GenericInterfaceItemMixin) – The generic to add, which isn’t in a generic group.

Return type:

None

_AddToNamespace(element)

Add an element’s identifiers to this region’s namespace.

Nothing is added to a region not indexed yet: IndexDeclaredItems() adds the element later. A generic subprogram is an overload (_AddOverloadToNamespace()).

Parameters:

element (NamedEntityMixin | MultipleNamedEntityMixin) – The named element to add, e.g. an interface item.

Return type:

None

_AddToPortGroup(position, portItem)

Add a port to the port group of the port before position; at position 0, the port group of the first port.

If there are no port groups, the port forms a new unnamed port group.

Parameters:
  • position (int) – Position of the port in the port clause, from 0 (first) to the length of PortItems (last).

  • portItem (PortSignalInterfaceItem) – The port to add, which isn’t in a port group.

Return type:

None

_ClashingDeclarations(item)

Return the declarations sharing an identifier with the given item, which may not share it.

The declarations (_Declarations()) and the labeled statements (_Labels()) of this declarative region and of the language constructs sharing it (_SharedRegions()) are searched: a statement label is declared implicitly. Items imported into the namespace (e.g. by a use clause) are no declarations.

Parameters:

item (ModelEntity) – The new declaration, or the new labeled statement.

Return type:

tuple[ModelEntity, ...]

Returns:

Tuple of clashing declarations, interface items first, then declared items in declaration order, then labeled statements.

_ConnectParentNamespace(parent)

Connect this region’s namespace to the namespace of the enclosing declarative region.

A declaration of this region then hides a same-named declaration of the enclosing region. A parent, which isn’t a declarative region (e.g. a subprogram of an interface list), has no namespace to connect to.

Parameters:

parent (ModelEntity) – The new parent of this region.

Return type:

None

_Declarations()[source]

Return all declarations of this component.

Return type:

tuple[ModelEntity, ...]

Returns:

Tuple of declarations: the generics, then the ports.

_END_KEYWORDS: ClassVar[tuple[ReservedWord, ...]] = (ReservedWord.Component,)

Reserved words after end.

_END_KEYWORDS_OPTIONAL: ClassVar[bool] = False

The reserved words after end are optional.

_IndexGenericItems()

Add the generics to the host’s namespace; a generic subprogram is an overload.

Return type:

None

_IndexPortItems()

Add the ports to the host’s namespace.

Return type:

None

_IterateStatementRegions()

Iterate the declarative regions nested in the statements of this declarative region.

Return type:

Generator[DeclarativeRegionMixin]

Returns:

An empty generator.

_Labels()

Return the labeled statements, whose labels are declared in this declarative region.

Return type:

tuple[ModelEntity, ...]

Returns:

An empty tuple.

_MayShareIdentifier(item, existing)

Check if two declarations may share an identifier in one declarative region.

Subprograms are overloadable. A protected type body completes its protected type, a full type completes its incomplete type, and a constant completes its deferred constant.

Parameters:
Return type:

bool

Returns:

True, if both declarations may share an identifier.

_RemoveFromGenericGroup(genericItem)

Remove a generic from its generic group and clear the generic’s group.

A generic group, which becomes empty, is removed from GenericGroups and its parent is cleared.

Parameters:

genericItem (GenericInterfaceItemMixin) – The generic to remove from its generic group.

Return type:

None

_RemoveFromNamespace(element)

Remove an element’s identifiers from this region’s namespace.

Nothing is removed from a region not indexed yet, as its namespace doesn’t contain the element. A generic subprogram is an overload (_RemoveOverloadFromNamespace()).

Parameters:

element (NamedEntityMixin | MultipleNamedEntityMixin) – The named element to remove, e.g. an interface item.

Raises:
  • NotInNamespaceError – If the region is indexed, and an identifier of the element isn’t declared in the namespace.

  • NotInNamespaceError – If the region is indexed, and an identifier of the element refers to another element, e.g. a duplicate declaration.

Return type:

None

_RemoveFromPortGroup(portItem)

Remove a port from its port group and clear the port’s group.

A port group, which becomes empty, is removed from PortGroups and its parent is cleared.

Parameters:

portItem (PortSignalInterfaceItem) – The port to remove from its port group.

Return type:

None

_RemoveOverloadFromNamespace(item)

Remove a function or procedure from the namespace.

Removing the overload the namespace refers to, the namespace refers to the remaining overload declared last (_Declarations()), or the identifier is removed, if no overload remains. Removing another overload leaves the namespace unchanged. The namespace is checked before it’s changed.

Parameters:

item (NamedEntityMixin | MultipleNamedEntityMixin) – The function or procedure, still an interface item or declared item of this region.

Raises:
  • NotInNamespaceError – If the identifier isn’t declared in the namespace.

  • NotInNamespaceError – If the identifier refers to an element, which is no overload, e.g. a duplicate declaration.

Return type:

None

_SharedRegions()

Return the other language constructs forming one declarative region with this one.

An entity and each of its architectures form one declarative region, as do a package and its body. Derived classes override it.

Return type:

tuple[DeclarativeRegionMixin, ...]

Returns:

Tuple of declarative regions.

_VisitGenericClause(visitor)

Walk the generic clause, if there are generics, with a visitor.

The generics are separated by semicolons.

Parameters:

visitor (Visitor) – The visitor receiving the events.

Return type:

None

_VisitPortClause(visitor)

Walk the port clause, if there are ports, with a visitor.

The ports are separated by semicolons.

Parameters:

visitor (Visitor) – The visitor receiving the events.

Return type:

None

__getstate__()

Return the object’s state for pickling, collecting every slot of the class hierarchy.

Return type:

dict[str, Any]

Returns:

Dictionary of slot names and their values.

Raises:

ExtendedTypeError – If a slot was never assigned, so it has no value to serialize.

__new__(**kwargs)
__repr__()[source]

Formats a representation of the component declaration.

Format: mylib.myPackage:myComponent

Return type:

str

Returns:

String representation of the component declaration.

__setstate__(state)

Restore the object’s state from unpickling, requiring exactly the slots of the class hierarchy.

Parameters:

state (dict[str, Any]) – Dictionary of slot names and their values.

Raises:

ExtendedTypeError – If the given state misses a slot or carries an unexpected one.

Return type:

None

__str__()[source]

Formats the component declaration.

Format: Component: myComponent

Return type:

str

Returns:

Formatted component declaration.

_allowBlackbox: bool | None

Allow blackboxes for components; None inherits the parent’s setting.

_areDeclaredItemsIndexed: bool

True if IndexDeclaredItems() filled the namespace.

_documentation: str | None

The associated documentation of a model entity.

_entity: Entity | None

Linked entity, or None if unresolved.

_genericGroups: list[GenericGroup]

List of all generic groups, in declaration order.

_genericItems: list[GenericInterfaceItemMixin]

List of all generics, in declaration order.

_identifier: str

The identifier of a model entity.

_isBlackbox: bool | None

Component is a blackbox.

_namespace: Namespace

The namespace of this component’s declarative region.

_normalizedIdentifier: str

The normalized (lower case) identifier of a model entity.

_parent: ModelEntity

Reference to a parent entity in the logical model hierarchy.

_portGroups: list[PortGroup]

List of all port groups, in declaration order.

_portItems: list[PortInterfaceItemMixin]

List of all ports, in declaration order.

class pyGHDL.dom.DesignUnit.Package(node, identifier, contextItems=None, genericItems=None, declaredItems=None, documentation=None)[source]

This class implements a pyGHDL.dom object derived from pyVHDLModel.DesignUnit.Package.

Represents a package declaration.

Example

package pkg is
  -- ...
end package;

Inheritance

Inheritance diagram of Package

Parameters:
  • node (Iir)

  • identifier (str)

  • contextItems (Iterable[VHDLModel_ContextUnion])

  • genericItems (Iterable[GenericInterfaceItemMixin])

  • declaredItems (Iterable)

  • documentation (str)

__init__(node, identifier, contextItems=None, genericItems=None, declaredItems=None, documentation=None)[source]

Initialize a package.

Parameters:
  • node (Iir) – The IIR node this object was translated from.

  • identifier (str) – Name of the VHDL package.

  • contextItems (Iterable[LibraryClause | UseClause | ContextReference]) – Optional, list of all context items (library, use and context clauses).

  • genericItems (Iterable[GenericInterfaceItemMixin]) – Optional, list of all generics, in declaration order.

  • declaredItems (Iterable) – Optional, list of all declared items in this concurrent declaration region.

  • documentation (str) – Optional, the documentation comment associated with this declaration.

Return type:

None

classmethod parse(packageNode, contextItems)[source]

Translates the IIR node of the package declaration to a Package.

Parameters:
Returns:

The translated package declaration.

_iirNode

The IIR node in libghdl’s tree this DOM object was translated from.

_position

The IIR node’s position in the source file, resolved on first access and then cached.

AddContextItem(contextItem)

Add a context item at the end of the context clause.

The context item’s parent is set to this design unit. A library clause is also added to LibraryReferences, a use clause to PackageReferences and a context reference to ContextReferences, in the order of ContextItems. A context item may repeat an earlier one.

Parameters:

contextItem (LibraryClause | UseClause | ContextReference) – The library clause, use clause or context reference to add.

Raises:
Return type:

None

Attention

The mutator doesn’t update what Analyze() derived from the context items: the referenced libraries, packages and contexts (ReferencedLibraries, ReferencedPackages, ReferencedContexts), the namespace entries of a use clause, the edges of the dependency graph, and the references of the symbols. A design changed after its analysis needs a new analysis.

See also

InsertContextItem()

→ Insert a context item at a position of the context clause.

RemoveContextItem()

→ Remove a context item from the context clause.

AddDeclaredItem(declaredItem)

Add a declared item at the end of the declarative region.

The declared item’s parent is set to this declarative region. If the region is indexed, its identifiers are added to the region’s namespace and to the lookup table matching its kind.

Parameters:

declaredItem (ModelEntity) – The declared item to add.

Raises:
  • ValueError – If parameter ‘declaredItem’ is None.

  • TypeError – If parameter ‘declaredItem’ is not a declaration allowed in this declarative region.

  • AlreadyInDesignError – If parameter ‘declaredItem’ already has a parent.

  • DuplicateDeclarationError – If an existing declaration of the declarative region shares an identifier with the declared item.

Return type:

None

See also

InsertDeclaredItem()

→ Insert a declared item at a position of the declarative region.

RemoveDeclaredItem()

→ Remove a declared item from the declarative region.

AddGenericItem(genericItem, group=None)

Add a generic at the end of the generic clause, or at the end of a generic group.

The generic’s parent is set to this language construct, and its identifiers are added to the language construct’s namespace, if it has one. Without a generic group, the generic joins the last generic group, or forms a new unnamed generic group if there are no generics.

Parameters:
  • genericItem (GenericInterfaceItemMixin) – The generic to add.

  • group (GenericGroup | None) – Optional, the generic group of this language construct to add the generic to, at its end. Default: None, the end of the generic clause.

Raises:
  • ValueError – If parameter ‘genericItem’ is None.

  • TypeError – If parameter ‘genericItem’ is not of type GenericInterfaceItemMixin.

  • AlreadyInDesignError – If parameter ‘genericItem’ already has a parent.

  • TypeError – If parameter ‘group’ is not of type GenericGroup.

  • NotAChildError – If parameter ‘group’ is not a generic group of this language construct.

  • DuplicateGenericError – If an existing declaration of the language construct shares an identifier with the generic.

Return type:

None

See also

InsertGenericItem()

→ Insert a generic at a position of the generic clause.

RemoveGenericItem()

→ Remove a generic from the generic clause.

property AllowBlackbox: bool

Property to return whether a design supports blackboxes, inherited from the parent if not set locally (_allowBlackbox).

Algorithm

  1. If allow blackbox property is locally set, return the local value,

  2. Otherwise, return allow blackbox value from parent object.

Returns:

True, if blackboxes are allowed.

Raises:

AllowBlackboxNotSetError – If neither a local value is set nor a parent object is available to inherit the value from.

Setter accepts:

bool | None

property Components: dict[str, Component]

Read-only property to access the components (_components).

Returns:

Dictionary of components, indexed by normalized identifier.

property Constants: dict[str, Constant]

Read-only property to access the constants (_constants).

Returns:

Dictionary of constants, indexed by normalized identifier.

property ContextItems: list[LibraryClause | UseClause | ContextReference]

Read-only property to access the sequence of all context items comprising library, use and context clauses (_contextItems).

Returns:

Sequence of context items.

property ContextReferences: list[ContextReference]

Read-only property to access the sequence of context clauses (_contextReferences).

Returns:

Sequence of context clauses.

property DeclaredItems: list

Read-only property to access the declared items (_declaredItems).

Returns:

List of declared items.

property DeferredConstants: dict[str, DeferredConstant]

Read-only property to access the deferred constants (_deferredConstants).

Returns:

Dictionary of deferred constants, indexed by normalized identifier.

DenoteBy(name, region, place, symbol)[source]

Return this package, the model entity a name in a type mark denotes.

Parameters:
  • name (Name) – The name denoting this declaration, a part of the type mark.

  • region (DeclarativeRegionMixin) – The declarative region containing the type mark.

  • place (ModelEntity) – The declaration containing the type mark.

  • symbol (Symbol) – The type mark.

Return type:

ModelEntity | None

Returns:

This package.

property DependencyVertex: Vertex

Read-only property to access the corresponding dependency vertex (_dependencyVertex).

The dependency vertex references this design unit by its value field.

Returns:

The corresponding dependency vertex.

property Document: Document

Property to access the document (_document).

Returns:

The document.

property Documentation: str | None

Read-only property to access the model entity’s documentation (_documentation).

Returns:

Associated documentation of a model entity.

property Files: dict[str, File]

Read-only property to access the files (_files).

Returns:

Dictionary of files, indexed by normalized identifier.

property Functions: dict[str, list[Function]]

Read-only property to access the functions (_functions).

Returns:

Dictionary of functions, indexed by normalized identifier; each entry is a list of overloads.

property GenericCount: int

Read-only property to return the number of generics declared by _genericItems.

A generic constant item with several identifiers (generic (A, B : natural)) declares several generics.

Returns:

The number of generics.

property GenericGroups: list[GenericGroup]

Read-only property to access the generic groups (_genericGroups).

The generic groups partition the generic clause: concatenated in order, they list every generic exactly once, in declaration order.

Returns:

List of generic groups, in declaration order.

property GenericItems: list[GenericInterfaceItemMixin]

Read-only property to access the generic items (_genericItems).

Returns:

List of generic items.

GetAncestor(type)

Return the closest ancestor of the given type found by walking the parent chain upwards.

Iterates the parent chain - starting at this model entity - upwards (toward the root of the model) until an ancestor of the requested type is found.

Parameters:

type (Type) – Class (type) of the ancestor to find.

Return type:

ModelEntity

Returns:

The closest ancestor of the requested type.

Raises:

AncestorNotFoundError – If the root of the model is reached without finding an ancestor of the requested type.

GetIdentifier(normalizedIdentifier)

Return the identifier as declared, for the model entity’s normalized identifier.

Parameters:

normalizedIdentifier (str) – The model entity’s normalized (lower case) identifier.

Return type:

str

Returns:

The identifier in its declared spelling.

classmethod GetMethodsWithAttributes(predicate=None)

Return the class’ methods that carry at least one matching attribute.

Parameters:

predicate (type[TAttr] | Iterable[type[TAttr]] | None) – Optional, an attribute class, an iterable of attribute classes, or None to accept every attribute.

Return type:

dict[Callable[..., Any], tuple[Attribute, ...]]

Returns:

Dictionary of methods and the matching attributes attached to them.

Raises:
  • ValueError – If an element of parameter ‘predicate’ is not a sub-class of Attribute.

  • ValueError – If parameter ‘predicate’ is neither an attribute class nor an iterable of those.

property HierarchyVertex: Vertex

Read-only property to access the corresponding hierarchy vertex (_hierarchyVertex).

The hierarchy vertex references this design unit by its value field.

Returns:

The corresponding hierarchy vertex.

property Identifier: str

Read-only property to access the model entity’s identifier (_identifier).

Returns:

Name of a model entity.

IndexDeclaredItems()[source]

A generic package’s generics share the declarative region of its declarative part.

Raises:

UnhandledCriticalWarningError – If an identifier is declared twice in a declarative region and no WarningCollector collects the DuplicateDeclarationWarning.

Return type:

None

InsertContextItem(index, contextItem)

Insert a context item at a position of the context clause.

The context item’s parent is set to this design unit. A library clause is also added to LibraryReferences, a use clause to PackageReferences and a context reference to ContextReferences, in the order of ContextItems. A context item may repeat an earlier one.

Parameters:
  • index (int) – Position, from 0 (first) to the number of context items (append). A negative index counts from the end, as for list.insert(): -1 inserts before the last context item.

  • contextItem (LibraryClause | UseClause | ContextReference) – The library clause, use clause or context reference to insert.

Raises:
Return type:

None

Attention

The mutator doesn’t update what Analyze() derived from the context items: the referenced libraries, packages and contexts (ReferencedLibraries, ReferencedPackages, ReferencedContexts), the namespace entries of a use clause, the edges of the dependency graph, and the references of the symbols. A design changed after its analysis needs a new analysis.

See also

AddContextItem()

→ Add a context item at the end of the context clause.

RemoveContextItem()

→ Remove a context item from the context clause.

InsertDeclaredItem(index, declaredItem)

Insert a declared item at a position of the declarative region.

The declared item’s parent is set to this declarative region. If the region is indexed, its identifiers are added to the region’s namespace and to the lookup table matching its kind.

An identifier is declared once per declarative region: interface items and declared items count, including those of the language construct sharing the declarative region (an entity and its architecture, a package and its body). Subprograms are overloadable: a subprogram may share its identifier with other subprograms. A protected type body may share its identifier with its protected type, a full type with its incomplete type declaration, and a constant with its deferred constant. Items imported into the namespace (e.g. by a use clause) are hidden.

Parameters:
  • index (int) – Position, from 0 (first) to the number of declared items (append). A negative index counts from the end, as for list.insert(): -1 inserts before the last declared item.

  • declaredItem (ModelEntity) – The declared item to insert.

Raises:
  • ValueError – If parameter ‘index’ is None.

  • TypeError – If parameter ‘index’ is not of type int.

  • ValueError – If parameter ‘index’ is out of range.

  • ValueError – If parameter ‘declaredItem’ is None.

  • TypeError – If parameter ‘declaredItem’ is not a declaration allowed in this declarative region.

  • AlreadyInDesignError – If parameter ‘declaredItem’ already has a parent.

  • DuplicateDeclarationError – If an existing declaration of the declarative region shares an identifier with the declared item.

Return type:

None

See also

AddDeclaredItem()

→ Add a declared item at the end of the declarative region.

InsertDeclaredItemBefore()

→ Insert a declared item before another declared item.

InsertDeclaredItemAfter()

→ Insert a declared item after another declared item.

RemoveDeclaredItem()

→ Remove a declared item from the declarative region.

MoveDeclaredItem()

→ Move a declared item to a position of the declarative region.

InsertDeclaredItemAfter(declaredItem, after)

Insert a declared item after another declared item.

The declared item’s parent is set to this declarative region. If the region is indexed, its identifiers are added to the region’s namespace and to the lookup table matching its kind.

Parameters:
  • declaredItem (ModelEntity) – The declared item to insert.

  • after (ModelEntity) – The declared item of this declarative region to insert after.

Raises:
  • ValueError – If parameter ‘declaredItem’ is None.

  • TypeError – If parameter ‘declaredItem’ is not a declaration allowed in this declarative region.

  • AlreadyInDesignError – If parameter ‘declaredItem’ already has a parent.

  • ValueError – If parameter ‘after’ is None.

  • TypeError – If parameter ‘after’ is not of type ModelEntity.

  • NotAChildError – If parameter ‘after’ is not a declared item of this declarative region.

  • DuplicateDeclarationError – If an existing declaration of the declarative region shares an identifier with the declared item.

Return type:

None

See also

InsertDeclaredItem()

→ Insert a declared item at a position of the declarative region.

InsertDeclaredItemBefore()

→ Insert a declared item before another declared item.

InsertDeclaredItemBefore(declaredItem, before)

Insert a declared item before another declared item.

The declared item’s parent is set to this declarative region. If the region is indexed, its identifiers are added to the region’s namespace and to the lookup table matching its kind.

Parameters:
  • declaredItem (ModelEntity) – The declared item to insert.

  • before (ModelEntity) – The declared item of this declarative region to insert before.

Raises:
  • ValueError – If parameter ‘declaredItem’ is None.

  • TypeError – If parameter ‘declaredItem’ is not a declaration allowed in this declarative region.

  • AlreadyInDesignError – If parameter ‘declaredItem’ already has a parent.

  • ValueError – If parameter ‘before’ is None.

  • TypeError – If parameter ‘before’ is not of type ModelEntity.

  • NotAChildError – If parameter ‘before’ is not a declared item of this declarative region.

  • DuplicateDeclarationError – If an existing declaration of the declarative region shares an identifier with the declared item.

Return type:

None

See also

InsertDeclaredItem()

→ Insert a declared item at a position of the declarative region.

InsertDeclaredItemAfter()

→ Insert a declared item after another declared item.

InsertGenericItem(index, genericItem, group=None)

Insert a generic at a position of the generic clause.

The generic’s parent is set to this language construct, and its identifiers are added to the language construct’s namespace, if it has one.

Without a generic group, the generic joins the generic group of the generic before index; at index 0, the generic group of the first generic. If there are no generics, the generic forms a new unnamed generic group. A generic group given must contain index or end at it, so the generic groups stay contiguous.

Parameters:
  • index (int) – Position, from 0 (first) to the length of GenericItems (append). A negative index counts from the end, as for list.insert(): -1 inserts before the last generic.

  • genericItem (GenericInterfaceItemMixin) – The generic to insert.

  • group (GenericGroup | None) – Optional, the generic group of this language construct to insert the generic into. Default: None, the generic group of the generic before index.

Raises:
  • ValueError – If parameter ‘index’ is None.

  • TypeError – If parameter ‘index’ is not of type int.

  • ValueError – If parameter ‘index’ is out of range.

  • ValueError – If parameter ‘genericItem’ is None.

  • TypeError – If parameter ‘genericItem’ is not of type GenericInterfaceItemMixin.

  • AlreadyInDesignError – If parameter ‘genericItem’ already has a parent.

  • TypeError – If parameter ‘group’ is not of type GenericGroup.

  • NotAChildError – If parameter ‘group’ is not a generic group of this language construct.

  • ValueError – If parameter ‘group’ neither contains nor ends at parameter ‘index’.

  • DuplicateGenericError – If an existing declaration of the language construct shares an identifier with the generic.

Return type:

None

See also

AddGenericItem()

→ Add a generic at the end of the generic clause.

RemoveGenericItem()

→ Remove a generic from the generic clause.

MoveGenericItem()

→ Move a generic to a position of the generic clause.

IsLibraryVisible(libraryIdentifier)

Check if the logical name of a library is visible in this design unit.

The name work is implicitly visible, the name std too, except in a context declaration. Every other name needs a library clause, also the real name of the working library. The library clause is searched in this design unit’s context clause, in the context clause of its primary unit, and in the contexts these reference, also in nested ones. The design unit must be in a library of a design.

Parameters:

libraryIdentifier (str) – The normalized identifier of the library.

Return type:

bool

Returns:

True, if the library’s name is visible.

property IsOverloadable: bool

Check if this model entity is an overloadable declaration: it may share its designator with other overloadable declarations.

Subprograms, enumeration literals and aliases, which may denote one of them, are overloadable; they override this property.

Returns:

True, if this model entity is an overloadable declaration.

IterateDeclarationRegions()

Iterate this declarative region and all declarative regions nested in it.

Nested regions are declarations (e.g. subprograms, generic subprograms, protected types, packages) and concurrent statements (blocks, processes, generate statements and their branches), each followed by the regions nested in it.

Return type:

Generator[DeclarativeRegionMixin]

Returns:

A generator to iterate the declarative regions, this region first.

IterateDeclarations()[source]

Iterate the declarations of this package a use clause can make potentially visible.

A declared item contributes its normalized identifiers; an enumerated type its enumeration literals too, a physical type its units. An incomplete type is completed by its full type declaration, so it’s skipped.

Return type:

Generator[tuple[str, ModelEntity]]

Returns:

A generator to iterate (normalized designator, declaration) pairs, in declaration order.

IterateImplicitDeclarations()

Iterate the declarations this declaration implies.

An enumerated type implies its enumeration literals, a physical type its units; they override this method.

Return type:

Generator[tuple[str, ModelEntity]]

Returns:

A generator to iterate (normalized designator, declaration) pairs, in declaration order: none.

IterateMemberDeclarations(memberIdentifier)[source]

Iterate the declarations of this package a use clause naming one package member makes potentially visible.

These are the declarations of the package with the member’s identifier, e.g. all overloads of a subprogram. A type brings its enumeration literals or physical units along (IEEE Std 1076-2008, 12.4), a subtype those of its base type: the known base type, else the type its type marks lead to, followed by simple names in the package.

Parameters:

memberIdentifier (str) – The normalized (lower case) identifier of the package member.

Return type:

Generator[tuple[str, ModelEntity]]

Returns:

A generator to iterate (normalized designator, declaration) pairs, in declaration order.

IterateSingleGenericDeclarations(predicate=None)

Iterate all generics per declared identifier, in declaration order.

A generic constant yields one single declaration per identifier: generic (A, B : positive) yields two. A generic type, subprogram or package declares exactly one identifier and is yielded itself.

Parameters:

predicate (Callable[[SingleGenericDeclarationMixin | GenericInterfaceItemMixin], bool] | None) – Optional, filter function to select the yielded generics. Default: all.

Return type:

Generator[SingleGenericDeclarationMixin | GenericInterfaceItemMixin]

Returns:

A generator to iterate all (selected) generics.

IterateTypeMarks(region)

Iterate the type marks of this declaration, each with the region and the place to look it up.

The place of a type mark is the declaration containing it. Declarations with type marks override this method, e.g. an object yields the type mark of its subtype indication, an array type its index and element subtypes.

Parameters:

region (DeclarativeRegionMixin) – The declarative region declaring this declaration.

Return type:

Generator[tuple[DeclarativeRegionMixin, ModelEntity, SubtypeSymbol]]

Returns:

A generator to iterate (region, place, type mark) tuples, in declaration order: none.

property Library: Library

Property to access the library (_parent).

Returns:

The library.

property LibraryReferences: list[LibraryClause]

Read-only property to access the sequence of library clauses (_libraryReferences).

Returns:

Sequence of library clauses.

LookupName(place, symbol, name, warningType)

Look up the declarations a simple name or an expanded name denotes at a place in this region.

A simple name is looked up at the place (Lookup()). An expanded name pkg.T or lib.pkg.T resolves its prefix: pkg to a package visible at the place, else to an enclosing declarative region of that name (e.g. the package or entity containing the place); lib.pkg by the library (work or a library whose name is visible in the design unit containing the place, IsLibraryVisible()) and the package’s name. Then the suffix is searched among the declarations of the package or region (FindDeclarations()).

A failure is reported as a warning of the given type, whose label names the kind of name in the message (e.g. Type mark); then no declaration is returned. A name, which is a part of the symbol’s name (e.g. the prefix s of the type mark s'subtype), is reported as a prefix of the symbol’s name.

Parameters:
  • place (ModelEntity) – The declaration containing the name.

  • symbol (Symbol) – The symbol containing the name.

  • name (Name) – The simple name or expanded name: the symbol’s name or a part of it.

  • warningType (type[UnresolvedNameWarning]) – The warning class reporting a failure.

Return type:

tuple[ModelEntity, ...]

Returns:

Tuple of the directly visible declarations, empty if none is.

Raises:

UnhandledCriticalWarningError – If the name isn’t visible, is ambiguous, or has a prefix, which isn’t a visible package or an enclosing region, and no WarningCollector collects the warning.

MoveDeclaredItem(declaredItem, index)

Move a declared item to a position of the declarative region.

The declared item stays a declared item of this declarative region: only the order of the declared items changes.

If the region is indexed, the lookup tables and the namespace follow the new order: a list of overloads (e.g. in Functions) follows the declaration order, and the namespace refers to the overload declared last. If another declaration shares an identifier with the declared item (e.g. a duplicate declaration read by a parser), the region is indexed again (IndexDeclaredItems()) after the move.

Parameters:
  • declaredItem (ModelEntity) – The declared item to move.

  • index (int) – Position of the declared item after the move, from 0 (first) to the number of declared items minus one (last). A negative index counts from the end, as for a list index: -1 moves the declared item to the end.

Raises:
  • ValueError – If parameter ‘declaredItem’ is None.

  • TypeError – If parameter ‘declaredItem’ is not of type ModelEntity.

  • NotAChildError – If parameter ‘declaredItem’ is not a declared item of this declarative region.

  • ValueError – If parameter ‘index’ is None.

  • TypeError – If parameter ‘index’ is not of type int.

  • ValueError – If parameter ‘index’ is out of range.

Return type:

None

See also

MoveDeclaredItemBefore()

→ Move a declared item before another declared item.

MoveDeclaredItemAfter()

→ Move a declared item after another declared item.

InsertDeclaredItem()

→ Insert a declared item at a position of the declarative region.

RemoveDeclaredItem()

→ Remove a declared item from the declarative region.

MoveDeclaredItemAfter(declaredItem, after)

Move a declared item after another declared item.

The declared item stays a declared item of this declarative region: only the order of the declared items changes, as for MoveDeclaredItem(). Moving a declared item after itself keeps it in place.

Parameters:
  • declaredItem (ModelEntity) – The declared item to move.

  • after (ModelEntity) – The declared item of this declarative region to move after.

Raises:
  • ValueError – If parameter ‘declaredItem’ is None.

  • TypeError – If parameter ‘declaredItem’ is not of type ModelEntity.

  • NotAChildError – If parameter ‘declaredItem’ is not a declared item of this declarative region.

  • ValueError – If parameter ‘after’ is None.

  • TypeError – If parameter ‘after’ is not of type ModelEntity.

  • NotAChildError – If parameter ‘after’ is not a declared item of this declarative region.

Return type:

None

See also

MoveDeclaredItem()

→ Move a declared item to a position of the declarative region.

MoveDeclaredItemBefore()

→ Move a declared item before another declared item.

MoveDeclaredItemBefore(declaredItem, before)

Move a declared item before another declared item.

The declared item stays a declared item of this declarative region: only the order of the declared items changes, as for MoveDeclaredItem(). Moving a declared item before itself keeps it in place.

Parameters:
  • declaredItem (ModelEntity) – The declared item to move.

  • before (ModelEntity) – The declared item of this declarative region to move before.

Raises:
  • ValueError – If parameter ‘declaredItem’ is None.

  • TypeError – If parameter ‘declaredItem’ is not of type ModelEntity.

  • NotAChildError – If parameter ‘declaredItem’ is not a declared item of this declarative region.

  • ValueError – If parameter ‘before’ is None.

  • TypeError – If parameter ‘before’ is not of type ModelEntity.

  • NotAChildError – If parameter ‘before’ is not a declared item of this declarative region.

Return type:

None

See also

MoveDeclaredItem()

→ Move a declared item to a position of the declarative region.

MoveDeclaredItemAfter()

→ Move a declared item after another declared item.

MoveGenericItem(genericItem, index)

Move a generic to a position of the generic clause.

The generic stays a generic of this language construct: only the order of the generic clause changes. A generic subprogram is an overload: if the language construct’s namespace is indexed, it refers to the overload declared last afterwards.

The generic leaves its generic group, like RemoveGenericItem(), and joins a generic group, like InsertGenericItem() without a generic group: the generic group of the generic before its new position; at index 0, the generic group of the first generic. A move to the generic’s current position changes nothing.

Parameters:
  • genericItem (GenericInterfaceItemMixin) – The generic to move.

  • index (int) – Position of the generic after the move, from 0 (first) to the length of GenericItems minus one (last). A negative index counts from the end, as for a list index: -1 moves the generic to the end.

Raises:
  • ValueError – If parameter ‘genericItem’ is None.

  • TypeError – If parameter ‘genericItem’ is not of type GenericInterfaceItemMixin.

  • NotAChildError – If parameter ‘genericItem’ is not a generic of this language construct.

  • ValueError – If parameter ‘index’ is None.

  • TypeError – If parameter ‘index’ is not of type int.

  • ValueError – If parameter ‘index’ is out of range.

  • NotInNamespaceError – If the namespace is indexed, and the identifier of a generic subprogram refers to an element, which is no overload, e.g. a duplicate declaration.

Return type:

None

See also

InsertGenericItem()

→ Insert a generic at a position of the generic clause.

RemoveGenericItem()

→ Remove a generic from the generic clause.

property NormalizedIdentifier: str

Read-only property to access the model entity’s normalized identifier (_normalizedIdentifier).

See also

Returns:

Normalized name of a model entity.

property PackageBody: PackageBody | None

Read-only property to access the package body (_packageBody).

Returns:

The package body, or None if not set.

property PackageReferences: list[UseClause]

Read-only property to access the sequence of use clauses (_packageReferences).

Returns:

Sequence of use clauses.

property Parent: ModelEntity

Property to access the model entity’s parent element reference in a logical hierarchy (_parent).

Returns:

Reference to the parent entity.

property Position: Position

Cached read-only property to access an IIR’s position in source code (_position).

If _position is None, resolve the position object from _iirNode

Returns:

The IIR’s position in the source file.

Precedes(item, anchor, inclusive)

Check if an item precedes an anchor in this declarative region.

An item, which isn’t a declaration of this region (e.g. a use clause of the context clause), precedes every anchor.

Parameters:
  • item (ModelEntity | None) – The item in declaration order, or None for the implicit use clause.

  • anchor (ModelEntity) – A declaration of this region, e.g. the one containing the place of a lookup.

  • inclusive (bool) – True, if the anchor precedes itself, i.e. the place is nested inside the anchor.

Return type:

bool

Returns:

True, if the item precedes the anchor.

property Procedures: dict[str, list[Procedure]]

Read-only property to access the procedures (_procedures).

Returns:

Dictionary of procedures, indexed by normalized identifier; each entry is a list of overloads.

property ReferencedContexts: dict[str, Context]

Read-only property to access the referenced contexts (_referencedContexts).

Returns:

Dictionary of referenced contexts, indexed by normalized identifier.

property ReferencedLibraries: dict[str, Library]

Read-only property to access the referenced libraries (_referencedLibraries).

Returns:

Dictionary of referenced libraries, indexed by normalized identifier.

property ReferencedPackages: dict[str, Package]

Read-only property to access the referenced packages (_referencedPackages).

Returns:

Dictionary of referenced packages, indexed by normalized identifier.

RemoveContextItem(contextItem)

Remove a context item from the context clause.

The context item is detached: its parent is cleared, and it’s removed from ContextItems and from LibraryReferences, PackageReferences or ContextReferences. The context item itself is unchanged and can be added to another design unit, or inserted at another position.

Parameters:

contextItem (LibraryClause | UseClause | ContextReference) – The library clause, use clause or context reference to remove.

Raises:
Return type:

None

Attention

The mutator doesn’t update what Analyze() derived from the context items: the referenced libraries, packages and contexts (ReferencedLibraries, ReferencedPackages, ReferencedContexts), the namespace entries of a use clause, the edges of the dependency graph, and the references of the symbols. A design changed after its analysis needs a new analysis.

See also

AddContextItem()

→ Add a context item at the end of the context clause.

InsertContextItem()

→ Insert a context item at a position of the context clause.

RemoveDeclaredItem(declaredItem)

Remove a declared item from the declarative region.

The declared item is detached: its parent is cleared. If the region is indexed, the declared item’s identifiers are removed from the region’s namespace and from the lookup table matching its kind first; they are checked before anything is changed. The declared item itself is unchanged and can be added to another declarative region, or inserted at another position.

The namespace refers to the overload declared last: removing it, the namespace refers to the remaining overload declared last. If another declaration shares an identifier with the declared item (e.g. a duplicate declaration read by a parser), the region is indexed again (IndexDeclaredItems()) after the removal.

Parameters:

declaredItem (ModelEntity) – The declared item to remove.

Raises:
  • ValueError – If parameter ‘declaredItem’ is None.

  • TypeError – If parameter ‘declaredItem’ is not of type ModelEntity.

  • NotAChildError – If parameter ‘declaredItem’ is not a declared item of this declarative region.

  • NotInNamespaceError – If the region is indexed, and an identifier of the declared item isn’t declared in its namespace.

  • NotInNamespaceError – If the region is indexed, and an identifier of the declared item refers to another declaration, e.g. a duplicate declaration.

Return type:

None

See also

AddDeclaredItem()

→ Add a declared item at the end of the declarative region.

InsertDeclaredItem()

→ Insert a declared item at a position of the declarative region.

MoveDeclaredItem()

→ Move a declared item to a position of the declarative region.

RemoveGenericItem(genericItem)

Remove a generic from the generic clause.

The generic is detached: its parent and generic group are cleared and its identifiers are removed from the language construct’s namespace, if it has one. A generic group, which becomes empty, is removed from GenericGroups and its parent is cleared. The generic itself is unchanged and can be added to another language construct, or inserted at another position.

Parameters:

genericItem (GenericInterfaceItemMixin) – The generic to remove.

Raises:
  • ValueError – If parameter ‘genericItem’ is None.

  • TypeError – If parameter ‘genericItem’ is not of type GenericInterfaceItemMixin.

  • NotAChildError – If parameter ‘genericItem’ is not a generic of this language construct.

  • NotInNamespaceError – If the namespace is indexed, and an identifier of the generic isn’t declared in it.

  • NotInNamespaceError – If the namespace is indexed, and an identifier of the generic refers to another element, e.g. a duplicate declaration.

Return type:

None

See also

AddGenericItem()

→ Add a generic at the end of the generic clause.

InsertGenericItem()

→ Insert a generic at a position of the generic clause.

MoveGenericItem()

→ Move a generic to a position of the generic clause.

ResetReferences(designUnit, region)

Reset the references ResolveReferences() derived: the references of this declaration’s type marks.

A use clause, an alias and a subtype extend this method.

Parameters:
  • designUnit (DesignUnit) – The design unit containing this declaration.

  • region (DeclarativeRegionMixin) – The declarative region declaring this declaration.

Return type:

None

ResolveReferences(designUnit, region)

Resolve the references of this declaration: its type marks (IterateTypeMarks()).

Each type mark is resolved at its place by the region it is looked up in (ResolveTypeMark()). An incomplete type, an alias and a subtype extend this method.

Parameters:
  • designUnit (DesignUnit) – The design unit containing this declaration.

  • region (DeclarativeRegionMixin) – The declarative region declaring this declaration.

Raises:

UnhandledCriticalWarningError – If a type mark can’t be resolved, and no WarningCollector collects the UnresolvedTypeMarkWarning.

Return type:

None

ResolveTypeMark(place, symbol)

Resolve a type mark at its place in this region and set the symbol’s reference.

Algorithm

  1. Clear the symbol’s reference.

  2. Look up the type mark’s name (LookupName()).

  3. An alias of a type is replaced by the type its name references.

  4. If the declaration is a type, a subtype or a generic type, it becomes the symbol’s reference. A full type, which follows the place in the same region, is visible by its incomplete type declaration only to an access type.

An attribute name denoting a type (e.g. s'subtype, A'element) is resolved part by part (Denote()); the type it denotes becomes the symbol’s reference.

Parameters:
Raises:

UnhandledCriticalWarningError – If the type mark isn’t visible, is ambiguous, has a prefix, which isn’t a visible package, denotes no type, or denotes an incomplete type outside of an access type, and no WarningCollector collects the UnresolvedTypeMarkWarning.

Return type:

None

property SharedVariables: dict[str, SharedVariable]

Read-only property to access the shared variables (_sharedVariables).

Returns:

Dictionary of shared variables, indexed by normalized identifier.

property Signals: dict[str, Signal]

Read-only property to access the signals (_signals).

Returns:

Dictionary of signals, indexed by normalized identifier.

SplitDeclaredItem(declaredItem)

Split a declared item with an identifier list into one declaration per identifier.

The declared item keeps its first identifier. For every other identifier, a new declaration is created by its Copy() and inserted right after it, in list order; its parent is set to this declarative region. If the region is indexed, the namespace and lookup table entries of the other identifiers refer to the new declarations; they are checked before anything is changed. A declared item declaring one identifier is unchanged.

Parameters:

declaredItem (ModelEntity) – The declared item to split.

Return type:

tuple[ModelEntity, ...]

Returns:

Tuple of declarations, one per identifier in list order, starting with the split declared item.

Raises:
  • ValueError – If parameter ‘declaredItem’ is None.

  • TypeError – If parameter ‘declaredItem’ is not of type ModelEntity.

  • NotAChildError – If parameter ‘declaredItem’ is not a declared item of this declarative region.

  • NotInNamespaceError – If the region is indexed, and an identifier of the declared item refers to another declaration, e.g. a duplicate declaration.

See also

Split()

→ Split a declaration with an identifier list.

RemoveDeclaredItem()

→ Remove a declared item from the declarative region.

SplitGenericItem(genericItem)

Split a generic with an identifier list into one generic per identifier.

The generic keeps its first identifier. For every other identifier, a new generic is created by its Copy() and inserted right after it, in list order, in the generic clause and in the generic’s generic group; its parent is set to this language construct. If the language construct has a namespace, the entries of the other identifiers refer to the new generics. A generic declaring one identifier is unchanged.

Parameters:

genericItem (GenericInterfaceItemMixin) – The generic to split.

Return type:

tuple[GenericInterfaceItemMixin, ...]

Returns:

Tuple of generics, one per identifier in list order, starting with the split generic.

Raises:
  • ValueError – If parameter ‘genericItem’ is None.

  • TypeError – If parameter ‘genericItem’ is not of type GenericInterfaceItemMixin.

  • NotAChildError – If parameter ‘genericItem’ is not a generic of this language construct.

  • NotInNamespaceError – If the namespace is indexed, and an identifier of the generic refers to another element, e.g. a duplicate declaration.

See also

Split()

→ Split a declaration with an identifier list.

RemoveGenericItem()

→ Remove a generic from the generic clause.

property Subtypes: dict[str, Subtype]

Read-only property to access the subtypes (_subtypes).

Returns:

Dictionary of subtypes, indexed by normalized identifier.

property Types: dict[str, FullType]

Read-only property to access the types (_types).

Returns:

Dictionary of types, indexed by normalized identifier.

Visit(visitor)[source]

Walk this package declaration, its context clause, its generic clause and its declared items with a visitor.

Parameters:

visitor (Visitor) – The visitor receiving the events.

Return type:

None

_AddOverloadToNamespace(item)

Add a function or procedure to the namespace, if it’s the overload declared last.

The namespace keeps one entry per identifier: the overload declared last, as after IndexDeclaredItems(), which adds interface items first, then declared items (_Declarations()).

Parameters:

item (NamedEntityMixin | MultipleNamedEntityMixin) – The function or procedure, already an interface item or declared item of this region.

Return type:

None

_AddToGenericGroup(position, genericItem)

Add a generic to the generic group of the generic before position.

At position 0, the generic joins the generic group of the first generic. If there are no generic groups, the generic forms a new unnamed generic group.

Parameters:
  • position (int) – Position of the generic in the generic clause, from 0 (first) to the length of GenericItems (last).

  • genericItem (GenericInterfaceItemMixin) – The generic to add, which isn’t in a generic group.

Return type:

None

_AddToNamespace(element)

Add an element’s identifiers to this region’s namespace.

Nothing is added to a region not indexed yet: IndexDeclaredItems() adds the element later. A generic subprogram is an overload (_AddOverloadToNamespace()).

Parameters:

element (NamedEntityMixin | MultipleNamedEntityMixin) – The named element to add, e.g. an interface item.

Return type:

None

_CONTINUES_PARENT_REGION = False

True if it continues its parent’s declarative region.

_ClashingDeclarations(item)

Return the declarations sharing an identifier with the given item, which may not share it.

The declarations (_Declarations()) and the labeled statements (_Labels()) of this declarative region and of the language constructs sharing it (_SharedRegions()) are searched: a statement label is declared implicitly. Items imported into the namespace (e.g. by a use clause) are no declarations.

Parameters:

item (ModelEntity) – The new declaration, or the new labeled statement.

Return type:

tuple[ModelEntity, ...]

Returns:

Tuple of clashing declarations, interface items first, then declared items in declaration order, then labeled statements.

_ConnectParentNamespace(parent)

Connect this region’s namespace to the namespace of the enclosing declarative region.

A declaration of this region then hides a same-named declaration of the enclosing region. A parent, which isn’t a declarative region (e.g. a subprogram of an interface list), has no namespace to connect to.

Parameters:

parent (ModelEntity) – The new parent of this region.

Return type:

None

_ContextClauseUnits()

Return the design units whose context clause applies to this design unit.

Return type:

tuple[DesignUnit, ...]

Returns:

Tuple of this design unit.

_DECLARED_ITEM_TYPES = (<class 'pyVHDLModel.Type.BaseType'>, <class 'pyVHDLModel.Subprogram.Subprogram'>, <class 'pyVHDLModel.DesignUnit.Package'>, <class 'pyVHDLModel.DesignUnit.PackageBody'>, <class 'pyVHDLModel.Object.Constant'>, <class 'pyVHDLModel.Object.Signal'>, <class 'pyVHDLModel.Object.SharedVariable'>, <class 'pyVHDLModel.Object.File'>, <class 'pyVHDLModel.Declaration.Alias'>, <class 'pyVHDLModel.DesignUnit.Component'>, <class 'pyVHDLModel.Declaration.Attribute'>, <class 'pyVHDLModel.Declaration.AttributeSpecification'>, <class 'pyVHDLModel.Configuration.ComponentConfiguration'>, <class 'pyVHDLModel.Interface.ModeViewDeclaration'>, <class 'pyVHDLModel.DesignUnit.UseClause'>, <class 'pyVHDLModel.PSLModel.PSLEntity'>, <class 'pyVHDLModel.Object.DeferredConstant'>)

Accepted classes of declared items (pyVHDLModel).

_Declarations()[source]

Return all declarations of this package: its generics share the declarative region.

Return type:

tuple[ModelEntity, ...]

Returns:

Tuple of declarations: the generics, then the declared items.

_DeclaredItemsSharingIdentifiers(declaredItem)

Return the other declared items of this region sharing an identifier with the given declared item.

Parameters:

declaredItem (ModelEntity) – The declared item.

Return type:

list[ModelEntity]

Returns:

List of declared items, in declaration order.

_END_KEYWORDS: ClassVar[tuple[ReservedWord, ...]] = (ReservedWord.Package,)

Reserved words after end.

_END_KEYWORDS_OPTIONAL: ClassVar[bool] = True

The reserved words after end are optional.

_IMPLICIT_LIBRARIES = ('work', 'std')

Library names visible without a library clause.

_IndexDeclaredItem(item)

Add a declared item to the namespace and to the lookup table matching its kind.

Parameters:

item (ModelEntity) – The declared item.

Return type:

None

_IndexGenericItems()

Add the generics to the host’s namespace; a generic subprogram is an overload.

Return type:

None

_IndexOtherDeclaredItem(item)[source]

Hook for declared items the region doesn’t handle itself. Derived classes may override it.

An alias, an attribute declaration and a package (also a package instantiation) declared in the region are added to the namespace, without a lookup table.

Parameters:

item – The declared item.

Return type:

None

_IndexOverload(item)

Add an inserted function or procedure to its lookup table and to the namespace.

The list of overloads follows the declaration order. The namespace is updated by _AddOverloadToNamespace().

Parameters:

item (NamedEntityMixin | MultipleNamedEntityMixin) – The inserted function or procedure.

Return type:

None

_IterateStatementRegions()

Iterate the declarative regions nested in the statements of this declarative region.

Return type:

Generator[DeclarativeRegionMixin]

Returns:

An empty generator.

_Labels()

Return the labeled statements, whose labels are declared in this declarative region.

Return type:

tuple[ModelEntity, ...]

Returns:

An empty tuple.

_MayShareIdentifier(item, existing)

Check if two declarations may share an identifier in one declarative region.

Subprograms are overloadable. A protected type body completes its protected type, a full type completes its incomplete type, and a constant completes its deferred constant.

Parameters:
Return type:

bool

Returns:

True, if both declarations may share an identifier.

_RemoveDeclaredItemEntries(lookupTable, item)

Remove a declared item’s entries from a lookup table and from the namespace.

Every identifier is checked before anything is removed.

Parameters:
Raises:
  • NotInNamespaceError – If an identifier of the declared item isn’t declared in the namespace.

  • NotInNamespaceError – If an identifier of the declared item refers to another element, e.g. a duplicate declaration.

Return type:

None

_RemoveDeclaredItemsFromNamespace()

Remove all declared items of this region from its namespace.

Interface items of this region and items imported from elsewhere (e.g. by a use clause) are kept.

Return type:

None

_RemoveFromGenericGroup(genericItem)

Remove a generic from its generic group and clear the generic’s group.

A generic group, which becomes empty, is removed from GenericGroups and its parent is cleared.

Parameters:

genericItem (GenericInterfaceItemMixin) – The generic to remove from its generic group.

Return type:

None

_RemoveFromNamespace(element)

Remove an element’s identifiers from this region’s namespace.

Nothing is removed from a region not indexed yet, as its namespace doesn’t contain the element. A generic subprogram is an overload (_RemoveOverloadFromNamespace()).

Parameters:

element (NamedEntityMixin | MultipleNamedEntityMixin) – The named element to remove, e.g. an interface item.

Raises:
  • NotInNamespaceError – If the region is indexed, and an identifier of the element isn’t declared in the namespace.

  • NotInNamespaceError – If the region is indexed, and an identifier of the element refers to another element, e.g. a duplicate declaration.

Return type:

None

_RemoveOverloadFromNamespace(item)

Remove a function or procedure from the namespace.

Removing the overload the namespace refers to, the namespace refers to the remaining overload declared last (_Declarations()), or the identifier is removed, if no overload remains. Removing another overload leaves the namespace unchanged. The namespace is checked before it’s changed.

Parameters:

item (NamedEntityMixin | MultipleNamedEntityMixin) – The function or procedure, still an interface item or declared item of this region.

Raises:
  • NotInNamespaceError – If the identifier isn’t declared in the namespace.

  • NotInNamespaceError – If the identifier refers to an element, which is no overload, e.g. a duplicate declaration.

Return type:

None

_SharedRegions()[source]

Return the other language constructs forming one declarative region with this package.

Return type:

tuple[ConcurrentDeclarationRegionMixin, ...]

Returns:

Tuple of the package body, if linked (_packageBody).

_UnindexDeclaredItem(item)

Remove a declared item from the namespace and from the lookup table matching its kind.

Parameters:

item (ModelEntity) – The declared item.

Return type:

None

_UnindexOtherDeclaredItem(item)[source]

Remove a declared item, which a concurrent declaration region doesn’t handle itself.

A deferred constant is removed from _deferredConstants. An entry referring to another deferred constant of the same identifier (a duplicate declaration) is kept: RemoveDeclaredItem() indexes the region again.

Parameters:

item (ModelEntity) – The declared item.

Return type:

None

_UnindexOverload(item)

Remove a function or procedure from its lookup table and from the namespace.

The namespace is updated first, by _RemoveOverloadFromNamespace().

Parameters:

item (NamedEntityMixin | MultipleNamedEntityMixin) – The function or procedure to remove, still a declared item of this region.

Raises:
  • NotInNamespaceError – If the identifier isn’t declared in the namespace.

  • NotInNamespaceError – If the identifier refers to an element, which is no overload, e.g. a duplicate declaration.

Return type:

None

_VisitContextClause(visitor)

Walk the context clause, i.e. the context items preceding the design unit, with a visitor.

The context clause is reported, even if it has no context items.

Parameters:

visitor (Visitor) – The visitor receiving the events.

Return type:

None

_VisitDeclaredItems(visitor)

Walk the declared items in declaration order with a visitor.

Parameters:

visitor (Visitor) – The visitor receiving the events.

Return type:

None

_VisitGenericClause(visitor)

Walk the generic clause, if there are generics, with a visitor.

The generics are separated by semicolons.

Parameters:

visitor (Visitor) – The visitor receiving the events.

Return type:

None

__getstate__()

Return the object’s state for pickling, collecting every slot of the class hierarchy.

Return type:

dict[str, Any]

Returns:

Dictionary of slot names and their values.

Raises:

ExtendedTypeError – If a slot was never assigned, so it has no value to serialize.

__new__(**kwargs)
__repr__()[source]

Formats a representation of the package declaration.

Format: mylib.myPackage

Return type:

str

Returns:

String representation of the package declaration.

__setstate__(state)

Restore the object’s state from unpickling, requiring exactly the slots of the class hierarchy.

Parameters:

state (dict[str, Any]) – Dictionary of slot names and their values.

Raises:

ExtendedTypeError – If the given state misses a slot or carries an unexpected one.

Return type:

None

__str__()[source]

Formats the package declaration.

Format: Package: 'mylib.myPackage'

Return type:

str

Returns:

Formatted package declaration.

_allowBlackbox

Allow blackboxes for components; None inherits the parent’s setting.

_areDeclaredItemsIndexed

True if IndexDeclaredItems() filled the namespace.

_components

Dictionary of all components declared in this concurrent declaration region.

_constants

Dictionary of all constants declared in this concurrent declaration region.

_contextItems

List of all context items (library, use and context clauses).

_contextReferences

List of context clauses.

_declaredItems

List of all declared items in this concurrent declaration region.

_deferredConstants: dict[str, DeferredConstant]

Deferred constants, indexed by name.

_dependencyVertex

Reference to the vertex in the dependency graph representing the design unit.
This reference is set by CreateDependencyGraph().

_document

The VHDL library, the design unit was analyzed into.

_documentation

The associated documentation of a model entity.

_files

Dictionary of all files declared in this concurrent declaration region.

_functions

Dictionary of all functions declared in this concurrent declaration region, indexed by name; each entry is a list of overloads.

_genericGroups

List of all generic groups, in declaration order.

_genericItems

List of all generics, in declaration order.

_hierarchyVertex

The vertex in the hierarchy graph

_identifier

The identifier of a model entity.

_libraryReferences

List of library clauses.

_namespace

The namespace of this concurrent declaration region.

_normalizedIdentifier

The normalized (lower case) identifier of a model entity.

_packageBody: Nullable[PackageBody]

The corresponding package body, or None if none was analyzed.

_packageReferences

List of use clauses.

_parent

Reference to a parent entity in the logical model hierarchy.

_procedures

Dictionary of all procedures declared in this concurrent declaration region, indexed by name; each entry is a list of overloads.

_referencedContexts

Referenced contexts based on explicit context references or implicit inheritance

_referencedLibraries

Referenced libraries based on explicit library clauses or implicit inheritance

_referencedPackages

Referenced packages based on explicit use clauses or implicit inheritance

_sharedVariables

Dictionary of all shared variables declared in this concurrent declaration region.

_signals

Dictionary of all signals declared in this concurrent declaration region.

_subtypes

Dictionary of all subtypes declared in this concurrent declaration region.

_types

Dictionary of all types declared in this concurrent declaration region.

class pyGHDL.dom.DesignUnit.PackageBody(node, packageSymbol, contextItems=None, declaredItems=None, documentation=None)[source]

This class implements a pyGHDL.dom object derived from pyVHDLModel.DesignUnit.PackageBody.

Represents a package body declaration.

Example

package body pkg is
  -- ...
end package body;

Inheritance

Inheritance diagram of PackageBody

Parameters:
  • node (Iir)

  • packageSymbol (PackageSymbol)

  • contextItems (Iterable[VHDLModel_ContextUnion])

  • declaredItems (Iterable)

  • documentation (str)

__init__(node, packageSymbol, contextItems=None, declaredItems=None, documentation=None)[source]

Initializes a package body declaration.

Parameters:
  • node (Iir) – The IIR node this object was translated from.

  • packageSymbol (PackageSymbol) – Reference to the package this body implements.

  • contextItems (Iterable[LibraryClause | UseClause | ContextReference]) – Optional, list of all context items (library, use and context clauses).

  • declaredItems (Iterable) – Optional, list of all declared items in this concurrent declaration region.

  • documentation (str) – Optional, the documentation comment associated with this declaration.

Return type:

None

classmethod parse(packageBodyNode, contextItems)[source]

Translates the IIR node of the package body to a PackageBody.

Parameters:
Returns:

The translated package body.

_iirNode

The IIR node in libghdl’s tree this DOM object was translated from.

_position

The IIR node’s position in the source file, resolved on first access and then cached.

AddContextItem(contextItem)

Add a context item at the end of the context clause.

The context item’s parent is set to this design unit. A library clause is also added to LibraryReferences, a use clause to PackageReferences and a context reference to ContextReferences, in the order of ContextItems. A context item may repeat an earlier one.

Parameters:

contextItem (LibraryClause | UseClause | ContextReference) – The library clause, use clause or context reference to add.

Raises:
Return type:

None

Attention

The mutator doesn’t update what Analyze() derived from the context items: the referenced libraries, packages and contexts (ReferencedLibraries, ReferencedPackages, ReferencedContexts), the namespace entries of a use clause, the edges of the dependency graph, and the references of the symbols. A design changed after its analysis needs a new analysis.

See also

InsertContextItem()

→ Insert a context item at a position of the context clause.

RemoveContextItem()

→ Remove a context item from the context clause.

AddDeclaredItem(declaredItem)

Add a declared item at the end of the declarative region.

The declared item’s parent is set to this declarative region. If the region is indexed, its identifiers are added to the region’s namespace and to the lookup table matching its kind.

Parameters:

declaredItem (ModelEntity) – The declared item to add.

Raises:
  • ValueError – If parameter ‘declaredItem’ is None.

  • TypeError – If parameter ‘declaredItem’ is not a declaration allowed in this declarative region.

  • AlreadyInDesignError – If parameter ‘declaredItem’ already has a parent.

  • DuplicateDeclarationError – If an existing declaration of the declarative region shares an identifier with the declared item.

Return type:

None

See also

InsertDeclaredItem()

→ Insert a declared item at a position of the declarative region.

RemoveDeclaredItem()

→ Remove a declared item from the declarative region.

property Components: dict[str, Any]

Read-only property to access the components (_components).

Returns:

Dictionary of components, indexed by normalized identifier.

property Constants: dict[str, Constant]

Read-only property to access the constants (_constants).

Returns:

Dictionary of constants, indexed by normalized identifier.

property ContextItems: list[LibraryClause | UseClause | ContextReference]

Read-only property to access the sequence of all context items comprising library, use and context clauses (_contextItems).

Returns:

Sequence of context items.

property ContextReferences: list[ContextReference]

Read-only property to access the sequence of context clauses (_contextReferences).

Returns:

Sequence of context clauses.

property DeclaredItems: list

Read-only property to access the declared items (_declaredItems).

Returns:

List of declared items.

DenoteBy(name, region, place, symbol)

Determine the model entity a name denoting this declaration denotes, as a part of a type mark (Name.Denote).

A declaration, which a name in a type mark can denote, overrides this method and returns itself: an object, an alias, a type or subtype, a record element, a package. Any other declaration (e.g. a subprogram) is reported.

Parameters:
  • name (Name) – The name denoting this declaration, a part of the type mark.

  • region (DeclarativeRegionMixin) – The declarative region containing the type mark.

  • place (ModelEntity) – The declaration containing the type mark.

  • symbol (Symbol) – The type mark.

Return type:

ModelEntity | None

Returns:

None, as a name in a type mark can’t denote this declaration (reported as a warning).

Raises:

UnhandledCriticalWarningError – Always, if no WarningCollector collects the UnresolvedTypeMarkWarning.

property DependencyVertex: Vertex

Read-only property to access the corresponding dependency vertex (_dependencyVertex).

The dependency vertex references this design unit by its value field.

Returns:

The corresponding dependency vertex.

property Document: Document

Property to access the document (_document).

Returns:

The document.

property Documentation: str | None

Read-only property to access the model entity’s documentation (_documentation).

Returns:

Associated documentation of a model entity.

property Files: dict[str, File]

Read-only property to access the files (_files).

Returns:

Dictionary of files, indexed by normalized identifier.

property Functions: dict[str, list[Function]]

Read-only property to access the functions (_functions).

Returns:

Dictionary of functions, indexed by normalized identifier; each entry is a list of overloads.

GetAncestor(type)

Return the closest ancestor of the given type found by walking the parent chain upwards.

Iterates the parent chain - starting at this model entity - upwards (toward the root of the model) until an ancestor of the requested type is found.

Parameters:

type (Type) – Class (type) of the ancestor to find.

Return type:

ModelEntity

Returns:

The closest ancestor of the requested type.

Raises:

AncestorNotFoundError – If the root of the model is reached without finding an ancestor of the requested type.

GetIdentifier(normalizedIdentifier)

Return the identifier as declared, for the model entity’s normalized identifier.

Parameters:

normalizedIdentifier (str) – The model entity’s normalized (lower case) identifier.

Return type:

str

Returns:

The identifier in its declared spelling.

classmethod GetMethodsWithAttributes(predicate=None)

Return the class’ methods that carry at least one matching attribute.

Parameters:

predicate (type[TAttr] | Iterable[type[TAttr]] | None) – Optional, an attribute class, an iterable of attribute classes, or None to accept every attribute.

Return type:

dict[Callable[..., Any], tuple[Attribute, ...]]

Returns:

Dictionary of methods and the matching attributes attached to them.

Raises:
  • ValueError – If an element of parameter ‘predicate’ is not a sub-class of Attribute.

  • ValueError – If parameter ‘predicate’ is neither an attribute class nor an iterable of those.

property HierarchyVertex: Vertex

Read-only property to access the corresponding hierarchy vertex (_hierarchyVertex).

The hierarchy vertex references this design unit by its value field.

Returns:

The corresponding hierarchy vertex.

property Identifier: str

Read-only property to access the model entity’s identifier (_identifier).

Returns:

Name of a model entity.

IndexDeclaredItems()

Index declared items listed in the concurrent declaration region.

Algorithm

  1. Clear all lookup tables and remove all declared items from _namespace. Interface items and imported items stay in the namespace.

  2. Iterate all declared items:

Indexing again yields the same lookup tables and namespace.

See also

pyVHDLModel.Design.IndexPackages()

Iterate all packages in the design and index declared items.

pyVHDLModel.Library.IndexPackages()

Iterate all packages in the library and index declared items.

pyVHDLModel.DesignUnit.Package._IndexOtherDeclaredItem()

Index the deferred constants and components of a package.

Raises:

UnhandledCriticalWarningError – If an identifier is declared twice in a declarative region and no WarningCollector collects the DuplicateDeclarationWarning.

Return type:

None

InsertContextItem(index, contextItem)

Insert a context item at a position of the context clause.

The context item’s parent is set to this design unit. A library clause is also added to LibraryReferences, a use clause to PackageReferences and a context reference to ContextReferences, in the order of ContextItems. A context item may repeat an earlier one.

Parameters:
  • index (int) – Position, from 0 (first) to the number of context items (append). A negative index counts from the end, as for list.insert(): -1 inserts before the last context item.

  • contextItem (LibraryClause | UseClause | ContextReference) – The library clause, use clause or context reference to insert.

Raises:
Return type:

None

Attention

The mutator doesn’t update what Analyze() derived from the context items: the referenced libraries, packages and contexts (ReferencedLibraries, ReferencedPackages, ReferencedContexts), the namespace entries of a use clause, the edges of the dependency graph, and the references of the symbols. A design changed after its analysis needs a new analysis.

See also

AddContextItem()

→ Add a context item at the end of the context clause.

RemoveContextItem()

→ Remove a context item from the context clause.

InsertDeclaredItem(index, declaredItem)

Insert a declared item at a position of the declarative region.

The declared item’s parent is set to this declarative region. If the region is indexed, its identifiers are added to the region’s namespace and to the lookup table matching its kind.

An identifier is declared once per declarative region: interface items and declared items count, including those of the language construct sharing the declarative region (an entity and its architecture, a package and its body). Subprograms are overloadable: a subprogram may share its identifier with other subprograms. A protected type body may share its identifier with its protected type, a full type with its incomplete type declaration, and a constant with its deferred constant. Items imported into the namespace (e.g. by a use clause) are hidden.

Parameters:
  • index (int) – Position, from 0 (first) to the number of declared items (append). A negative index counts from the end, as for list.insert(): -1 inserts before the last declared item.

  • declaredItem (ModelEntity) – The declared item to insert.

Raises:
  • ValueError – If parameter ‘index’ is None.

  • TypeError – If parameter ‘index’ is not of type int.

  • ValueError – If parameter ‘index’ is out of range.

  • ValueError – If parameter ‘declaredItem’ is None.

  • TypeError – If parameter ‘declaredItem’ is not a declaration allowed in this declarative region.

  • AlreadyInDesignError – If parameter ‘declaredItem’ already has a parent.

  • DuplicateDeclarationError – If an existing declaration of the declarative region shares an identifier with the declared item.

Return type:

None

See also

AddDeclaredItem()

→ Add a declared item at the end of the declarative region.

InsertDeclaredItemBefore()

→ Insert a declared item before another declared item.

InsertDeclaredItemAfter()

→ Insert a declared item after another declared item.

RemoveDeclaredItem()

→ Remove a declared item from the declarative region.

MoveDeclaredItem()

→ Move a declared item to a position of the declarative region.

InsertDeclaredItemAfter(declaredItem, after)

Insert a declared item after another declared item.

The declared item’s parent is set to this declarative region. If the region is indexed, its identifiers are added to the region’s namespace and to the lookup table matching its kind.

Parameters:
  • declaredItem (ModelEntity) – The declared item to insert.

  • after (ModelEntity) – The declared item of this declarative region to insert after.

Raises:
  • ValueError – If parameter ‘declaredItem’ is None.

  • TypeError – If parameter ‘declaredItem’ is not a declaration allowed in this declarative region.

  • AlreadyInDesignError – If parameter ‘declaredItem’ already has a parent.

  • ValueError – If parameter ‘after’ is None.

  • TypeError – If parameter ‘after’ is not of type ModelEntity.

  • NotAChildError – If parameter ‘after’ is not a declared item of this declarative region.

  • DuplicateDeclarationError – If an existing declaration of the declarative region shares an identifier with the declared item.

Return type:

None

See also

InsertDeclaredItem()

→ Insert a declared item at a position of the declarative region.

InsertDeclaredItemBefore()

→ Insert a declared item before another declared item.

InsertDeclaredItemBefore(declaredItem, before)

Insert a declared item before another declared item.

The declared item’s parent is set to this declarative region. If the region is indexed, its identifiers are added to the region’s namespace and to the lookup table matching its kind.

Parameters:
  • declaredItem (ModelEntity) – The declared item to insert.

  • before (ModelEntity) – The declared item of this declarative region to insert before.

Raises:
  • ValueError – If parameter ‘declaredItem’ is None.

  • TypeError – If parameter ‘declaredItem’ is not a declaration allowed in this declarative region.

  • AlreadyInDesignError – If parameter ‘declaredItem’ already has a parent.

  • ValueError – If parameter ‘before’ is None.

  • TypeError – If parameter ‘before’ is not of type ModelEntity.

  • NotAChildError – If parameter ‘before’ is not a declared item of this declarative region.

  • DuplicateDeclarationError – If an existing declaration of the declarative region shares an identifier with the declared item.

Return type:

None

See also

InsertDeclaredItem()

→ Insert a declared item at a position of the declarative region.

InsertDeclaredItemAfter()

→ Insert a declared item after another declared item.

IsLibraryVisible(libraryIdentifier)

Check if the logical name of a library is visible in this design unit.

The name work is implicitly visible, the name std too, except in a context declaration. Every other name needs a library clause, also the real name of the working library. The library clause is searched in this design unit’s context clause, in the context clause of its primary unit, and in the contexts these reference, also in nested ones. The design unit must be in a library of a design.

Parameters:

libraryIdentifier (str) – The normalized identifier of the library.

Return type:

bool

Returns:

True, if the library’s name is visible.

property IsOverloadable: bool

Check if this model entity is an overloadable declaration: it may share its designator with other overloadable declarations.

Subprograms, enumeration literals and aliases, which may denote one of them, are overloadable; they override this property.

Returns:

True, if this model entity is an overloadable declaration.

IterateDeclarationRegions()

Iterate this declarative region and all declarative regions nested in it.

Nested regions are declarations (e.g. subprograms, generic subprograms, protected types, packages) and concurrent statements (blocks, processes, generate statements and their branches), each followed by the regions nested in it.

Return type:

Generator[DeclarativeRegionMixin]

Returns:

A generator to iterate the declarative regions, this region first.

IterateImplicitDeclarations()

Iterate the declarations this declaration implies.

An enumerated type implies its enumeration literals, a physical type its units; they override this method.

Return type:

Generator[tuple[str, ModelEntity]]

Returns:

A generator to iterate (normalized designator, declaration) pairs, in declaration order: none.

IterateTypeMarks(region)

Iterate the type marks of this declaration, each with the region and the place to look it up.

The place of a type mark is the declaration containing it. Declarations with type marks override this method, e.g. an object yields the type mark of its subtype indication, an array type its index and element subtypes.

Parameters:

region (DeclarativeRegionMixin) – The declarative region declaring this declaration.

Return type:

Generator[tuple[DeclarativeRegionMixin, ModelEntity, SubtypeSymbol]]

Returns:

A generator to iterate (region, place, type mark) tuples, in declaration order: none.

property Library: Library

Property to access the library (_parent).

Returns:

The library.

property LibraryReferences: list[LibraryClause]

Read-only property to access the sequence of library clauses (_libraryReferences).

Returns:

Sequence of library clauses.

LookupName(place, symbol, name, warningType)

Look up the declarations a simple name or an expanded name denotes at a place in this region.

A simple name is looked up at the place (Lookup()). An expanded name pkg.T or lib.pkg.T resolves its prefix: pkg to a package visible at the place, else to an enclosing declarative region of that name (e.g. the package or entity containing the place); lib.pkg by the library (work or a library whose name is visible in the design unit containing the place, IsLibraryVisible()) and the package’s name. Then the suffix is searched among the declarations of the package or region (FindDeclarations()).

A failure is reported as a warning of the given type, whose label names the kind of name in the message (e.g. Type mark); then no declaration is returned. A name, which is a part of the symbol’s name (e.g. the prefix s of the type mark s'subtype), is reported as a prefix of the symbol’s name.

Parameters:
  • place (ModelEntity) – The declaration containing the name.

  • symbol (Symbol) – The symbol containing the name.

  • name (Name) – The simple name or expanded name: the symbol’s name or a part of it.

  • warningType (type[UnresolvedNameWarning]) – The warning class reporting a failure.

Return type:

tuple[ModelEntity, ...]

Returns:

Tuple of the directly visible declarations, empty if none is.

Raises:

UnhandledCriticalWarningError – If the name isn’t visible, is ambiguous, or has a prefix, which isn’t a visible package or an enclosing region, and no WarningCollector collects the warning.

MoveDeclaredItem(declaredItem, index)

Move a declared item to a position of the declarative region.

The declared item stays a declared item of this declarative region: only the order of the declared items changes.

If the region is indexed, the lookup tables and the namespace follow the new order: a list of overloads (e.g. in Functions) follows the declaration order, and the namespace refers to the overload declared last. If another declaration shares an identifier with the declared item (e.g. a duplicate declaration read by a parser), the region is indexed again (IndexDeclaredItems()) after the move.

Parameters:
  • declaredItem (ModelEntity) – The declared item to move.

  • index (int) – Position of the declared item after the move, from 0 (first) to the number of declared items minus one (last). A negative index counts from the end, as for a list index: -1 moves the declared item to the end.

Raises:
  • ValueError – If parameter ‘declaredItem’ is None.

  • TypeError – If parameter ‘declaredItem’ is not of type ModelEntity.

  • NotAChildError – If parameter ‘declaredItem’ is not a declared item of this declarative region.

  • ValueError – If parameter ‘index’ is None.

  • TypeError – If parameter ‘index’ is not of type int.

  • ValueError – If parameter ‘index’ is out of range.

Return type:

None

See also

MoveDeclaredItemBefore()

→ Move a declared item before another declared item.

MoveDeclaredItemAfter()

→ Move a declared item after another declared item.

InsertDeclaredItem()

→ Insert a declared item at a position of the declarative region.

RemoveDeclaredItem()

→ Remove a declared item from the declarative region.

MoveDeclaredItemAfter(declaredItem, after)

Move a declared item after another declared item.

The declared item stays a declared item of this declarative region: only the order of the declared items changes, as for MoveDeclaredItem(). Moving a declared item after itself keeps it in place.

Parameters:
  • declaredItem (ModelEntity) – The declared item to move.

  • after (ModelEntity) – The declared item of this declarative region to move after.

Raises:
  • ValueError – If parameter ‘declaredItem’ is None.

  • TypeError – If parameter ‘declaredItem’ is not of type ModelEntity.

  • NotAChildError – If parameter ‘declaredItem’ is not a declared item of this declarative region.

  • ValueError – If parameter ‘after’ is None.

  • TypeError – If parameter ‘after’ is not of type ModelEntity.

  • NotAChildError – If parameter ‘after’ is not a declared item of this declarative region.

Return type:

None

See also

MoveDeclaredItem()

→ Move a declared item to a position of the declarative region.

MoveDeclaredItemBefore()

→ Move a declared item before another declared item.

MoveDeclaredItemBefore(declaredItem, before)

Move a declared item before another declared item.

The declared item stays a declared item of this declarative region: only the order of the declared items changes, as for MoveDeclaredItem(). Moving a declared item before itself keeps it in place.

Parameters:
  • declaredItem (ModelEntity) – The declared item to move.

  • before (ModelEntity) – The declared item of this declarative region to move before.

Raises:
  • ValueError – If parameter ‘declaredItem’ is None.

  • TypeError – If parameter ‘declaredItem’ is not of type ModelEntity.

  • NotAChildError – If parameter ‘declaredItem’ is not a declared item of this declarative region.

  • ValueError – If parameter ‘before’ is None.

  • TypeError – If parameter ‘before’ is not of type ModelEntity.

  • NotAChildError – If parameter ‘before’ is not a declared item of this declarative region.

Return type:

None

See also

MoveDeclaredItem()

→ Move a declared item to a position of the declarative region.

MoveDeclaredItemAfter()

→ Move a declared item after another declared item.

property NormalizedIdentifier: str

Read-only property to access the model entity’s normalized identifier (_normalizedIdentifier).

See also

Returns:

Normalized name of a model entity.

property Package: PackageSymbol

Read-only property to access the package (_package).

Returns:

The package.

property PackageReferences: list[UseClause]

Read-only property to access the sequence of use clauses (_packageReferences).

Returns:

Sequence of use clauses.

property Parent: ModelEntity

Property to access the model entity’s parent element reference in a logical hierarchy (_parent).

Returns:

Reference to the parent entity.

property Position: Position

Cached read-only property to access an IIR’s position in source code (_position).

If _position is None, resolve the position object from _iirNode

Returns:

The IIR’s position in the source file.

Precedes(item, anchor, inclusive)

Check if an item precedes an anchor in this declarative region.

An item, which isn’t a declaration of this region (e.g. a use clause of the context clause), precedes every anchor.

Parameters:
  • item (ModelEntity | None) – The item in declaration order, or None for the implicit use clause.

  • anchor (ModelEntity) – A declaration of this region, e.g. the one containing the place of a lookup.

  • inclusive (bool) – True, if the anchor precedes itself, i.e. the place is nested inside the anchor.

Return type:

bool

Returns:

True, if the item precedes the anchor.

property Procedures: dict[str, list[Procedure]]

Read-only property to access the procedures (_procedures).

Returns:

Dictionary of procedures, indexed by normalized identifier; each entry is a list of overloads.

property ReferencedContexts: dict[str, Context]

Read-only property to access the referenced contexts (_referencedContexts).

Returns:

Dictionary of referenced contexts, indexed by normalized identifier.

property ReferencedLibraries: dict[str, Library]

Read-only property to access the referenced libraries (_referencedLibraries).

Returns:

Dictionary of referenced libraries, indexed by normalized identifier.

property ReferencedPackages: dict[str, Package]

Read-only property to access the referenced packages (_referencedPackages).

Returns:

Dictionary of referenced packages, indexed by normalized identifier.

RemoveContextItem(contextItem)

Remove a context item from the context clause.

The context item is detached: its parent is cleared, and it’s removed from ContextItems and from LibraryReferences, PackageReferences or ContextReferences. The context item itself is unchanged and can be added to another design unit, or inserted at another position.

Parameters:

contextItem (LibraryClause | UseClause | ContextReference) – The library clause, use clause or context reference to remove.

Raises:
Return type:

None

Attention

The mutator doesn’t update what Analyze() derived from the context items: the referenced libraries, packages and contexts (ReferencedLibraries, ReferencedPackages, ReferencedContexts), the namespace entries of a use clause, the edges of the dependency graph, and the references of the symbols. A design changed after its analysis needs a new analysis.

See also

AddContextItem()

→ Add a context item at the end of the context clause.

InsertContextItem()

→ Insert a context item at a position of the context clause.

RemoveDeclaredItem(declaredItem)

Remove a declared item from the declarative region.

The declared item is detached: its parent is cleared. If the region is indexed, the declared item’s identifiers are removed from the region’s namespace and from the lookup table matching its kind first; they are checked before anything is changed. The declared item itself is unchanged and can be added to another declarative region, or inserted at another position.

The namespace refers to the overload declared last: removing it, the namespace refers to the remaining overload declared last. If another declaration shares an identifier with the declared item (e.g. a duplicate declaration read by a parser), the region is indexed again (IndexDeclaredItems()) after the removal.

Parameters:

declaredItem (ModelEntity) – The declared item to remove.

Raises:
  • ValueError – If parameter ‘declaredItem’ is None.

  • TypeError – If parameter ‘declaredItem’ is not of type ModelEntity.

  • NotAChildError – If parameter ‘declaredItem’ is not a declared item of this declarative region.

  • NotInNamespaceError – If the region is indexed, and an identifier of the declared item isn’t declared in its namespace.

  • NotInNamespaceError – If the region is indexed, and an identifier of the declared item refers to another declaration, e.g. a duplicate declaration.

Return type:

None

See also

AddDeclaredItem()

→ Add a declared item at the end of the declarative region.

InsertDeclaredItem()

→ Insert a declared item at a position of the declarative region.

MoveDeclaredItem()

→ Move a declared item to a position of the declarative region.

ResetReferences(designUnit, region)

Reset the references ResolveReferences() derived: the references of this declaration’s type marks.

A use clause, an alias and a subtype extend this method.

Parameters:
  • designUnit (DesignUnit) – The design unit containing this declaration.

  • region (DeclarativeRegionMixin) – The declarative region declaring this declaration.

Return type:

None

ResolveReferences(designUnit, region)

Resolve the references of this declaration: its type marks (IterateTypeMarks()).

Each type mark is resolved at its place by the region it is looked up in (ResolveTypeMark()). An incomplete type, an alias and a subtype extend this method.

Parameters:
  • designUnit (DesignUnit) – The design unit containing this declaration.

  • region (DeclarativeRegionMixin) – The declarative region declaring this declaration.

Raises:

UnhandledCriticalWarningError – If a type mark can’t be resolved, and no WarningCollector collects the UnresolvedTypeMarkWarning.

Return type:

None

ResolveTypeMark(place, symbol)

Resolve a type mark at its place in this region and set the symbol’s reference.

Algorithm

  1. Clear the symbol’s reference.

  2. Look up the type mark’s name (LookupName()).

  3. An alias of a type is replaced by the type its name references.

  4. If the declaration is a type, a subtype or a generic type, it becomes the symbol’s reference. A full type, which follows the place in the same region, is visible by its incomplete type declaration only to an access type.

An attribute name denoting a type (e.g. s'subtype, A'element) is resolved part by part (Denote()); the type it denotes becomes the symbol’s reference.

Parameters:
Raises:

UnhandledCriticalWarningError – If the type mark isn’t visible, is ambiguous, has a prefix, which isn’t a visible package, denotes no type, or denotes an incomplete type outside of an access type, and no WarningCollector collects the UnresolvedTypeMarkWarning.

Return type:

None

property SharedVariables: dict[str, SharedVariable]

Read-only property to access the shared variables (_sharedVariables).

Returns:

Dictionary of shared variables, indexed by normalized identifier.

property Signals: dict[str, Signal]

Read-only property to access the signals (_signals).

Returns:

Dictionary of signals, indexed by normalized identifier.

SplitDeclaredItem(declaredItem)

Split a declared item with an identifier list into one declaration per identifier.

The declared item keeps its first identifier. For every other identifier, a new declaration is created by its Copy() and inserted right after it, in list order; its parent is set to this declarative region. If the region is indexed, the namespace and lookup table entries of the other identifiers refer to the new declarations; they are checked before anything is changed. A declared item declaring one identifier is unchanged.

Parameters:

declaredItem (ModelEntity) – The declared item to split.

Return type:

tuple[ModelEntity, ...]

Returns:

Tuple of declarations, one per identifier in list order, starting with the split declared item.

Raises:
  • ValueError – If parameter ‘declaredItem’ is None.

  • TypeError – If parameter ‘declaredItem’ is not of type ModelEntity.

  • NotAChildError – If parameter ‘declaredItem’ is not a declared item of this declarative region.

  • NotInNamespaceError – If the region is indexed, and an identifier of the declared item refers to another declaration, e.g. a duplicate declaration.

See also

Split()

→ Split a declaration with an identifier list.

RemoveDeclaredItem()

→ Remove a declared item from the declarative region.

property Subtypes: dict[str, Subtype]

Read-only property to access the subtypes (_subtypes).

Returns:

Dictionary of subtypes, indexed by normalized identifier.

property Types: dict[str, FullType]

Read-only property to access the types (_types).

Returns:

Dictionary of types, indexed by normalized identifier.

Visit(visitor)[source]

Walk this package body, its context clause and its declared items with a visitor.

Parameters:

visitor (Visitor) – The visitor receiving the events.

Return type:

None

_AddOverloadToNamespace(item)

Add a function or procedure to the namespace, if it’s the overload declared last.

The namespace keeps one entry per identifier: the overload declared last, as after IndexDeclaredItems(), which adds interface items first, then declared items (_Declarations()).

Parameters:

item (NamedEntityMixin | MultipleNamedEntityMixin) – The function or procedure, already an interface item or declared item of this region.

Return type:

None

_AddToNamespace(element)

Add an element’s identifiers to this region’s namespace.

Nothing is added to a region not indexed yet: IndexDeclaredItems() adds the element later. A generic subprogram is an overload (_AddOverloadToNamespace()).

Parameters:

element (NamedEntityMixin | MultipleNamedEntityMixin) – The named element to add, e.g. an interface item.

Return type:

None

_CONTINUES_PARENT_REGION: ClassVar[bool] = True

A package body continues its package’s declarative region.

_ClashingDeclarations(item)

Return the declarations sharing an identifier with the given item, which may not share it.

The declarations (_Declarations()) and the labeled statements (_Labels()) of this declarative region and of the language constructs sharing it (_SharedRegions()) are searched: a statement label is declared implicitly. Items imported into the namespace (e.g. by a use clause) are no declarations.

Parameters:

item (ModelEntity) – The new declaration, or the new labeled statement.

Return type:

tuple[ModelEntity, ...]

Returns:

Tuple of clashing declarations, interface items first, then declared items in declaration order, then labeled statements.

_ConnectParentNamespace(parent)

Connect this region’s namespace to the namespace of the enclosing declarative region.

A declaration of this region then hides a same-named declaration of the enclosing region. A parent, which isn’t a declarative region (e.g. a subprogram of an interface list), has no namespace to connect to.

Parameters:

parent (ModelEntity) – The new parent of this region.

Return type:

None

_ContextClauseUnits()[source]

Return the design units whose context clause applies to this package body.

Return type:

tuple[DesignUnit, ...]

Returns:

Tuple of this package body and its package, if linked.

_DECLARED_ITEM_TYPES = (<class 'pyVHDLModel.Type.BaseType'>, <class 'pyVHDLModel.Subprogram.Subprogram'>, <class 'pyVHDLModel.DesignUnit.Package'>, <class 'pyVHDLModel.DesignUnit.PackageBody'>, <class 'pyVHDLModel.Object.Constant'>, <class 'pyVHDLModel.Object.Signal'>, <class 'pyVHDLModel.Object.SharedVariable'>, <class 'pyVHDLModel.Object.File'>, <class 'pyVHDLModel.Declaration.Alias'>, <class 'pyVHDLModel.DesignUnit.Component'>, <class 'pyVHDLModel.Declaration.Attribute'>, <class 'pyVHDLModel.Declaration.AttributeSpecification'>, <class 'pyVHDLModel.Configuration.ComponentConfiguration'>, <class 'pyVHDLModel.Interface.ModeViewDeclaration'>, <class 'pyVHDLModel.DesignUnit.UseClause'>, <class 'pyVHDLModel.PSLModel.PSLEntity'>)

Accepted classes of declared items (pyVHDLModel).

_Declarations()

Return all declarations of this declarative region.

A host class with interface items extends the list by its interface items, listed first.

Return type:

tuple[ModelEntity, ...]

Returns:

Tuple of declarations: the declared items, in declaration order.

_DeclaredItemsSharingIdentifiers(declaredItem)

Return the other declared items of this region sharing an identifier with the given declared item.

Parameters:

declaredItem (ModelEntity) – The declared item.

Return type:

list[ModelEntity]

Returns:

List of declared items, in declaration order.

_END_KEYWORDS: ClassVar[tuple[ReservedWord, ...]] = (ReservedWord.Package, ReservedWord.Body)

Reserved words after end.

_END_KEYWORDS_OPTIONAL: ClassVar[bool] = True

The reserved words after end are optional.

_IMPLICIT_LIBRARIES = ('work', 'std')

Library names visible without a library clause.

_IndexDeclaredItem(item)

Add a declared item to the namespace and to the lookup table matching its kind.

Parameters:

item (ModelEntity) – The declared item.

Return type:

None

_IndexOtherDeclaredItem(item)

Hook for declared items the region doesn’t handle itself. Derived classes may override it.

An alias, an attribute declaration and a package (also a package instantiation) declared in the region are added to the namespace, without a lookup table.

Parameters:

item (ModelEntity) – The declared item.

Return type:

None

_IndexOverload(item)

Add an inserted function or procedure to its lookup table and to the namespace.

The list of overloads follows the declaration order. The namespace is updated by _AddOverloadToNamespace().

Parameters:

item (NamedEntityMixin | MultipleNamedEntityMixin) – The inserted function or procedure.

Return type:

None

_IterateStatementRegions()

Iterate the declarative regions nested in the statements of this declarative region.

Return type:

Generator[DeclarativeRegionMixin]

Returns:

An empty generator.

_Labels()

Return the labeled statements, whose labels are declared in this declarative region.

Return type:

tuple[ModelEntity, ...]

Returns:

An empty tuple.

_MayShareIdentifier(item, existing)

Check if two declarations may share an identifier in one declarative region.

Subprograms are overloadable. A protected type body completes its protected type, a full type completes its incomplete type, and a constant completes its deferred constant.

Parameters:
Return type:

bool

Returns:

True, if both declarations may share an identifier.

_RemoveDeclaredItemEntries(lookupTable, item)

Remove a declared item’s entries from a lookup table and from the namespace.

Every identifier is checked before anything is removed.

Parameters:
Raises:
  • NotInNamespaceError – If an identifier of the declared item isn’t declared in the namespace.

  • NotInNamespaceError – If an identifier of the declared item refers to another element, e.g. a duplicate declaration.

Return type:

None

_RemoveDeclaredItemsFromNamespace()

Remove all declared items of this region from its namespace.

Interface items of this region and items imported from elsewhere (e.g. by a use clause) are kept.

Return type:

None

_RemoveFromNamespace(element)

Remove an element’s identifiers from this region’s namespace.

Nothing is removed from a region not indexed yet, as its namespace doesn’t contain the element. A generic subprogram is an overload (_RemoveOverloadFromNamespace()).

Parameters:

element (NamedEntityMixin | MultipleNamedEntityMixin) – The named element to remove, e.g. an interface item.

Raises:
  • NotInNamespaceError – If the region is indexed, and an identifier of the element isn’t declared in the namespace.

  • NotInNamespaceError – If the region is indexed, and an identifier of the element refers to another element, e.g. a duplicate declaration.

Return type:

None

_RemoveOverloadFromNamespace(item)

Remove a function or procedure from the namespace.

Removing the overload the namespace refers to, the namespace refers to the remaining overload declared last (_Declarations()), or the identifier is removed, if no overload remains. Removing another overload leaves the namespace unchanged. The namespace is checked before it’s changed.

Parameters:

item (NamedEntityMixin | MultipleNamedEntityMixin) – The function or procedure, still an interface item or declared item of this region.

Raises:
  • NotInNamespaceError – If the identifier isn’t declared in the namespace.

  • NotInNamespaceError – If the identifier refers to an element, which is no overload, e.g. a duplicate declaration.

Return type:

None

_SharedRegions()[source]

Return the other language constructs forming one declarative region with this package body.

Return type:

tuple[ConcurrentDeclarationRegionMixin, ...]

Returns:

Tuple of the package, if linked.

_UnindexDeclaredItem(item)

Remove a declared item from the namespace and from the lookup table matching its kind.

Parameters:

item (ModelEntity) – The declared item.

Return type:

None

_UnindexOtherDeclaredItem(item)

Hook to remove declared items the region doesn’t handle itself. Derived classes may override it.

An alias, an attribute declaration and a package are removed from the namespace.

Parameters:

item (ModelEntity) – The declared item.

Raises:

NotInNamespaceError – If the item is an alias, an attribute declaration or a package, which isn’t declared in the namespace.

Return type:

None

_UnindexOverload(item)

Remove a function or procedure from its lookup table and from the namespace.

The namespace is updated first, by _RemoveOverloadFromNamespace().

Parameters:

item (NamedEntityMixin | MultipleNamedEntityMixin) – The function or procedure to remove, still a declared item of this region.

Raises:
  • NotInNamespaceError – If the identifier isn’t declared in the namespace.

  • NotInNamespaceError – If the identifier refers to an element, which is no overload, e.g. a duplicate declaration.

Return type:

None

_VisitContextClause(visitor)

Walk the context clause, i.e. the context items preceding the design unit, with a visitor.

The context clause is reported, even if it has no context items.

Parameters:

visitor (Visitor) – The visitor receiving the events.

Return type:

None

_VisitDeclaredItems(visitor)

Walk the declared items in declaration order with a visitor.

Parameters:

visitor (Visitor) – The visitor receiving the events.

Return type:

None

__getstate__()

Return the object’s state for pickling, collecting every slot of the class hierarchy.

Return type:

dict[str, Any]

Returns:

Dictionary of slot names and their values.

Raises:

ExtendedTypeError – If a slot was never assigned, so it has no value to serialize.

__new__(**kwargs)
__repr__()[source]

Formats a representation of the package body declaration.

Format: mylib.myPackage(body)

Return type:

str

Returns:

String representation of the package body declaration.

__setstate__(state)

Restore the object’s state from unpickling, requiring exactly the slots of the class hierarchy.

Parameters:

state (dict[str, Any]) – Dictionary of slot names and their values.

Raises:

ExtendedTypeError – If the given state misses a slot or carries an unexpected one.

Return type:

None

__str__()[source]

Formats the package body declaration.

Format: Package Body: mylib.myPackage(body)

Return type:

str

Returns:

Formatted package body declaration.

_areDeclaredItemsIndexed

True if IndexDeclaredItems() filled the namespace.

_components

Dictionary of all components declared in this concurrent declaration region.

_constants

Dictionary of all constants declared in this concurrent declaration region.

_contextItems

List of all context items (library, use and context clauses).

_contextReferences

List of context clauses.

_declaredItems

List of all declared items in this concurrent declaration region.

_dependencyVertex

Reference to the vertex in the dependency graph representing the design unit.
This reference is set by CreateDependencyGraph().

_document

The VHDL library, the design unit was analyzed into.

_documentation

The associated documentation of a model entity.

_files

Dictionary of all files declared in this concurrent declaration region.

_functions

Dictionary of all functions declared in this concurrent declaration region, indexed by name; each entry is a list of overloads.

_hierarchyVertex

The vertex in the hierarchy graph

_identifier

The identifier of a model entity.

_libraryReferences

List of library clauses.

_namespace

The namespace of this concurrent declaration region.

_normalizedIdentifier

The normalized (lower case) identifier of a model entity.

_package: PackageSymbol

Reference to the package this body implements.

_packageReferences

List of use clauses.

_parent

Reference to a parent entity in the logical model hierarchy.

_procedures

Dictionary of all procedures declared in this concurrent declaration region, indexed by name; each entry is a list of overloads.

_referencedContexts

Referenced contexts based on explicit context references or implicit inheritance

_referencedLibraries

Referenced libraries based on explicit library clauses or implicit inheritance

_referencedPackages

Referenced packages based on explicit use clauses or implicit inheritance

_sharedVariables

Dictionary of all shared variables declared in this concurrent declaration region.

_signals

Dictionary of all signals declared in this concurrent declaration region.

_subtypes

Dictionary of all subtypes declared in this concurrent declaration region.

_types

Dictionary of all types declared in this concurrent declaration region.

class pyGHDL.dom.DesignUnit.PackageInstantiation(node, identifier, uninstantiatedPackageName, contextItems=None, genericAssociationItems=None, documentation=None)[source]

This class implements a pyGHDL.dom object derived from pyVHDLModel.Instantiation.PackageInstantiation.

Represents the instantiation of a generic package.

Example

package p is new gp generic map (N => 1);
--      ^                                   <- Identifier
--               ^^                         <- PackageReference

Inheritance

Inheritance diagram of PackageInstantiation

Parameters:
  • node (Iir)

  • identifier (str)

  • uninstantiatedPackageName (Symbol)

  • contextItems (Iterable[VHDLModel_ContextUnion])

  • genericAssociationItems (Iterable[VHDLModel_GenericAssociationItem])

  • documentation (str)

__init__(node, identifier, uninstantiatedPackageName, contextItems=None, genericAssociationItems=None, documentation=None)[source]

Initializes a package instantiation.

Parameters:
  • node (Iir) – The IIR node this object was translated from.

  • identifier (str) – The instantiated package’s identifier.

  • uninstantiatedPackageName (Symbol) – The name of the uninstantiated generic package.

  • contextItems (Iterable[LibraryClause | UseClause | ContextReference]) – Optional, list of all context items (library, use and context clauses).

  • genericAssociationItems (Iterable[GenericAssociationItem]) – Optional, list of all generic associations in the generic map aspect.

  • documentation (str) – Optional, the documentation comment associated with this declaration.

Return type:

None

classmethod parse(packageNode, contextItems=None)[source]

Translates the IIR node of the package declaration to a PackageInstantiation.

Parameters:
Returns:

The translated package declaration.

_iirNode

The IIR node in libghdl’s tree this DOM object was translated from.

_position

The IIR node’s position in the source file, resolved on first access and then cached.

AddContextItem(contextItem)

Add a context item at the end of the context clause.

The context item’s parent is set to this design unit. A library clause is also added to LibraryReferences, a use clause to PackageReferences and a context reference to ContextReferences, in the order of ContextItems. A context item may repeat an earlier one.

Parameters:

contextItem (LibraryClause | UseClause | ContextReference) – The library clause, use clause or context reference to add.

Raises:
Return type:

None

Attention

The mutator doesn’t update what Analyze() derived from the context items: the referenced libraries, packages and contexts (ReferencedLibraries, ReferencedPackages, ReferencedContexts), the namespace entries of a use clause, the edges of the dependency graph, and the references of the symbols. A design changed after its analysis needs a new analysis.

See also

InsertContextItem()

→ Insert a context item at a position of the context clause.

RemoveContextItem()

→ Remove a context item from the context clause.

AddDeclaredItem(declaredItem)

Add a declared item at the end of the declarative region.

The declared item’s parent is set to this declarative region. If the region is indexed, its identifiers are added to the region’s namespace and to the lookup table matching its kind.

Parameters:

declaredItem (ModelEntity) – The declared item to add.

Raises:
  • ValueError – If parameter ‘declaredItem’ is None.

  • TypeError – If parameter ‘declaredItem’ is not a declaration allowed in this declarative region.

  • AlreadyInDesignError – If parameter ‘declaredItem’ already has a parent.

  • DuplicateDeclarationError – If an existing declaration of the declarative region shares an identifier with the declared item.

Return type:

None

See also

InsertDeclaredItem()

→ Insert a declared item at a position of the declarative region.

RemoveDeclaredItem()

→ Remove a declared item from the declarative region.

AddGenericAssociationItem(genericAssociationItem)

Add a generic association at the end of the generic map aspect.

The association’s parent is set to this language construct.

Parameters:

genericAssociationItem (GenericAssociationItem) – The generic association to add.

Raises:
  • ValueError – If parameter ‘genericAssociationItem’ is None.

  • TypeError – If parameter ‘genericAssociationItem’ is not of type GenericAssociationItem.

  • AlreadyInDesignError – If parameter ‘genericAssociationItem’ already has a parent.

  • DuplicateGenericAssociationError – If the association is named, and another named association of the generic map aspect has the same formal.

  • AssociationOrderError – If the association is positional, and the generic map aspect has a named association.

Return type:

None

See also

InsertGenericAssociationItem()

→ Insert a generic association at a position of the generic map aspect.

RemoveGenericAssociationItem()

→ Remove a generic association from the generic map aspect.

AddGenericItem(genericItem, group=None)

Add a generic at the end of the generic clause, or at the end of a generic group.

The generic’s parent is set to this language construct, and its identifiers are added to the language construct’s namespace, if it has one. Without a generic group, the generic joins the last generic group, or forms a new unnamed generic group if there are no generics.

Parameters:
  • genericItem (GenericInterfaceItemMixin) – The generic to add.

  • group (GenericGroup | None) – Optional, the generic group of this language construct to add the generic to, at its end. Default: None, the end of the generic clause.

Raises:
  • ValueError – If parameter ‘genericItem’ is None.

  • TypeError – If parameter ‘genericItem’ is not of type GenericInterfaceItemMixin.

  • AlreadyInDesignError – If parameter ‘genericItem’ already has a parent.

  • TypeError – If parameter ‘group’ is not of type GenericGroup.

  • NotAChildError – If parameter ‘group’ is not a generic group of this language construct.

  • DuplicateGenericError – If an existing declaration of the language construct shares an identifier with the generic.

Return type:

None

See also

InsertGenericItem()

→ Insert a generic at a position of the generic clause.

RemoveGenericItem()

→ Remove a generic from the generic clause.

property AllowBlackbox: bool

Property to return whether a design supports blackboxes, inherited from the parent if not set locally (_allowBlackbox).

Algorithm

  1. If allow blackbox property is locally set, return the local value,

  2. Otherwise, return allow blackbox value from parent object.

Returns:

True, if blackboxes are allowed.

Raises:

AllowBlackboxNotSetError – If neither a local value is set nor a parent object is available to inherit the value from.

Setter accepts:

bool | None

property Components: dict[str, Component]

Read-only property to access the components (_components).

Returns:

Dictionary of components, indexed by normalized identifier.

property Constants: dict[str, Constant]

Read-only property to access the constants (_constants).

Returns:

Dictionary of constants, indexed by normalized identifier.

property ContextItems: list[LibraryClause | UseClause | ContextReference]

Read-only property to access the sequence of all context items comprising library, use and context clauses (_contextItems).

Returns:

Sequence of context items.

property ContextReferences: list[ContextReference]

Read-only property to access the sequence of context clauses (_contextReferences).

Returns:

Sequence of context clauses.

property DeclaredItems: list

Read-only property to access the declared items (_declaredItems).

Returns:

List of declared items.

property DeferredConstants: dict[str, DeferredConstant]

Read-only property to access the deferred constants (_deferredConstants).

Returns:

Dictionary of deferred constants, indexed by normalized identifier.

DenoteBy(name, region, place, symbol)

Return this package, the model entity a name in a type mark denotes.

Parameters:
  • name (Name) – The name denoting this declaration, a part of the type mark.

  • region (DeclarativeRegionMixin) – The declarative region containing the type mark.

  • place (ModelEntity) – The declaration containing the type mark.

  • symbol (Symbol) – The type mark.

Return type:

ModelEntity | None

Returns:

This package.

property DependencyVertex: Vertex

Read-only property to access the corresponding dependency vertex (_dependencyVertex).

The dependency vertex references this design unit by its value field.

Returns:

The corresponding dependency vertex.

property Document: Document

Property to access the document (_document).

Returns:

The document.

property Documentation: str | None

Read-only property to access the model entity’s documentation (_documentation).

Returns:

Associated documentation of a model entity.

property Files: dict[str, File]

Read-only property to access the files (_files).

Returns:

Dictionary of files, indexed by normalized identifier.

property Functions: dict[str, list[Function]]

Read-only property to access the functions (_functions).

Returns:

Dictionary of functions, indexed by normalized identifier; each entry is a list of overloads.

property GenericAssociationItems: list[GenericAssociationItem]

Read-only property to access the generic associations (_genericAssociationItems).

Returns:

List of generic association items.

property GenericCount: int

Read-only property to return the number of generics declared by _genericItems.

A generic constant item with several identifiers (generic (A, B : natural)) declares several generics.

Returns:

The number of generics.

property GenericGroups: list[GenericGroup]

Read-only property to access the generic groups (_genericGroups).

The generic groups partition the generic clause: concatenated in order, they list every generic exactly once, in declaration order.

Returns:

List of generic groups, in declaration order.

property GenericItems: list[GenericInterfaceItemMixin]

Read-only property to access the generic items (_genericItems).

Returns:

List of generic items.

GetAncestor(type)

Return the closest ancestor of the given type found by walking the parent chain upwards.

Iterates the parent chain - starting at this model entity - upwards (toward the root of the model) until an ancestor of the requested type is found.

Parameters:

type (Type) – Class (type) of the ancestor to find.

Return type:

ModelEntity

Returns:

The closest ancestor of the requested type.

Raises:

AncestorNotFoundError – If the root of the model is reached without finding an ancestor of the requested type.

GetIdentifier(normalizedIdentifier)

Return the identifier as declared, for the model entity’s normalized identifier.

Parameters:

normalizedIdentifier (str) – The model entity’s normalized (lower case) identifier.

Return type:

str

Returns:

The identifier in its declared spelling.

classmethod GetMethodsWithAttributes(predicate=None)

Return the class’ methods that carry at least one matching attribute.

Parameters:

predicate (type[TAttr] | Iterable[type[TAttr]] | None) – Optional, an attribute class, an iterable of attribute classes, or None to accept every attribute.

Return type:

dict[Callable[..., Any], tuple[Attribute, ...]]

Returns:

Dictionary of methods and the matching attributes attached to them.

Raises:
  • ValueError – If an element of parameter ‘predicate’ is not a sub-class of Attribute.

  • ValueError – If parameter ‘predicate’ is neither an attribute class nor an iterable of those.

property HierarchyVertex: Vertex

Read-only property to access the corresponding hierarchy vertex (_hierarchyVertex).

The hierarchy vertex references this design unit by its value field.

Returns:

The corresponding hierarchy vertex.

property Identifier: str

Read-only property to access the model entity’s identifier (_identifier).

Returns:

Name of a model entity.

IndexDeclaredItems()

A generic package’s generics share the declarative region of its declarative part.

Raises:

UnhandledCriticalWarningError – If an identifier is declared twice in a declarative region and no WarningCollector collects the DuplicateDeclarationWarning.

Return type:

None

InsertContextItem(index, contextItem)

Insert a context item at a position of the context clause.

The context item’s parent is set to this design unit. A library clause is also added to LibraryReferences, a use clause to PackageReferences and a context reference to ContextReferences, in the order of ContextItems. A context item may repeat an earlier one.

Parameters:
  • index (int) – Position, from 0 (first) to the number of context items (append). A negative index counts from the end, as for list.insert(): -1 inserts before the last context item.

  • contextItem (LibraryClause | UseClause | ContextReference) – The library clause, use clause or context reference to insert.

Raises:
Return type:

None

Attention

The mutator doesn’t update what Analyze() derived from the context items: the referenced libraries, packages and contexts (ReferencedLibraries, ReferencedPackages, ReferencedContexts), the namespace entries of a use clause, the edges of the dependency graph, and the references of the symbols. A design changed after its analysis needs a new analysis.

See also

AddContextItem()

→ Add a context item at the end of the context clause.

RemoveContextItem()

→ Remove a context item from the context clause.

InsertDeclaredItem(index, declaredItem)

Insert a declared item at a position of the declarative region.

The declared item’s parent is set to this declarative region. If the region is indexed, its identifiers are added to the region’s namespace and to the lookup table matching its kind.

An identifier is declared once per declarative region: interface items and declared items count, including those of the language construct sharing the declarative region (an entity and its architecture, a package and its body). Subprograms are overloadable: a subprogram may share its identifier with other subprograms. A protected type body may share its identifier with its protected type, a full type with its incomplete type declaration, and a constant with its deferred constant. Items imported into the namespace (e.g. by a use clause) are hidden.

Parameters:
  • index (int) – Position, from 0 (first) to the number of declared items (append). A negative index counts from the end, as for list.insert(): -1 inserts before the last declared item.

  • declaredItem (ModelEntity) – The declared item to insert.

Raises:
  • ValueError – If parameter ‘index’ is None.

  • TypeError – If parameter ‘index’ is not of type int.

  • ValueError – If parameter ‘index’ is out of range.

  • ValueError – If parameter ‘declaredItem’ is None.

  • TypeError – If parameter ‘declaredItem’ is not a declaration allowed in this declarative region.

  • AlreadyInDesignError – If parameter ‘declaredItem’ already has a parent.

  • DuplicateDeclarationError – If an existing declaration of the declarative region shares an identifier with the declared item.

Return type:

None

See also

AddDeclaredItem()

→ Add a declared item at the end of the declarative region.

InsertDeclaredItemBefore()

→ Insert a declared item before another declared item.

InsertDeclaredItemAfter()

→ Insert a declared item after another declared item.

RemoveDeclaredItem()

→ Remove a declared item from the declarative region.

MoveDeclaredItem()

→ Move a declared item to a position of the declarative region.

InsertDeclaredItemAfter(declaredItem, after)

Insert a declared item after another declared item.

The declared item’s parent is set to this declarative region. If the region is indexed, its identifiers are added to the region’s namespace and to the lookup table matching its kind.

Parameters:
  • declaredItem (ModelEntity) – The declared item to insert.

  • after (ModelEntity) – The declared item of this declarative region to insert after.

Raises:
  • ValueError – If parameter ‘declaredItem’ is None.

  • TypeError – If parameter ‘declaredItem’ is not a declaration allowed in this declarative region.

  • AlreadyInDesignError – If parameter ‘declaredItem’ already has a parent.

  • ValueError – If parameter ‘after’ is None.

  • TypeError – If parameter ‘after’ is not of type ModelEntity.

  • NotAChildError – If parameter ‘after’ is not a declared item of this declarative region.

  • DuplicateDeclarationError – If an existing declaration of the declarative region shares an identifier with the declared item.

Return type:

None

See also

InsertDeclaredItem()

→ Insert a declared item at a position of the declarative region.

InsertDeclaredItemBefore()

→ Insert a declared item before another declared item.

InsertDeclaredItemBefore(declaredItem, before)

Insert a declared item before another declared item.

The declared item’s parent is set to this declarative region. If the region is indexed, its identifiers are added to the region’s namespace and to the lookup table matching its kind.

Parameters:
  • declaredItem (ModelEntity) – The declared item to insert.

  • before (ModelEntity) – The declared item of this declarative region to insert before.

Raises:
  • ValueError – If parameter ‘declaredItem’ is None.

  • TypeError – If parameter ‘declaredItem’ is not a declaration allowed in this declarative region.

  • AlreadyInDesignError – If parameter ‘declaredItem’ already has a parent.

  • ValueError – If parameter ‘before’ is None.

  • TypeError – If parameter ‘before’ is not of type ModelEntity.

  • NotAChildError – If parameter ‘before’ is not a declared item of this declarative region.

  • DuplicateDeclarationError – If an existing declaration of the declarative region shares an identifier with the declared item.

Return type:

None

See also

InsertDeclaredItem()

→ Insert a declared item at a position of the declarative region.

InsertDeclaredItemAfter()

→ Insert a declared item after another declared item.

InsertGenericAssociationItem(index, genericAssociationItem)

Insert a generic association at a position of the generic map aspect.

The association’s parent is set to this language construct.

A named association (formal => actual) can’t repeat the formal of another named association of the generic map aspect. Only formals given as a simple name are compared: a partial association (a(0) => x) or a conversion function (to_integer(a) => x) is accepted. All positional associations precede the named associations.

Parameters:
  • index (int) – Position, from 0 (first) to the number of generic associations (append). A negative index counts from the end, as for list.insert(): -1 inserts before the last generic association.

  • genericAssociationItem (GenericAssociationItem) – The generic association to insert.

Raises:
  • ValueError – If parameter ‘index’ is None.

  • TypeError – If parameter ‘index’ is not of type int.

  • ValueError – If parameter ‘index’ is out of range.

  • ValueError – If parameter ‘genericAssociationItem’ is None.

  • TypeError – If parameter ‘genericAssociationItem’ is not of type GenericAssociationItem.

  • AlreadyInDesignError – If parameter ‘genericAssociationItem’ already has a parent.

  • DuplicateGenericAssociationError – If the association is named, and another named association of the generic map aspect has the same formal.

  • AssociationOrderError – If the association is positional, and a named association precedes the position.

  • AssociationOrderError – If the association is named, and a positional association follows the position.

Return type:

None

See also

AddGenericAssociationItem()

→ Add a generic association at the end of the generic map aspect.

RemoveGenericAssociationItem()

→ Remove a generic association from the generic map aspect.

InsertGenericItem(index, genericItem, group=None)

Insert a generic at a position of the generic clause.

The generic’s parent is set to this language construct, and its identifiers are added to the language construct’s namespace, if it has one.

Without a generic group, the generic joins the generic group of the generic before index; at index 0, the generic group of the first generic. If there are no generics, the generic forms a new unnamed generic group. A generic group given must contain index or end at it, so the generic groups stay contiguous.

Parameters:
  • index (int) – Position, from 0 (first) to the length of GenericItems (append). A negative index counts from the end, as for list.insert(): -1 inserts before the last generic.

  • genericItem (GenericInterfaceItemMixin) – The generic to insert.

  • group (GenericGroup | None) – Optional, the generic group of this language construct to insert the generic into. Default: None, the generic group of the generic before index.

Raises:
  • ValueError – If parameter ‘index’ is None.

  • TypeError – If parameter ‘index’ is not of type int.

  • ValueError – If parameter ‘index’ is out of range.

  • ValueError – If parameter ‘genericItem’ is None.

  • TypeError – If parameter ‘genericItem’ is not of type GenericInterfaceItemMixin.

  • AlreadyInDesignError – If parameter ‘genericItem’ already has a parent.

  • TypeError – If parameter ‘group’ is not of type GenericGroup.

  • NotAChildError – If parameter ‘group’ is not a generic group of this language construct.

  • ValueError – If parameter ‘group’ neither contains nor ends at parameter ‘index’.

  • DuplicateGenericError – If an existing declaration of the language construct shares an identifier with the generic.

Return type:

None

See also

AddGenericItem()

→ Add a generic at the end of the generic clause.

RemoveGenericItem()

→ Remove a generic from the generic clause.

MoveGenericItem()

→ Move a generic to a position of the generic clause.

Instantiate()[source]

Copy the components of the generic package into this package instantiation.

Raises:

PackageInstantiationNotLinkedError – If this package instantiation isn’t linked to its generic package.

Return type:

None

IsLibraryVisible(libraryIdentifier)

Check if the logical name of a library is visible in this design unit.

The name work is implicitly visible, the name std too, except in a context declaration. Every other name needs a library clause, also the real name of the working library. The library clause is searched in this design unit’s context clause, in the context clause of its primary unit, and in the contexts these reference, also in nested ones. The design unit must be in a library of a design.

Parameters:

libraryIdentifier (str) – The normalized identifier of the library.

Return type:

bool

Returns:

True, if the library’s name is visible.

property IsOverloadable: bool

Check if this model entity is an overloadable declaration: it may share its designator with other overloadable declarations.

Subprograms, enumeration literals and aliases, which may denote one of them, are overloadable; they override this property.

Returns:

True, if this model entity is an overloadable declaration.

IterateDeclarationRegions()

Iterate this declarative region and all declarative regions nested in it.

Nested regions are declarations (e.g. subprograms, generic subprograms, protected types, packages) and concurrent statements (blocks, processes, generate statements and their branches), each followed by the regions nested in it.

Return type:

Generator[DeclarativeRegionMixin]

Returns:

A generator to iterate the declarative regions, this region first.

IterateDeclarations()[source]

Iterate the declarations of the instantiated generic package a use clause can make potentially visible.

Return type:

Generator[tuple[str, ModelEntity]]

Returns:

A generator to iterate (normalized designator, declaration) pairs, in declaration order.

Raises:

PackageInstantiationNotLinkedError – If this package instantiation isn’t linked to its generic package.
Call LinkPackageInstances() before linking use clauses.

IterateImplicitDeclarations()

Iterate the declarations this declaration implies.

An enumerated type implies its enumeration literals, a physical type its units; they override this method.

Return type:

Generator[tuple[str, ModelEntity]]

Returns:

A generator to iterate (normalized designator, declaration) pairs, in declaration order: none.

IterateMemberDeclarations(memberIdentifier)

Iterate the declarations of this package a use clause naming one package member makes potentially visible.

These are the declarations of the package with the member’s identifier, e.g. all overloads of a subprogram. A type brings its enumeration literals or physical units along (IEEE Std 1076-2008, 12.4), a subtype those of its base type: the known base type, else the type its type marks lead to, followed by simple names in the package.

Parameters:

memberIdentifier (str) – The normalized (lower case) identifier of the package member.

Return type:

Generator[tuple[str, ModelEntity]]

Returns:

A generator to iterate (normalized designator, declaration) pairs, in declaration order.

IterateSingleGenericDeclarations(predicate=None)

Iterate all generics per declared identifier, in declaration order.

A generic constant yields one single declaration per identifier: generic (A, B : positive) yields two. A generic type, subprogram or package declares exactly one identifier and is yielded itself.

Parameters:

predicate (Callable[[SingleGenericDeclarationMixin | GenericInterfaceItemMixin], bool] | None) – Optional, filter function to select the yielded generics. Default: all.

Return type:

Generator[SingleGenericDeclarationMixin | GenericInterfaceItemMixin]

Returns:

A generator to iterate all (selected) generics.

IterateTypeMarks(region)

Iterate the type marks of this declaration, each with the region and the place to look it up.

The place of a type mark is the declaration containing it. Declarations with type marks override this method, e.g. an object yields the type mark of its subtype indication, an array type its index and element subtypes.

Parameters:

region (DeclarativeRegionMixin) – The declarative region declaring this declaration.

Return type:

Generator[tuple[DeclarativeRegionMixin, ModelEntity, SubtypeSymbol]]

Returns:

A generator to iterate (region, place, type mark) tuples, in declaration order: none.

property Library: Library

Property to access the library (_parent).

Returns:

The library.

property LibraryReferences: list[LibraryClause]

Read-only property to access the sequence of library clauses (_libraryReferences).

Returns:

Sequence of library clauses.

LookupName(place, symbol, name, warningType)

Look up the declarations a simple name or an expanded name denotes at a place in this region.

A simple name is looked up at the place (Lookup()). An expanded name pkg.T or lib.pkg.T resolves its prefix: pkg to a package visible at the place, else to an enclosing declarative region of that name (e.g. the package or entity containing the place); lib.pkg by the library (work or a library whose name is visible in the design unit containing the place, IsLibraryVisible()) and the package’s name. Then the suffix is searched among the declarations of the package or region (FindDeclarations()).

A failure is reported as a warning of the given type, whose label names the kind of name in the message (e.g. Type mark); then no declaration is returned. A name, which is a part of the symbol’s name (e.g. the prefix s of the type mark s'subtype), is reported as a prefix of the symbol’s name.

Parameters:
  • place (ModelEntity) – The declaration containing the name.

  • symbol (Symbol) – The symbol containing the name.

  • name (Name) – The simple name or expanded name: the symbol’s name or a part of it.

  • warningType (type[UnresolvedNameWarning]) – The warning class reporting a failure.

Return type:

tuple[ModelEntity, ...]

Returns:

Tuple of the directly visible declarations, empty if none is.

Raises:

UnhandledCriticalWarningError – If the name isn’t visible, is ambiguous, or has a prefix, which isn’t a visible package or an enclosing region, and no WarningCollector collects the warning.

MoveDeclaredItem(declaredItem, index)

Move a declared item to a position of the declarative region.

The declared item stays a declared item of this declarative region: only the order of the declared items changes.

If the region is indexed, the lookup tables and the namespace follow the new order: a list of overloads (e.g. in Functions) follows the declaration order, and the namespace refers to the overload declared last. If another declaration shares an identifier with the declared item (e.g. a duplicate declaration read by a parser), the region is indexed again (IndexDeclaredItems()) after the move.

Parameters:
  • declaredItem (ModelEntity) – The declared item to move.

  • index (int) – Position of the declared item after the move, from 0 (first) to the number of declared items minus one (last). A negative index counts from the end, as for a list index: -1 moves the declared item to the end.

Raises:
  • ValueError – If parameter ‘declaredItem’ is None.

  • TypeError – If parameter ‘declaredItem’ is not of type ModelEntity.

  • NotAChildError – If parameter ‘declaredItem’ is not a declared item of this declarative region.

  • ValueError – If parameter ‘index’ is None.

  • TypeError – If parameter ‘index’ is not of type int.

  • ValueError – If parameter ‘index’ is out of range.

Return type:

None

See also

MoveDeclaredItemBefore()

→ Move a declared item before another declared item.

MoveDeclaredItemAfter()

→ Move a declared item after another declared item.

InsertDeclaredItem()

→ Insert a declared item at a position of the declarative region.

RemoveDeclaredItem()

→ Remove a declared item from the declarative region.

MoveDeclaredItemAfter(declaredItem, after)

Move a declared item after another declared item.

The declared item stays a declared item of this declarative region: only the order of the declared items changes, as for MoveDeclaredItem(). Moving a declared item after itself keeps it in place.

Parameters:
  • declaredItem (ModelEntity) – The declared item to move.

  • after (ModelEntity) – The declared item of this declarative region to move after.

Raises:
  • ValueError – If parameter ‘declaredItem’ is None.

  • TypeError – If parameter ‘declaredItem’ is not of type ModelEntity.

  • NotAChildError – If parameter ‘declaredItem’ is not a declared item of this declarative region.

  • ValueError – If parameter ‘after’ is None.

  • TypeError – If parameter ‘after’ is not of type ModelEntity.

  • NotAChildError – If parameter ‘after’ is not a declared item of this declarative region.

Return type:

None

See also

MoveDeclaredItem()

→ Move a declared item to a position of the declarative region.

MoveDeclaredItemBefore()

→ Move a declared item before another declared item.

MoveDeclaredItemBefore(declaredItem, before)

Move a declared item before another declared item.

The declared item stays a declared item of this declarative region: only the order of the declared items changes, as for MoveDeclaredItem(). Moving a declared item before itself keeps it in place.

Parameters:
  • declaredItem (ModelEntity) – The declared item to move.

  • before (ModelEntity) – The declared item of this declarative region to move before.

Raises:
  • ValueError – If parameter ‘declaredItem’ is None.

  • TypeError – If parameter ‘declaredItem’ is not of type ModelEntity.

  • NotAChildError – If parameter ‘declaredItem’ is not a declared item of this declarative region.

  • ValueError – If parameter ‘before’ is None.

  • TypeError – If parameter ‘before’ is not of type ModelEntity.

  • NotAChildError – If parameter ‘before’ is not a declared item of this declarative region.

Return type:

None

See also

MoveDeclaredItem()

→ Move a declared item to a position of the declarative region.

MoveDeclaredItemAfter()

→ Move a declared item after another declared item.

MoveGenericItem(genericItem, index)

Move a generic to a position of the generic clause.

The generic stays a generic of this language construct: only the order of the generic clause changes. A generic subprogram is an overload: if the language construct’s namespace is indexed, it refers to the overload declared last afterwards.

The generic leaves its generic group, like RemoveGenericItem(), and joins a generic group, like InsertGenericItem() without a generic group: the generic group of the generic before its new position; at index 0, the generic group of the first generic. A move to the generic’s current position changes nothing.

Parameters:
  • genericItem (GenericInterfaceItemMixin) – The generic to move.

  • index (int) – Position of the generic after the move, from 0 (first) to the length of GenericItems minus one (last). A negative index counts from the end, as for a list index: -1 moves the generic to the end.

Raises:
  • ValueError – If parameter ‘genericItem’ is None.

  • TypeError – If parameter ‘genericItem’ is not of type GenericInterfaceItemMixin.

  • NotAChildError – If parameter ‘genericItem’ is not a generic of this language construct.

  • ValueError – If parameter ‘index’ is None.

  • TypeError – If parameter ‘index’ is not of type int.

  • ValueError – If parameter ‘index’ is out of range.

  • NotInNamespaceError – If the namespace is indexed, and the identifier of a generic subprogram refers to an element, which is no overload, e.g. a duplicate declaration.

Return type:

None

See also

InsertGenericItem()

→ Insert a generic at a position of the generic clause.

RemoveGenericItem()

→ Remove a generic from the generic clause.

property NormalizedIdentifier: str

Read-only property to access the model entity’s normalized identifier (_normalizedIdentifier).

See also

Returns:

Normalized name of a model entity.

property PackageBody: PackageBody | None

Read-only property to access the package body (_packageBody).

Returns:

The package body, or None if not set.

property PackageReference: PackageReferenceSymbol

Read-only property to access the package reference (_packageReference).

Returns:

The package reference.

property PackageReferences: list[UseClause]

Read-only property to access the sequence of use clauses (_packageReferences).

Returns:

Sequence of use clauses.

property Parent: ModelEntity

Property to access the model entity’s parent element reference in a logical hierarchy (_parent).

Returns:

Reference to the parent entity.

property Position: Position

Cached read-only property to access an IIR’s position in source code (_position).

If _position is None, resolve the position object from _iirNode

Returns:

The IIR’s position in the source file.

Precedes(item, anchor, inclusive)

Check if an item precedes an anchor in this declarative region.

An item, which isn’t a declaration of this region (e.g. a use clause of the context clause), precedes every anchor.

Parameters:
  • item (ModelEntity | None) – The item in declaration order, or None for the implicit use clause.

  • anchor (ModelEntity) – A declaration of this region, e.g. the one containing the place of a lookup.

  • inclusive (bool) – True, if the anchor precedes itself, i.e. the place is nested inside the anchor.

Return type:

bool

Returns:

True, if the item precedes the anchor.

property Procedures: dict[str, list[Procedure]]

Read-only property to access the procedures (_procedures).

Returns:

Dictionary of procedures, indexed by normalized identifier; each entry is a list of overloads.

property ReferencedContexts: dict[str, Context]

Read-only property to access the referenced contexts (_referencedContexts).

Returns:

Dictionary of referenced contexts, indexed by normalized identifier.

property ReferencedLibraries: dict[str, Library]

Read-only property to access the referenced libraries (_referencedLibraries).

Returns:

Dictionary of referenced libraries, indexed by normalized identifier.

property ReferencedPackages: dict[str, Package]

Read-only property to access the referenced packages (_referencedPackages).

Returns:

Dictionary of referenced packages, indexed by normalized identifier.

RemoveContextItem(contextItem)

Remove a context item from the context clause.

The context item is detached: its parent is cleared, and it’s removed from ContextItems and from LibraryReferences, PackageReferences or ContextReferences. The context item itself is unchanged and can be added to another design unit, or inserted at another position.

Parameters:

contextItem (LibraryClause | UseClause | ContextReference) – The library clause, use clause or context reference to remove.

Raises:
Return type:

None

Attention

The mutator doesn’t update what Analyze() derived from the context items: the referenced libraries, packages and contexts (ReferencedLibraries, ReferencedPackages, ReferencedContexts), the namespace entries of a use clause, the edges of the dependency graph, and the references of the symbols. A design changed after its analysis needs a new analysis.

See also

AddContextItem()

→ Add a context item at the end of the context clause.

InsertContextItem()

→ Insert a context item at a position of the context clause.

RemoveDeclaredItem(declaredItem)

Remove a declared item from the declarative region.

The declared item is detached: its parent is cleared. If the region is indexed, the declared item’s identifiers are removed from the region’s namespace and from the lookup table matching its kind first; they are checked before anything is changed. The declared item itself is unchanged and can be added to another declarative region, or inserted at another position.

The namespace refers to the overload declared last: removing it, the namespace refers to the remaining overload declared last. If another declaration shares an identifier with the declared item (e.g. a duplicate declaration read by a parser), the region is indexed again (IndexDeclaredItems()) after the removal.

Parameters:

declaredItem (ModelEntity) – The declared item to remove.

Raises:
  • ValueError – If parameter ‘declaredItem’ is None.

  • TypeError – If parameter ‘declaredItem’ is not of type ModelEntity.

  • NotAChildError – If parameter ‘declaredItem’ is not a declared item of this declarative region.

  • NotInNamespaceError – If the region is indexed, and an identifier of the declared item isn’t declared in its namespace.

  • NotInNamespaceError – If the region is indexed, and an identifier of the declared item refers to another declaration, e.g. a duplicate declaration.

Return type:

None

See also

AddDeclaredItem()

→ Add a declared item at the end of the declarative region.

InsertDeclaredItem()

→ Insert a declared item at a position of the declarative region.

MoveDeclaredItem()

→ Move a declared item to a position of the declarative region.

RemoveGenericAssociationItem(genericAssociationItem)

Remove a generic association from the generic map aspect.

The association is detached: its parent is cleared. The association itself is unchanged and can be added to another language construct, or inserted at another position.

Parameters:

genericAssociationItem (GenericAssociationItem) – The generic association to remove.

Raises:
  • ValueError – If parameter ‘genericAssociationItem’ is None.

  • TypeError – If parameter ‘genericAssociationItem’ is not of type GenericAssociationItem.

  • NotAChildError – If parameter ‘genericAssociationItem’ is not a generic association of this language construct.

Return type:

None

See also

AddGenericAssociationItem()

→ Add a generic association at the end of the generic map aspect.

InsertGenericAssociationItem()

→ Insert a generic association at a position of the generic map aspect.

RemoveGenericItem(genericItem)

Remove a generic from the generic clause.

The generic is detached: its parent and generic group are cleared and its identifiers are removed from the language construct’s namespace, if it has one. A generic group, which becomes empty, is removed from GenericGroups and its parent is cleared. The generic itself is unchanged and can be added to another language construct, or inserted at another position.

Parameters:

genericItem (GenericInterfaceItemMixin) – The generic to remove.

Raises:
  • ValueError – If parameter ‘genericItem’ is None.

  • TypeError – If parameter ‘genericItem’ is not of type GenericInterfaceItemMixin.

  • NotAChildError – If parameter ‘genericItem’ is not a generic of this language construct.

  • NotInNamespaceError – If the namespace is indexed, and an identifier of the generic isn’t declared in it.

  • NotInNamespaceError – If the namespace is indexed, and an identifier of the generic refers to another element, e.g. a duplicate declaration.

Return type:

None

See also

AddGenericItem()

→ Add a generic at the end of the generic clause.

InsertGenericItem()

→ Insert a generic at a position of the generic clause.

MoveGenericItem()

→ Move a generic to a position of the generic clause.

ResetReferences(designUnit, region)

Reset the references ResolveReferences() derived: the references of this declaration’s type marks.

A use clause, an alias and a subtype extend this method.

Parameters:
  • designUnit (DesignUnit) – The design unit containing this declaration.

  • region (DeclarativeRegionMixin) – The declarative region declaring this declaration.

Return type:

None

ResolveReferences(designUnit, region)

Resolve the references of this declaration: its type marks (IterateTypeMarks()).

Each type mark is resolved at its place by the region it is looked up in (ResolveTypeMark()). An incomplete type, an alias and a subtype extend this method.

Parameters:
  • designUnit (DesignUnit) – The design unit containing this declaration.

  • region (DeclarativeRegionMixin) – The declarative region declaring this declaration.

Raises:

UnhandledCriticalWarningError – If a type mark can’t be resolved, and no WarningCollector collects the UnresolvedTypeMarkWarning.

Return type:

None

ResolveTypeMark(place, symbol)

Resolve a type mark at its place in this region and set the symbol’s reference.

Algorithm

  1. Clear the symbol’s reference.

  2. Look up the type mark’s name (LookupName()).

  3. An alias of a type is replaced by the type its name references.

  4. If the declaration is a type, a subtype or a generic type, it becomes the symbol’s reference. A full type, which follows the place in the same region, is visible by its incomplete type declaration only to an access type.

An attribute name denoting a type (e.g. s'subtype, A'element) is resolved part by part (Denote()); the type it denotes becomes the symbol’s reference.

Parameters:
Raises:

UnhandledCriticalWarningError – If the type mark isn’t visible, is ambiguous, has a prefix, which isn’t a visible package, denotes no type, or denotes an incomplete type outside of an access type, and no WarningCollector collects the UnresolvedTypeMarkWarning.

Return type:

None

property SharedVariables: dict[str, SharedVariable]

Read-only property to access the shared variables (_sharedVariables).

Returns:

Dictionary of shared variables, indexed by normalized identifier.

property Signals: dict[str, Signal]

Read-only property to access the signals (_signals).

Returns:

Dictionary of signals, indexed by normalized identifier.

SplitDeclaredItem(declaredItem)

Split a declared item with an identifier list into one declaration per identifier.

The declared item keeps its first identifier. For every other identifier, a new declaration is created by its Copy() and inserted right after it, in list order; its parent is set to this declarative region. If the region is indexed, the namespace and lookup table entries of the other identifiers refer to the new declarations; they are checked before anything is changed. A declared item declaring one identifier is unchanged.

Parameters:

declaredItem (ModelEntity) – The declared item to split.

Return type:

tuple[ModelEntity, ...]

Returns:

Tuple of declarations, one per identifier in list order, starting with the split declared item.

Raises:
  • ValueError – If parameter ‘declaredItem’ is None.

  • TypeError – If parameter ‘declaredItem’ is not of type ModelEntity.

  • NotAChildError – If parameter ‘declaredItem’ is not a declared item of this declarative region.

  • NotInNamespaceError – If the region is indexed, and an identifier of the declared item refers to another declaration, e.g. a duplicate declaration.

See also

Split()

→ Split a declaration with an identifier list.

RemoveDeclaredItem()

→ Remove a declared item from the declarative region.

SplitGenericItem(genericItem)

Split a generic with an identifier list into one generic per identifier.

The generic keeps its first identifier. For every other identifier, a new generic is created by its Copy() and inserted right after it, in list order, in the generic clause and in the generic’s generic group; its parent is set to this language construct. If the language construct has a namespace, the entries of the other identifiers refer to the new generics. A generic declaring one identifier is unchanged.

Parameters:

genericItem (GenericInterfaceItemMixin) – The generic to split.

Return type:

tuple[GenericInterfaceItemMixin, ...]

Returns:

Tuple of generics, one per identifier in list order, starting with the split generic.

Raises:
  • ValueError – If parameter ‘genericItem’ is None.

  • TypeError – If parameter ‘genericItem’ is not of type GenericInterfaceItemMixin.

  • NotAChildError – If parameter ‘genericItem’ is not a generic of this language construct.

  • NotInNamespaceError – If the namespace is indexed, and an identifier of the generic refers to another element, e.g. a duplicate declaration.

See also

Split()

→ Split a declaration with an identifier list.

RemoveGenericItem()

→ Remove a generic from the generic clause.

property Subtypes: dict[str, Subtype]

Read-only property to access the subtypes (_subtypes).

Returns:

Dictionary of subtypes, indexed by normalized identifier.

property Types: dict[str, FullType]

Read-only property to access the types (_types).

Returns:

Dictionary of types, indexed by normalized identifier.

Visit(visitor)[source]

Walk this package instantiation, its context clause, its generic package and its generic map aspect with a visitor.

Parameters:

visitor (Visitor) – The visitor receiving the events.

Return type:

None

_AddOverloadToNamespace(item)

Add a function or procedure to the namespace, if it’s the overload declared last.

The namespace keeps one entry per identifier: the overload declared last, as after IndexDeclaredItems(), which adds interface items first, then declared items (_Declarations()).

Parameters:

item (NamedEntityMixin | MultipleNamedEntityMixin) – The function or procedure, already an interface item or declared item of this region.

Return type:

None

_AddToGenericGroup(position, genericItem)

Add a generic to the generic group of the generic before position.

At position 0, the generic joins the generic group of the first generic. If there are no generic groups, the generic forms a new unnamed generic group.

Parameters:
  • position (int) – Position of the generic in the generic clause, from 0 (first) to the length of GenericItems (last).

  • genericItem (GenericInterfaceItemMixin) – The generic to add, which isn’t in a generic group.

Return type:

None

_AddToNamespace(element)

Add an element’s identifiers to this region’s namespace.

Nothing is added to a region not indexed yet: IndexDeclaredItems() adds the element later. A generic subprogram is an overload (_AddOverloadToNamespace()).

Parameters:

element (NamedEntityMixin | MultipleNamedEntityMixin) – The named element to add, e.g. an interface item.

Return type:

None

_CONTINUES_PARENT_REGION = False

True if it continues its parent’s declarative region.

_ClashingDeclarations(item)

Return the declarations sharing an identifier with the given item, which may not share it.

The declarations (_Declarations()) and the labeled statements (_Labels()) of this declarative region and of the language constructs sharing it (_SharedRegions()) are searched: a statement label is declared implicitly. Items imported into the namespace (e.g. by a use clause) are no declarations.

Parameters:

item (ModelEntity) – The new declaration, or the new labeled statement.

Return type:

tuple[ModelEntity, ...]

Returns:

Tuple of clashing declarations, interface items first, then declared items in declaration order, then labeled statements.

_ConnectParentNamespace(parent)

Connect this region’s namespace to the namespace of the enclosing declarative region.

A declaration of this region then hides a same-named declaration of the enclosing region. A parent, which isn’t a declarative region (e.g. a subprogram of an interface list), has no namespace to connect to.

Parameters:

parent (ModelEntity) – The new parent of this region.

Return type:

None

_ContextClauseUnits()

Return the design units whose context clause applies to this design unit.

Return type:

tuple[DesignUnit, ...]

Returns:

Tuple of this design unit.

_DECLARED_ITEM_TYPES = (<class 'pyVHDLModel.Type.BaseType'>, <class 'pyVHDLModel.Subprogram.Subprogram'>, <class 'pyVHDLModel.DesignUnit.Package'>, <class 'pyVHDLModel.DesignUnit.PackageBody'>, <class 'pyVHDLModel.Object.Constant'>, <class 'pyVHDLModel.Object.Signal'>, <class 'pyVHDLModel.Object.SharedVariable'>, <class 'pyVHDLModel.Object.File'>, <class 'pyVHDLModel.Declaration.Alias'>, <class 'pyVHDLModel.DesignUnit.Component'>, <class 'pyVHDLModel.Declaration.Attribute'>, <class 'pyVHDLModel.Declaration.AttributeSpecification'>, <class 'pyVHDLModel.Configuration.ComponentConfiguration'>, <class 'pyVHDLModel.Interface.ModeViewDeclaration'>, <class 'pyVHDLModel.DesignUnit.UseClause'>, <class 'pyVHDLModel.PSLModel.PSLEntity'>, <class 'pyVHDLModel.Object.DeferredConstant'>)

Accepted classes of declared items (pyVHDLModel).

_Declarations()

Return all declarations of this package: its generics share the declarative region.

Return type:

tuple[ModelEntity, ...]

Returns:

Tuple of declarations: the generics, then the declared items.

_DeclaredItemsSharingIdentifiers(declaredItem)

Return the other declared items of this region sharing an identifier with the given declared item.

Parameters:

declaredItem (ModelEntity) – The declared item.

Return type:

list[ModelEntity]

Returns:

List of declared items, in declaration order.

_END_KEYWORDS = (ReservedWord.Package,)

Reserved words after end.

_END_KEYWORDS_OPTIONAL = True

The reserved words after end are optional.

_IMPLICIT_LIBRARIES = ('work', 'std')

Library names visible without a library clause.

_IndexDeclaredItem(item)

Add a declared item to the namespace and to the lookup table matching its kind.

Parameters:

item (ModelEntity) – The declared item.

Return type:

None

_IndexGenericItems()

Add the generics to the host’s namespace; a generic subprogram is an overload.

Return type:

None

_IndexOtherDeclaredItem(item)

Hook for declared items the region doesn’t handle itself. Derived classes may override it.

An alias, an attribute declaration and a package (also a package instantiation) declared in the region are added to the namespace, without a lookup table.

Parameters:

item – The declared item.

Return type:

None

_IndexOverload(item)

Add an inserted function or procedure to its lookup table and to the namespace.

The list of overloads follows the declaration order. The namespace is updated by _AddOverloadToNamespace().

Parameters:

item (NamedEntityMixin | MultipleNamedEntityMixin) – The inserted function or procedure.

Return type:

None

_IterateStatementRegions()

Iterate the declarative regions nested in the statements of this declarative region.

Return type:

Generator[DeclarativeRegionMixin]

Returns:

An empty generator.

_Labels()

Return the labeled statements, whose labels are declared in this declarative region.

Return type:

tuple[ModelEntity, ...]

Returns:

An empty tuple.

_MayShareIdentifier(item, existing)

Check if two declarations may share an identifier in one declarative region.

Subprograms are overloadable. A protected type body completes its protected type, a full type completes its incomplete type, and a constant completes its deferred constant.

Parameters:
Return type:

bool

Returns:

True, if both declarations may share an identifier.

_RemoveDeclaredItemEntries(lookupTable, item)

Remove a declared item’s entries from a lookup table and from the namespace.

Every identifier is checked before anything is removed.

Parameters:
Raises:
  • NotInNamespaceError – If an identifier of the declared item isn’t declared in the namespace.

  • NotInNamespaceError – If an identifier of the declared item refers to another element, e.g. a duplicate declaration.

Return type:

None

_RemoveDeclaredItemsFromNamespace()

Remove all declared items of this region from its namespace.

Interface items of this region and items imported from elsewhere (e.g. by a use clause) are kept.

Return type:

None

_RemoveFromGenericGroup(genericItem)

Remove a generic from its generic group and clear the generic’s group.

A generic group, which becomes empty, is removed from GenericGroups and its parent is cleared.

Parameters:

genericItem (GenericInterfaceItemMixin) – The generic to remove from its generic group.

Return type:

None

_RemoveFromNamespace(element)

Remove an element’s identifiers from this region’s namespace.

Nothing is removed from a region not indexed yet, as its namespace doesn’t contain the element. A generic subprogram is an overload (_RemoveOverloadFromNamespace()).

Parameters:

element (NamedEntityMixin | MultipleNamedEntityMixin) – The named element to remove, e.g. an interface item.

Raises:
  • NotInNamespaceError – If the region is indexed, and an identifier of the element isn’t declared in the namespace.

  • NotInNamespaceError – If the region is indexed, and an identifier of the element refers to another element, e.g. a duplicate declaration.

Return type:

None

_RemoveOverloadFromNamespace(item)

Remove a function or procedure from the namespace.

Removing the overload the namespace refers to, the namespace refers to the remaining overload declared last (_Declarations()), or the identifier is removed, if no overload remains. Removing another overload leaves the namespace unchanged. The namespace is checked before it’s changed.

Parameters:

item (NamedEntityMixin | MultipleNamedEntityMixin) – The function or procedure, still an interface item or declared item of this region.

Raises:
  • NotInNamespaceError – If the identifier isn’t declared in the namespace.

  • NotInNamespaceError – If the identifier refers to an element, which is no overload, e.g. a duplicate declaration.

Return type:

None

_SharedRegions()

Return the other language constructs forming one declarative region with this package.

Return type:

tuple[ConcurrentDeclarationRegionMixin, ...]

Returns:

Tuple of the package body, if linked (_packageBody).

_UnindexDeclaredItem(item)

Remove a declared item from the namespace and from the lookup table matching its kind.

Parameters:

item (ModelEntity) – The declared item.

Return type:

None

_UnindexOtherDeclaredItem(item)

Remove a declared item, which a concurrent declaration region doesn’t handle itself.

A deferred constant is removed from _deferredConstants. An entry referring to another deferred constant of the same identifier (a duplicate declaration) is kept: RemoveDeclaredItem() indexes the region again.

Parameters:

item (ModelEntity) – The declared item.

Return type:

None

_UnindexOverload(item)

Remove a function or procedure from its lookup table and from the namespace.

The namespace is updated first, by _RemoveOverloadFromNamespace().

Parameters:

item (NamedEntityMixin | MultipleNamedEntityMixin) – The function or procedure to remove, still a declared item of this region.

Raises:
  • NotInNamespaceError – If the identifier isn’t declared in the namespace.

  • NotInNamespaceError – If the identifier refers to an element, which is no overload, e.g. a duplicate declaration.

Return type:

None

_VisitContextClause(visitor)

Walk the context clause, i.e. the context items preceding the design unit, with a visitor.

The context clause is reported, even if it has no context items.

Parameters:

visitor (Visitor) – The visitor receiving the events.

Return type:

None

_VisitDeclaredItems(visitor)

Walk the declared items in declaration order with a visitor.

Parameters:

visitor (Visitor) – The visitor receiving the events.

Return type:

None

_VisitGenericClause(visitor)

Walk the generic clause, if there are generics, with a visitor.

The generics are separated by semicolons.

Parameters:

visitor (Visitor) – The visitor receiving the events.

Return type:

None

_VisitGenericMapAspect(visitor)

Walk the generic map aspect, if there are generic associations, with a visitor.

The associations are separated by commas.

Parameters:

visitor (Visitor) – The visitor receiving the events.

Return type:

None

__getstate__()

Return the object’s state for pickling, collecting every slot of the class hierarchy.

Return type:

dict[str, Any]

Returns:

Dictionary of slot names and their values.

Raises:

ExtendedTypeError – If a slot was never assigned, so it has no value to serialize.

__new__(**kwargs)
__repr__()

Formats a representation of the package declaration.

Format: mylib.myPackage

Return type:

str

Returns:

String representation of the package declaration.

__setstate__(state)

Restore the object’s state from unpickling, requiring exactly the slots of the class hierarchy.

Parameters:

state (dict[str, Any]) – Dictionary of slot names and their values.

Raises:

ExtendedTypeError – If the given state misses a slot or carries an unexpected one.

Return type:

None

__str__()

Formats the package declaration.

Format: Package: 'mylib.myPackage'

Return type:

str

Returns:

Formatted package declaration.

_allowBlackbox

Allow blackboxes for components; None inherits the parent’s setting.

_areDeclaredItemsIndexed

True if IndexDeclaredItems() filled the namespace.

_components

Dictionary of all components declared in this concurrent declaration region.

_constants

Dictionary of all constants declared in this concurrent declaration region.

_contextItems

List of all context items (library, use and context clauses).

_contextReferences

List of context clauses.

_declaredItems

List of all declared items in this concurrent declaration region.

_deferredConstants

Deferred constants, indexed by name.

_dependencyVertex

Reference to the vertex in the dependency graph representing the design unit.
This reference is set by CreateDependencyGraph().

_document

The VHDL library, the design unit was analyzed into.

_documentation

The associated documentation of a model entity.

_files

Dictionary of all files declared in this concurrent declaration region.

_functions

Dictionary of all functions declared in this concurrent declaration region, indexed by name; each entry is a list of overloads.

_genericAssociationItems

List of all generic associations.

_genericGroups

List of all generic groups, in declaration order.

_genericItems

List of all generics, in declaration order.

_hierarchyVertex

The vertex in the hierarchy graph

_identifier

The identifier of a model entity.

_libraryReferences

List of library clauses.

_namespace

The namespace of this concurrent declaration region.

_normalizedIdentifier

The normalized (lower case) identifier of a model entity.

_packageBody

The corresponding package body, or None if none was analyzed.

_packageReference: PackageReferenceSymbol

Reference to the instantiated generic package.

_packageReferences

List of use clauses.

_parent

Reference to a parent entity in the logical model hierarchy.

_procedures

Dictionary of all procedures declared in this concurrent declaration region, indexed by name; each entry is a list of overloads.

_referencedContexts

Referenced contexts based on explicit context references or implicit inheritance

_referencedLibraries

Referenced libraries based on explicit library clauses or implicit inheritance

_referencedPackages

Referenced packages based on explicit use clauses or implicit inheritance

_sharedVariables

Dictionary of all shared variables declared in this concurrent declaration region.

_signals

Dictionary of all signals declared in this concurrent declaration region.

_subtypes

Dictionary of all subtypes declared in this concurrent declaration region.

_types

Dictionary of all types declared in this concurrent declaration region.

class pyGHDL.dom.DesignUnit.Context(node, identifier, references=None, documentation=None)[source]

This class implements a pyGHDL.dom object derived from pyVHDLModel.DesignUnit.Context.

Represents a context declaration.

A context contains a generic list of all its items (library clauses, use clauses and context references) in _contextItems.

Furthermore, when a context gets initialized, the item kinds get separated into individual lists:

When pyVHDLModel.Design.LinkContexts() got called, these lists were processed and the fields:

are populated. The declarations the use clauses make potentially visible are imported into _namespace.

Example

context ctx is
  -- ...
end context;

Inheritance

Inheritance diagram of Context

Parameters:
  • node (Iir)

  • identifier (str)

  • references (Iterable[VHDLModel_ContextUnion])

  • documentation (str)

__init__(node, identifier, references=None, documentation=None)[source]

Initializes a context declaration.

Parameters:
  • node (Iir) – The IIR node this object was translated from.

  • identifier (str) – The context’s identifier.

  • references (Iterable[LibraryClause | UseClause | ContextReference]) – Optional, all context items, in declaration order.

  • documentation (str) – Optional, the documentation comment associated with this declaration.

Return type:

None

classmethod parse(contextNode)[source]

Translates the IIR node of the context to a Context.

Parameters:

contextNode (Iir) – The IIR node of the context.

Returns:

The translated context.

_iirNode

The IIR node in libghdl’s tree this DOM object was translated from.

_position

The IIR node’s position in the source file, resolved on first access and then cached.

AddContextItem(contextItem)

Add a context item at the end of the context clause.

The context item’s parent is set to this design unit. A library clause is also added to LibraryReferences, a use clause to PackageReferences and a context reference to ContextReferences, in the order of ContextItems. A context item may repeat an earlier one.

Parameters:

contextItem (LibraryClause | UseClause | ContextReference) – The library clause, use clause or context reference to add.

Raises:
Return type:

None

Attention

The mutator doesn’t update what Analyze() derived from the context items: the referenced libraries, packages and contexts (ReferencedLibraries, ReferencedPackages, ReferencedContexts), the namespace entries of a use clause, the edges of the dependency graph, and the references of the symbols. A design changed after its analysis needs a new analysis.

See also

InsertContextItem()

→ Insert a context item at a position of the context clause.

RemoveContextItem()

→ Remove a context item from the context clause.

property ContextItems: list[LibraryClause | UseClause | ContextReference]

Read-only property to access the sequence of all context items comprising library, use and context clauses (_contextItems).

Returns:

Sequence of context items.

property ContextReferences: list[ContextReference]

Read-only property to access the sequence of context clauses (_contextReferences).

Returns:

Sequence of context clauses.

DenoteBy(name, region, place, symbol)

Determine the model entity a name denoting this declaration denotes, as a part of a type mark (Name.Denote).

A declaration, which a name in a type mark can denote, overrides this method and returns itself: an object, an alias, a type or subtype, a record element, a package. Any other declaration (e.g. a subprogram) is reported.

Parameters:
  • name (Name) – The name denoting this declaration, a part of the type mark.

  • region (DeclarativeRegionMixin) – The declarative region containing the type mark.

  • place (ModelEntity) – The declaration containing the type mark.

  • symbol (Symbol) – The type mark.

Return type:

ModelEntity | None

Returns:

None, as a name in a type mark can’t denote this declaration (reported as a warning).

Raises:

UnhandledCriticalWarningError – Always, if no WarningCollector collects the UnresolvedTypeMarkWarning.

property DependencyVertex: Vertex

Read-only property to access the corresponding dependency vertex (_dependencyVertex).

The dependency vertex references this design unit by its value field.

Returns:

The corresponding dependency vertex.

property Document: Document

Property to access the document (_document).

Returns:

The document.

property Documentation: str | None

Read-only property to access the model entity’s documentation (_documentation).

Returns:

Associated documentation of a model entity.

GetAncestor(type)

Return the closest ancestor of the given type found by walking the parent chain upwards.

Iterates the parent chain - starting at this model entity - upwards (toward the root of the model) until an ancestor of the requested type is found.

Parameters:

type (Type) – Class (type) of the ancestor to find.

Return type:

ModelEntity

Returns:

The closest ancestor of the requested type.

Raises:

AncestorNotFoundError – If the root of the model is reached without finding an ancestor of the requested type.

GetIdentifier(normalizedIdentifier)

Return the identifier as declared, for the model entity’s normalized identifier.

Parameters:

normalizedIdentifier (str) – The model entity’s normalized (lower case) identifier.

Return type:

str

Returns:

The identifier in its declared spelling.

classmethod GetMethodsWithAttributes(predicate=None)

Return the class’ methods that carry at least one matching attribute.

Parameters:

predicate (type[TAttr] | Iterable[type[TAttr]] | None) – Optional, an attribute class, an iterable of attribute classes, or None to accept every attribute.

Return type:

dict[Callable[..., Any], tuple[Attribute, ...]]

Returns:

Dictionary of methods and the matching attributes attached to them.

Raises:
  • ValueError – If an element of parameter ‘predicate’ is not a sub-class of Attribute.

  • ValueError – If parameter ‘predicate’ is neither an attribute class nor an iterable of those.

property HierarchyVertex: Vertex

Read-only property to access the corresponding hierarchy vertex (_hierarchyVertex).

The hierarchy vertex references this design unit by its value field.

Returns:

The corresponding hierarchy vertex.

property Identifier: str

Read-only property to access the model entity’s identifier (_identifier).

Returns:

Name of a model entity.

InsertContextItem(index, contextItem)

Insert a context item at a position of the context clause.

The context item’s parent is set to this design unit. A library clause is also added to LibraryReferences, a use clause to PackageReferences and a context reference to ContextReferences, in the order of ContextItems. A context item may repeat an earlier one.

Parameters:
  • index (int) – Position, from 0 (first) to the number of context items (append). A negative index counts from the end, as for list.insert(): -1 inserts before the last context item.

  • contextItem (LibraryClause | UseClause | ContextReference) – The library clause, use clause or context reference to insert.

Raises:
Return type:

None

Attention

The mutator doesn’t update what Analyze() derived from the context items: the referenced libraries, packages and contexts (ReferencedLibraries, ReferencedPackages, ReferencedContexts), the namespace entries of a use clause, the edges of the dependency graph, and the references of the symbols. A design changed after its analysis needs a new analysis.

See also

AddContextItem()

→ Add a context item at the end of the context clause.

RemoveContextItem()

→ Remove a context item from the context clause.

IsLibraryVisible(libraryIdentifier)

Check if the logical name of a library is visible in this design unit.

The name work is implicitly visible, the name std too, except in a context declaration. Every other name needs a library clause, also the real name of the working library. The library clause is searched in this design unit’s context clause, in the context clause of its primary unit, and in the contexts these reference, also in nested ones. The design unit must be in a library of a design.

Parameters:

libraryIdentifier (str) – The normalized identifier of the library.

Return type:

bool

Returns:

True, if the library’s name is visible.

property IsOverloadable: bool

Check if this model entity is an overloadable declaration: it may share its designator with other overloadable declarations.

Subprograms, enumeration literals and aliases, which may denote one of them, are overloadable; they override this property.

Returns:

True, if this model entity is an overloadable declaration.

IterateImplicitDeclarations()

Iterate the declarations this declaration implies.

An enumerated type implies its enumeration literals, a physical type its units; they override this method.

Return type:

Generator[tuple[str, ModelEntity]]

Returns:

A generator to iterate (normalized designator, declaration) pairs, in declaration order: none.

IterateTypeMarks(region)

Iterate the type marks of this declaration, each with the region and the place to look it up.

The place of a type mark is the declaration containing it. Declarations with type marks override this method, e.g. an object yields the type mark of its subtype indication, an array type its index and element subtypes.

Parameters:

region (DeclarativeRegionMixin) – The declarative region declaring this declaration.

Return type:

Generator[tuple[DeclarativeRegionMixin, ModelEntity, SubtypeSymbol]]

Returns:

A generator to iterate (region, place, type mark) tuples, in declaration order: none.

property Library: Library

Property to access the library (_parent).

Returns:

The library.

property LibraryReferences: list[LibraryClause]

Read-only property to access the sequence of library clauses (_libraryReferences).

Returns:

Sequence of library clauses.

property NormalizedIdentifier: str

Read-only property to access the model entity’s normalized identifier (_normalizedIdentifier).

See also

Returns:

Normalized name of a model entity.

property PackageReferences: list[UseClause]

Read-only property to access the sequence of use clauses (_packageReferences).

Returns:

Sequence of use clauses.

property Parent: ModelEntity

Property to access the model entity’s parent element reference in a logical hierarchy (_parent).

Returns:

Reference to the parent entity.

property Position: Position

Cached read-only property to access an IIR’s position in source code (_position).

If _position is None, resolve the position object from _iirNode

Returns:

The IIR’s position in the source file.

property ReferencedContexts: dict[str, Context]

Read-only property to access the referenced contexts (_referencedContexts).

Returns:

Dictionary of referenced contexts, indexed by normalized identifier.

property ReferencedLibraries: dict[str, Library]

Read-only property to access the referenced libraries (_referencedLibraries).

Returns:

Dictionary of referenced libraries, indexed by normalized identifier.

property ReferencedPackages: dict[str, Package]

Read-only property to access the referenced packages (_referencedPackages).

Returns:

Dictionary of referenced packages, indexed by normalized identifier.

RemoveContextItem(contextItem)

Remove a context item from the context clause.

The context item is detached: its parent is cleared, and it’s removed from ContextItems and from LibraryReferences, PackageReferences or ContextReferences. The context item itself is unchanged and can be added to another design unit, or inserted at another position.

Parameters:

contextItem (LibraryClause | UseClause | ContextReference) – The library clause, use clause or context reference to remove.

Raises:
Return type:

None

Attention

The mutator doesn’t update what Analyze() derived from the context items: the referenced libraries, packages and contexts (ReferencedLibraries, ReferencedPackages, ReferencedContexts), the namespace entries of a use clause, the edges of the dependency graph, and the references of the symbols. A design changed after its analysis needs a new analysis.

See also

AddContextItem()

→ Add a context item at the end of the context clause.

InsertContextItem()

→ Insert a context item at a position of the context clause.

ResetReferences(designUnit, region)

Reset the references ResolveReferences() derived: the references of this declaration’s type marks.

A use clause, an alias and a subtype extend this method.

Parameters:
  • designUnit (DesignUnit) – The design unit containing this declaration.

  • region (DeclarativeRegionMixin) – The declarative region declaring this declaration.

Return type:

None

ResolveReferences(designUnit, region)

Resolve the references of this declaration: its type marks (IterateTypeMarks()).

Each type mark is resolved at its place by the region it is looked up in (ResolveTypeMark()). An incomplete type, an alias and a subtype extend this method.

Parameters:
  • designUnit (DesignUnit) – The design unit containing this declaration.

  • region (DeclarativeRegionMixin) – The declarative region declaring this declaration.

Raises:

UnhandledCriticalWarningError – If a type mark can’t be resolved, and no WarningCollector collects the UnresolvedTypeMarkWarning.

Return type:

None

Visit(visitor)[source]

Walk this context declaration and its context items with a visitor.

A context declaration has no context clause: its context items are walked inside the declaration.

Parameters:

visitor (Visitor) – The visitor receiving the events.

Return type:

None

_CONTINUES_PARENT_REGION = False

True if it continues its parent’s declarative region.

_ContextClauseUnits()

Return the design units whose context clause applies to this design unit.

Return type:

tuple[DesignUnit, ...]

Returns:

Tuple of this design unit.

_END_KEYWORDS: ClassVar[tuple[ReservedWord, ...]] = (ReservedWord.Context,)

Reserved words after end.

_END_KEYWORDS_OPTIONAL: ClassVar[bool] = True

The reserved words after end are optional.

_IMPLICIT_LIBRARIES: ClassVar[tuple[str, ...]] = ('work',)

No std: a context declaration has no implicit library clause (13.2).

_VisitContextClause(visitor)

Walk the context clause, i.e. the context items preceding the design unit, with a visitor.

The context clause is reported, even if it has no context items.

Parameters:

visitor (Visitor) – The visitor receiving the events.

Return type:

None

__getstate__()

Return the object’s state for pickling, collecting every slot of the class hierarchy.

Return type:

dict[str, Any]

Returns:

Dictionary of slot names and their values.

Raises:

ExtendedTypeError – If a slot was never assigned, so it has no value to serialize.

__new__(**kwargs)
__setstate__(state)

Restore the object’s state from unpickling, requiring exactly the slots of the class hierarchy.

Parameters:

state (dict[str, Any]) – Dictionary of slot names and their values.

Raises:

ExtendedTypeError – If the given state misses a slot or carries an unexpected one.

Return type:

None

__str__()[source]

Formats the context declaration.

Format: Context: mylib.myContext

Return type:

str

Returns:

Formatted context declaration.

_contextItems

List of all context items (library, use and context clauses).

_contextReferences

List of context clauses.

_dependencyVertex

Reference to the vertex in the dependency graph representing the design unit.
This reference is set by CreateDependencyGraph().

_document

The VHDL library, the design unit was analyzed into.

_documentation

The associated documentation of a model entity.

_hierarchyVertex

The vertex in the hierarchy graph

_identifier

The identifier of a model entity.

_libraryReferences

List of library clauses.

_namespace: Namespace

The namespace of the declarations imported by this context’s use clauses.

_normalizedIdentifier

The normalized (lower case) identifier of a model entity.

_packageReferences

List of use clauses.

_parent

Reference to a parent entity in the logical model hierarchy.

_referencedContexts

Referenced contexts based on explicit context references or implicit inheritance

_referencedLibraries

Referenced libraries based on explicit library clauses or implicit inheritance

_referencedPackages

Referenced packages based on explicit use clauses or implicit inheritance

class pyGHDL.dom.DesignUnit.Configuration(node, identifier, entity, blockConfiguration, contextItems=None, documentation=None)[source]

This class implements a pyGHDL.dom object derived from pyVHDLModel.DesignUnit.Configuration.

Represents a configuration declaration.

Example

configuration cfg of ent is
  for rtl
    -- ...
  end for;
end configuration;

Inheritance

Inheritance diagram of Configuration

Parameters:
__init__(node, identifier, entity, blockConfiguration, contextItems=None, documentation=None)[source]

Initializes a configuration declaration.

Parameters:
  • node (Iir) – The IIR node this object was translated from.

  • identifier (str) – The configuration’s identifier.

  • entity (EntitySymbol) – Reference to the entity this configuration configures.

  • blockConfiguration (BlockConfiguration) – The configuration of the entity’s architecture.

  • contextItems (Iterable[Context]) – Optional, list of all context items (library, use and context clauses).

  • documentation (str) – Optional, the documentation comment associated with this declaration.

Return type:

None

classmethod parse(configurationNode, contextItems)[source]

Translates the IIR node of the configuration declaration to a Configuration.

Parameters:
  • configurationNode (Iir) – The IIR node of the configuration declaration.

  • contextItems (Iterable[Context]) – List of all context items (library, use and context clauses) preceding the unit.

Return type:

Self

Returns:

The translated configuration declaration.

_iirNode

The IIR node in libghdl’s tree this DOM object was translated from.

_position

The IIR node’s position in the source file, resolved on first access and then cached.

AddContextItem(contextItem)

Add a context item at the end of the context clause.

The context item’s parent is set to this design unit. A library clause is also added to LibraryReferences, a use clause to PackageReferences and a context reference to ContextReferences, in the order of ContextItems. A context item may repeat an earlier one.

Parameters:

contextItem (LibraryClause | UseClause | ContextReference) – The library clause, use clause or context reference to add.

Raises:
Return type:

None

Attention

The mutator doesn’t update what Analyze() derived from the context items: the referenced libraries, packages and contexts (ReferencedLibraries, ReferencedPackages, ReferencedContexts), the namespace entries of a use clause, the edges of the dependency graph, and the references of the symbols. A design changed after its analysis needs a new analysis.

See also

InsertContextItem()

→ Insert a context item at a position of the context clause.

RemoveContextItem()

→ Remove a context item from the context clause.

property BlockConfiguration: BlockConfiguration

Read-only property to access the block configuration (_blockConfiguration).

Returns:

The block configuration.

property ContextItems: list[LibraryClause | UseClause | ContextReference]

Read-only property to access the sequence of all context items comprising library, use and context clauses (_contextItems).

Returns:

Sequence of context items.

property ContextReferences: list[ContextReference]

Read-only property to access the sequence of context clauses (_contextReferences).

Returns:

Sequence of context clauses.

DenoteBy(name, region, place, symbol)

Determine the model entity a name denoting this declaration denotes, as a part of a type mark (Name.Denote).

A declaration, which a name in a type mark can denote, overrides this method and returns itself: an object, an alias, a type or subtype, a record element, a package. Any other declaration (e.g. a subprogram) is reported.

Parameters:
  • name (Name) – The name denoting this declaration, a part of the type mark.

  • region (DeclarativeRegionMixin) – The declarative region containing the type mark.

  • place (ModelEntity) – The declaration containing the type mark.

  • symbol (Symbol) – The type mark.

Return type:

ModelEntity | None

Returns:

None, as a name in a type mark can’t denote this declaration (reported as a warning).

Raises:

UnhandledCriticalWarningError – Always, if no WarningCollector collects the UnresolvedTypeMarkWarning.

property DependencyVertex: Vertex

Read-only property to access the corresponding dependency vertex (_dependencyVertex).

The dependency vertex references this design unit by its value field.

Returns:

The corresponding dependency vertex.

property Document: Document

Property to access the document (_document).

Returns:

The document.

property Documentation: str | None

Read-only property to access the model entity’s documentation (_documentation).

Returns:

Associated documentation of a model entity.

property Entity: EntitySymbol

Read-only property to access the entity (_entity).

Returns:

The entity.

GetAncestor(type)

Return the closest ancestor of the given type found by walking the parent chain upwards.

Iterates the parent chain - starting at this model entity - upwards (toward the root of the model) until an ancestor of the requested type is found.

Parameters:

type (Type) – Class (type) of the ancestor to find.

Return type:

ModelEntity

Returns:

The closest ancestor of the requested type.

Raises:

AncestorNotFoundError – If the root of the model is reached without finding an ancestor of the requested type.

GetIdentifier(normalizedIdentifier)

Return the identifier as declared, for the model entity’s normalized identifier.

Parameters:

normalizedIdentifier (str) – The model entity’s normalized (lower case) identifier.

Return type:

str

Returns:

The identifier in its declared spelling.

classmethod GetMethodsWithAttributes(predicate=None)

Return the class’ methods that carry at least one matching attribute.

Parameters:

predicate (type[TAttr] | Iterable[type[TAttr]] | None) – Optional, an attribute class, an iterable of attribute classes, or None to accept every attribute.

Return type:

dict[Callable[..., Any], tuple[Attribute, ...]]

Returns:

Dictionary of methods and the matching attributes attached to them.

Raises:
  • ValueError – If an element of parameter ‘predicate’ is not a sub-class of Attribute.

  • ValueError – If parameter ‘predicate’ is neither an attribute class nor an iterable of those.

property HierarchyVertex: Vertex

Read-only property to access the corresponding hierarchy vertex (_hierarchyVertex).

The hierarchy vertex references this design unit by its value field.

Returns:

The corresponding hierarchy vertex.

property Identifier: str

Read-only property to access the model entity’s identifier (_identifier).

Returns:

Name of a model entity.

InsertContextItem(index, contextItem)

Insert a context item at a position of the context clause.

The context item’s parent is set to this design unit. A library clause is also added to LibraryReferences, a use clause to PackageReferences and a context reference to ContextReferences, in the order of ContextItems. A context item may repeat an earlier one.

Parameters:
  • index (int) – Position, from 0 (first) to the number of context items (append). A negative index counts from the end, as for list.insert(): -1 inserts before the last context item.

  • contextItem (LibraryClause | UseClause | ContextReference) – The library clause, use clause or context reference to insert.

Raises:
Return type:

None

Attention

The mutator doesn’t update what Analyze() derived from the context items: the referenced libraries, packages and contexts (ReferencedLibraries, ReferencedPackages, ReferencedContexts), the namespace entries of a use clause, the edges of the dependency graph, and the references of the symbols. A design changed after its analysis needs a new analysis.

See also

AddContextItem()

→ Add a context item at the end of the context clause.

RemoveContextItem()

→ Remove a context item from the context clause.

IsLibraryVisible(libraryIdentifier)

Check if the logical name of a library is visible in this design unit.

The name work is implicitly visible, the name std too, except in a context declaration. Every other name needs a library clause, also the real name of the working library. The library clause is searched in this design unit’s context clause, in the context clause of its primary unit, and in the contexts these reference, also in nested ones. The design unit must be in a library of a design.

Parameters:

libraryIdentifier (str) – The normalized identifier of the library.

Return type:

bool

Returns:

True, if the library’s name is visible.

property IsOverloadable: bool

Check if this model entity is an overloadable declaration: it may share its designator with other overloadable declarations.

Subprograms, enumeration literals and aliases, which may denote one of them, are overloadable; they override this property.

Returns:

True, if this model entity is an overloadable declaration.

IterateImplicitDeclarations()

Iterate the declarations this declaration implies.

An enumerated type implies its enumeration literals, a physical type its units; they override this method.

Return type:

Generator[tuple[str, ModelEntity]]

Returns:

A generator to iterate (normalized designator, declaration) pairs, in declaration order: none.

IterateTypeMarks(region)

Iterate the type marks of this declaration, each with the region and the place to look it up.

The place of a type mark is the declaration containing it. Declarations with type marks override this method, e.g. an object yields the type mark of its subtype indication, an array type its index and element subtypes.

Parameters:

region (DeclarativeRegionMixin) – The declarative region declaring this declaration.

Return type:

Generator[tuple[DeclarativeRegionMixin, ModelEntity, SubtypeSymbol]]

Returns:

A generator to iterate (region, place, type mark) tuples, in declaration order: none.

property Library: Library

Property to access the library (_parent).

Returns:

The library.

property LibraryReferences: list[LibraryClause]

Read-only property to access the sequence of library clauses (_libraryReferences).

Returns:

Sequence of library clauses.

property NormalizedIdentifier: str

Read-only property to access the model entity’s normalized identifier (_normalizedIdentifier).

See also

Returns:

Normalized name of a model entity.

property PackageReferences: list[UseClause]

Read-only property to access the sequence of use clauses (_packageReferences).

Returns:

Sequence of use clauses.

property Parent: ModelEntity

Property to access the model entity’s parent element reference in a logical hierarchy (_parent).

Returns:

Reference to the parent entity.

property Position: Position

Cached read-only property to access an IIR’s position in source code (_position).

If _position is None, resolve the position object from _iirNode

Returns:

The IIR’s position in the source file.

property ReferencedContexts: dict[str, Context]

Read-only property to access the referenced contexts (_referencedContexts).

Returns:

Dictionary of referenced contexts, indexed by normalized identifier.

property ReferencedLibraries: dict[str, Library]

Read-only property to access the referenced libraries (_referencedLibraries).

Returns:

Dictionary of referenced libraries, indexed by normalized identifier.

property ReferencedPackages: dict[str, Package]

Read-only property to access the referenced packages (_referencedPackages).

Returns:

Dictionary of referenced packages, indexed by normalized identifier.

RemoveContextItem(contextItem)

Remove a context item from the context clause.

The context item is detached: its parent is cleared, and it’s removed from ContextItems and from LibraryReferences, PackageReferences or ContextReferences. The context item itself is unchanged and can be added to another design unit, or inserted at another position.

Parameters:

contextItem (LibraryClause | UseClause | ContextReference) – The library clause, use clause or context reference to remove.

Raises:
Return type:

None

Attention

The mutator doesn’t update what Analyze() derived from the context items: the referenced libraries, packages and contexts (ReferencedLibraries, ReferencedPackages, ReferencedContexts), the namespace entries of a use clause, the edges of the dependency graph, and the references of the symbols. A design changed after its analysis needs a new analysis.

See also

AddContextItem()

→ Add a context item at the end of the context clause.

InsertContextItem()

→ Insert a context item at a position of the context clause.

ResetReferences(designUnit, region)

Reset the references ResolveReferences() derived: the references of this declaration’s type marks.

A use clause, an alias and a subtype extend this method.

Parameters:
  • designUnit (DesignUnit) – The design unit containing this declaration.

  • region (DeclarativeRegionMixin) – The declarative region declaring this declaration.

Return type:

None

ResolveReferences(designUnit, region)

Resolve the references of this declaration: its type marks (IterateTypeMarks()).

Each type mark is resolved at its place by the region it is looked up in (ResolveTypeMark()). An incomplete type, an alias and a subtype extend this method.

Parameters:
  • designUnit (DesignUnit) – The design unit containing this declaration.

  • region (DeclarativeRegionMixin) – The declarative region declaring this declaration.

Raises:

UnhandledCriticalWarningError – If a type mark can’t be resolved, and no WarningCollector collects the UnresolvedTypeMarkWarning.

Return type:

None

Visit(visitor)[source]

Walk this configuration, its context clause, its entity and its block configuration with a visitor.

Parameters:

visitor (Visitor) – The visitor receiving the events.

Return type:

None

_CONTINUES_PARENT_REGION = False

True if it continues its parent’s declarative region.

_ContextClauseUnits()

Return the design units whose context clause applies to this design unit.

Return type:

tuple[DesignUnit, ...]

Returns:

Tuple of this design unit.

_END_KEYWORDS: ClassVar[tuple[ReservedWord, ...]] = (ReservedWord.Configuration,)

Reserved words after end.

_END_KEYWORDS_OPTIONAL: ClassVar[bool] = True

The reserved words after end are optional.

_IMPLICIT_LIBRARIES = ('work', 'std')

Library names visible without a library clause.

_VisitContextClause(visitor)

Walk the context clause, i.e. the context items preceding the design unit, with a visitor.

The context clause is reported, even if it has no context items.

Parameters:

visitor (Visitor) – The visitor receiving the events.

Return type:

None

__getstate__()

Return the object’s state for pickling, collecting every slot of the class hierarchy.

Return type:

dict[str, Any]

Returns:

Dictionary of slot names and their values.

Raises:

ExtendedTypeError – If a slot was never assigned, so it has no value to serialize.

__new__(**kwargs)
__repr__()[source]

Formats a representation of the configuration declaration.

Format: mylib.myConfiguration

Return type:

str

Returns:

String representation of the configuration declaration.

__setstate__(state)

Restore the object’s state from unpickling, requiring exactly the slots of the class hierarchy.

Parameters:

state (dict[str, Any]) – Dictionary of slot names and their values.

Raises:

ExtendedTypeError – If the given state misses a slot or carries an unexpected one.

Return type:

None

__str__()[source]

Formats the configuration declaration.

Format: Configuration: mylib.myConfiguration

Return type:

str

Returns:

Formatted configuration declaration.

_blockConfiguration: BlockConfiguration

The configuration of the entity’s architecture.

_contextItems

List of all context items (library, use and context clauses).

_contextReferences

List of context clauses.

_dependencyVertex

Reference to the vertex in the dependency graph representing the design unit.
This reference is set by CreateDependencyGraph().

_document

The VHDL library, the design unit was analyzed into.

_documentation

The associated documentation of a model entity.

_entity: EntitySymbol

Reference to the entity this configuration configures.

_hierarchyVertex

The vertex in the hierarchy graph

_identifier

The identifier of a model entity.

_libraryReferences

List of library clauses.

_namespace: Namespace

The namespace of this configuration’s declarative region.

_normalizedIdentifier

The normalized (lower case) identifier of a model entity.

_packageReferences

List of use clauses.

_parent

Reference to a parent entity in the logical model hierarchy.

_referencedContexts

Referenced contexts based on explicit context references or implicit inheritance

_referencedLibraries

Referenced libraries based on explicit library clauses or implicit inheritance

_referencedPackages

Referenced packages based on explicit use clauses or implicit inheritance