Usage

The pyHDLParser library has two main modules vhdl_parser and verilog_parser. You import one or both of them as needed.

import hdlparse.vhdl_parser as vhdl
import hdlparse.verilog_parser as vlog

Within each module are extractor classes VhdlExtractor and VerilogExtractor that are the central mechanisms for using pyHDLParser.

vhdl_ex = vhdl.VhdlExtractor()
vlog_ex = vlog.VerilogExtractor()

VHDL

The VHDL parser can extract a variety of different objects from sourec code. It can be used to access package definitions and component declarations,type and subtype definitions, functions, and procedures found within a package. It will not process entity declarations or nested subprograms and types.

Extraction proceeds as follows:

with io.open(fname, 'rt', encoding='latin-1') as fh:
  code = fh.read()
vhdl_objs = vhdl_ex.extract_objects_from_source(code)

vhdl_objs = vhdl_ex.extract_objects(fname)

These will extract a list of all supported object types. The result is a list of objects subclassed from VhdlObject. You can pass an optional subclass of VhdlObject to filter the results for just that type. Repeated calls are more efficient when using extract_objects() which maintains a cache of all previously parsed objects in the extractor.

package example is
  component demo is
    generic (
      GENERIC1: boolean := false;
      GENERIC2: integer := 100
    );
    port (
      a, b : in std_ulogic := '1';
      c, d : out std_ulogic_vector(7 downto 0);
      e, f : inout unsigned(7 downto 0)
    );
  end component;
end package;

Each port and generic is an instance of VhdlParameter containing the name, mode (input, output, inout), and type.

import hdlparse.vhdl_parser as vhdl
from hdlparse.vhdl_parser import VhdlComponent

vhdl_ex = vhdl.VhdlExtractor()
vhdl_comps = vhdl_ex.extract_objects('example.vhdl', VhdlComponent)

for c in vhdl_comps:
  print('Component "{}":'.format(c.name))

  print('  Generics:')
  for p in c.generics:
    print('\t{:20}{:8} {}'.format(p.name, p.mode, p.data_type))

  print('  Ports:')
  for p in c.ports:
    print('\t{:20}{:8} {}'.format(p.name, p.mode, p.data_type ))

When run against the example code produces the following:

VHDL arrays

It can be useful to know which data types are an array. The VhdlExtractor class will keep track of all visited array type definitions it sees. The is_array() method lets you query the internal list to check if a type is for an array. All IEEE standard array types are supported by default. Any subtypes derived from an array type will also be considered as arrays.

import hdlparse.vhdl_parser as vhdl

vhdl_ex = vhdl.VhdlExtractor()

code = '''
package foobar is
  type custom_array is array(integer range <>) of boolean;
  subtype custom_subtype is custom_array(1 to 10);
end package;
'''
vhdl_comps = vhdl_ex.extract_objects(code)

# These all return true:
print(vhdl_ex.is_array('unsigned'))
print(vhdl_ex.is_array('custom_array'))
print(vhdl_ex.is_array('custom_subtype'))

Parsed array data can be saved to a file with save_array_types() and restored with load_array_types(). This lets you parse one set of files for type definitions and use the saved info for parsing other code at a different time.

Verilog

The Verilog parser is only able to extract module definitions with a port and optional parameter list. Verilog modules are extracted using the extract_objects() and extract_objects_from_source() methods. The latter is used when you have the code in a string. The former when you want to read the Veirlog source from a file. When parsing a file, a cache of objects is maintained so you can repeatedly call extract_objects() without reparsing the file.

with open(fname, 'rt') as fh:
  code = fh.read()
vlog_mods = vlog_ex.extract_objects_from_source(code)

vlog_mods = vlog_ex.extract_objects(fname)

The result is a list of extracted VerilogModule objects. Each instance of this class has name, generics, and ports attributes. The name attribute is the name of the module. The generics attribute is a list of extracted parameters and ports is a list of the ports on the module.

module newstyle // This is a new style module def
#(parameter real foo = 8, bar=1, baz=2,
parameter signed [7:0] zip = 100)
(
  input x, x2, inout y, y2_long_output,
  output wire [4:1] z, z2
);
endmodule

