Skip to main content

Crate vhdl_syntax

Crate vhdl_syntax 

Source
Expand description

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

Lossless means that the a parsed tree contains the entire source file including whitespaces, comments, or fragments that are invalid VHDL. As a consequence, parsing a tree from input and writing the parsed tree back out reproduces identical input. This is opposed to, for example, a compiler that discards that information for efficiency since it does not influence the compilation.

use vhdl_syntax::parser;
use vhdl_syntax::syntax::AstNode;

let src = "\
entity foo is -- this comment is part of the tree
end foo;
";
let (design, errors) = parser::parse(src);
assert!(errors.is_empty());

let mut out = Vec::new();
design.raw().write_to(&mut out).unwrap();
assert_eq!(out, src.as_bytes());

§Untyped tree

A consequence of being lossless is that the tree must be able to represent all possible, potentially incorrect, inputs. To do this, each node can contain arbitrary children. This is opposed to a typed node that contains a defined subset of children. Read more at the documentation for SyntaxNodes.

§Character set

With the exception of comments, VHDL source is Latin-1. Entry-points using rust str, String, or other UTF-8 might get unexpected results for non-ASCII UTF-8. Therefore, the byte-oriented input facilities are preferred (i.e., read a file in binary mode, not to string, and parse that). Additionally, the latin_1 module contains facilities to convert from UTF-8 to Latin-1.

Modules§

builder
Domain types for the builder API. Each type has named constructors that accept Rust values and produces a VHDL token.
fmt
Provides facilities to format nodes and tokens to encoded strings. Note: this is not a VHDL-formatter implementation.
latin_1
Latin-1 String Types
parser
Parsing tokens into a syntax tree.
serde
Support for serializing syntax elements.
standard
VHDL standard version identification and comparison.
syntax
The syntax tree: Untyped nodes, and typed views.
text
Utilities for mapping between byte offsets and source locations (line/column).
tokens
Basic building blocks of syntax trees