Skip to main content

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}