Each port and generic is an instance of VerilogParameter containing the name, mode (input, output, inout), and type.

import hdlparse.verilog_parser as vlog

vlog_ex = vlog.VerilogExtractor()
vlog_mods = vlog_ex.extract_objects('example.v')

for m in vlog_mods:
  print('Module "{}":'.format(m.name))

  print('  Parameters:')
  for p in m.generics:
    print('\t{:20}{:8}{}'.format(p.name, p.mode, p.data_type))

  print('  Ports:')
  for p in m.ports:
    print('\t{:20}{:8}{}'.format(p.name, p.mode, p.data_type))

When run against the example code produces the following:

Module "newstyle":
  Parameters:
        foo                 in      real
        bar                 in      real
        baz                 in      real
        zip                 in      signed [7:0]
  Ports:
        x                   input
        x2                  input
        y                   inout
        y2_long_output      inout
        z                   output  wire [4:1]
        z2                  output  wire [4:1]

Reference

hdlparse.minilexer

class hdlparse.minilexer.MiniLexer(tokens, flags=RegexFlag.MULTILINE)

Bases: object

Simple lexer state machine with regex matching rules

run(text)

Run lexer rules against a source text

Parameters

text (str) – Text to apply lexer to

Yields

A sequence of lexer matches.

hdlparse.verilog_parser

class hdlparse.verilog_parser.VerilogExtractor

Bases: object

Utility class that caches parsed objects

extract_objects(fname, type_filter=None)

Extract objects from a source file

Parameters

  • fname (str) – Name of file to read from

  • type_filter (class, optional) – Object class to filter results

Returns

List of objects extracted from the file.

extract_objects_from_source(text, type_filter=None)

Extract object declarations from a text buffer

Parameters

  • text (str) – Source code to parse

  • type_filter (class, optional) – Object class to filter results

Returns

List of parsed objects.

is_array(data_type)

Check if a type is an array type

Parameters

data_type (str) – Data type

Returns

True when a data type is an array.

class hdlparse.verilog_parser.VerilogModule(name, ports, generics=None, sections=None, desc=None)

Bases: hdlparse.verilog_parser.VerilogObject

Module definition

class hdlparse.verilog_parser.VerilogObject(name, desc=None)

Bases: object

Base class for parsed Verilog objects

class hdlparse.verilog_parser.VerilogParameter(name, mode=None, data_type=None, default_value=None, desc=None)

Bases: object

Parameter and port to a module

hdlparse.verilog_parser.is_verilog(fname)

Identify file as Verilog by its extension

Parameters

fname (str) – File name to check

Returns

True when file has a Verilog extension.

hdlparse.verilog_parser.parse_verilog(text)

Parse a text buffer of Verilog code

Parameters

text (str) – Source code to parse

Returns

List of parsed objects.

hdlparse.verilog_parser.parse_verilog_file(fname)

Parse a named Verilog file

Parameters

fname (str) – File to parse.

Returns

List of parsed objects.

hdlparse.vhdl_parser

class hdlparse.vhdl_parser.VhdlComponent(name, package, ports, generics=None, sections=None, desc=None)

Bases: hdlparse.vhdl_parser.VhdlObject

Component declaration

Parameters

  • name (str) – Name of the component

  • package (str) – Package containing the component

  • ports (list of VhdlParameter) – Port parameters to the component

  • generics (list of VhdlParameter) – Generic parameters to the component

  • sections (list of str) – Metacomment sections

  • desc (str, optional) – Description from object metacomments

dump()
class hdlparse.vhdl_parser.VhdlConstant(name, package, base_type, desc=None)

Bases: hdlparse.vhdl_parser.VhdlObject

Constant definition

Parameters

  • name (str) – Name of the constant

  • package (str) – Package containing the constant

  • base_type (str) – Type fo the constant

  • desc (str, optional) – Description from object metacomments

class hdlparse.vhdl_parser.VhdlExtractor(array_types={})

Bases: object

Utility class that caches parsed objects and tracks array type definitions

Parameters

array_types (set) – Initial array types

extract_objects(fname, type_filter=None)

Extract objects from a source file

