eternal_ui/macros.rs
1// This Source Code Form is subject to the terms of the Mozilla Public
2// License, v. 2.0. If a copy of the MPL was not distributed with this
3// file, You can obtain one at https://mozilla.org/MPL/2.0/.
4
5/// Builds an [`Element`](crate::Element) tree from markup.
6///
7/// The syntax is a small subset of HTML, inside Rust:
8///
9/// ```
10/// use eternal_ui::{ui, Element};
11///
12/// #[derive(Clone, Debug)]
13/// enum Msg { Save, Rename(String), Wrap(bool) }
14///
15/// let name = "sketch.png";
16/// let root: Element<Msg> = ui! {
17/// <column class="panel" id="main">
18/// <row class="toolbar">
19/// <button id="save" shortcut="Ctrl+S" on:click={|| Msg::Save}>"Save"</button>
20/// <spacer/>
21/// <label class="dim">{format!("Editing {name}")}</label>
22/// </row>
23/// <input value={name} placeholder="File name" on:change={Msg::Rename}/>
24/// <checkbox checked="true" on:toggle={Msg::Wrap}>"Wrap around"</checkbox>
25/// </column>
26/// };
27/// assert_eq!(root.tag(), "column");
28/// assert_eq!(root.children().len(), 3);
29/// ```
30///
31/// - A tag is one of the constructors in [`elements`](crate::elements):
32/// `column`, `row`, `panel`, `label`, `button`, `checkbox`, `input`,
33/// `separator`, `spacer`. Elements can be self-closing (`<spacer/>`).
34/// - `name="literal"` and `name={expression}` set attributes, as
35/// [`Element::attr`](crate::Element::attr) does. The expression can be
36/// anything with a `Display` impl.
37/// - `on:click={handler}` attaches a handler; the name is one of the
38/// functions in [`on`](crate::on) and the handler is a closure with the
39/// matching signature.
40/// - A child is another tag, a string literal, or `{expression}` where the
41/// expression is an element, a `Vec` of elements, an `Option<Element>`, or
42/// a `String`. Text inside a label becomes its text; text elsewhere
43/// becomes a child label.
44///
45/// A closing tag has to match its opening tag, or the macro produces a type
46/// error naming both. Every token costs a level of macro recursion, so a
47/// large template may need `#![recursion_limit = "512"]` on the crate.
48#[macro_export]
49macro_rules! ui {
50 // Closing tag: pop the frame, checking that the tags match.
51 (@m [ [ $tag:ident [ $($calls:tt)* ] ] $($stack:tt)* ] < / $close:ident > $($rest:tt)*) => {
52 $crate::ui!(@close [ [ $tag [ $($calls)* ] ] $($stack)* ] $close $($rest)*)
53 };
54 // Opening tag: push a frame and parse its attributes.
55 (@m [ $($stack:tt)* ] < $tag:ident $($rest:tt)*) => {
56 $crate::ui!(@a [ [ $tag [ ] ] $($stack)* ] $($rest)*)
57 };
58 // A text child.
59 (@m [ [ $tag:ident [ $($calls:tt)* ] ] $($stack:tt)* ] $text:literal $($rest:tt)*) => {
60 $crate::ui!(@m [ [ $tag [ $($calls)* .child($text) ] ] $($stack)* ] $($rest)*)
61 };
62 // An expression child.
63 (@m [ [ $tag:ident [ $($calls:tt)* ] ] $($stack:tt)* ] { $child:expr } $($rest:tt)*) => {
64 $crate::ui!(@m [ [ $tag [ $($calls)* .child($child) ] ] $($stack)* ] $($rest)*)
65 };
66
67 // A handler attribute.
68 (@a [ [ $tag:ident [ $($calls:tt)* ] ] $($stack:tt)* ] on : $event:ident = { $handler:expr } $($rest:tt)*) => {
69 $crate::ui!(@a [ [ $tag [ $($calls)* .on($crate::on::$event($handler)) ] ] $($stack)* ] $($rest)*)
70 };
71 // A literal attribute.
72 (@a [ [ $tag:ident [ $($calls:tt)* ] ] $($stack:tt)* ] $name:ident = $value:literal $($rest:tt)*) => {
73 $crate::ui!(@a [ [ $tag [ $($calls)* .attr(stringify!($name), $value) ] ] $($stack)* ] $($rest)*)
74 };
75 // An expression attribute.
76 (@a [ [ $tag:ident [ $($calls:tt)* ] ] $($stack:tt)* ] $name:ident = { $value:expr } $($rest:tt)*) => {
77 $crate::ui!(@a [ [ $tag [ $($calls)* .attr(stringify!($name), $value) ] ] $($stack)* ] $($rest)*)
78 };
79 // End of the opening tag: on to the children.
80 (@a [ $($stack:tt)* ] > $($rest:tt)*) => {
81 $crate::ui!(@m [ $($stack)* ] $($rest)*)
82 };
83 // A self-closing tag.
84 (@a [ [ $tag:ident [ $($calls:tt)* ] ] $($stack:tt)* ] / > $($rest:tt)*) => {
85 $crate::ui!(@close [ [ $tag [ $($calls)* ] ] $($stack)* ] $tag $($rest)*)
86 };
87
88 // The root closed and nothing follows: build it.
89 (@close [ [ $tag:ident [ $($calls:tt)* ] ] ] $close:ident) => {{
90 let _: $crate::tags::$tag = $crate::tags::$close;
91 $crate::elements::$tag() $($calls)*
92 }};
93 // A child closed: build it and add it to its parent.
94 (@close [ [ $tag:ident [ $($calls:tt)* ] ] [ $parent:ident [ $($parent_calls:tt)* ] ] $($stack:tt)* ] $close:ident $($rest:tt)*) => {
95 $crate::ui!(@m [ [ $parent [ $($parent_calls)* .child({
96 let _: $crate::tags::$tag = $crate::tags::$close;
97 $crate::elements::$tag() $($calls)*
98 }) ] ] $($stack)* ] $($rest)*)
99 };
100
101 // Entry point.
102 (< $($rest:tt)*) => {
103 $crate::ui!(@m [ ] < $($rest)*)
104 };
105}