VHDLDomain.Directive

The directives of the domain vhdl: each describes an object of a design read into the domain.

vhdl:design and vhdl:library set the design and library the following directives and references of the document are in, until the next one.

Classes

  • VHDLDirective: Base-class of the directives of domain vhdl: access to the domain, the current design and library, and the

  • DesignDirective: The directive vhdl:design: a design’s target and index entry, and the current design of the document.

  • LibraryDirective: The directive vhdl:library: a library’s target, index entry and design units, and the current library of the

Classes

class VHDLDomain.Directive.VHDLDirective(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)[source]

Base-class of the directives of domain vhdl: access to the domain, the current design and library, and the registration of a described object.

Inheritance

Inheritance diagram of VHDLDirective

_WARNING_TYPE: ClassVar[str] = 'vhdl'

Type of the warnings the directives emit, the domain’s name.

_Domain()[source]

Return the domain vhdl.

Return type:

VHDLDomain

Returns:

The domain.

_CurrentDesign()[source]

Return the design the directive is in: the one of option :design:, else the current one.

A missing design is warned about.

Return type:

tuple[str | None, Design | None]

Returns:

The design’s name and the design, or None and None if no design is current, or the name and None if the design wasn’t read.

_NodeID(objectType, qualifiedName)[source]

Return the anchor of a described object, unique in the document.

The anchor is built from the object type and the lower-case qualified name, e.g. vhdl-entity-stopwatch.lib_stopwatch.counter.

Parameters:

  • objectType (str) – The object type, as entity.

  • qualifiedName (str) – The object’s qualified name, as StopWatch.lib_StopWatch.Counter.

Return type:

str

Returns:

The anchor, from the lower-case qualified name.

_Target(objectType, qualifiedName, indexText)[source]

Create the target and the index entry of a described object, and register it in the domain.

Parameters:

  • objectType (str) – The object type, as entity.

  • qualifiedName (str) – The object’s qualified name, as StopWatch.lib_StopWatch.Counter.

  • indexText (str) – The text of the object’s entry in the general index.

Return type:

list[Node]

Returns:

The index node and the target node.

_Documentation(documentation)[source]

Parse an object’s documentation comment as reStructuredText.

A line’s leading comment marker -- and the space following it are removed, so a comment block reads as text.

Parameters:

documentation (str | None) – The documentation comment, as the frontend extracted it, or None.

Return type:

list[Node]

Returns:

The parsed nodes, none for no or an empty comment.

_Format(element)[source]

Write a model element - a symbol, an expression - as VHDL source text.

An element the writer of pyVHDLModel can’t write yet is written by its name, if it has one, and warned about.

Parameters:

element (object) – The model element.

Return type:

str

Returns:

The VHDL source text.

property config: Config

Reference to the Config object.

Added in version 1.8.

property env: BuildEnvironment

Reference to the BuildEnvironment object.

Added in version 1.8.

final_argument_whitespace = False

May the final argument contain whitespace?

has_content = False

May the directive have content?

option_spec = None

Mapping of option names to validator functions.

optional_arguments = 0

Number of optional arguments after the required arguments.

required_arguments = 0

Number of required directive arguments.

class VHDLDomain.Directive.DesignDirective(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)[source]

The directive vhdl:design: a design’s target and index entry, and the current design of the document.

.. vhdl:design:: StopWatch

The argument is the design’s name, a key of vhdl_designs. Every directive and reference following it in the document is in this design. The directive writes no visible output except its content; placed above a page’s title, its target is the title, as a label is. With :no-index:, it only makes the design the current one - for the other pages of a design.

A design with generated pages (key pages in vhdl_designs) lists its library pages in a hidden table of contents, so they are below the directive’s document in the navigation.

Inheritance

Inheritance diagram of DesignDirective

directiveName: ClassVar[str] = 'vhdl:design'

Name the directive is invoked by.

has_content = True

The content describes the design.

required_arguments = 1

The design’s name.

option_spec = {'no-index': <function flag>}

Make the design current, without a target and index entry.

run()[source]

Register the design, make it the current one, and parse the content.

Return type:

list[Node]

Returns:

An index node, the design’s target and the content’s nodes.

_CurrentDesign()

Return the design the directive is in: the one of option :design:, else the current one.

A missing design is warned about.

Return type:

tuple[str | None, Design | None]

Returns:

The design’s name and the design, or None and None if no design is current, or the name and None if the design wasn’t read.

_Documentation(documentation)

Parse an object’s documentation comment as reStructuredText.

A line’s leading comment marker -- and the space following it are removed, so a comment block reads as text.

Parameters:

documentation (str | None) – The documentation comment, as the frontend extracted it, or None.

Return type:

list[Node]

Returns:

The parsed nodes, none for no or an empty comment.

_Domain()

Return the domain vhdl.

Return type:

VHDLDomain

Returns:

The domain.

_Format(element)

Write a model element - a symbol, an expression - as VHDL source text.

An element the writer of pyVHDLModel can’t write yet is written by its name, if it has one, and warned about.

Parameters:

element (object) – The model element.

Return type:

str

Returns:

