`vhdl_parser` module

Provides the VHDLParser class that is used to load and parse VHDL files and extract the key information (entities, ports etc.) in an easy to use structure.

Module functions summary

`pp`	Pretty printer for the XElement tree.

Module classes summary

`Namespace`	Dict whose values can be accessed as attributes
`VHDLParser`	ElementTree object representing a set of VHDL files and allows loading and parsing VHDL files, and provides direct access to entity, architectures, variables etc across the project

Module functions

pp(elem, level=0, collapse=(), max_depth=0, width=80): Pretty printer for the XElement tree.

Module classes

class Namespace

Bases: dict

Dict whose values can be accessed as attributes

__init__(*args, **kwargs)

clear() → None. Remove all items from D.

copy() → a shallow copy of D

fromkeys(value=None, /): Create a new dictionary with keys from iterable and values set to value.

get(key, default=None, /): Return the value for key if key is in the dictionary, else default.

items() → a set-like object providing a view on D's items

keys() → a set-like object providing a view on D's keys

pop(k[, d]) → v, remove specified key and return the corresponding value.: If the key is not found, return the default if given; otherwise, raise a KeyError.

popitem()

Remove and return a (key, value) pair as a 2-tuple.

Pairs are returned in LIFO (last-in, first-out) order. Raises KeyError if the dict is empty.

setdefault(key, default=None, /)

Insert key with a value of default if key is not in the dictionary.

Return the value for key if key is in the dictionary, else default.

update([E, ]**F) → None. Update D from dict/iterable E and F.: If E is present and has a .keys() method, then does: for k in E: D[k] = E[k] If E is present and lacks a .keys() method, then does: for k, v in E: D[k] = v In either case, this is followed by: for k in F: D[k] = F[k]

values() → an object providing a view on D's values

class VHDLParser

Bases: XElement

ElementTree object representing a set of VHDL files and allows loading and parsing VHDL files, and provides direct access to entity, architectures, variables etc across the project

__init__()

Creates a new parser object.

The following attributes are initialied:

