pyGHDL.dom.Object

This module implements derived object classes from pyVHDLModel.Object.

Classes


Classes

class pyGHDL.dom.Object.Constant(node, identifiers, subtype, defaultExpression, documentation=None)[source]

Represents a constant.

This class implements a pyGHDL.dom object derived from pyVHDLModel.Object.Constant.

Example

constant BITS : positive := 8;

Inheritance

Inheritance diagram of Constant

Parameters:
  • node (Iir)

  • identifiers (List[str])

  • subtype (Symbol)

  • defaultExpression (ExpressionUnion)

  • documentation (str)

__init__(node, identifiers, subtype, defaultExpression, documentation=None)[source]

Initializes a constant.

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

  • identifiers (List[str]) – A list of identifiers.

  • subtype (Symbol) – Reference to the object’s subtype.

  • defaultExpression (BaseExpression | QualifiedExpression | FunctionCall | TypeConversion | Literal) – The default value, or None if none was given.

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

Return type:

None

classmethod parse(constantNode, furtherIdentifiers=None)[source]

Translates the IIR node of the constant declaration to a Constant.

Parameters:
  • constantNode (Iir) – The IIR node of the constant declaration.

  • furtherIdentifiers (Iterable[str]) – Optional, the remaining identifiers, when one declaration names several.

Return type:

Constant | DeferredConstant

Returns:

The translated constant 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.

Copy()[source]

Create a copy of this constant.

The copy has no parent and no object vertex. Its subtype and default expression are copies of this constant’s subtype and default expression.

Return type:

Self

Returns:

The new constant.

property DefaultExpression: BaseExpression | QualifiedExpression | FunctionCall | TypeConversion | Literal | None

Read-only property to access the default expression (_defaultExpression).

Returns:

The default expression, or None if not set.

DenoteBy(name, region, place, symbol)

Determine the model entity a name denoting this object denotes, as a part of a type mark: this object.

