1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
// This Source Code Form is subject to the terms of the Mozilla Public
// License, v. 2.0. If a copy of the MPL was not distributed with this file,
// You can obtain one at http://mozilla.org/MPL/2.0/.
//
// Copyright (c) 2024, Lukas Scheller lukasscheller@icloud.com
//! 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](crate::syntax::SyntaxNode).
//!
//! # Character set
//!
//! With the exception of [comments](crate::tokens::comment), 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.
pub