Parameters

  • fname (str) – File to parse

  • type_filter (class, optional) – Object class to filter results

Returns

List of parsed objects.

extract_objects_from_source(text, type_filter=None)

Extract object declarations from a text buffer

Parameters

  • text (str) – Source code to parse

  • type_filter (class, optional) – Object class to filter results

Returns

List of parsed objects.

is_array(data_type)

Check if a type is a known array type

Parameters

data_type (str) – Name of type to check

Returns

True if data_type is a known array type.

load_array_types(fname)

Load file of previously extracted data types

Parameters

fname (str) – Name of file to load array database from

register_array_types_from_sources(source_files)

Add array type definitions from a file list to internal registry

Parameters

source_files (list of str) – Files to parse for array definitions

save_array_types(fname)

Save array type registry to a file

Parameters

fname (str) – Name of file to save array database to

class hdlparse.vhdl_parser.VhdlFunction(name, package, parameters, return_type=None, desc=None)

Bases: hdlparse.vhdl_parser.VhdlObject

Function declaration

Parameters

  • name (str) – Name of the function

  • package (str) – Package containing the function

  • parameters (list of VhdlParameter) – Parameters to the function

  • return_type (str, optional) – Type of the return value

  • desc (str, optional) – Description from object metacomments

class hdlparse.vhdl_parser.VhdlObject(name, desc=None)

Bases: object

Base class for parsed VHDL objects

Parameters

  • name (str) – Name of the object

  • desc (str) – Description from object metacomments

class hdlparse.vhdl_parser.VhdlPackage(name, desc=None)

Bases: hdlparse.vhdl_parser.VhdlObject

Package declaration

Parameters

  • name (str) – Name of the package

  • desc (str) – Description from object metacomments

class hdlparse.vhdl_parser.VhdlParameter(name, mode=None, data_type=None, default_value=None, desc=None)

Bases: object

Parameter to subprograms, ports, and generics

Parameters

  • name (str) – Name of the object

  • mode (str) – Direction mode for the parameter

  • data_type (str) – Type name for the parameter

  • default_value (str) – Default value of the parameter

  • desc (str) – Description from object metacomments

class hdlparse.vhdl_parser.VhdlProcedure(name, package, parameters, desc=None)

Bases: hdlparse.vhdl_parser.VhdlObject

Procedure declaration

Parameters

  • name (str) – Name of the procedure

  • package (str) – Package containing the procedure

  • parameters (list of VhdlParameter) – Parameters to the procedure

  • desc (str, optional) – Description from object metacomments

class hdlparse.vhdl_parser.VhdlSubtype(name, package, base_type, desc=None)

Bases: hdlparse.vhdl_parser.VhdlObject

Subtype definition

Parameters

  • name (str) – Name of the subtype

  • package (str) – Package containing the subtype

  • base_type (str) – Base type name derived from

  • desc (str, optional) – Description from object metacomments

class hdlparse.vhdl_parser.VhdlType(name, package, type_of, desc=None)

Bases: hdlparse.vhdl_parser.VhdlObject

Type definition

Parameters

  • name (str) – Name of the type

  • package (str) – Package containing the type

  • type_of (str) – Object type of this type definition

  • desc (str, optional) – Description from object metacomments

hdlparse.vhdl_parser.is_vhdl(fname)

Identify file as VHDL by its extension

Parameters

fname (str) – File name to check

Returns

True when file has a VHDL extension.

hdlparse.vhdl_parser.parse_vhdl(text)

Parse a text buffer of VHDL code

Parameters

text (str) – Source code to parse

Returns

Parsed objects.

hdlparse.vhdl_parser.parse_vhdl_file(fname)

Parse a named VHDL file

Parameters

fname (str) – Name of file to parse

Returns

Parsed objects.

hdlparse.vhdl_parser.subprogram_prototype(vo)

Generate a canonical prototype string

Parameters

vo (VhdlFunction, VhdlProcedure) – Subprogram object

Returns

Prototype string.

hdlparse.vhdl_parser.subprogram_signature(vo, fullname=None)

Generate a signature string

Parameters

vo (VhdlFunction, VhdlProcedure) – Subprogram object

Returns

Signature string.