Alternative BSN Syntax: <> Entity Syntax

[cart]

This is a potential alternative BSN syntax that attempts to resolve some issues with the current BSN syntax. It comes down to introducing new <> syntax to indicate the bounds of an Entity.

First, here is an example with the current bsn! syntax:

bsn! {
    Node { width: px(100) }
    BackgroundColor(GREEN)
    [
        (
            Node { width: px(10) }
            BackgroundColor(RED)
        ),
        (
            :checkbox
            InteractionDisabled
            Children [
                Text("Hello there")
            ]
        ),
        Node { width: px(10) }
    ]
}

And here is the <> syntax:

bsn! {
    Node { width: px(100) }
    BackgroundColor(GREEN)
    <
        Node { width: px(10) }
        BackgroundColor(RED)
    >
    <
        :checkbox
        InteractionDisabled
        <Text("Hello there")>
    >
    <Node { width: px(10) }>
}

Resolved Issue: Over-indentation / newlines

In the current syntax, children with more than one component use () for clarity. This sadly results in both over-indentation and unnecessary newlines:

Node { width: px(100) }
BackgroundColor(GREEN)
[      // This is awkward!
    (  // This is also awkward!
        Node { width: px(10) }
        BackgroundColor(RED)
    )
    (
        Node { width: px(10) }
        BackgroundColor(RED)
    ),
]

The proposed <> syntax resolves these problems:

Node { width: px(100) }
BackgroundColor(GREEN)
<
    Node { width: px(10) }
    BackgroundColor(RED)
>
<
    Node { width: px(10) }
    BackgroundColor(RED)
>

Resolved Issue: Eliminates the RelationshipTarget [] vs Component [] ambiguity

The current [] shorthand for Children [] creates ambiguities with SomeParentComponent [] and RelationshipTarget []. This new syntax removes the [] shorthand, freeing up RelationshipTarget [] (if we still want it in this new world ... coming up a with a new syntax might be better).

Resolved Issue: Syntax Noise

Currently defining children involves a mix of [], (), and ,:

// Note this doesn't use newlines like it normally would to put the focus on the syntax
Node [(Node Marker [ Node ]), (Node Marker [ Node ])]

<> syntax cuts this down substantially:

Node <Node Marker <Node>><Node Marker <Node>>

Resolved Issue: Child misalignment

Currently for terseness, children don't require () wrappers for small numbers of components:

Node [
    // Omitting `()` is encouraged here
    #Child1 [
        Node
    ],
    // Including `()` is encouraged here
    (
        #Child2
        Marker
        [
            Node
        ]
    )
]

This makes it visually challenging to pair #Child1 and #Child2 together. <> syntax would be required, which forces a "pairing" between them:

Node
<
    #Child1
    <Node>
>
<
    #Child2
    Marker
    <Node>
>

Resolved Issue: Where to put commas

The current BSN syntax has rules that feel a bit "arbitrary". Components within a single entity do not use comma separators, lists of entities do:

Node // no commas here
Marker 
[
    Node, // commas here
    Node,
]

Some people find this confusing / arbitrary. <> removes the comma case from the "structural BSN syntax", reserving it only for initializing rust types:

Node // no commas
Marker 
<Node> // no commas
<Node>

BSN currenty exists in a middle ground where it largely feels like Rust, but it makes targeted departures from Rust syntax in the interest of ergonomics or clarity. This creates a kind of "wait why aren't there commas here" discomfort in some people, as it feels like a violation of Rust-like expectations (ex: (Node Marker) when defining a child entity instead of (Node, Marker)). Adding commas to that case feels ergonomically non-viable to me in the context of BSN.

The proposed <> helps resolve that discomfort by more fully decoupling ourselves from the Rust context. <> feels less "Rust-ey" and more "user-interface-ey". When defining hierachies in <> elsewhere (ex: the web), people expect no commas:

<button style="width: 10px" onclick="button_click" />

We're just replacing these attributes with components (and abandoning the "closing" aspect of XML):

<:Button Node { width: px(10) } on(button_click)>

Resolved Issue: Removes an annoying "syntax refactor" case

Currently, adding a component can force a move from the "shorthand" approach to the () wrapper approach:

// before
Node [
    Node,
    Node [
        Node
    ],
]
// after
Node [
    Node,
    (
        Node 
        BackgroundColor(RED)
        [
            Node
        ]
    ),
]

With <> syntax, this is not necessary:

// before
Node
<Node>
<
    Node
    <Node>
