Redesign template macro

[NthTensor]

I've redesigned several aspects of the template macro to incorporate community feedback.

Changes

• The internals have been simplified. The confusing Prototype trait has been removed. Fragment no longer is generic over bundle type.
• The Commands based api has been replaced with a more flexible EntityCommands version.
• More things have been made pub.
• The docs have been significantly improved.
• The syntax of the macro itself has been streamlined to reduce boilerplate. Expressions are now used instead of blocks where possible, reducing the bracket and parenthesis clutter.
• Bundles can now be dynamic using the new BoxedBundle trait and b!() macro. I've opted for b!(Foo) over bundle!(Foo) because it gets tedious to write.
• Receipts are now stored in the ECS as components.
• Applying templates to child entities created by other templates now works as expected.
• A new example has been added.
• Adds a new Callback component and on(into_observer_system) helper for adding observers to templates. Observers are added as children which always observe their parents.

This is a breaking change, as the syntax of the macro is not fully backwards compatible. Here is the full list of syntax changes:

• A => symbol is now required between a fragment's bundle and it's list of children.
• Bundles no longer need to be wrapped in blocks: {(Foo, Bar)} is now just (Foo, Bar).

Example

The proposed syntax changes:

// BEFORE
fn counter<T: Component>(num: usize, name: &str, inc: T, dec: T) -> Template {
    template! {
        { Text::new("You have ") }
        [
            { TextSpan::new(format!("{num}")) };
            { TextSpan::new(format!(" {name}!")) };
        ];
        {( Button, Text::new("Increase"), TextColor(css::GREEN.into()), inc, visible_if(num < 100) )};
        {( Button, Text::new("Decrease"), TextColor(css::RED.into()), dec, visible_if(num > 0) )};
    }
}

// AFTER
fn counter<T: Component>(num: usize, name: &str, inc: T, dec: T) -> Template {
    template! {
        Text::new("You have ") => [
            TextSpan::new(format!("{num}"));
            TextSpan::new(format!(" {name}!"));
        ];
        ( Button, Text::new("Increase"), TextColor(css::GREEN.into()), inc, visible_if(num < 100) );
        ( Button, Text::new("Decrease"), TextColor(css::RED.into()), dec, visible_if(num > 0) );
    }
}

Conditional bundles:

/// BEFORE
template !{
    @{
        if cond {
            template!{ name: {(ComponentA)}; } 
        } else {
            template!{ name: {(ComponentB, ComponentC)}; }
        }
    }
}

/// AFTER
template !{
    name: if cond { b!(ComponentA) } else { b!(ComponentB, ComponentC) };
}

Observers:

template!{
    Name::new("MyEntity") => [
        on(|trigger: Trigger<Pointer<Click>>| {
            // Do something when "MyEntity" is clicked.
        });
        on(|trigger: Trigger<Pointer<Drag>>| {
            // Do something when "MyEntity" is dragged.
        });
    ];
}

Other Notes

For increased compatibility with bsn, i'm considering swapping the ; for a ,.

[NthTensor]

Notice how this is building a template on a child of another template. Now that receipts are stored on-entity, you can apply any template to any entity and it will just work (remove any components/children included in the previous template but not the new one).

[alice-i-cecile]

Remember to update RELEASES.md :) I like these changes, but we should get ready to cut a new major version.

[NthTensor]

Yep yep. Just random question, how do we feel about a 1.0 release?

[alice-i-cecile]

No strong feelings. I suppose this is about as 1.0 as we'll ever get?

[villor]

Awesome evolution of this very handy macro! Loving the neater syntax and the b!-macro.

[JMS55]

I would hold off on a 1.0 for now. I'm planning to test this out in some editor stuff sometime soon hopefully, and might find additional stuff to change.

[omaskery]

Exciting!

[omaskery]