files (dict): dict in the format {filename: file_node, ...} that maps filenames to top node of the element tree describing the parsed VHDL file.
- filename (str) is a string containing the filename of the parsed VHDL file
- file_node (XElement): is the top XElement node of the parsed VHDL code.
entities (dict): dict in the format {entity_name : entity_node, ...}` that maps entity name to the Xelement node that described that entity in the parsed element tree.
- entity (str): entity name
- entity_node (XElement): node corresponding to the entity

add_label(namespace, labels, obj)

Adds one or labels pointing to the object obj to the global label dict under the namespace namespace

Parameters:

namespace (str) – namespace (‘libraries’, ‘entities’ etc) to which the label(s) are associated with.
labels (str or list) – label strings or list of label strings that contain the label name.
obj – element associated with the label.

analyze_entities(top_elem)

Extracts useful information about all entities in the file.

Parameters:

top_elem (XElement) – file element to analyze
() (label_list) – List of all encountered labels, to be updated with labels encountered in the analysis

Returns:

containsthe following information:

<entity_name_in_lowercase1>:
    name: <entity_name>
    ports: <list of ports>
    generics: <list of generics>
    brief: <brief description of entity>
    details: <detailed description of entity
    tail_comment: <tail comment after end of entity>
    source_file: <name of the source filename>
<entity_name_in_lowercase2>:
    ...

Return type:

Namespace

analyze_entity_interface(interface_nodes)

Extract port or generics information from an entity element entity_elem.

Parameters:

line_name (str) – Xpath used to find the element list
element_name (str) – Xpath used to find the element within the list

Returns:

list of dicts containing:

name_list (list of str): list of port/generic identifier names. Is empty if the entry is for an isolated (sectionning) comment. definition (str): rest of the port/generics definition comments (str): Single newline-separated string containing both the head and tail comment for that interface element

Return type:

(list)

analyze_libraries(top_elem)

Analyze the file node top_elem and extract the library information.

Parameters:

top_elem (XElement) – file element to analyze
() (label_list) – unused List of all encountered labels, to be updated with labels encountered in the analysis

Returns:

Summary information on library usage

Return type:

Namespace

append(subelement, /)

attrib: Dictionary of the element’s attributes.

clear()

dedent(s)

extend(elements, /)

find(path, namespaces=None)

findall(paths, namespaces=None)

Extesion of findall to return a list of nodes matching one or multiple tag or Xpath strings.

Parameters:: paths (str or list of str) – If paths is a string, search for the nodes with the tag or XPath it specifies. If paths is a list of strings, returns nodes matchin all the specified tags or Xpaths.

Returns: list: list of nodes matching the specified tag(s) or Xpath(s). If multiple strings: are provided, the same nodes may appear multiple times, and nodes are not listed in their order of appearance in the tree.

findallbetween(tag, start_at=None, start_after=None, stop_before=None, stop_at=None, recurse=True)

findindex(elem_or_path)

Like find(), looks recursively for an element, but returns both the parent and index of the element. Also can search for an object in addition to a tag or path.

Parameters:: elem_or_path (str or Element) – element to search.

findsibling(elem_or_path, offset=1)

findsubtext(path, default=None, namespaces=None): Returns the combined text of the element specified by path and all its children, crossing all hierarchy levels

findtext(path, default=None, namespaces=None)

findwithsubtext(path, text, caseless=False)

findwithtext(text, path='.//*', caseless=False)

get(key, default=None)

get_comments(entity, start_before=None, start_after=None, end_before=None, end_after=None, dedent=True)

get_entity(entity_name)

get_file_with_entity(name): Returns the file node than contains the entity name

get_head_and_tail_comments(node, verbose=0)

Return the head and tail comment node of the object described by node.

Essentially returns the first and last comment_block Element of node.

Parameters:

node (Xelement) – Xelement node from which the comments are to be extracted
verbose (int) – When non-zero, prints debugging messages.

Returns:

(head_comment, tail_comment) tuple providing the head and tail comment nodes. Each of these: elements can be None if unavailable.

Return type:

tuple

group(element_list, tag)

Group the elements in element_list into a new XElement with tag tag.

Parameters:

element_list (list) – List of XElements to group. If element_list is empty of is None, nothing is done.
tag (str) – Tag of the new parent Xelement that contains the specified elements

group_comments(et, verbose=0)

Scan the Element tree and group sequence of comments lines into comment_block or blank_line elements.

The provided element tree is modified in-place, but the text represented by the tree is unchanged.

Handles delimited (/* */) as well as line comments (--).

A comment_block ends when its indentation level moves left or when a non-comment/non-blank token is detected.

Parameters:

et (XElement) – element tree to be processed
verbose (int) – If non-zero, prints debugging messages

index(children)

Returns the the index of a children within this element only (does not search into the children elements; see findindex() for this.)

Parameters:: children (Element) – Element object for which we seek the index
Returns:: index of object.
Return type:: int

Exceptions:

Raises a ValueError if the children cannot be found

insert(index, subelement, /)

is_fence(s)

Returns True if the string is a valid RestructuredText fence line.

A valid fence line contains only a consecutive series of three or more fence characters preceded and succeded by spaces. The string such as === New Function or --- Function below --- return False.

Parameters:: s (str) – string to be tested
Returns:: True if the string is a valid RestructuredText fence.
Return type:: bool

items()

iter(tag=None)

iterbetween(start_at=None, start_after=None, stop_before=None, stop_at=None, recurse=True)

Same as iter(), excepts this method yields only the elements between the specified starting and ending nodes.

Parameters:

start_at (str) – Xpath describing the first element to be included
start_after (str) – Xpath describing the element after which the elements will be included
stop_before (str) – Xpath indicating the element before which the elements will be included.
stop_at (str) – Xpath indicating the last element to be included.

Notes

Both start options should not be provided. If so, start_after will takes precedence over start_at.
Both end options should not be provided. If so, stop_before will takes precedence over stop_at.
The end nodes should not appear before the start nodes

iterfind(path, namespaces=None)

itertext()

keys()

makeelement(tag, attrib, /)

move(element, target_element, index=None)

Move element(s) element into target_element at specified position.

Parameters:

element (list or XElement) – Element(s) to move. If element is a list or tuple, move all the specified elements.
target_element (XElement) – Destination element
index (int or None) – If index = None or index = -1, appends data to the target element. If index >= 0, insert the elements starting at the specified index on the target element.

move_header_comments(et, verbose=0)

Scan the Element tree and move comments and spaces immediately before a production element into that element.

The provided element tree is modified in-place, but the text represented by the tree is unchanged.

Assumes that comments have been grouped into comment blocks by :meth:group_comments.

Only comment_blocks starting on column 0 are moved. COmments blocks include the indentation whitespace, so comments indented to any level are candidates, but not comments appearing after any other statements (such as trailing comments).

Parameters:

et (XElement) – Element tree to process
verbose (int) – if non-zero, prints debugging messages

move_tail_comments(et, verbose=0)

Scan the Element tree and move comments and spaces immediately after a production element into that element.

Assumes that comments have been grouped into comment blocks by :meth:group_comments.

The provided element tree is modified in-place, but the text represented by the tree is unchanged.

Parameters:

et (XElement) – Element tree to process
verbose (int) – if non-zero, prints debugging messages

parse_file(filename, verbose=0)

Parse and analyze the specified VHDL file and add the resulting file node to this element, and also stores summarized information on the file, entities etc.

self.files map is updated with the file node.

self.entities is updated with the summarized information on the entity(ies) in the file.

Parameters:

filename (str) – filename of the VHDL file to be parsed. The path is relative to the root vhdl path defined in the sphinx config file.
verbose (int) – If non-zero, debugging messages are printed.

Returns:

A XElement with tag='file' and attribute filename=<current_filename>' whose children describe the parsed file.

Return type:

XElement

pp(level=0, collapsed_expr=['comment', 'target', 'name', 'expression', 'simple_expression', 'simple_name', 'association_element', '_'], max_depth=0, width=80): Pretty printer for the XElement tree.

print_debug(verbose_level, *args)

Prints strings depending on the verbose level.

Parameters:

verbose_level (int) – Selects which string to print. 0 prints none, 1 prints the first one, 2 prints the first two etc.
args (list) – list of string to print

remove(subelement, /)

remove_comment_marks(lines, dedent=False)

Remove leading and trailing comment marks, decorative headers as well as Doxygen markers.

A decorative header is a repeated fence character (-,`*`, # etc) followed by some text (e.g. ### Example 1, —— Example 2 —)).

replace(s, substrings, replacement_string): Replace all occurences of the substrings in string s by replacement_string

set(key, value, /)

split_block_comments(block_comments, dedent_brief=True, dedent_details=True, verbose=0)

Split a comment block in two parts: the first paragraph is stripped of spaces and is return as a first list, while the rest of the comment block is in the second list and is dedented as a block.

Returns:

(brief, details) tuple where

brief (list of str) is the lines of the first paragraph of the first comment block

details (list of str) is the dedented lines of the subsequent blocks

property subtext: Return the text of this element and all its subelements.

subtextbetween(start_at=None, start_after=None, end_before=None, end_after=None): Like subtext(), but only returns the contatenated text between the specified starting and ending elements, crossing hierarchy.

tag: The element’s name.

tail: Text after this element’s end tag, but before the next sibling element’s start tag. This is either a string or the value None. Note that if there was no text, this attribute may be either None or an empty string, depending on the parser.

text: Text before first subelement. This is either a string or the value None. Note that if there is no text, this attribute may be either None or the empty string, depending on the parser.

token_list_to_element_tree(token_list)

Convert VSG token list representing the content of a VHDL file into an hierarchichal XElement tree.

This method converts each token of token_list into an Xelement that is added as children to the parent Xelement with the text of the original token. The row and column where each element appears is stored as an Xelement attribute to facilitate processing.

The enter_prod and leave_prod attributes of the tokens are used to determine when we are entering and leaving a hiearchy level. When a level is entered, a new parent Xelement is created tagged with the name of the production we entered, and all subsequent tokens are assigned to that parent until we exit that hierarchy level. This is repeated recursively.

The top (i.e root) Xelement represents the VHDL files from which the tagged list was revived, and is tagged with the filename attribute containing the full file path and name of the source file, as provided by the parameter filename.

The parent nodes do not have associated text. The overall text represented by the top Xelement and recursively by all its children is identical to the original text reprented by the VSG token list.

All tokens

Parameters:: token_list (list) – list of tokens produced by VSG. The first element of the list shall have the filename attribute that described the path to the source file from which the tokens were parsed.
Returns:: A XElement tree representing the VHDL file.
Return type:: XElement

vhdl_parser module

`vhdl_parser` module