Skip to main content

tabnas_alchemy/
lib.rs

1//! The alchemy language: declarative streaming transducers and renderers
2//! for the tabnas engine, parsed by a tabnas grammar plugin; and the types
3//! every tabnas transducer and renderer shares.
4//!
5//! [`shared`] is the types: the event and table protocols, sinks,
6//! failures and their codes, limits, selectors, datums, the renderers'
7//! options and text boundary, and the two interfaces a program is lowered
8//! through, [`shared::Routers`] and [`shared::Renderers`]. It depends on
9//! nothing else in the fleet; with `default-features = false` it is the
10//! whole crate, and tabnas-transduce and tabnas-render build on it.
11//!
12//! Everything else is the language, behind the default `language`
13//! feature. The reader:
14//!
15//! - [`lex`] and [`grammar`]: the grammar plugin, installed on an engine
16//!   with [`alchemy`], or built with [`make`]; [`parse_value`] answers the
17//!   reader's tagged tree and [`parse`] the [`Expr`] forms.
18//! - [`ast`]: [`Expr`] with [`SourceSpan`]s, the [`canonical`] and layout
19//!   [`format`] printers, and [`MAX_NESTING`], the bound every form this
20//!   crate builds respects.
21//! - [`desugar`]: the core-form rewrites (`def` with parameters, `pipe`,
22//!   the shapes of `let`, `if` and `match`).
23//!
24//! The language, reading [`Expr`] after [`desugar`] has run:
25//!
26//! - [`resolve`]: scopes and linking; [`types`] and [`check`]: inference,
27//!   affine streams, protocols, strict mode; [`effects`]: the effect
28//!   summary and the `explain` report.
29//! - [`value`]: runtime values, every one `Send`, with streams and texts
30//!   as plans; [`interp`]: the evaluator; [`lower`]: plans to the stages
31//!   the host's routers and renderers make; [`stdlib`]: the natives and
32//!   the embedded library.
33//! - [`program`]: [`compile`] and [`Program`], the API a host embeds. The
34//!   host passes the routers (tabnas-transduce's) and the renderers
35//!   (tabnas-render's) in; the `dmog` command, which does, is
36//!   tabnas-dmog.
37//!
38//! ```
39//! use tabnas_alchemy::{canonical, desugar, parse};
40//! let src = "def export [input]\n  pipe input\n    table-from-json api-binding\n    csv csv-options";
41//! let core = desugar::program(parse(src)?, src)?;
42//! assert_eq!(
43//!     canonical(&core),
44//!     "(def export (fn [input] (csv csv-options (table-from-json api-binding input))))"
45//! );
46//! # Ok::<(), tabnas_alchemy::shared::Fail>(())
47//! ```
48
49#![forbid(unsafe_code)]
50// The crate's documentation above names the language, which a build
51// without the `language` feature leaves out.
52#![cfg_attr(not(feature = "language"), allow(rustdoc::broken_intra_doc_links))]
53
54/// The README's Rust examples run as doctests, so a stale one fails the
55/// gate rather than misleading the reader.
56#[cfg(all(doctest, feature = "language"))]
57#[doc = include_str!("../README.md")]
58mod readme_examples {}
59
60pub mod shared;
61
62#[cfg(feature = "language")]
63pub mod ast;
64#[cfg(feature = "language")]
65pub mod check;
66#[cfg(feature = "language")]
67pub mod desugar;
68#[cfg(feature = "language")]
69pub mod effects;
70#[cfg(feature = "language")]
71mod fx;
72#[cfg(feature = "language")]
73pub mod grammar;
74#[cfg(feature = "language")]
75pub mod interp;
76#[cfg(feature = "language")]
77pub mod lex;
78#[cfg(feature = "language")]
79pub mod lower;
80#[cfg(feature = "language")]
81pub mod program;
82#[cfg(feature = "language")]
83pub mod pvec;
84#[cfg(feature = "language")]
85pub mod resolve;
86#[cfg(feature = "language")]
87pub mod rope;
88#[cfg(feature = "language")]
89pub mod stdlib;
90#[cfg(feature = "language")]
91pub mod translate;
92#[cfg(feature = "language")]
93pub mod types;
94#[cfg(feature = "language")]
95pub mod value;
96
97#[cfg(feature = "language")]
98pub use ast::{
99    canonical, canonical_form, format, same_program, Expr, SourceSpan, Sources, MAX_NESTING,
100};
101#[cfg(feature = "language")]
102pub use check::MAX_APPLIED;
103#[cfg(feature = "language")]
104pub use grammar::{alchemy, make, parse, parse_file, parse_value, UNNAMED};
105#[cfg(feature = "language")]
106pub use interp::{MAX_EVAL_DEPTH, MAX_PLAN_STEPS};
107#[cfg(feature = "language")]
108pub use program::{
109    compile, compile_sources, compile_sources_with, compile_with, Input, Output, Program, Renderer,
110    Source,
111};
112
113/// The stack the checker and the evaluator are given: [`compile`] runs on
114/// a thread of this size, and so does the `dmog` command, so a program
115/// at [`MAX_NESTING`] and an evaluation at [`MAX_EVAL_DEPTH`] fit in a
116/// debug build as in a release one. A host that pushes events into a
117/// [`Program::sink`] runs the program's per-item functions on its own
118/// thread and gives it at least this much (aless's parse thread has it).
119#[cfg(feature = "language")]
120pub const STACK_BYTES: usize = 64 << 20;
121
122/// This crate's version, as `Cargo.toml` declares it.
123pub const VERSION: &str = env!("CARGO_PKG_VERSION");