# daml-syntax
`daml-syntax` is the shared parsed-source surface for Daml tools in this
workspace. It owns source presentation around `daml-parser`: diagnostics, line
mapping, UTF-16 offsets, token/trivia access, and parser span conversion.
## Public dependencies
`daml-parser` and `text-size` are intentional public dependencies: parser AST,
lexer, and layout types plus `TextRange`/`TextSize` appear in this crate's public
API. SemVer for `daml-syntax` includes compatible major versions of those crates
when upgrading.
## Coordinate safety
Line and column APIs use distinct coordinate newtypes: `LineNumber`,
`ByteColumn`, `CharColumn`, `ByteOffset`, and `Utf16Offset`. One-based
coordinates reject zero through `try_new` and `TryFrom<usize>`, while raw
coordinate extraction uses `usize::from(coordinate)`. UTF-16 column lookup
returns `CoordinateRangeError` instead of clamping lines or columns past the
source. UTF-16 slices are returned as `Utf16Range` values with named
`start()`/`end()` accessors. Diagnostic end columns use `DiagnosticEndColumn`:
non-empty same-line diagnostic spans carry an exclusive 1-based Unicode-scalar
end column, while multi-line and empty spans are named separately so callers
cannot collapse them accidentally.
## Quick start
```rust
use daml_syntax::{LineNumber, SourceFile};
let source = "module M where\nfoo : Int\nfoo = 1\n";
let file = SourceFile::parse(source);
assert!(file.diagnostics().is_empty());
assert_eq!(file.module().name, "M");
assert_eq!(file.line_index().line_col(0.into()).line, LineNumber::new(1));
```
For callers that only need lexer, trivia, or laid-out token facts, use the
lighter tokenized surface:
```rust
use daml_syntax::SourceTokens;
let source = "module M where\nfoo : Int\nfoo = 1\n";
let tokens = SourceTokens::lex(source);
assert!(tokens.lex_errors().is_empty());
assert!(!tokens.laid_out_tokens().is_empty());
```
README examples are included in hidden rustdoc items and compile-tested via
`cargo test -p daml-syntax --doc`.