styx_cst/lib.rs
1#![doc = include_str!("../README.md")]
2//! Lossless Concrete Syntax Tree for the Styx configuration language.
3//!
4//! This crate provides a CST (Concrete Syntax Tree) representation of Styx documents
5//! using the [rowan](https://docs.rs/rowan) library. Unlike an AST, the CST preserves
6//! all source information including whitespace, comments, and exact token positions,
7//! making it ideal for tooling like formatters, refactoring tools, and language servers.
8//!
9//! # Features
10//!
11//! - **Lossless representation**: Source text can be exactly reconstructed from the CST
12//! - **Cheap cloning**: Syntax nodes use reference counting internally
13//! - **Parent pointers**: Navigate up and down the tree
14//! - **Typed AST layer**: Ergonomic wrappers over raw CST nodes
15//! - **Semantic validation**: Check for issues like duplicate keys and mixed separators
16//!
17//! # Example
18//!
19//! ```
20//! use styx_cst::{parse, ast::{AstNode, Document}};
21//!
22//! let source = r#"
23//! host localhost
24//! port 8080
25//! "#;
26//!
27//! let parsed = parse(source);
28//! assert!(parsed.is_ok());
29//!
30//! let doc = Document::cast(parsed.syntax()).unwrap();
31//! for entry in doc.entries() {
32//! if let Some(key) = entry.key_text() {
33//! println!("Found key: {}", key);
34//! }
35//! }
36//!
37//! // Roundtrip: source can be exactly reconstructed
38//! assert_eq!(parsed.syntax().to_string(), source);
39//! ```
40//!
41//! # Validation
42//!
43//! ```
44//! use styx_cst::{parse, validation::validate};
45//!
46//! let source = "{ a 1, a 2 }"; // Duplicate key
47//! let parsed = parse(source);
48//! let diagnostics = validate(&parsed.syntax());
49//!
50//! assert!(!diagnostics.is_empty());
51//! ```
52
53pub mod ast;
54pub mod parser;
55pub mod syntax_kind;
56pub mod validation;
57
58pub use parser::{Parse, ParseError, parse};
59pub use syntax_kind::{StyxLanguage, SyntaxElement, SyntaxKind, SyntaxNode, SyntaxToken};
60pub use validation::{Diagnostic, Severity, validate};
61
62// Re-export rowan types for convenience
63pub use rowan::{TextRange, TextSize, TokenAtOffset};