scarf_syntax/lib.rs
1// =======================================================================
2// lib.rs
3// =======================================================================
4// The top-level collection of CST nodes
5
6//! A SystemVerilog (concrete) syntax tree for representing
7//! [1800-2023](https://ieeexplore.ieee.org/document/10458102) syntax.
8//!
9//! Each syntactic category is represented as a struct or enum with the
10//! same name as appears in Annex A, with additional types as needed for
11//! unnamed alternatives.
12//!
13//! While the tree can be treated as a normal data structure, it can
14//! also be iterated across (depth-first). Iterating produces [`Node`]s,
15//! which reference a specific data structure in the tree
16//!
17//! ```rust
18//! # use scarf_syntax::*;
19//! fn is_always_comb_block<'a, 'b>(node: Node<'a, 'b>) -> bool {
20//! matches!(node, Node::AlwaysConstruct(AlwaysConstruct(AlwaysKeyword::AlwaysComb(_), _)))
21//! }
22//!
23//! fn num_inferred_latches<'a>(source: &SourceText<'a>) -> i32 {
24//! let mut count = 0;
25//! for node in source.find(is_always_comb_block) {
26//! for child_node in node.iter() {
27//! if let Node::BlockingAssignment(_) = child_node {
28//! count += 1;
29//! }
30//! }
31//! }
32//! count
33//! }
34//! ```
35//!
36//! Compiler directives are not supported due to their arbitrary
37//! location/semantics in a syntax tree.
38//!
39//! ## Features
40//!
41//! - `lossless`: Allows for whitespace/comments to be preserved in [`Metadata`]
42
43include!(concat!(env!("OUT_DIR"), "/nodes.rs"));
44
45/// CST Nodes from 1800-2023 A.6
46pub mod behavioral_statements;
47/// CST Nodes from 1800-2023 A.2
48pub mod declarations;
49/// CST Nodes from 1800-2023 A.8
50pub mod expressions;
51/// CST Nodes from 1800-2023 A.9
52pub mod general;
53/// CST Nodes from 1800-2023 A.4
54pub mod instantiations;
55/// Iterating over a CST
56pub mod iter;
57/// Extra metadata attached to leaf nodes to encode a CST
58pub mod metadata;
59/// CST Nodes from 1800-2023 A.3
60pub mod primitive_instances;
61/// CST Nodes from 1800-2023 A.1
62pub mod source_text;
63/// CST Nodes from 1800-2023 A.7
64pub mod specify_section;
65/// CST Nodes from 1800-2023 A.5
66pub mod udp_declaration_and_instantiation;
67pub use behavioral_statements::*;
68pub use declarations::*;
69pub use expressions::*;
70pub use general::*;
71pub use instantiations::*;
72pub use iter::*;
73pub use metadata::*;
74pub use primitive_instances::*;
75pub use source_text::*;
76pub use specify_section::*;
77pub use udp_declaration_and_instantiation::*;