zirium 0.4.0

Lossless textual MLIR syntax parsing and semantic processing
Documentation 
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
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86

//! Lossless MLIR syntax, semantic processing, editing, and output.
//!
//! The usual flow is to parse an owning [`parser::ParsedFile`], lower it to a
//! [`semantic::Document`], validate or verify it, optionally edit it, and then
//! choose an output mode:
//!
//! - [`parser::ParsedFile::write_original`] reproduces the input bytes exactly.
//! - [`parser::ParsedFile::write_formatted`] normalizes layout while retaining
//!   source assembly, names, aliases, and comments.
//! - [`semantic::Document::write_canonical`](crate::semantic::Document::write_canonical)
//!   emits deterministic generic MLIR from semantic storage.
//! - [`semantic::Document::write_preserving`](crate::semantic::Document::write_preserving)
//!   reuses unchanged source and regenerates edited regions; it requires
//!   [`semantic::RetentionProfile::Hybrid`].
//!
//! [`semantic::RetentionProfile`] controls whether lowering retains syntax,
//! semantic storage, or both. [`semantic::LoweringMode::Strict`] returns no
//! document when lowering is incomplete, while `BestEffort` returns a document
//! containing invalid sentinels together with diagnostics. Structural
//! [`semantic::Document::validate_structure`] checks storage invariants;
//! [`semantic::Document::verify_semantics`] additionally runs registered
//! dialect schemas and verifiers.
//!
//! This example edits a hybrid document, commits the transaction, writes
//! source-preserving output, and then shows what happens to an erased handle:
//!
//! ```
//! use zirium::{
//!     dialect::DialectRegistry,
//!     parser::ParsedFile,
//!     printer::PrintLayout,
//!     semantic::{
//!         AttributeSpec, EditError, LoweringMode, RetentionProfile,
//!         lower_with_dialect_registry_and_retention,
//!     },
//! };
//!
//! let source = b"\"keep\"() : () -> ()\n\"edit\"() : () -> ()\n";
//! let parsed = ParsedFile::parse(source.as_slice())?;
//! let registry = DialectRegistry::EMPTY;
//! let lowered = lower_with_dialect_registry_and_retention(
//!     &parsed,
//!     LoweringMode::Strict,
//!     RetentionProfile::Hybrid,
//!     &registry,
//! );
//! let mut document = lowered.document.expect("strict lowering succeeds");
//! document.verify_semantics(&registry)?;
//! let edited = document.root_operations()[1];
//!
//! let mut transaction = document.edit(&registry)?;
//! transaction.set_attribute(
//!     edited,
//!     AttributeSpec::string("tag", "checked"),
//! )?;
//! transaction.commit()?;
//! let output = document.preserving_bytes(PrintLayout::Pretty)?;
//! assert!(String::from_utf8(output)?.contains("tag = \"checked\""));
//!
//! let mut transaction = document.edit(&registry)?;
//! transaction.erase(edited)?;
//! transaction.commit()?;
//! assert!(matches!(
//!     document.check_operation(edited),
//!     Err(EditError::StaleOperation(_))
//! ));
//! # Ok::<(), Box<dyn std::error::Error>>(())
//! ```

#[cfg(test)]
mod benchmark_allocator;
pub mod dialect;
pub mod diff;
pub mod formatter;
pub mod lexer;
pub mod parser;
pub mod printer;
pub mod query;
mod representation;
pub mod semantic;
pub mod source;

pub use representation::{
    CompactError, CompletedMarker, Event, EventBuilder, Marker, NodeId, SyntaxElement, SyntaxKind,
    SyntaxTree,
};