Placeholders

The web application developer may use so-called placeholders in the source document for [Templating]: the bracy template files. [The Basic Idea] wiki page already mentioned the placeholders that this page will discuss further.

Where Do Placeholders Appear?

<p {quantifier} title={substitute2a} class="beautiful emphasized {substitute2b}">Dear {substitute1},</p>

• In text nodes of the template. These are substitution placeholders.
  • Any part of a child text node of an element. (See {substitute1} in the example above.)
  • As an attribute value (See {substitute2a} in the example above); or as a part of that (See {substitute2b} in the example above.)
• In the start tag of an element, but not in the attribute value part - rather in place of an HTML attribute. These will be called quantifiers. (See {quantifier} in the example above.) The value of the quantifier will not appear in the resulting DOM, but it will affect template instantiation.

Note: the template should be syntactically correct as an HTML fragment, and will be parsed as such. The quantifier gets parsed as an attribute without a value. You can't use characters such as >, /, &, ", ', =, whitespaces in the placeholders because HTML rules apply.
Note: the substitution value of {substitute2a} may or may not have spaces in it, and even though the placeholder itself is not between quotation marks, the value is substituted as a whole in the title attribute.

Syntax Inside The Placeholder

{name} contains a variable name that is in scope of the backing javascript; by type:

• undefined: fail templating with an error;
• null or empty object: the parent element from the template won't appear in the target;
• object instanceof Observable: subscribe for changes and redo substitution each time it changes;
• object with entries: instantiate the parent element for each entry; for each i in name...
  - in an attribute value: name[i] gets inserted as its value,
  - in the inner text: name[i] gets inserted as the text node,
  - in a start tag, as quantifier: if the value is again an object, name[i].field can be referred to as {field} from the child text nodes.
• boolean:
  - in an attribute value: remove attribute if false, attr="" if true,
  - in a start tag, as quantifier: remove element if false; copy element to target without the placeholder if true,
  - in the inner text: templating fails with error,
• string/number/bigint:
  - in an attribute value/the inner text: the value gets substituted as a text node
  - in a start tag, as quantifier: remove element if == 0
• function: call it without params, process its return value according to its type like a variable of that type; re-evaluate if function is decorated with @expiry
• symbol: templating fails with error

{i:name} make {i} refer to the value of the variable name in this element of the template document

• Observable: {i} refers to the value stored in the Observable object
• object with entries: the index can be referred to as {i} (be it numeric or string); refer to the value as {@i}
  - in a start tag, as quantifier: nothing is substituted for the placeholder itself, value will only appear where {@i} explicitely appears
  - otherwise: the same value is substituted as for {name}
• other types: the same value is substituted as for {name}
  - in a start tag, as quantifier: if t:times="1" or "1+" and the value == 0: just assign to {i}
  - in a child text node: assign to {i}, fail with error for boolean and string value for others
  - in the value of an attribute: assign to {i}

{name(arg1,arg2)}

• call function and substitute the return value
  - pass value of Observable arguments instead of the Observable object to the function (unless function annotated with @Observables)
  - re-evaluate when any of the parameters are Observable and change
  - also re-evaluate if function has an @expiry and expires
• handle each return type like in variable placeholders

{i:name(arg1,arg2)} function call, store its return value as {i}

{name1}{name2} several placeholders in the same element:
* Cartesian product of elements get instantiated,
* i.e. removed if any of the names evaluate to empty object or null or false, and
* N times M instances appear if name1 has N entries and name2 has M.

Operations Inside Placeholder Brackets

• Not all javascript operators are supported; if you need more complex operations, use function calls instead and implement such in the backing script;
• placeholders appear in different contexts of an html document, where restrictions apply; the grammar of these expressions will avoid the usage of equals (=) sign, the and (&) ligature and whitespaces among others;
• {v|0} or short {v?} converts anything to boolean (potentially removes the element if it is a quantifier)
  - boolean: unchanged,
  - number: whether != 0,
  - null: false,
  - object instanceof Observable: get the value and convert that,
  - object otherwise: whether it has entries,
  - string that represents a boolean: convert to that boolean,
  - string literally "null": false,
  - string that converts to number using javascript coerce: whether != 0,
  - other string: true,
  - other types: true;
