| Name | hdltree JSON |
| Version |
0.3.4
JSON |
| download |
| home_page | None |
| Summary | Pure Python HDL parser, plus symbol generator and sphinx domain |
| upload_time | 2025-02-06 01:22:43 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.10 |
| license | Copyright © 2025 Rajan Patel
Permission is hereby granted, free of charge, to any person obtaining a
copy of this software and associated documentation files (the "Software"),
to deal in the Software without restriction, including without limitation
the rights to use, copy, modify, merge, publish, distribute, sublicense,
and/or sell copies of the Software, and to permit persons to whom the
Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
DEALINGS IN THE SOFTWARE.
|
| keywords |
rtl
hdl
vhdl
system
verilog
systemverilog
symbol
symbolator
sphinx
hdlparse
parse
format
validate
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# HDLTree
HDLTree is a pure Python HDL parser that uses [Lark](https://github.com/lark-parser/lark) to create a parse tree, then transform it into a syntax tree. Currently only VHDL-2008 is supported.
The HDLTree repo also includes the [Hdlparse](https://github.com/kevinpt/hdlparse) and [Symbolator](https://github.com/kevinpt/symbolator) packages, originally written by [kevinpt](https://github.com/kevinpt). This repo is based on a [fork](https://github.com/zebreus/symbolator) maintained by [zebreus](https://github.com/zebreus) which consolidated the two packages and applied several patches. The version of Hdlparse in this repo has been rewritten to use HDLTree for parsing VHDL instead of the simple partial parser in the original. Verilog is still handled by the original parser, until such time as HDLTree supports parsing Verilog.
Included with Symbolator are the symbolator_sphinx package for embedding symbolator symbols in Sphinx documentation, and the nucanvas package as a wrapper around Pycairo and PyGObject.
## Getting HDLTree
### Prerequisites
HDLTree and Hdlparse don't have any dependencies besides python packages automatically installed by pip. Symbolator requires Cairo and Pango. On Linux, these are likely packaged by your distribution and can be installed with pacman, apt-get, dnf, etc. On Windows, the best way is probably to install [GTK](https://www.gtk.org/docs/installations/windows/).
### Installing releases from pip
HDLTree is available on [PyPI](https://pypi.org/project/hdltree/):
```sh
pip install hdltree
```
### Installing from latest source
The GitHub repo may be ahead of the released package. You can install the bleeding edge version:
```sh
pip install git+https://github.com/rpatel3001/hdltree.git
```
### Extra Dependencies
#### Symbolator Dependencies
Symbolator requires the pygobject and pycairo packages as bindings for Cairo and Pango.
```sh
pip install hdltree[symbolator]
```
#### Regex Library
[Lark](https://lark-parser.readthedocs.io/en/stable/classes.html#using-unicode-character-classes-with-regex) can use the regex library instead of the builtin re library for regular expressions. HDLTree will automatically use the regex library if it is installed.
```sh
pip install hdltree[regex]
```
### CLI Scripts
After a successful install the `hdltree`, `hdlparse`, and `symbolator` executables will be available. On Linux they should be immediately accessible on your $PATH. On Windows you may need to add the `<Python root>\Scripts` directory to your %PATH%.
The `hdltree` and `hdlparse` scripts are not particularly useful for end use. `hdltree` will print the syntax tree for the input files. `hdlparse` will print the parsed information from a fixed piece of code. `symbolator` is the only one meant to be used primarily from a terminal and its use is described [below](#symbolator).
## Usage
Coming soon. For now, see [an example](examples/example.py) that parses input files, generates a Graphviz/DOT based symbol as an alternative to symbolator, and compares the input file to a recreation from the syntax tree for equivalency (minus comments and whitespace).
## Hdlparse
Hdlparse is a simple package implementing a rudimentary parser for VHDL and Verilog. It is not capable of fully parsing the entire language. Rather, it is meant to extract enough key information from a source file to create generated documentation.
For VHDL this library can extract component, subprogram, type, subtype, and constant declarations from a package. For Verilog it can extract module declarations (both 1995 and 2001 syntax). Because this version of Hdlparse replaces the VHDL parser with HDLTree, it's behavior may not exactly match other versions of Hdlparse for VHDL files. One restriction is that input files must be full, valid VHDL files. Partial files with bare component or entity declarations are not supported.
Full documentation can be found at [here](http://kevinpt.github.io/hdlparse/).
## Symbolator
Symbolator is a component diagramming tool for VHDL and Verilog. It will parse HDL source files, extract components or entities and render them as an image.
Full documentation can be found [here](https://zebreus.github.io/symbolator/). Due to limitations of the Lark based parser, symbol sections defined in metacomments are not supported by this version of symbolator.
```vhdl
library ieee;
use ieee.std_logic_1164.all;
package demo is
component demo_device_comp is
generic (
SIZE : positive;
RESET_ACTIVE_LEVEL : std_ulogic := '1'
);
port (
Clock : in std_ulogic;
Reset : in std_ulogic;
Enable : in std_ulogic;
Data_in : in std_ulogic_vector(SIZE-1 downto 0);
Data_out : out std_ulogic_vector(SIZE-1 downto 0)
);
end component;
end package;
```
```console
$ symbolator -i docs/images/demo_device.vhdl
Created demo_device_comp.svg from demo_device_comp (docs/images/demo_device.vhdl)
```
Produces the following:
Symbolator can render to PNG bitmap images or SVG, PDF, PS, and EPS vector images. SVG is the default.
Raw data
{
"_id": null,
"home_page": null,
"name": "hdltree",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "RTL, HDL, VHDL, System, Verilog, SystemVerilog, symbol, symbolator, sphinx, hdlparse, parse, format, validate",
"author": null,
"author_email": "Rajan Patel <rpatel3001@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/b1/fd/bde5890c71d889ac963c2cf681cd746a7a5fb9c989c2ef827b454aed67a9/hdltree-0.3.4.tar.gz",
"platform": null,
"description": "# HDLTree\r\n\r\nHDLTree is a pure Python HDL parser that uses [Lark](https://github.com/lark-parser/lark) to create a parse tree, then transform it into a syntax tree. Currently only VHDL-2008 is supported.\r\n\r\nThe HDLTree repo also includes the [Hdlparse](https://github.com/kevinpt/hdlparse) and [Symbolator](https://github.com/kevinpt/symbolator) packages, originally written by [kevinpt](https://github.com/kevinpt). This repo is based on a [fork](https://github.com/zebreus/symbolator) maintained by [zebreus](https://github.com/zebreus) which consolidated the two packages and applied several patches. The version of Hdlparse in this repo has been rewritten to use HDLTree for parsing VHDL instead of the simple partial parser in the original. Verilog is still handled by the original parser, until such time as HDLTree supports parsing Verilog.\r\n\r\nIncluded with Symbolator are the symbolator_sphinx package for embedding symbolator symbols in Sphinx documentation, and the nucanvas package as a wrapper around Pycairo and PyGObject.\r\n\r\n## Getting HDLTree\r\n\r\n### Prerequisites\r\n\r\nHDLTree and Hdlparse don't have any dependencies besides python packages automatically installed by pip. Symbolator requires Cairo and Pango. On Linux, these are likely packaged by your distribution and can be installed with pacman, apt-get, dnf, etc. On Windows, the best way is probably to install [GTK](https://www.gtk.org/docs/installations/windows/).\r\n\r\n### Installing releases from pip\r\n\r\nHDLTree is available on [PyPI](https://pypi.org/project/hdltree/):\r\n\r\n```sh\r\npip install hdltree\r\n```\r\n\r\n### Installing from latest source\r\n\r\nThe GitHub repo may be ahead of the released package. You can install the bleeding edge version:\r\n\r\n```sh\r\npip install git+https://github.com/rpatel3001/hdltree.git\r\n```\r\n\r\n### Extra Dependencies\r\n\r\n#### Symbolator Dependencies\r\n\r\nSymbolator requires the pygobject and pycairo packages as bindings for Cairo and Pango.\r\n\r\n```sh\r\npip install hdltree[symbolator]\r\n```\r\n\r\n#### Regex Library\r\n\r\n[Lark](https://lark-parser.readthedocs.io/en/stable/classes.html#using-unicode-character-classes-with-regex) can use the regex library instead of the builtin re library for regular expressions. HDLTree will automatically use the regex library if it is installed.\r\n\r\n```sh\r\npip install hdltree[regex]\r\n```\r\n\r\n### CLI Scripts\r\n\r\nAfter a successful install the `hdltree`, `hdlparse`, and `symbolator` executables will be available. On Linux they should be immediately accessible on your $PATH. On Windows you may need to add the `<Python root>\\Scripts` directory to your %PATH%.\r\n\r\nThe `hdltree` and `hdlparse` scripts are not particularly useful for end use. `hdltree` will print the syntax tree for the input files. `hdlparse` will print the parsed information from a fixed piece of code. `symbolator` is the only one meant to be used primarily from a terminal and its use is described [below](#symbolator).\r\n\r\n## Usage\r\n\r\nComing soon. For now, see [an example](examples/example.py) that parses input files, generates a Graphviz/DOT based symbol as an alternative to symbolator, and compares the input file to a recreation from the syntax tree for equivalency (minus comments and whitespace).\r\n\r\n## Hdlparse\r\n\r\nHdlparse is a simple package implementing a rudimentary parser for VHDL and Verilog. It is not capable of fully parsing the entire language. Rather, it is meant to extract enough key information from a source file to create generated documentation.\r\n\r\nFor VHDL this library can extract component, subprogram, type, subtype, and constant declarations from a package. For Verilog it can extract module declarations (both 1995 and 2001 syntax). Because this version of Hdlparse replaces the VHDL parser with HDLTree, it's behavior may not exactly match other versions of Hdlparse for VHDL files. One restriction is that input files must be full, valid VHDL files. Partial files with bare component or entity declarations are not supported.\r\n\r\nFull documentation can be found at [here](http://kevinpt.github.io/hdlparse/).\r\n\r\n## Symbolator\r\n\r\nSymbolator is a component diagramming tool for VHDL and Verilog. It will parse HDL source files, extract components or entities and render them as an image.\r\n\r\nFull documentation can be found [here](https://zebreus.github.io/symbolator/). Due to limitations of the Lark based parser, symbol sections defined in metacomments are not supported by this version of symbolator.\r\n\r\n```vhdl\r\nlibrary ieee;\r\nuse ieee.std_logic_1164.all;\r\n\r\npackage demo is\r\n component demo_device_comp is\r\n generic (\r\n SIZE : positive;\r\n RESET_ACTIVE_LEVEL : std_ulogic := '1'\r\n );\r\n port (\r\n Clock : in std_ulogic;\r\n Reset : in std_ulogic;\r\n\r\n Enable : in std_ulogic;\r\n Data_in : in std_ulogic_vector(SIZE-1 downto 0);\r\n Data_out : out std_ulogic_vector(SIZE-1 downto 0)\r\n );\r\n end component;\r\nend package;\r\n```\r\n\r\n```console\r\n$ symbolator -i docs/images/demo_device.vhdl\r\nCreated demo_device_comp.svg from demo_device_comp (docs/images/demo_device.vhdl)\r\n```\r\n\r\nProduces the following:\r\n\r\n\r\n\r\nSymbolator can render to PNG bitmap images or SVG, PDF, PS, and EPS vector images. SVG is the default.\r\n",
"bugtrack_url": null,
"license": "Copyright \u00a9 2025 Rajan Patel\r\n \r\n Permission is hereby granted, free of charge, to any person obtaining a\r\n copy of this software and associated documentation files (the \"Software\"),\r\n to deal in the Software without restriction, including without limitation\r\n the rights to use, copy, modify, merge, publish, distribute, sublicense,\r\n and/or sell copies of the Software, and to permit persons to whom the\r\n Software is furnished to do so, subject to the following conditions:\r\n \r\n The above copyright notice and this permission notice shall be included in\r\n all copies or substantial portions of the Software.\r\n \r\n THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\r\n IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\r\n FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\r\n AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\r\n LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING\r\n FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER\r\n DEALINGS IN THE SOFTWARE.\r\n ",
"summary": "Pure Python HDL parser, plus symbol generator and sphinx domain",
"version": "0.3.4",
"project_urls": {
"source": "https://github.com/rpatel3001/hdltree"
},
"split_keywords": [
"rtl",
" hdl",
" vhdl",
" system",
" verilog",
" systemverilog",
" symbol",
" symbolator",
" sphinx",
" hdlparse",
" parse",
" format",
" validate"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "c1255fe0a9c8c67b4ab5c76d0c621ba05a3962947c635d8eea2c7f41ae3460e2",
"md5": "624105d4b47a28c45a6c60617ee61f47",
"sha256": "ee04a26f9e43261e87b2289599d8586eeca4644fe8a33b15e7b134219157cdec"
},
"downloads": -1,
"filename": "hdltree-0.3.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "624105d4b47a28c45a6c60617ee61f47",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 72681,
"upload_time": "2025-02-06T01:22:41",
"upload_time_iso_8601": "2025-02-06T01:22:41.391978Z",
"url": "https://files.pythonhosted.org/packages/c1/25/5fe0a9c8c67b4ab5c76d0c621ba05a3962947c635d8eea2c7f41ae3460e2/hdltree-0.3.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "b1fdbde5890c71d889ac963c2cf681cd746a7a5fb9c989c2ef827b454aed67a9",
"md5": "f0b92d9b36e6f1c679ad2e8269598628",
"sha256": "7fb956e5add35728560300ff9af7060aef769c973e23c6ef88b225bcbf781d54"
},
"downloads": -1,
"filename": "hdltree-0.3.4.tar.gz",
"has_sig": false,
"md5_digest": "f0b92d9b36e6f1c679ad2e8269598628",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 69218,
"upload_time": "2025-02-06T01:22:43",
"upload_time_iso_8601": "2025-02-06T01:22:43.096766Z",
"url": "https://files.pythonhosted.org/packages/b1/fd/bde5890c71d889ac963c2cf681cd746a7a5fb9c989c2ef827b454aed67a9/hdltree-0.3.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-02-06 01:22:43",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "rpatel3001",
"github_project": "hdltree",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "hdltree"
}
