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}