Skip to main content

teksilo_macros/
lib.rs

1// SPDX-License-Identifier: MPL-2.0
2// SPDX-FileCopyrightText: 2026 FernTech
3
4//! The `teksu!` DSL proc-macro for Teksilo widget trees.
5//!
6//! See `engineering/docs/teksu-language-spec-v3.md` for the surface language. This
7//! crate implements a one-to-one syntactic transform from the DSL to
8//! Teksilo V2 builder calls. The macro's only job is to remove syntactic
9//! noise: every construct desugars to code the user could have written
10//! by hand.
11//!
12//! # Crate path dispatch
13//!
14//! Apps depend on `teksilo` (the umbrella crate) and receive `teksu!`
15//! through `teksilo::prelude`. The emitted code references Teksilo types
16//! through `::teksilo::core::...`. Internal workspace crates (any crate
17//! whose name starts with `teksilo-`) cannot depend on `teksilo` (circular),
18//! so the macro detects `CARGO_PKG_NAME` and emits `::teksilo_core::...`
19//! paths instead. This mirrors the pattern in `teksilo-i18n-macros/src/lib.rs`.
20
21use proc_macro::TokenStream;
22use proc_macro2::TokenStream as TokenStream2;
23use quote::quote;
24use syn::{DeriveInput, parse_macro_input};
25
26mod intent_kind;
27mod lower;
28
29/// Crate-root token stream used inside emitted code. Internal teksilo
30/// workspace library crates (which depend on `teksilo-core` directly but
31/// typically not on the `teksilo` umbrella crate) route through
32/// `::teksilo_core`; everything else — including examples and external
33/// applications that depend on the umbrella crate — routes through
34/// `::teksilo::core`.
35///
36/// The detection is an explicit allowlist rather than `starts_with("teksilo-")`
37/// because application crates commonly share the `teksilo-` prefix (e.g. a
38/// downstream `teksilo-app` binary), and the `teksilo-app` binary in this
39/// workspace itself is one such case. A bare prefix match silently routed
40/// them through `::teksilo_core`, which isn't a direct dependency from an
41/// external app and failed to resolve.
42#[allow(dead_code)]
43pub(crate) fn teksilo_core_root() -> TokenStream2 {
44    let pkg = std::env::var("CARGO_PKG_NAME").unwrap_or_default();
45    let is_internal = matches!(
46        pkg.as_str(),
47        "teksilo-core"
48            | "teksilo-canvas"
49            | "teksilo-tokens"
50            | "teksilo-widgets"
51            | "teksilo-data"
52            | "teksilo-text"
53            | "teksilo-i18n"
54            | "teksilo-i18n-macros"
55            | "teksilo-macros"
56            | "teksilo-render"
57            | "teksilo-platform"
58            | "teksilo-resources"
59    );
60    if is_internal {
61        quote!(::teksilo_core)
62    } else {
63        quote!(::teksilo::core)
64    }
65}
66
67/// The `teksu!` DSL entry point. Parses a block-structured widget-tree
68/// description and expands to a sequence of Teksilo V2 builder calls.
69///
70/// Two forms:
71///
72/// ```text
73/// teksu!(ctx => <root-element>)    // inserts into the arena via ctx.add,
74///                                  // returns a WidgetId
75/// teksu!(<root-element>)           // returns a widget value, suitable
76///                                  // for passing to .child(...) etc.
77/// ```
78///
79/// See `engineering/docs/teksu-language-spec-v3.md` for the full surface language.
80#[proc_macro]
81pub fn teksu(input: TokenStream) -> TokenStream {
82    match teksilo_parse::parse_root(input.into()) {
83        Ok(root) => lower::lower_root(&root).into(),
84        Err(err) => err.to_compile_error().into(),
85    }
86}
87
88/// `#[derive(IntentKind)]` — generate a typed DTO bridge between an
89/// app's intent enum and the runtime `Intent` dispatch type.
90///
91/// Each variant must carry a `#[name = "..."]` attribute; the string
92/// is used as the runtime intent name. The derive never inspects the
93/// fields — the whole variant (unit, tuple or struct, any field types)
94/// is stored as the intent's type-erased payload; see the docs on the
95/// `IntentKind` trait in `teksilo-core::intent`.
96#[proc_macro_derive(IntentKind, attributes(name))]
97pub fn derive_intent_kind(input: TokenStream) -> TokenStream {
98    let input = parse_macro_input!(input as DeriveInput);
99    match intent_kind::derive_intent_kind(input) {
100        Ok(ts) => ts.into(),
101        Err(err) => err.to_compile_error().into(),
102    }
103}