cabalist_parser/lib.rs
1//! # cabalist-parser
2//!
3//! A Rust library that parses `.cabal` files into a concrete syntax tree (CST),
4//! preserving every byte of the original source — whitespace, comments, blank
5//! lines, indentation style. The CST can be rendered back to text with
6//! byte-identical round-tripping when no edits have been made.
7//!
8//! The parser maintains two representations:
9//!
10//! - **CST (Concrete Syntax Tree):** A flat-arena tree that captures every byte
11//! of the source. This is what gets mutated during edits and rendered back to
12//! text.
13//!
14//! - **AST (Abstract Syntax Tree):** A typed, ergonomic view derived from the
15//! CST for querying and validation. *(Implemented in a separate module.)*
16//!
17//! ## Quick start
18//!
19//! ```
20//! use cabalist_parser::parse;
21//!
22//! let source = "cabal-version: 3.0\nname: my-package\nversion: 0.1.0.0\n";
23//! let result = parse(source);
24//!
25//! // No diagnostics for a valid file.
26//! assert!(result.diagnostics.is_empty());
27//!
28//! // Round-trip: render produces the original source.
29//! assert_eq!(result.cst.render(), source);
30//! ```
31
32/// Typed abstract syntax tree derived from the CST.
33pub mod ast;
34/// Concrete syntax tree with byte-identical round-trip fidelity.
35pub mod cst;
36/// Parser diagnostics (errors and warnings).
37pub mod diagnostic;
38/// CST mutation operations (add, remove, update fields).
39pub mod edit;
40/// Lexer that tokenizes `.cabal` source into CST nodes.
41pub mod lexer;
42/// Parser that builds a CST from source text.
43pub mod parse;
44/// Byte spans and node identifiers.
45pub mod span;
46/// Structural validation of parsed `.cabal` files.
47pub mod validate;
48
49// Re-export the main entry point and key types at the crate root.
50pub use ast::{CabalFile, Dependency, Version, VersionRange};
51pub use cst::{CabalCst, CstNode, CstNodeKind};
52pub use diagnostic::{Diagnostic, Severity};
53pub use edit::{EditBatch, ListStyle, TextEdit};
54pub use parse::ParseResult;
55pub use span::{NodeId, Span};
56pub use validate::validate;
57
58/// Parse a `.cabal` source string into a [`ParseResult`] containing the CST
59/// and any diagnostics.
60///
61/// The returned CST preserves every byte of the input. Calling
62/// [`CabalCst::render()`] on an unmodified CST produces byte-identical output.
63pub fn parse(source: &str) -> ParseResult {
64 parse::parse(source)
65}