Perhaps this is just obvious to other people (I'm not super familiar with how observers work), but perhaps this could do with a comment briefly explaining why we observe the parent if it's there, and why we fallback to listening to all entities otherwise?

[NthTensor]

Ah yeah, I'll be sure to document that. My thinking was, this could let you swap out different global observers by collecting them into a template.

[xenolithviktor]

Suggested change

	($fragments:ident; @ $block:block ; $( $($sib:tt)+ )? ) => {
	$fragments.extend({ $block }); // Extend the fragments with the value of the block.
	$(push_item!($fragments; $($sib)*))* // Continue pushing siblings onto the current list.
	};
	($fragments:ident; @ $splice:expr ; $( $($sib:tt)+ )? ) => {
	$fragments.extend({ $splice }); // Extend the fragments with the result of the expression.
	$(push_item!($fragments; $($sib)*))* // Continue pushing siblings onto the current list.
	};

Maybe the brace-requirement could be removed for splices as well for consistency:

@counter(num_sheep, "sheep", Button::Increment, Button::Decrement);

[villor]

Forgot to switch from the work account. Again...

[NthTensor]

I considered that, I was still on the fence.

[villor]

For increased compatibility with bsn, i'm considering swapping the ; for a ,.

I actually like that there is a separation between entity delimiters and component delimiters. Maybe BSN should do the same 🤷‍♂️

[NthTensor]

Same. Will keep then.

[JeanMertz]

@NthTensor is the name part of the fragment also used to insert the Name component? That would be convenient, but I can't seem to find it in the code. I name (most of) my components to be able to search for them in egui-inspector during debugging.

[JeanMertz]

Also, could the name part (also) accept a literal ? That would allow using static strings without needing a block.

[JeanMertz]

One more comment: I know cart previously mentioned that formatting would work inside the macro, but in this implementation it does not (it seems?).

Are you aware of anything specific that causes formatting not to work? I assume anything inside the macro has to be "valid rust syntax" for formatting to work?

edit appologies, I misread. Cart mentioned:

Support the scenarios above, while still feeling "at home" alongside normal Rust code. This includes playing nicely with Rust Analyzer for autocomplete, go-to-definition, documentation-on-hover, etc.

And later mentioned in post-MVP work:

bsn! macro auto-formatter (command line tool + editor extensions)

[villor]

@JeanMertz
Actually, formatting can be supported directly by rustfmt . As long as the syntax in the macro can be interpreted as a valid rust AST.

Here's the only description I could find on how rustfmt handles macro invocations, two things we'd have to keep in mind:

1. Calls using { ... } are ignored by the formatter.
2. Calls using ( ... ) or [ ... ] can be formatted, as long as their contents are valid rust.

Let's try and see if we can make this template formattable using the above information!

template! {
    Node { position_type: PositionType::Absolute, ..Default::default() } => [ Node { padding: UiRect::all(Val::px(5.0)), ..default() }; Text("Hello World"); ];
};

The first problem is it is using { ... }. So let's replace them with [ ...]. This actually kinda makes sense since a template is a Vec.

template! [
    Node { position_type: PositionType::Absolute, ..Default::default() } => [ Node { padding: UiRect::all(Val::px(5.0)), ..default() }; Text("Hello World"); ];
];

Still not formattable... In valid rust, the delimiters inside a slice [] are ,, not ;. So let's try using commas instead:

template! [
    Node { position_type: PositionType::Absolute, ..Default::default() } => [ Node { padding: UiRect::all(Val::px(5.0)), ..default() }, Text("Hello World"), ],
];

Still no formatting... But wait, => is not actually a valid operator in expressions, what if we used one that was, like >? Note that rustfmt does not care about the types and whether the operator actually makes sense for them. It only sees the syntax.

template![
    Node {
        position_type: PositionType::Absolute,
        ..default()
    } > [
        Node {
            padding: UiRect::all(Val::px(5.0)),
            ..default()
        },
        Text("Hello World")
    ],
];

It works! 🥳

@NthTensor it might make sense to use commas after all. The alternative is to do something like this, in which case each fragment is interpreted as a statement, allowing the formatter to work:

template!({
    Node {
        position_type: PositionType::Absolute,
        ..default()
    } > {
        Node {
            padding: UiRect::all(Val::px(5.0)),
            ..default()
        };
        Text("Hello World");
    };
});

Along with changing the => to something that rustfmt sees as an operator. My vote goes to >, but there are a lot of options:
+ - * / % & | ^ << >> == != > < >= <= || && = -= *= /= %= &= |= ^= <<= >>=

Of course we'd also have to figure out ways to make names and splices look like valid rust...

[NthTensor]

Oh wow, cool! Unfortunately I think => is one of the only valid operators that can appear after an expression in rust, there's limited options there (the syntax also has to be something that can be parsed to AST before the macro runs. I'll have a look at this tomorrow.

[villor]

Riiiight, because it wouldn't be able to tell where the expression ends... Yeah that might get tricky

[NthTensor]

I just checked, expressions can only be followed by =>, , and ;, but I think I may be able to get around that actually by using another token tree. The other big issue here is names, it will be difficult to massage the name: bundle syntax into the form expected by tuples or lists.

[villor]

For splices, the @ would need to be replaced by something that can come before an expression, .. makes sense to me as it acts like a "spread" operation.

For names, it would need to use one of the expr <operator> expr kinds I guess... Not as beautiful as :. But may work with something like name | Node or name < Node 🤷‍♂️

[villor]

I don't know how you feel about abandoning macro_rules! for a proc macro, but here is the syn parser I'm currently using for hot_reload experiments if you need it:

use syn::{
    bracketed,
    parse::{Parse, ParseStream},
    punctuated::Punctuated,
    visit::Visit,
    Block, Expr, Macro, Token,
};

pub struct AstTemplate {
    pub items: Punctuated<AstItem, Token![;]>,
}

impl Parse for AstTemplate {
    fn parse(input: ParseStream) -> syn::Result<Self> {
        let items = input.parse_terminated(AstItem::parse, Token![;])?;
        Ok(AstTemplate { items })
    }
}

pub enum AstName {
    Static(String),
    Dynamic(Block),
}

pub enum AstItem {
    Fragment {
        name: Option<AstName>,
        expr: Expr,
        children: Punctuated<AstItem, Token![;]>,
    },
    Splice(Block),
}

impl Parse for AstItem {
    fn parse(input: ParseStream) -> syn::Result<Self> {
        if input.peek(Token![@]) {
            input.parse::<Token![@]>()?;
            Ok(AstItem::Splice(input.parse()?))
        } else {
            let (name, expr) = match input.parse()? {
                // Static name
                Expr::Path(expr_path) if input.peek(Token![:]) => {
                    let name = expr_path.path.get_ident().unwrap().to_string();
                    input.parse::<Token![:]>()?;
                    (Some(AstName::Static(name)), input.parse()?)
                }
                // Dynamic name
                Expr::Block(expr_block) if input.peek(Token![:]) => {
                    input.parse::<Token![:]>()?;
                    (Some(AstName::Dynamic(expr_block.block)), input.parse()?)
                }
                // Anonymous
                expr => (None, expr),
            };

            let children = if input.peek(Token![=]) {
                input.parse::<Token![=]>()?;
                input.parse::<Token![>]>()?;
                let content;
                bracketed!(content in input);
                content.parse_terminated(AstItem::parse, Token![;])?
            } else {
                Punctuated::new()
            };

            Ok(AstItem::Fragment {
                name,
                expr,
                children,
            })
        }
    }
}

[NthTensor]

In principle I'd be fine with it. I went with macro_rules initially to keep the complexity down, but I think we are basically at the limit of what it can be used for. There's no additional avenues for extension that don't rely on code duplication.

[villor]

I think it's a good idea to stay away from proc macros where not needed. My experience with proc macros and RA is not good... Slow and buggy. But when it gets to a point where trying to figure out the declarative way is an even bigger headache than dealing with RA-issues... ⚖️

[JeanMertz]

It’s also worth pointing out that one of the goals is for the scene format to be (roughly?) equal both in rust code and in external files.

Formatting using rustfmt in Rust code makes sense, but when you have external .bsn files, you’re likely going to write your own formatter anyway, at which point a) you want to prioritize a pleasing looking syntax over a syntactically valid Rust one, and b) with tech like Treesitter and injected languages, it’s a small step to using that same formatter to format code in your bsn macro in Rust code (f.e. I use a Lua formatter/highlighter to format/highlight Lua strings in my Nix files)