vhdl_syntax 0.2.0

VHDL parser for lossless concrete syntax trees
Documentation
# VHDL Syntax Library

A lossless library for tokenizing, parsing, inspecting, and modifying VHDL code.

Currently processes VHDL-2008 code.

## Status

> [!WARNING]
> **Early Stage**: This crate is in an early stage of development.
> Until Version 1.0, all public API methods are subject to change at any given time.
> Bugs are expected to occur at any time.

## Quickstart

Add the package:

```shell
cargo add vhdl_syntax
```

To parse a VHDL file, call the `parse` function from the `parser` submodule:

```rust
use vhdl_syntax::parser;

let vhdl_file = b"\
library ieee;
    use ieee.std_logic_1164.all;

entity foo is
    port (
        clk : in std_logic
    );
end entity foo;
";
let (cst, diagnostics) = parser::parse(vhdl_file);
```

`diagnostics` is a `Vec<SyntaxErr>` that reports any syntactical errors from the input file. `cst` is the concrete syntax tree describing the parsed VHDL file.

Refer to the examples for concrete use-cases:

## Examples

All examples can be found in the [examples](./examples/) folder.

### [doc_extraction]./examples/doc_extraction.rs

Contains a minimalistic documentation extraction tool.

### [empty_entity_builder]./examples/empty_entity_builder.rs

Uses the builder API to programmatically construct an entity declaration from scratch.

### [import_sorting]./examples/import_sorting.rs

Alphabetically sorts and deduplicates the `use` clauses of a context clause using the rewriter API.

### [linting]./examples/linting.rs

Shows how to use this crate to build a simple VHDL linter

### [name_changing]./examples/name_changing.rs

Showcases the AST rewriting capabilities to change the name of a VHDL entity.

### [source_refactoring]./examples/source_refactoring.rs

Shows how the library can be used to exchange source code elements that are more than just a token.

### [testbench_generation]./examples/testbench_generation.rs

Walks a design and emits a minimal testbench skeleton for every entity it finds.