wazabin_qcode_parser/
lib.rs

1//! Parser and AST for the QCode text format.
2//!
3//! QCode has a textual surface syntax, which is how much of the toolchain's
4//! test suite is written and what the `qcode!` macro accepts. This crate turns
5//! that text into a syntax tree and nothing more: it performs no name
6//! resolution, no typing, and no lowering, so it depends on neither the IR nor
7//! the rest of the toolchain.
8//!
9//! **Most users want [`qcode`] instead**, and its `qcode::lower::lower_str`,
10//! which parses *and* lowers into a live module. Reach for this crate when a
11//! tool needs the syntax itself — a formatter, a linter, an editor, or
12//! anything reporting source spans back to a human. It is also what
13//! [`wazabin_qcode_macro`] uses to validate QCode literals at compile time.
14//!
15//! # Example
16//!
17//! ```
18//! use wazabin_qcode_parser::{ast::ProgramKind, qcode_from_str};
19//!
20//! let program = qcode_from_str("%sum = i64 0x2 + 0x3;").expect("valid QCode");
21//! match program.kind {
22//!     ProgramKind::Statements(statements) => assert_eq!(statements.len(), 1),
23//!     ProgramKind::Functions { .. } => panic!("this source declares no functions"),
24//! }
25//! ```
26//!
27//! A syntax error carries its location rather than just a message:
28//!
29//! ```
30//! use wazabin_qcode_parser::qcode_from_str;
31//!
32//! assert!(qcode_from_str("%sum = i64 0x2 +;").is_err());
33//! ```
34//!
35//! [`qcode`]: https://docs.rs/qcode
36//! [`wazabin_qcode_macro`]: https://docs.rs/wazabin-qcode-macro
37
38pub mod ast;
39mod parser;
40
41pub use parser::{ParseError, parse_program};
42
43/// Parse QCode source into a [`ast::Program`].
44///
45/// An alias for [`parse_program`], named for readability at call sites.
46pub fn qcode_from_str(program: &str) -> Result<ast::Program, ParseError> {
47    parse_program(program)
48}
wazabin_qcode_parser/lib.rs

wazabin_qcode_parser/
lib.rs
