108 lines
3.1 KiB
Markdown
108 lines
3.1 KiB
Markdown
# Decodal
|
|
|
|
Decodal is a small deterministic DSL for describing, composing, validating, and materializing structured data.
|
|
|
|
It is designed around a lightweight Rust library:
|
|
|
|
- host-supplied source and structured-value imports through `ImportLoader`
|
|
- shared host environments for production and semantic editor tooling
|
|
- no filesystem access in the library core
|
|
- concrete and abstract values with constraints and defaults
|
|
- asymmetric range refinement with `narrower as wider`
|
|
- homogeneous associative-array schemas with `{...valueSchema}`
|
|
- deterministic expression evaluation
|
|
- optional regex support behind a Cargo feature
|
|
- browser playground support through WebAssembly
|
|
|
|
## Library crate
|
|
|
|
Embedded hosts should depend on `decodal` and provide imports with an `ImportLoader`.
|
|
|
|
```toml
|
|
[dependencies]
|
|
decodal = "0.1"
|
|
```
|
|
|
|
## Derive support
|
|
|
|
For embedded Rust applications, Decodal can generate a schema and typed decoder from a Rust struct with the `derive` feature.
|
|
|
|
```toml
|
|
[dependencies]
|
|
decodal = { version = "0.1", features = ["derive"] }
|
|
```
|
|
|
|
```rust
|
|
use decodal::{Decodal, DecodalDecode, DecodalSchema, Engine};
|
|
|
|
#[derive(Decodal)]
|
|
struct Service {
|
|
name: String,
|
|
#[decodal(gt = 443, default = 8443)]
|
|
port: i64,
|
|
#[decodal(rename = "feature.enable", default = true)]
|
|
feature_enabled: bool,
|
|
}
|
|
```
|
|
|
|
The derive implements:
|
|
|
|
- `DecodalSchema`, which produces a host schema for `Engine::bind_global`
|
|
- `DecodalDecode`, which converts materialized `Data` into the Rust struct
|
|
|
|
## CLI
|
|
|
|
A standalone CLI is kept in this repository as the `decodal-cli` workspace package.
|
|
It builds a `decodal` binary, but it is not the primary crates.io package.
|
|
|
|
Run a Decodal file from the repository:
|
|
|
|
```sh
|
|
cargo run -q -p decodal-cli -- examples/advanced/main.dcdl
|
|
```
|
|
|
|
Enable optional regex support when needed:
|
|
|
|
```sh
|
|
cargo run -q -p decodal-cli --features regex -- examples/regex/main.dcdl
|
|
```
|
|
|
|
## Language server
|
|
|
|
The `decodal-language-service` crate provides transport-independent evaluation and completion, while `decodal-lsp` exposes it through the Language Server Protocol with live semantic diagnostics and document formatting.
|
|
Its library API accepts the same host environment used for production evaluation, so application-defined globals and structured import routing remain available in the editor.
|
|
|
|
```toml
|
|
[dependencies]
|
|
decodal = "0.2.0"
|
|
decodal-language-service = "0.2.0"
|
|
decodal-lsp = "0.2.0"
|
|
```
|
|
|
|
Run the default filesystem-backed server from the repository:
|
|
|
|
```sh
|
|
cargo run -q -p decodal-lsp
|
|
```
|
|
|
|
Embedded applications can implement `decodal_lsp::LspEnvironment` for their existing `HostEnvironment` and construct it from the `InitializeParams` passed to `decodal_lsp::run_stdio`.
|
|
|
|
## Web playground
|
|
|
|
The static documentation site and browser playground live under:
|
|
|
|
```text
|
|
site/decodal-site/
|
|
```
|
|
|
|
Browser hosts can use `decodal-wasm`. Its `DecodalLanguageService` accepts JavaScript-owned `globals`, `loadImport`, and `completeImport` callbacks; filesystem and virtual-project policy remain outside the package.
|
|
|
|
## License
|
|
|
|
Licensed under either of:
|
|
|
|
- Apache License, Version 2.0
|
|
- MIT license
|
|
|
|
at your option.
|