• {p|q} OR-combines booleans (result is guaranteed to be boolean);
• {p*q} AND-combines booleans, same as {p}{q} but with precedence over |
  - we could use & entity for * but it would look cluttered;
• {!p} negates boolean, top precedence;
• {p!} negates boolean but on lower precedence level than | (or even +, which is discussed below);
• {i+1} converts a 0-based index into 1-based ordinal;
• {obj-1} to get the highest existing 0-based index of an object;
• {v+0} or short {v#} converts anything to number/string
  - null: 0,
  - object instanceof Observable: get the value and convert that,
  - object otherwise: number of elements,
  - string that represents a boolean: convert that boolean to 0 or 1,
  - string literally "null": 0,
  - string that converts to number using javascript coerce: do it,
  - other string: leave it unchanged,
  - boolean/number/other types: javascript coerce to number;
• {s~t} equals (the = sign is to be avoided in a start tag because of html parsing;)
• {s~_} true if the string is blank; distinguishes "" from "0", latter is not blank;
• {booing(s)} boolean string (either "true" or "false" as string;)
• {join(a)} convert an array to string by joining;
• {obj.field} field selector - second argument is taken as a name, not evaluated
• {obj[i]}indexing - evaluate even the second operand to its value, unlike with the dot operator
• precedence of operations:
  - {!p*q} (NOT p) AND q, because prefix ! is top precedence,
  - {p|q*r} p OR (q AND r), because * has precedence over |,
  - {w:p|q} assign (p OR q) to w, because : has the lowest precedence,
  - {i-1|0} (i-1) to boolean, because arithmetic - is prior to |,
  - {w:v-1!} convert v to number, decrement, convert to boolean then negate as boolean and finally assign to w,
  - {i+j-k} (i+j)-k, because of left-associativity,
  - {j~i+1} j=(i+1), because precedence of ~ is in between logic binary and arithmetic operators.

        1. x.w (field selector; w taken by name!)
        2. x(v), x[y] (function call and indexing)
        3. !x, ?x, #x, @w (prefix unaries: one thing negate etc.)
        4. x+y, x-y (left-to-right; arithmetic add/subtract)
        5. x~y (equality)
        6. x*y (boolean and)
        7. x|y (boolean or)
        8. x!, x?, x#, w@ (postfix unaries: whole shit negate etc.)
        9. x,y (argument list separator)
        10. w:x (assignment)

Formally:

class CalculateOperations {
    // {v|w}
    or(u, v) {
        return this.toBoolean(u) || this.toBoolean(v)
    }

    // {v*w}
    and(u, v) {
        return this.toBoolean(u) && this.toBoolean(v)
    }

    // {v~w}
    matches(u, v) {
        if (isNaN(v)) {
            return ("" + u).trim() == ("" + v).trim()
        }
        return this.toNumber(u) == v
    }

    // {v|0} - result is guaranteed to be boolean
    // a string converts to false if (and only if) any nullish value would
    // convert to that string
    toBoolean(v) {
        return !!this.toNumber(v)
    }

    // {!v} negate as boolean, result is always boolean
    not(v) {
        return !this.toNumber(v)
    }

    // {v+1} - numbers increment, result is never nullish (except for v = -1)
    successor(v) { 
        var num = this.toNumber(v)
        return isNaN(num) ? v : (num + 1)
    }

    // {v-1} - numbers decrement, booleans negate and convert to number
    predecessor(v) {
        var num = this.toNumber(v)
        return isNaN(num) ? 0 : (num - 1) 
    }

    // {v+0} - try converting to number, leave alone strings that fail parsing
    toNumber(v) {
        return Subtype.toNumber(v)
    }

    // {v~_} whether the string is blank; "" differs from "0" unlike in {!v}
    blank(v) {
        if (typeof v == "string") {
            return !(v.trim())
        }
        return this.not(v)
    }

    // {booing(v)}
    booing(v) {
        return this.toBoolean(v) ? "true" : "false"
    }

    // {join(v)}
    join(v) {
        if (Array.isArray(v)) {
            return v.join(" ")
        }
        return v.toString() //object? Observable?
    }
}

[Csaba Skrabák]

JavaScript keywords should be preserved, like true and false. Some engine-defined variables would be useful to enable more no-script functionality, like observable[1], observable[2] as intrapage communication pipes? String literals are missing so much!