A port or a parameter isn’t usable in its own interface list (_USABLE_IN_OWN_INTERFACE_LIST): e.g. the subtype of a port can’t name another port of the same port list (i'subtype).

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 object, or None if a name can’t denote it here (reported as a warning).

Raises:

UnhandledCriticalWarningError – If the object is a port or parameter used in its own interface list, and 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.

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 one of the model entity’s normalized identifiers.

Parameters:

normalizedIdentifier (str) – One of the model entity’s normalized (lower case) identifiers.

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 Identifiers: tuple[str]

Read-only property to access the model entity’s identifiers (_identifiers).

Returns:

Tuple of identifiers.

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 object: the type mark of its subtype indication.

Parameters:

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

Return type:

Generator[tuple[DeclarativeRegionMixin, ModelEntity, SubtypeSymbol]]

Returns:

A generator to iterate (region, place, type mark) tuples: the object’s subtype indication.

property NormalizedIdentifiers: tuple[str]

Read-only property to access the model entity’s normalized identifiers (_normalizedIdentifiers).

See also

Returns:

Tuple of normalized identifiers.

property ObjectVertex: Vertex | None

Read-only property to access the corresponding object vertex (_objectVertex).

The object vertex references this Object by its value field.

Returns:

The corresponding object vertex.

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

Split()

Split this declaration into one declaration per identifier.

IEEE Std 1076 defines a declaration with an identifier list as equivalent to a sequence of single declarations, one per identifier, in list order: signal a, b : bit; declares the same as signal a : bit; signal b : bit;. This declaration keeps its first identifier. For every other identifier, a new declaration is created by Copy(): it has its own copy of the subtype indication and of the default expression, and the same documentation. Single declarations created before are dropped.

Without a parent, the new declarations have no parent either: the caller places them. With a parent, the parent’s mutator splits the declaration and inserts the new declarations right after it, e.g. WithPortsMixin.SplitPortItem for a port.

A declaration with one identifier is unchanged.

Return type:

tuple[Self, ...]

Returns:

Tuple of declarations, one per identifier in list order, starting with this declaration.

Raises:
  • NotAChildError – If this declaration’s parent doesn’t list it.

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

property Subtype: Symbol

Read-only property to access the subtype (_subtype).

Returns:

The subtype.

Visit(visitor)[source]

Walk this constant declaration, its subtype and its default expression with a visitor.

Parameters:

visitor (Visitor) – The visitor receiving the events.

Return type:

None

_KeepIdentifier(position)

Reduce the identifier list to the identifier at a position and drop the single declarations.

Parameters:

position (int) – The position of the identifier to keep.

Return type:

None

_OBJECT_KEYWORD: ClassVar[tuple[ReservedWord, ...]] = (ReservedWord.Constant,)

The reserved words introducing this object class.

_SplitCopies()

Create one parentless copy of this declaration per identifier after the first, each keeping its identifier.

Return type:

list[Self]

Returns:

List of new declarations, in list order.

_SplitInParent()

Split this object declaration by the mutator of its parent (SplitDeclaredItem()).

Return type:

tuple[Self, ...]

Returns:

Tuple of declarations, one per identifier in list order, starting with this object declaration.

_USABLE_IN_OWN_INTERFACE_LIST = True

Usable by a name in its own interface list.

_VisitDefaultExpression(visitor)

Walk the default expression, if any, after a variable assignment delimiter (:=) 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

__str__()

Formats the object declaration.

Format: signal s1, s2 : bit

Return type:

str

Returns:

Formatted object declaration.

_defaultExpression

The default value, or None if none was given.

_documentation

The associated documentation of a model entity.

_identifiers

A list of identifiers.

_normalizedIdentifiers

A list of normalized (lower case) identifiers.

_objectVertex

The vertex representing this object in the design’s object graph.

_parent

Reference to a parent entity in the logical model hierarchy.

_singleDeclarations

Cached single declarations, or None.

_subtype

Reference to the object’s subtype.

class pyGHDL.dom.Object.DeferredConstant(node, identifiers, subtype, documentation=None)[source]

Represents a deferred constant.

This class implements a pyGHDL.dom object derived from pyVHDLModel.Object.DeferredConstant.

Example

constant BITS : positive;

Inheritance

Inheritance diagram of DeferredConstant

Parameters:
__init__(node, identifiers, subtype, documentation=None)[source]

Initializes a deferred constant.

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

  • identifiers (List[str]) – A list of identifiers.

  • subtype (Symbol) – Reference to the object’s subtype.

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

Return type:

None

classmethod parse(constantNode, furtherIdentifiers=None)[source]

Translates the IIR node of the constant declaration to a DeferredConstant.

Parameters:
  • constantNode (Iir) – The IIR node of the constant declaration.

  • furtherIdentifiers (Iterable[str]) – Optional, the remaining identifiers, when one declaration names several.

Return type:

Self

Returns:

The translated constant 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.

property ConstantReference: Constant | None

Read-only property to access the constant reference (_constantReference).

Returns:

The constant reference, or None if not set.

Copy()[source]

Create a copy of this deferred constant.

The copy has no parent and no object vertex. Its subtype is a copy of this deferred constant’s subtype; the full constant declaration, if linked, is the same.

Return type:

Self

Returns:

The new deferred constant.

DenoteBy(name, region, place, symbol)

Determine the model entity a name denoting this object denotes, as a part of a type mark: this object.

A port or a parameter isn’t usable in its own interface list (_USABLE_IN_OWN_INTERFACE_LIST): e.g. the subtype of a port can’t name another port of the same port list (i'subtype).

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 object, or None if a name can’t denote it here (reported as a warning).

Raises:

UnhandledCriticalWarningError – If the object is a port or parameter used in its own interface list, and 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.

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 one of the model entity’s normalized identifiers.

Parameters:

normalizedIdentifier (str) – One of the model entity’s normalized (lower case) identifiers.

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 Identifiers: tuple[str]

Read-only property to access the model entity’s identifiers (_identifiers).

Returns:

Tuple of identifiers.

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 object: the type mark of its subtype indication.

Parameters:

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

Return type:

Generator[tuple[DeclarativeRegionMixin, ModelEntity, SubtypeSymbol]]

Returns:

A generator to iterate (region, place, type mark) tuples: the object’s subtype indication.

property NormalizedIdentifiers: tuple[str]

Read-only property to access the model entity’s normalized identifiers (_normalizedIdentifiers).

See also

Returns:

Tuple of normalized identifiers.

property ObjectVertex: Vertex | None

Read-only property to access the corresponding object vertex (_objectVertex).

The object vertex references this Object by its value field.

Returns:

The corresponding object vertex.

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

Split()

Split this declaration into one declaration per identifier.

IEEE Std 1076 defines a declaration with an identifier list as equivalent to a sequence of single declarations, one per identifier, in list order: signal a, b : bit; declares the same as signal a : bit; signal b : bit;. This declaration keeps its first identifier. For every other identifier, a new declaration is created by Copy(): it has its own copy of the subtype indication and of the default expression, and the same documentation. Single declarations created before are dropped.

Without a parent, the new declarations have no parent either: the caller places them. With a parent, the parent’s mutator splits the declaration and inserts the new declarations right after it, e.g. WithPortsMixin.SplitPortItem for a port.

A declaration with one identifier is unchanged.

Return type:

tuple[Self, ...]

Returns:

Tuple of declarations, one per identifier in list order, starting with this declaration.

Raises:
  • NotAChildError – If this declaration’s parent doesn’t list it.

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

property Subtype: Symbol

Read-only property to access the subtype (_subtype).

Returns:

The subtype.

Visit(visitor)[source]

Walk this deferred constant declaration, its subtype with a visitor.

Parameters:

visitor (Visitor) – The visitor receiving the events.

Return type:

None

_KeepIdentifier(position)

Reduce the identifier list to the identifier at a position and drop the single declarations.

Parameters:

position (int) – The position of the identifier to keep.

Return type:

None

_OBJECT_KEYWORD: ClassVar[tuple[ReservedWord, ...]] = (ReservedWord.Constant,)

The reserved words introducing this object class.

_SplitCopies()

Create one parentless copy of this declaration per identifier after the first, each keeping its identifier.

Return type:

list[Self]

Returns:

List of new declarations, in list order.

_SplitInParent()

Split this object declaration by the mutator of its parent (SplitDeclaredItem()).

Return type:

tuple[Self, ...]

Returns:

Tuple of declarations, one per identifier in list order, starting with this object declaration.

_USABLE_IN_OWN_INTERFACE_LIST: ClassVar[bool] = True

Usable by a name in its own interface list.

__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__()

Formats the object declaration.

Format: signal s1, s2 : bit

Return type:

str

Returns:

Formatted object declaration.

_constantReference: Constant | None

The full declaration, or None if unlinked.

_documentation: str | None

The associated documentation of a model entity.

_identifiers: tuple[str]

A list of identifiers.

_normalizedIdentifiers: tuple[str]

A list of normalized (lower case) identifiers.

_objectVertex: Vertex | None

The vertex representing this object in the design’s object graph.

_parent: ModelEntity

Reference to a parent entity in the logical model hierarchy.

_singleDeclarations: list[SingleDeclarationMixin] | None

Cached single declarations, or None.

_subtype: Symbol

Reference to the object’s subtype.

class pyGHDL.dom.Object.Variable(node, identifiers, subtype, defaultExpression, documentation=None)[source]

Represents a variable.

This class implements a pyGHDL.dom object derived from pyVHDLModel.Object.Variable.

Example

variable result : natural := 0;

Inheritance

Inheritance diagram of Variable

Parameters:
  • node (Iir)

  • identifiers (List[str])

  • subtype (Symbol)

  • defaultExpression (ExpressionUnion)

  • documentation (str)

__init__(node, identifiers, subtype, defaultExpression, documentation=None)[source]

Initializes a variable.

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

  • identifiers (List[str]) – A list of identifiers.

  • subtype (Symbol) – Reference to the object’s subtype.

  • defaultExpression (BaseExpression | QualifiedExpression | FunctionCall | TypeConversion | Literal) – The default value, or None if none was given.

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

Return type:

None

classmethod parse(variableNode, furtherIdentifiers=None)[source]

Translates the IIR node of the variable declaration to a Variable.

Parameters:
  • variableNode (Iir) – The IIR node of the variable declaration.

  • furtherIdentifiers (Iterable[str]) – Optional, the remaining identifiers, when one declaration names several.

Return type:

Self

Returns:

The translated variable 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.

Copy()[source]

Create a copy of this variable.

The copy has no parent and no object vertex. Its subtype and default expression are copies of this variable’s subtype and default expression.

Return type:

Self

Returns:

The new variable.

property DefaultExpression: BaseExpression | QualifiedExpression | FunctionCall | TypeConversion | Literal | None

Read-only property to access the default expression (_defaultExpression).

Returns:

The default expression, or None if not set.

DenoteBy(name, region, place, symbol)

Determine the model entity a name denoting this object denotes, as a part of a type mark: this object.

A port or a parameter isn’t usable in its own interface list (_USABLE_IN_OWN_INTERFACE_LIST): e.g. the subtype of a port can’t name another port of the same port list (i'subtype).

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 object, or None if a name can’t denote it here (reported as a warning).

Raises:

UnhandledCriticalWarningError – If the object is a port or parameter used in its own interface list, and 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.

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 one of the model entity’s normalized identifiers.

Parameters:

normalizedIdentifier (str) – One of the model entity’s normalized (lower case) identifiers.

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 Identifiers: tuple[str]

Read-only property to access the model entity’s identifiers (_identifiers).

Returns:

Tuple of identifiers.

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 object: the type mark of its subtype indication.

Parameters:

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

Return type:

Generator[tuple[DeclarativeRegionMixin, ModelEntity, SubtypeSymbol]]

Returns:

A generator to iterate (region, place, type mark) tuples: the object’s subtype indication.

property NormalizedIdentifiers: tuple[str]

Read-only property to access the model entity’s normalized identifiers (_normalizedIdentifiers).

See also

Returns:

Tuple of normalized identifiers.

property ObjectVertex: Vertex | None

Read-only property to access the corresponding object vertex (_objectVertex).

The object vertex references this Object by its value field.

Returns:

The corresponding object vertex.

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

Split()

Split this declaration into one declaration per identifier.

IEEE Std 1076 defines a declaration with an identifier list as equivalent to a sequence of single declarations, one per identifier, in list order: signal a, b : bit; declares the same as signal a : bit; signal b : bit;. This declaration keeps its first identifier. For every other identifier, a new declaration is created by Copy(): it has its own copy of the subtype indication and of the default expression, and the same documentation. Single declarations created before are dropped.

Without a parent, the new declarations have no parent either: the caller places them. With a parent, the parent’s mutator splits the declaration and inserts the new declarations right after it, e.g. WithPortsMixin.SplitPortItem for a port.

A declaration with one identifier is unchanged.

Return type:

tuple[Self, ...]

Returns:

Tuple of declarations, one per identifier in list order, starting with this declaration.

Raises:
  • NotAChildError – If this declaration’s parent doesn’t list it.

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

property Subtype: Symbol

Read-only property to access the subtype (_subtype).

Returns:

The subtype.

Visit(visitor)[source]

Walk this variable declaration, its subtype and its default expression with a visitor.

Parameters:

visitor (Visitor) – The visitor receiving the events.

Return type:

None

_KeepIdentifier(position)

Reduce the identifier list to the identifier at a position and drop the single declarations.

Parameters:

position (int) – The position of the identifier to keep.

Return type:

None

_OBJECT_KEYWORD: ClassVar[tuple[ReservedWord, ...]] = (ReservedWord.Variable,)

The reserved words introducing this object class.

_SplitCopies()

Create one parentless copy of this declaration per identifier after the first, each keeping its identifier.

Return type:

list[Self]

Returns:

List of new declarations, in list order.

_SplitInParent()

Split this object declaration by the mutator of its parent (SplitDeclaredItem()).

Return type:

tuple[Self, ...]

Returns:

Tuple of declarations, one per identifier in list order, starting with this object declaration.

_USABLE_IN_OWN_INTERFACE_LIST = True

Usable by a name in its own interface list.

_VisitDefaultExpression(visitor)

Walk the default expression, if any, after a variable assignment delimiter (:=) 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

__str__()

Formats the object declaration.

Format: signal s1, s2 : bit

Return type:

str

Returns:

Formatted object declaration.

_defaultExpression

The default value, or None if none was given.

_documentation

The associated documentation of a model entity.

_identifiers

A list of identifiers.

_normalizedIdentifiers

A list of normalized (lower case) identifiers.

_objectVertex

The vertex representing this object in the design’s object graph.

_parent

Reference to a parent entity in the logical model hierarchy.

_singleDeclarations

Cached single declarations, or None.

_subtype

Reference to the object’s subtype.

class pyGHDL.dom.Object.SharedVariable(node, identifiers, subtype, documentation=None)[source]

Represents a shared variable.

This class implements a pyGHDL.dom object derived from pyVHDLModel.Object.SharedVariable.

Example

shared variable counter : counter_pt;

Inheritance

Inheritance diagram of SharedVariable

Parameters:
__init__(node, identifiers, subtype, documentation=None)[source]

Initializes a shared variable.

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

  • identifiers (List[str]) – A list of identifiers.

  • subtype (Symbol) – Reference to the object’s subtype.

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

Return type:

None

classmethod parse(variableNode, furtherIdentifiers=None)[source]

Translates the IIR node of the variable declaration to a SharedVariable.

Parameters:
  • variableNode (Iir) – The IIR node of the variable declaration.

  • furtherIdentifiers (Iterable[str]) – Optional, the remaining identifiers, when one declaration names several.

Return type:

Self

Returns:

The translated variable 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.

Copy()

Create a copy of this object declaration.

The copy has no parent and no object vertex. Its subtype is a copy of this declaration’s subtype.

Return type:

Self

Returns:

The new object declaration.

DenoteBy(name, region, place, symbol)

Determine the model entity a name denoting this object denotes, as a part of a type mark: this object.

A port or a parameter isn’t usable in its own interface list (_USABLE_IN_OWN_INTERFACE_LIST): e.g. the subtype of a port can’t name another port of the same port list (i'subtype).

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 object, or None if a name can’t denote it here (reported as a warning).

Raises:

UnhandledCriticalWarningError – If the object is a port or parameter used in its own interface list, and 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.

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 one of the model entity’s normalized identifiers.

Parameters:

normalizedIdentifier (str) – One of the model entity’s normalized (lower case) identifiers.

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 Identifiers: tuple[str]

Read-only property to access the model entity’s identifiers (_identifiers).

Returns:

Tuple of identifiers.

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 object: the type mark of its subtype indication.

Parameters:

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

Return type:

Generator[tuple[DeclarativeRegionMixin, ModelEntity, SubtypeSymbol]]

Returns:

A generator to iterate (region, place, type mark) tuples: the object’s subtype indication.

property NormalizedIdentifiers: tuple[str]

Read-only property to access the model entity’s normalized identifiers (_normalizedIdentifiers).

See also

Returns:

Tuple of normalized identifiers.

property ObjectVertex: Vertex | None

Read-only property to access the corresponding object vertex (_objectVertex).

The object vertex references this Object by its value field.

Returns:

The corresponding object vertex.

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

Split()

Split this declaration into one declaration per identifier.

IEEE Std 1076 defines a declaration with an identifier list as equivalent to a sequence of single declarations, one per identifier, in list order: signal a, b : bit; declares the same as signal a : bit; signal b : bit;. This declaration keeps its first identifier. For every other identifier, a new declaration is created by Copy(): it has its own copy of the subtype indication and of the default expression, and the same documentation. Single declarations created before are dropped.

Without a parent, the new declarations have no parent either: the caller places them. With a parent, the parent’s mutator splits the declaration and inserts the new declarations right after it, e.g. WithPortsMixin.SplitPortItem for a port.

A declaration with one identifier is unchanged.

Return type:

tuple[Self, ...]

Returns:

Tuple of declarations, one per identifier in list order, starting with this declaration.

Raises:
  • NotAChildError – If this declaration’s parent doesn’t list it.

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

property Subtype: Symbol

Read-only property to access the subtype (_subtype).

Returns:

The subtype.

Visit(visitor)[source]

Walk this shared variable declaration, its subtype with a visitor.

Parameters:

visitor (Visitor) – The visitor receiving the events.

Return type:

None

_KeepIdentifier(position)

Reduce the identifier list to the identifier at a position and drop the single declarations.

Parameters:

position (int) – The position of the identifier to keep.

Return type:

None

_OBJECT_KEYWORD: ClassVar[tuple[ReservedWord, ...]] = (ReservedWord.Shared, ReservedWord.Variable)

The reserved words introducing this object class.

_SplitCopies()

Create one parentless copy of this declaration per identifier after the first, each keeping its identifier.

Return type:

list[Self]

Returns:

List of new declarations, in list order.

_SplitInParent()

Split this object declaration by the mutator of its parent (SplitDeclaredItem()).

Return type:

tuple[Self, ...]

Returns:

Tuple of declarations, one per identifier in list order, starting with this object declaration.

_USABLE_IN_OWN_INTERFACE_LIST: ClassVar[bool] = True

Usable by a name in its own interface list.

__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__()

Formats the object declaration.

Format: signal s1, s2 : bit

Return type:

str

Returns:

Formatted object declaration.

_documentation: str | None

The associated documentation of a model entity.

_identifiers: tuple[str]

A list of identifiers.

_normalizedIdentifiers: tuple[str]

A list of normalized (lower case) identifiers.

_objectVertex: Vertex | None

The vertex representing this object in the design’s object graph.

_parent: ModelEntity

Reference to a parent entity in the logical model hierarchy.

_singleDeclarations: list[SingleDeclarationMixin] | None

Cached single declarations, or None.

_subtype: Symbol

Reference to the object’s subtype.

class pyGHDL.dom.Object.Signal(node, identifiers, subtype, defaultExpression, documentation=None)[source]

Represents a signal.

This class implements a pyGHDL.dom object derived from pyVHDLModel.Object.Signal.

Example

signal counter : unsigned := (others => '0');

Inheritance

Inheritance diagram of Signal

Parameters:
  • node (Iir)

  • identifiers (List[str])

  • subtype (Symbol)

  • defaultExpression (ExpressionUnion)

  • documentation (str)

__init__(node, identifiers, subtype, defaultExpression, documentation=None)[source]

Initializes a signal.

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

  • identifiers (List[str]) – A list of identifiers.

  • subtype (Symbol) – Reference to the object’s subtype.

  • defaultExpression (BaseExpression | QualifiedExpression | FunctionCall | TypeConversion | Literal) – The default value, or None if none was given.

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

Return type:

None

classmethod parse(signalNode, furtherIdentifiers=None)[source]

Translates the IIR node of the signal declaration to a Signal.

Parameters:
  • signalNode (Iir) – The IIR node of the signal declaration.

  • furtherIdentifiers (Iterable[str]) – Optional, the remaining identifiers, when one declaration names several.

Return type:

Self

Returns:

The translated signal 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.

Copy()[source]

Create a copy of this signal.

The copy has no parent and no object vertex. Its subtype and default expression are copies of this signal’s subtype and default expression.

Return type:

Self

Returns:

The new signal.

property DefaultExpression: BaseExpression | QualifiedExpression | FunctionCall | TypeConversion | Literal | None

Read-only property to access the default expression (_defaultExpression).

Returns:

The default expression, or None if not set.

DenoteBy(name, region, place, symbol)

Determine the model entity a name denoting this object denotes, as a part of a type mark: this object.

A port or a parameter isn’t usable in its own interface list (_USABLE_IN_OWN_INTERFACE_LIST): e.g. the subtype of a port can’t name another port of the same port list (i'subtype).

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 object, or None if a name can’t denote it here (reported as a warning).

Raises:

UnhandledCriticalWarningError – If the object is a port or parameter used in its own interface list, and 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.

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 one of the model entity’s normalized identifiers.

Parameters:

normalizedIdentifier (str) – One of the model entity’s normalized (lower case) identifiers.

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 Identifiers: tuple[str]

Read-only property to access the model entity’s identifiers (_identifiers).

Returns:

Tuple of identifiers.

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 object: the type mark of its subtype indication.

Parameters:

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

Return type:

Generator[tuple[DeclarativeRegionMixin, ModelEntity, SubtypeSymbol]]

Returns:

A generator to iterate (region, place, type mark) tuples: the object’s subtype indication.

property NormalizedIdentifiers: tuple[str]

Read-only property to access the model entity’s normalized identifiers (_normalizedIdentifiers).

See also

Returns:

Tuple of normalized identifiers.

property ObjectVertex: Vertex | None

Read-only property to access the corresponding object vertex (_objectVertex).

The object vertex references this Object by its value field.

Returns:

The corresponding object vertex.

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

Split()

Split this declaration into one declaration per identifier.

IEEE Std 1076 defines a declaration with an identifier list as equivalent to a sequence of single declarations, one per identifier, in list order: signal a, b : bit; declares the same as signal a : bit; signal b : bit;. This declaration keeps its first identifier. For every other identifier, a new declaration is created by Copy(): it has its own copy of the subtype indication and of the default expression, and the same documentation. Single declarations created before are dropped.

Without a parent, the new declarations have no parent either: the caller places them. With a parent, the parent’s mutator splits the declaration and inserts the new declarations right after it, e.g. WithPortsMixin.SplitPortItem for a port.

A declaration with one identifier is unchanged.

Return type:

tuple[Self, ...]

Returns:

Tuple of declarations, one per identifier in list order, starting with this declaration.

Raises:
  • NotAChildError – If this declaration’s parent doesn’t list it.

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

property Subtype: Symbol

Read-only property to access the subtype (_subtype).

Returns:

The subtype.

Visit(visitor)[source]

Walk this signal declaration, its subtype and its default expression with a visitor.

Parameters:

visitor (Visitor) – The visitor receiving the events.

Return type:

None

_KeepIdentifier(position)

Reduce the identifier list to the identifier at a position and drop the single declarations.

Parameters:

position (int) – The position of the identifier to keep.

Return type:

None

_OBJECT_KEYWORD: ClassVar[tuple[ReservedWord, ...]] = (ReservedWord.Signal,)

The reserved words introducing this object class.

_SplitCopies()

Create one parentless copy of this declaration per identifier after the first, each keeping its identifier.

Return type:

list[Self]

Returns:

List of new declarations, in list order.

_SplitInParent()

Split this object declaration by the mutator of its parent (SplitDeclaredItem()).

Return type:

tuple[Self, ...]

Returns:

Tuple of declarations, one per identifier in list order, starting with this object declaration.

_USABLE_IN_OWN_INTERFACE_LIST = True

Usable by a name in its own interface list.

_VisitDefaultExpression(visitor)

Walk the default expression, if any, after a variable assignment delimiter (:=) 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

__str__()

Formats the object declaration.

Format: signal s1, s2 : bit

Return type:

str

Returns:

Formatted object declaration.

_defaultExpression

The default value, or None if none was given.

_documentation

The associated documentation of a model entity.

_identifiers

A list of identifiers.

_normalizedIdentifiers

A list of normalized (lower case) identifiers.

_objectVertex

The vertex representing this object in the design’s object graph.

_parent

Reference to a parent entity in the logical model hierarchy.

_singleDeclarations

Cached single declarations, or None.

_subtype

Reference to the object’s subtype.

class pyGHDL.dom.Object.File(node, identifiers, subtype, documentation=None)[source]

Represents a file.

This class implements a pyGHDL.dom object derived from pyVHDLModel.Object.File.

Example

file INPUT : TEXT;

Inheritance

Inheritance diagram of File

Parameters:
__init__(node, identifiers, subtype, documentation=None)[source]

Initializes a file object.

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

  • identifiers (List[str]) – A list of identifiers.

  • subtype (Symbol) – Reference to the object’s subtype.

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

Return type:

None

classmethod parse(fileNode, furtherIdentifiers=None)[source]

Translates the IIR node of the file declaration to a File.

Parameters:
  • fileNode (Iir) – The IIR node of the file declaration.

  • furtherIdentifiers (Iterable[str]) – Optional, the remaining identifiers, when one declaration names several.

Return type:

Self

Returns:

The translated file 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.

Copy()

Create a copy of this object declaration.

The copy has no parent and no object vertex. Its subtype is a copy of this declaration’s subtype.

Return type:

Self

Returns:

The new object declaration.

DenoteBy(name, region, place, symbol)

Determine the model entity a name denoting this object denotes, as a part of a type mark: this object.

A port or a parameter isn’t usable in its own interface list (_USABLE_IN_OWN_INTERFACE_LIST): e.g. the subtype of a port can’t name another port of the same port list (i'subtype).

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 object, or None if a name can’t denote it here (reported as a warning).

Raises:

UnhandledCriticalWarningError – If the object is a port or parameter used in its own interface list, and 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.

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 one of the model entity’s normalized identifiers.

Parameters:

normalizedIdentifier (str) – One of the model entity’s normalized (lower case) identifiers.

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 Identifiers: tuple[str]

Read-only property to access the model entity’s identifiers (_identifiers).

Returns:

Tuple of identifiers.

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 object: the type mark of its subtype indication.

Parameters:

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

Return type:

Generator[tuple[DeclarativeRegionMixin, ModelEntity, SubtypeSymbol]]

Returns:

A generator to iterate (region, place, type mark) tuples: the object’s subtype indication.

property NormalizedIdentifiers: tuple[str]

Read-only property to access the model entity’s normalized identifiers (_normalizedIdentifiers).

See also

Returns:

Tuple of normalized identifiers.

property ObjectVertex: Vertex | None

Read-only property to access the corresponding object vertex (_objectVertex).

The object vertex references this Object by its value field.

Returns:

The corresponding object vertex.

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

Split()

Split this declaration into one declaration per identifier.

IEEE Std 1076 defines a declaration with an identifier list as equivalent to a sequence of single declarations, one per identifier, in list order: signal a, b : bit; declares the same as signal a : bit; signal b : bit;. This declaration keeps its first identifier. For every other identifier, a new declaration is created by Copy(): it has its own copy of the subtype indication and of the default expression, and the same documentation. Single declarations created before are dropped.

Without a parent, the new declarations have no parent either: the caller places them. With a parent, the parent’s mutator splits the declaration and inserts the new declarations right after it, e.g. WithPortsMixin.SplitPortItem for a port.

A declaration with one identifier is unchanged.

Return type:

tuple[Self, ...]

Returns:

Tuple of declarations, one per identifier in list order, starting with this declaration.

Raises:
  • NotAChildError – If this declaration’s parent doesn’t list it.

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

property Subtype: Symbol

Read-only property to access the subtype (_subtype).

Returns:

The subtype.

Visit(visitor)[source]

Walk this file declaration, its subtype with a visitor.

Parameters:

visitor (Visitor) – The visitor receiving the events.

Return type:

None

_KeepIdentifier(position)

Reduce the identifier list to the identifier at a position and drop the single declarations.

Parameters:

position (int) – The position of the identifier to keep.

Return type:

None

_OBJECT_KEYWORD: ClassVar[tuple[ReservedWord, ...]] = (ReservedWord.File,)

The reserved words introducing this object class.

_SplitCopies()

Create one parentless copy of this declaration per identifier after the first, each keeping its identifier.

Return type:

list[Self]

Returns:

List of new declarations, in list order.

_SplitInParent()

Split this object declaration by the mutator of its parent (SplitDeclaredItem()).

Return type:

tuple[Self, ...]

Returns:

Tuple of declarations, one per identifier in list order, starting with this object declaration.

_USABLE_IN_OWN_INTERFACE_LIST: ClassVar[bool] = True

Usable by a name in its own interface list.

__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__()

Formats the object declaration.

Format: signal s1, s2 : bit

Return type:

str

Returns:

Formatted object declaration.

_documentation: str | None

The associated documentation of a model entity.

_identifiers: tuple[str]

A list of identifiers.

_normalizedIdentifiers: tuple[str]

A list of normalized (lower case) identifiers.

_objectVertex: Vertex | None

The vertex representing this object in the design’s object graph.

_parent: ModelEntity

Reference to a parent entity in the logical model hierarchy.

_singleDeclarations: list[SingleDeclarationMixin] | None

Cached single declarations, or None.

_subtype: Symbol

Reference to the object’s subtype.