pyGHDL.dom._Utils

This module offers helper functions to read an IIR node’s kind, name, label, mode and documentation.

Functions


Functions

pyGHDL.dom._Utils.CheckForErrors()[source]

Check if an error occurred in libghdl and raise an exception if so.

Behavior:

  1. read the error buffer and clear it afterwards.

  2. convert it into a list of internal messages for a LibGHDLException.

  3. raise a DOMException with a nested LibGHDLException as a __cause__.

Raises:

DOMException – If an error occurred in libghdl.

Return type:

None

pyGHDL.dom._Utils.GetIirKindOfNode(node)[source]

Return the kind of a node in the IIR tree.

Parameters:

node (Iir) – The IIR node to read the kind of.

Return type:

Iir_Kind

Returns:

The IIR kind of a node.

Raises:

ValueError – If parameter node is Null_Iir.

pyGHDL.dom._Utils.GetNameOfNode(node)[source]

Return the Python string from node node identifier.

A character literal ('0') is returned as its character, without quotes (0). An operator symbol ("and") is returned with its quotation marks.

Parameters:

node (Iir) – The IIR node to read the identifier of.

Return type:

str

Returns:

The node’s identifier as written in the source file.

Raises:

ValueError – If parameter node is Null_Iir.

pyGHDL.dom._Utils.GetLabelOfNode(node)[source]

Return the Python string from node node’s optional label.

A statement carries its label in Label, while a generate-statement body - the branch of an if-generate or case-generate statement - carries it in Alternative_Label. No node kind has both, so the field is chosen from the node’s kind.

The label is returned as written in the source file (U1), read at the node’s location, which is the label’s.

Parameters:

node (Iir) – The IIR node to read the label of.

Return type:

str | None

Returns:

The label, or None if the node has no label field or no label was given in the source.

Raises:

ValueError – If parameter node is Null_Iir.

pyGHDL.dom._Utils.GetSourceTextOfNode(node, length=None)[source]

Reads the source text starting at an IIR node’s location.

Parameters:
  • node (Iir) – The IIR node, whose location the text starts at.

  • length (int | None) – Optional, number of bytes to read. Default: None, up to the end of the source file.

Return type:

str

Returns:

The source text, decoded with ENCODING.

pyGHDL.dom._Utils.GetDocumentationOfNode(node)[source]

Collects the doc-comment lines attached to an IIR node.

libghdl only gathers comments if Flag_Gather_Comments was enabled before parsing, which Design does.

Parameters:

node (Iir) – The IIR node to read the comments of.

Return type:

str | None

Returns:

The comment lines joined by newlines, or None if the node has no comment.

pyGHDL.dom._Utils.GetDocumentationOfDesignUnit(unitNode)[source]

Collects the doc-comment lines of a design unit (entity, architecture, package, …).

In IIR, a design unit is a Design_Unit node holding the context clause and the unit’s declaration (the Library_Unit), as in IEEE Std 1076, 13.1. A design unit’s documentation consists of the comments libghdl attached to the Design_Unit node (the comments before the unit, except the file header), followed by the comments attached to the declaration node itself. A nested package has no Design_Unit node, so only its own comments are read.

Parameters:

unitNode (Iir) – The IIR node of the unit’s declaration (entity declaration, architecture body, …).

Return type:

str | None

Returns:

The comment lines joined by newlines, or None if the unit has no comment.

pyGHDL.dom._Utils.GetModeOfNode(node)[source]

Return the mode of a node.

If the source text gives no mode (generic (G : natural)), the mode is Default.

Parameters:

node (Iir) – The IIR node to read the mode of.

Return type:

Mode

Returns:

The node’s mode as a pyVHDLModel enumeration value.

Raises: