daml_parser/lib.rs
1//! daml-parser: a **lossless** lexer, layout resolver, and parser for the Daml
2//! smart-contract language.
3//!
4//! This is the shared foundation under both `daml-lint` and `daml-fmt`. The
5//! pipeline is `lexer` → `layout` → `parse` over the [`ast`] types. The tree is
6//! lossless: the lexer records every comment and whitespace run as *trivia*
7//! (see [`lexer::lex_with_trivia`]), so a consumer can reconstruct the original
8//! bytes exactly. The linter ignores trivia and reads meaning; the formatter
9//! keeps trivia and re-prints layout. One tree, two readers.
10//!
11//! Start at [`parse::parse_module`] for tolerant parsing, or
12//! [`parse::parse_module_strict`] when any diagnostic should fail the caller.
13//! For byte-faithful reconstruction from the parse tree, see
14//! [`ast_span::render_from_ast`] and [`lexer::render_lossless`].
15//!
16//! ## API posture
17//!
18//! This crate is pre-1.0. Its public AST/IR-like types are intentionally direct
19//! data shapes that tools consume directly; additions or shape changes are
20//! SemVer-relevant and should be treated as breaking contract changes.
21//! Prefer adding helpers only when they can be used without changing these
22//! shapes, and use `#[non_exhaustive]` enums/variants for forward-safe
23//! extension. New enums introduced here should be documented as `non_exhaustive`
24//! when future variants are expected (for example
25//! [`SectionSide`](crate::ast::SectionSide)).
26//!
27//! Parser-created trees are the supported construction path.
28//!
29//! # Example
30//!
31//! ```rust
32//! let result =
33//! daml_parser::parse::parse_module("module M where\nfoo : Int\nfoo = 1\n");
34//!
35//! assert!(result.diagnostics.is_empty());
36//! assert_eq!(result.module.name, "M");
37//! ```
38
39/// Lossless AST node types produced by the parser.
40pub mod ast;
41/// AST byte-span losslessness oracle (`render_from_ast`): reconstruct source
42/// from the parse tree to prove the tree lost nothing.
43pub mod ast_span;
44/// Indentation-sensitive layout resolver.
45///
46/// Inserts virtual braces and semicolons for the parser.
47pub mod layout;
48/// Lexer and token/trivia types for Daml source text.
49pub mod lexer;
50/// Recursive-descent parser entry points and diagnostics.
51pub mod parse;
52
53#[cfg(test)]
54mod diag_tests;
55#[cfg(test)]
56mod projection_tests;
57#[cfg(test)]
58mod span_tests;