>
// after
Node
<Node>
<
    Node
    BackgroundColor(RED)
    <Node>
>

New Issue: What do we do for custom relationships?

Previously, all "hierarchical relationships" felt the same:

bsn! {
    Node { width: px(10) }
    [
        Node,
        Node,
    ]
}
// which is just shorthand for
bsn! {
    Node { width: px(10) }
    Children [
        Node,
        Node,
    ]
}
// other relationships pair nicely
bsn! {
    Node { width: px(10) }
    Inventory [
        Item,
        Item,
    ]
    Children [
        Node,
        Node,
    ]
}

We will almost certainly lose that pairing in the new world, and are likely to lose the "shared levels of indentation".

// Option 1: Keep the "RelationshipTarget []" syntax (it is no longer ambiguous)
// This currently has my preference
bsn! {
    Node { width: px(10) }
    Inventory [
        <Item> 
        <Item> 
    ]
    <Node>
}

// Option 2: Alternative RelationshipTarget syntax
bsn! {
    Node { width: px(10) }
    Inventory:
        <Item> 
        <Item>
    // Note that this is relying on newlines to avoid ambiguity ... not ideal
    <Node>
}

// Option 3: rely on the relationship name w/ new syntax
bsn! {
    Node { width: px(10) }
    // This feels awkward to me
    InInventory: <Item> 
    InInventory: <Item> 
    <Node>
}

