Skip to main content

Crate styx_cst

Crate styx_cst

Expand description

§styx-cst

Lossless Concrete Syntax Tree for the Styx configuration language. Preserves all whitespace and comments for formatting and refactoring tools.

This crate provides a CST (Concrete Syntax Tree) representation of Styx documents using the rowan library. Unlike an AST, the CST preserves all source information including whitespace, comments, and exact token positions, making it ideal for tooling like formatters, refactoring tools, and language servers.

§Features

Lossless representation: Source text can be exactly reconstructed from the CST
Cheap cloning: Syntax nodes use reference counting internally
Parent pointers: Navigate up and down the tree
Typed AST layer: Ergonomic wrappers over raw CST nodes
Semantic validation: Check for issues like duplicate keys and mixed separators

§Example

use styx_cst::{parse, ast::{AstNode, Document}};

let source = r#"
host localhost
port 8080
"#;

let parsed = parse(source);
assert!(parsed.is_ok());

let doc = Document::cast(parsed.syntax()).unwrap();
for entry in doc.entries() {
    if let Some(key) = entry.key_text() {
        println!("Found key: {}", key);
    }
}

// Roundtrip: source can be exactly reconstructed
assert_eq!(parsed.syntax().to_string(), source);

§Validation

use styx_cst::{parse, validation::validate};

let source = "{ a 1, a 2 }"; // Duplicate key
let parsed = parse(source);
let diagnostics = validate(&parsed.syntax());

assert!(!diagnostics.is_empty());

§Sponsors

Thanks to all individual sponsors:

…along with corporate sponsors:

…without whom this work could not exist.

§License

Licensed under either of:

Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

Structs§

Diagnostic: A diagnostic message from validation.
Document: The root document node.
Entry: An entry (key-value pair or sequence element).
Heredoc: A heredoc value.
Key: The key part of an entry.
Object: An explicit object { ... }.
Parse: A parsed Styx document.
ParseError: A parse error with location information.
Scalar: A scalar value.
Sequence: A sequence ( ... ).
Tag: A tag @name with optional payload.
TextRange: A range in text, represented as a pair of TextSize.
TextSize: A measure of text length. Also, equivalently, an index into text.
Unit: A unit value @.
Value: The value part of an entry.

Enums§

NodeOrToken
ScalarKind: The kind of scalar.
Separator: The separator mode detected in an object.
Severity: Diagnostic severity level.
StyxLanguage: Language definition for Styx, used by rowan.
SyntaxKind: The kind of a syntax element (node or token).
TokenAtOffset: There might be zero, one or two leaves at a given offset.
ValueKind: The kind of value in an entry.

Traits§

AstNode: Trait for AST nodes that wrap CST nodes.

Functions§

parse: Parse Styx source into a CST.
validate: Validate a document and return all diagnostics.
validate_document: Validate a document AST node.

Type Aliases§

SyntaxElement: A syntax element (either node or token) in the Styx CST.
SyntaxNode: A syntax node in the Styx CST.
SyntaxToken: A syntax token in the Styx CST.