The VHDL source text.

_NodeID(objectType, qualifiedName)

Return the anchor of a described object, unique in the document.

The anchor is built from the object type and the lower-case qualified name, e.g. vhdl-entity-stopwatch.lib_stopwatch.counter.

Parameters:

  • objectType (str) – The object type, as entity.

  • qualifiedName (str) – The object’s qualified name, as StopWatch.lib_StopWatch.Counter.

Return type:

str

Returns:

The anchor, from the lower-case qualified name.

_Target(objectType, qualifiedName, indexText)

Create the target and the index entry of a described object, and register it in the domain.

Parameters:

  • objectType (str) – The object type, as entity.

  • qualifiedName (str) – The object’s qualified name, as StopWatch.lib_StopWatch.Counter.

  • indexText (str) – The text of the object’s entry in the general index.

Return type:

list[Node]

Returns:

The index node and the target node.

_WARNING_TYPE: ClassVar[str] = 'vhdl'

Type of the warnings the directives emit, the domain’s name.

property config: Config

Reference to the Config object.

Added in version 1.8.

property env: BuildEnvironment

Reference to the BuildEnvironment object.

Added in version 1.8.

final_argument_whitespace = False

May the final argument contain whitespace?

optional_arguments = 0

Number of optional arguments after the required arguments.

class VHDLDomain.Directive.LibraryDirective(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)[source]

The directive vhdl:library: a library’s target, index entry and design units, and the current library of the document.

.. vhdl:library:: lib_StopWatch
   :design: StopWatch

The argument is the library’s name; without :design:, the library is in the current design. Every directive and reference following it in the document is in this library. The directive writes the library’s documentation, its content, and a table of the library’s design units - each name referring to the unit’s description, if there is one. With :no-index:, it only makes the library the current one, and writes nothing.

Inheritance

Inheritance diagram of LibraryDirective

directiveName: ClassVar[str] = 'vhdl:library'

Name the directive is invoked by.

has_content = True

The content describes the library.

required_arguments = 1

The library’s name.

option_spec = {'design': <function unchanged_required>, 'no-index': <function flag>}

The design, if not the current one; :no-index: makes the library current, without describing it.

_UNIT_KINDS: ClassVar[tuple[tuple[str, str, str], ...]] = (('Context', 'Contexts', 'ctx'), ('Entity', 'Entities', 'ent'), ('Package', 'Packages', 'pack'), ('Configuration', 'Configurations', 'config'))

The kinds of design units the table lists, with the collection of Library and the role.

run()[source]

Register the library, make it the current one, and write its documentation, content and design units.

Return type:

list[Node]

Returns:

An index node, the library’s target, and the library’s description.

_DesignUnits(library)[source]

Create the table of a library’s design units: kind and name, the name referring to the unit’s description.

Parameters:

library (Library) – The library.

Return type:

table | None

Returns:

The table, or None if the library has no design units.

_CurrentDesign()

Return the design the directive is in: the one of option :design:, else the current one.

A missing design is warned about.

Return type:

tuple[str | None, Design | None]

Returns:

The design’s name and the design, or None and None if no design is current, or the name and None if the design wasn’t read.

_Documentation(documentation)

Parse an object’s documentation comment as reStructuredText.

A line’s leading comment marker -- and the space following it are removed, so a comment block reads as text.

Parameters:

documentation (str | None) – The documentation comment, as the frontend extracted it, or None.

Return type:

list[Node]

Returns:

The parsed nodes, none for no or an empty comment.

_Domain()

Return the domain vhdl.

Return type:

VHDLDomain

Returns:

The domain.

_Format(element)

Write a model element - a symbol, an expression - as VHDL source text.

An element the writer of pyVHDLModel can’t write yet is written by its name, if it has one, and warned about.

Parameters:

element (object) – The model element.

Return type:

str

Returns:

The VHDL source text.

_NodeID(objectType, qualifiedName)

Return the anchor of a described object, unique in the document.

The anchor is built from the object type and the lower-case qualified name, e.g. vhdl-entity-stopwatch.lib_stopwatch.counter.

Parameters:

  • objectType (str) – The object type, as entity.

  • qualifiedName (str) – The object’s qualified name, as StopWatch.lib_StopWatch.Counter.

Return type:

str

Returns:

The anchor, from the lower-case qualified name.

_Target(objectType, qualifiedName, indexText)

Create the target and the index entry of a described object, and register it in the domain.

Parameters:

  • objectType (str) – The object type, as entity.

  • qualifiedName (str) – The object’s qualified name, as StopWatch.lib_StopWatch.Counter.

  • indexText (str) – The text of the object’s entry in the general index.

Return type:

list[Node]

Returns:

The index node and the target node.

_WARNING_TYPE: ClassVar[str] = 'vhdl'

Type of the warnings the directives emit, the domain’s name.

property config: Config

Reference to the Config object.

Added in version 1.8.

property env: BuildEnvironment

Reference to the BuildEnvironment object.

Added in version 1.8.

final_argument_whitespace = False

May the final argument contain whitespace?

optional_arguments = 0

Number of optional arguments after the required arguments.