// Nonviable Option 1: Use the Relationship component + #Name features as currently proposed
bsn! {
    #Root
    Node { width: px(10) }
    // this would _need_ to also add the Item entities as Children, as we want to support
    // layering additional relationships on top of children.
    <Item InInventory(#Root)> 
    // this also requires more boilerplate: specifying the relationship for each Inventory item,
    // _and_ defining a #Name _and_ passing it in for each Item
    <Item InInventory(#Root)> 
    <Node>
}

New Issue: XML / HTML similarity

<> introduces a similarity to XML / HTML that may cause some developers to wrongly assume they are compatible. I personally think this is worth it.

Note that I think embracing more XML syntax would make things worse (ex: "closing syntax like </div>" or <button /> syntax would degrade our ergonmics)

Alternative: Use () instead of <>

// <> Syntax
bsn! {
    Node { width: px(100) }
    BackgroundColor(GREEN)
    <
        Node { width: px(10) }
        BackgroundColor(RED)
    >
    <
        :checkbox
        InteractionDisabled
        <Text("Hello there")>
    >
    <Node { width: px(10) }>
}
// () Syntax
bsn! {
    Node { width: px(100) }
    BackgroundColor(GREEN)
    (
        Node { width: px(10) }
        BackgroundColor(RED)
    )
    (
        :checkbox
        InteractionDisabled
        (Text("Hello there"))
    )
    (Node { width: px(10) })
}

Pros:

• Feels more Rust-ey
• Drops the "xml similarity"

Cons:

• Losing special "entity syntax" means it is harder to pick out entities / children from other rust code. Everything starts to blur together. Consider this:

  Node
  Thing(RED) // These two lines feel
  (Red)      // very similar

• Perhaps too Rusty ... people expect to use commas inside ()

I'm personally still biased toward <>.

[cart]

Hmm one problem: providing an inline bsn list is now ambiguous with providing a single BSN:

// before 
bsn! {
   Node [
      {children}
   ]
}

// after
bsn! {
  Node
  // this expects an `impl Scene` not an `impl SceneList`
  {children}
}

[TheShowMy]

Here's a random shower thought: define the entire hierarchy upfront, and then create the specific entities directly at their correct level. Just spitballing here!

bsn! {
    {
        bg
        bg_top
        bg_top_label
        bg_checkbox
        bg_bottom
    },
    bg{
        Node { width: px(100) }
        BackgroundColor(GREEN)
    }
    bg_top{
        Node { width: px(10) }
        BackgroundColor(RED)
    }
    bg_checkbox{
        : checkbox
        InteractionDisabled
        Children[
            Text("Hello there")
        ]
    }
    bg_bottom{
        Node { width: px(10) }
    }
}

bsn! {
    {
        *bg
        **top
        ***top_label
        **checkbox
        **bottom
    },
    bg{
        Node { width: px(100) }
        BackgroundColor(GREEN)
    }
    top{
        Node { width: px(10) }
        BackgroundColor(RED)
    }
    checkbox{
        : checkbox
        InteractionDisabled
        Children[
            Text("Hello there")
        ]
    }
    bottom{
        Node { width: px(10) }
    }
}

[viridia]

@cart Here's an alternate proposal, in three parts. The first part doesn't address the children ambiguity, but it does deal with the over-indentation, and avoids the "XML uncanny valley" effect.

The idea is to use the YAML / Markdown page break token --- as a separator between entities. This also implies that it is no longer required to put parentheses around a group of component to define an entity.

bsn! {
    Node { width: px(100) }
    BackgroundColor(GREEN)
    [
        Node { width: px(10) }
        BackgroundColor(RED)
        ---
        :checkbox
        InteractionDisabled
        Children [
            Text("Hello there")
        ]
        ---
        Node { width: px(10) }
    ]
}

In effect, the triple-dash token is functioning as a comma, but it looks better when appearing on a line by itself than a naked comma. Note that I'm not completely enamored of this syntax, but I like it better than <>.

For the children ambiguity, I have an even more radical suggestion, but it will require some context.

Several suggestions for resolving the "children" ambiguity have involved making the initial token more than just a single [, but the choice of token (e.g. @[) has been arbitrary. However, what if the token actually meant something outside of the children case?

Up to this point we've mostly been discussing the "leaf-level" BSN syntax: the examples are mostly concentrated on defining individual entities and components, and while there are some inherited scenes there are relatively few. However, my vision, for UI anyway (and possibly other things) is that we'll have a rich set of inheritable scenes and mixins, and that users will mostly be working at that level: that is, most of the syntax will be a composition of mixins and inherited scenes, with actual raw components and relations being the minority case. This means that I want to optimize BSN syntax for that mode of authoring.

In particular, one thing that happens quite a lot at higher levels of abstraction is the frequent use of embedded bsn_list! macros. The listview example that I recently created is an example:

:listview(
    bsn_list! [
        :listrow [(Text("First World") ThemedText)],
        :listrow Selected::default() [(Text("Second Nature") ThemedText)],
        :listrow [(Text("Third Degree") ThemedText)],
        :listrow InteractionDisabled::default() [(Text("Fourth Wall") ThemedText)],
        :listrow [(Text("Fifth Column") ThemedText)],
        :listrow [(Text("Sixth Sense") ThemedText)],
        :listrow [(Text("Seventh Heaven") ThemedText)],
        :listrow [(Text("Eighth Wonder") ThemedText)],
        :listrow [(Text("Ninth Inning") ThemedText)],
        :listrow [(Text("Tenth Amendment") ThemedText)],
        :listrow [(Text("Eleventh Hour") ThemedText)],
        :listrow [(Text("Twelfth Night") ThemedText)],
    ]
)

Here we are passing in the contents of the listview as a template parameter rather than using the children syntax. The reason we have to do this is because listview has a more complex internal structure: it has an outer "frame" element which holds the scrollbars, and an inner "scrolling" element which contains the actual rows. Thus, the actual row entities are the grandchildren of the listview entity, which the existing children syntax doesn't let us do.

Similarly, in my bevy_reactor experiments, I use bsn_list! quite a bit:

if_then_else(
    |cx: &Cx| *cx.resource::<State<GameState>>().get() == GameState::Play,
    || bsn_list![Text("Yes: Playing")],
    || bsn_list![Text("No: Not Playing")]
)

The bsn_list! macro gets used so much at this level that it starts to become noise.

So one idea would be to define a shortcut. The most obvious is to simply delete the word bsn_list and make the token ![ a shortcut for bsn_list![:

:listview(![
    :listrow [(Text("First World") ThemedText)],
    :listrow Selected::default() [(Text("Second Nature") ThemedText)],
    :listrow [(Text("Third Degree") ThemedText)],
    :listrow InteractionDisabled::default() [(Text("Fourth Wall") ThemedText)],
    :listrow [(Text("Fifth Column") ThemedText)],
    :listrow [(Text("Sixth Sense") ThemedText)],
    :listrow [(Text("Seventh Heaven") ThemedText)],
    :listrow [(Text("Eighth Wonder") ThemedText)],
    :listrow [(Text("Ninth Inning") ThemedText)],
    :listrow [(Text("Tenth Amendment") ThemedText)],
    :listrow [(Text("Eleventh Hour") ThemedText)],
    :listrow [(Text("Twelfth Night") ThemedText)],
])

(BTW note that the ::default() on Selected and InteractionDisabled is a workaround for the children ambiguity).

So now we have created an association in the user's mind between the token ![ and a list of entities. So let's take a step further and say that a bare ![...] list is presumed to be a list of children:

:listview(![
    :listrow ![(Text("First World") ThemedText)],
    :listrow Selected ![(Text("Second Nature") ThemedText)],
    :listrow ![(Text("Third Degree") ThemedText)],
    :listrow InteractionDisabled ![(Text("Fourth Wall") ThemedText)],
    :listrow ![(Text("Fifth Column") ThemedText)],
    :listrow ![(Text("Sixth Sense") ThemedText)],
    :listrow ![(Text("Seventh Heaven") ThemedText)],
    :listrow ![(Text("Eighth Wonder") ThemedText)],
    :listrow ![(Text("Ninth Inning") ThemedText)],
    :listrow ![(Text("Tenth Amendment") ThemedText)],
    :listrow ![(Text("Eleventh Hour") ThemedText)],
    :listrow ![(Text("Twelfth Night") ThemedText)],
])

Combining this with the --- syntax let's us drop the parens. It does take more vertical space in this example, but one-liners are not generally that common:

:listview(![
    :listrow ![Text("First World") ThemedText]
    ---
    :listrow Selected ![Text("Second Nature") ThemedText]
    ---
    :listrow ![Text("Third Degree") ThemedText]
    ---
    :listrow InteractionDisabled ![Text("Fourth Wall") ThemedText]
    ---
    :listrow ![Text("Fifth Column") ThemedText]
    ---
    :listrow ![Text("Sixth Sense") ThemedText]
    ---
    :listrow ![Text("Seventh Heaven") ThemedText]
    ---
    :listrow ![Text("Eighth Wonder") ThemedText]
    ---
    :listrow ![Text("Ninth Inning") ThemedText]
    ---
    :listrow ![Text("Tenth Amendment") ThemedText]
    ---
    :listrow ![Text("Eleventh Hour") ThemedText]
    ---
    :listrow ![Text("Twelfth Night") ThemedText]
])

What about regular relations? If we use the ![ token for their arguments, it re-introduces the syntactical ambiguity again, so we can't do that. Instead, we'll just use the regular [ token for arguments to relations:

bsn! {
    Node { width: px(100) }
    BackgroundColor(GREEN)
    ![
        Node { width: px(10) }
        BackgroundColor(RED)
        Owned [
            Mutable(true)
            ---
            Reaction(false)
        ]
    ]
}

I realize that this argument is on fairly weak ground: that purely in terms of semantics, the association between children and other relations is stronger than the association between children and template parameters, and my syntax is inconsistent with this. However, we're working in a highly constrained space here and don't have a lot of options, so I'm willing to live with a little bit of inconsistency for pragmatic purposes.

OK to sum up, I have laid out three proposals, which can be adopted (or not) individually:

• The use of the triple-dash token as an entity separator
• The use of ![ as a shorthand for bsn_list![ when used as an expression.
• The use of ![ as a shorthand for Children [ when used as a component.

[viridia]

Thinking about this some more, I have a modification of my proposal which may be slightly better: swapping the meaning of [ and ![. So the rules would be:

• [] used in component context always means "a list of children".
• ![] always means "a parameter containing a list of scenes":
  • When used as an expression, it's a bsn_list passed as a template parameter
  • When used in component context, it's always an argument to the previous component (which is presumably a relation)

This has a couple of advantages:

• The meaning are more consistent (at least, if you squint)
• Since "children" are used far more than "relations", we reserve the "nicer" syntax for the more common case.

So my earlier example becomes:

:listview(![
    :listrow [Text("First World") ThemedText]
    ---
    :listrow Selected [Text("Second Nature") ThemedText]
    ---
    :listrow [Text("Third Degree") ThemedText]
    ---
    :listrow InteractionDisabled [Text("Fourth Wall") ThemedText]
    ---
    :listrow [Text("Fifth Column") ThemedText]
    ---
    :listrow [Text("Sixth Sense") ThemedText]
    ---
    :listrow [Text("Seventh Heaven") ThemedText]
    ---
    :listrow [Text("Eighth Wonder") ThemedText]
    ---
    :listrow [Text("Ninth Inning") ThemedText]
    ---
    :listrow [Text("Tenth Amendment") ThemedText]
    ---
    :listrow [Text("Eleventh Hour") ThemedText]
    ---
    :listrow [Text("Twelfth Night") ThemedText]
])

and

bsn! {
    Node { width: px(100) }
    BackgroundColor(GREEN)
    [
        Node { width: px(10) }
        BackgroundColor(RED)
        Owned ![
            Mutable(true)
            ---
            Reaction(false)
        ]
    ]
}