XEG Operators
Higher precedence binds tighter. Parentheses group without adding anything to the expression. This page is generated from spec/expression-reference.json; the builtins are on XEG Builtins and the full grammar on Expressions.
| Precedence | Operator | Name | Form | Associativity | Summary |
|---|---|---|---|---|---|
| 10 | . | member | postfix | left | a.key reads an own key of an object. |
| 10 | [ ] | index | postfix | left | a[i] reads an array element, a string’s UTF-16 code unit, or an object key. |
| 10 | ( ) | call | postfix | left | name(args) calls a builtin. |
| 9 | ! | not | prefix | right | true when the operand is falsy, false otherwise. |
| 9 | - | negate | prefix | right | The numeric negation of the operand. |
| 9 | + | plus | prefix | right | The operand unchanged when it is a number. |
| 8 | * | multiply | binary | left | Numeric multiplication. |
| 8 | / | divide | binary | left | Numeric division. |
| 8 | % | remainder | binary | left | The remainder of numeric division, taking the sign of the dividend. |
| 7 | + | add or concatenate | binary | left | Numeric addition, or string concatenation when either side is a string. |
| 7 | - | subtract | binary | left | Numeric subtraction. |
| 6 | < | less than | binary | left | Whether a orders before b. |
| 6 | <= | less than or equal | binary | left | Whether a orders before or equal to b. |
| 6 | > | greater than | binary | left | Whether a orders after b. |
| 6 | >= | greater than or equal | binary | left | Whether a orders after or equal to b. |
| 5 | === | equal | binary | left | Strict equality between two primitives. |
| 5 | == | equal (loose spelling) | binary | left | Another spelling of ===. |
| 5 | !== | not equal | binary | left | The negation of ===. |
| 5 | != | not equal (loose spelling) | binary | left | Another spelling of !==. |
| 4 | && | logical and | binary | left | a && b is a when a is falsy, otherwise b. |
| 3 | || | logical or | binary | left | a || b is a when a is truthy, otherwise b. |
| 2 | ?? | nullish coalescing | binary | left | a ?? b is a unless a is null, in which case it is b. |
| 1 | ? : | conditional | ternary | right | test ? a : b evaluates to a when test is truthy and b otherwise. |
Operators in detail
Section titled “Operators in detail”. member
Section titled “. member”a.key reads an own key of an object.
A key the object does not own, or a member of anything that is not an object, is null. length on a string or an array is its length, counting UTF-16 code units for a string.
| Expression | Result |
|---|---|
player.stats.str | 12 |
nothing.anything | null |
effects.length | 2 |
[ ] index
Section titled “[ ] index”a[i] reads an array element, a string’s UTF-16 code unit, or an object key.
A whole number indexes an array or a string, counting from the end when negative; a fractional one is null. A number on an object reads the key str of it spells, so o[1.5] reads "1.5". A string reads an object key or length; on an array it reads the element its JavaScript Number value names ("1", " 1 ", and "0x1" all read element 1, a blank string reads element 0, and a negative one is null). Anything out of range or not owned is null.
| Expression | Result |
|---|---|
effects[1] | "slow" |
effects[-1] | "slow" |
player['name'] | "Hero" |
( ) call
Section titled “( ) call”name(args) calls a builtin.
Only a builtin can be called, and only by name: an identifier in call position is never looked up in the bindings, and a binding value is never callable. An unknown name or a wrong argument count is a parse error.
| Expression | Result |
|---|---|
round(hp / 3) | 12 |
true when the operand is falsy, false otherwise.
Always returns a boolean.
| Expression | Result |
|---|---|
!dead | true |
!empty | false |
- negate
Section titled “- negate”The numeric negation of the operand.
Defined on numbers only; anything else is null.
| Expression | Result |
|---|---|
-hp | -35 |
+ plus
Section titled “+ plus”The operand unchanged when it is a number.
Does not coerce: +'3' is null. Use num to parse a string.
| Expression | Result |
|---|---|
+hp | 35 |
+'3' | null |
* multiply
Section titled “* multiply”Numeric multiplication.
Defined on numbers only; anything else is null, and a non-finite result is null.
| Expression | Result |
|---|---|
hp * 2 | 70 |
/ divide
Section titled “/ divide”Numeric division.
Defined on numbers only. Division by zero is null, not Infinity or NaN.
| Expression | Result |
|---|---|
hp / maxHp | 0.35 |
hp / zero | null |
% remainder
Section titled “% remainder”The remainder of numeric division, taking the sign of the dividend.
Defined on numbers only. A remainder by zero is null.
| Expression | Result |
|---|---|
hp % 10 | 5 |
hp % zero | null |
+ add or concatenate
Section titled “+ add or concatenate”Numeric addition, or string concatenation when either side is a string.
Two numbers add. When either side is a string and the other is a primitive, both render with str and concatenate. Anything else, including an array or object operand, is null.
| Expression | Result |
|---|---|
hp + 5 | 40 |
'HP: ' + hp | "HP: 35" |
effects + 'x' | null |
- subtract
Section titled “- subtract”Numeric subtraction.
Defined on numbers only; anything else is null.
| Expression | Result |
|---|---|
maxHp - hp | 65 |
< less than
Section titled “< less than”Whether a orders before b.
Defined on two numbers or two strings; strings order by UTF-16 code unit, as JavaScript’s < does. Mixed types are false, not a coercion.
| Expression | Result |
|---|---|
hp < maxHp | true |
hp < '50' | false |
<= less than or equal
Section titled “<= less than or equal”Whether a orders before or equal to b.
Defined on two numbers or two strings; strings order by UTF-16 code unit, as JavaScript’s < does. Mixed types are false.
| Expression | Result |
|---|---|
hp <= 35 | true |
> greater than
Section titled “> greater than”Whether a orders after b.
Defined on two numbers or two strings; strings order by UTF-16 code unit, as JavaScript’s < does. Mixed types are false.
| Expression | Result |
|---|---|
'b' > 'a' | true |
>= greater than or equal
Section titled “>= greater than or equal”Whether a orders after or equal to b.
Defined on two numbers or two strings; strings order by UTF-16 code unit, as JavaScript’s < does. Mixed types are false.
| Expression | Result |
|---|---|
score >= 7 | true |
=== equal
Section titled “=== equal”Strict equality between two primitives.
No coercion: 1 === '1' is false. Two arrays or two objects are never equal, even to themselves, because XEG has no identity to compare.
| Expression | Result |
|---|---|
name === 'Hero' | true |
effects === effects | false |
== equal (loose spelling)
Section titled “== equal (loose spelling)”Another spelling of ===.
Accepted so existing data-if bodies keep working. It is strict: 1 == '1' is false.
| Expression | Result |
|---|---|
score == '7' | false |
!== not equal
Section titled “!== not equal”The negation of ===.
Two arrays or two objects are always unequal.
| Expression | Result |
|---|---|
name !== 'Villain' | true |
!= not equal (loose spelling)
Section titled “!= not equal (loose spelling)”Another spelling of !==.
It is strict: 1 != '1' is true.
| Expression | Result |
|---|---|
score != '7' | true |
&& logical and
Section titled “&& logical and”a && b is a when a is falsy, otherwise b.
Returns one of its operands, not a boolean, and does not evaluate b when a is falsy.
| Expression | Result |
|---|---|
alive && hp | 35 |
|| logical or
Section titled “|| logical or”a || b is a when a is truthy, otherwise b.
Returns one of its operands, not a boolean, and does not evaluate b when a is truthy.
| Expression | Result |
|---|---|
blank || 'anonymous' | "anonymous" |
?? nullish coalescing
Section titled “?? nullish coalescing”a ?? b is a unless a is null, in which case it is b.
Only null falls through. 0, false, and the empty string are kept, which is what separates it from ||. A failed computation is null, so ?? also supplies a fallback for one.
| Expression | Result |
|---|---|
nothing ?? 'none' | "none" |
zero ?? 5 | 0 |
? : conditional
Section titled “? : conditional”test ? a : b evaluates to a when test is truthy and b otherwise.
Selects a value, never a branch of markup. Only the chosen side is evaluated.
| Expression | Result |
|---|---|
hp < 50 ? 'hurt' : 'fine' | "hurt" |
Evaluation rules
Section titled “Evaluation rules”Truthiness
Section titled “Truthiness”null, false, 0, and the empty string are falsy. Everything else is truthy, including an empty array and an empty object.
Nothing throws
Section titled “Nothing throws”Any evaluation failure yields null: a type mismatch, a missing key, an index out of range, a division by zero, or a non-finite result. null is falsy for data-if and renders as the empty string for data-bind and interpolation.
Identifiers
Section titled “Identifiers”An identifier resolves only against the fill’s declared bindings and, inside a data-each template, the names that template binds. An undeclared identifier is a validate-time error and null at runtime. Nothing reaches a host global.
Literals
Section titled “Literals”Numbers (42, 3.5, .5, 2e3; a decimal point is always followed by a digit, and a literal that opens with its point takes no exponent), strings in single or double quotes with the escapes \n, \t, \r, \b, \f, \0, and \uXXXX, true, false, and null. There are no array, object, template, or regular-expression literals.
Deliberately absent
Section titled “Deliberately absent”No assignment, increment, comma operator, arrow function, function, new, typeof, in, instanceof, delete, optional chaining, bitwise operator, or method call on a value. Every expression is a total, pure function of its bindings.
Where expressions appear
Section titled “Where expressions appear”| Attribute | Value | Summary |
|---|---|---|
data-if | expression | Shows the node when the expression is truthy and hides it when it is falsy. |
data-bind | expression | Writes the expression’s value into the node: its text, or the prop the vocabulary names with bindTo. |
data-each | repeat header | Renders the node once per element of an array. |
data-key | expression | Names each repeated copy’s identity, so an update patches copies by key instead of replacing them. |
{{ }} | expression | Interpolates an expression’s value into a text node. |
data-if
Section titled “data-if”The result is reported to the host in conditions, keyed by the node’s position, and the host hides the node by whatever means its renderer has. The tree is never pruned. An expression that fails or does not parse is false.
<div data-if="hp < 50">You're hurting!</div>data-bind
Section titled “data-bind”The value renders with str, so null writes the empty string. A bare binding name is writable: an input or change handler can push a new value back through the binding’s path, and a name whose binding is absent writes nothing so the authored fallback survives. Any other expression is read-only, and a write-back handler aimed at one is a lint error.
<span data-bind="hp">0</span><span data-bind="round(hp / maxHp * 100)">0</span>data-each
Section titled “data-each”The header is item in expr or (item, index) in expr. The expression is evaluated in the enclosing scope and must yield an array; anything else renders zero copies. Each copy has the item, the optional index name, and $index in scope for every expression inside it, shadowing bindings of the same name. Repeat names are values with no host path, so they are not writable. One render produces at most 10,000 copies across every repeat.
<li data-each="effect in effects"><span data-bind="effect"></span></li><li data-each="(member, i) in party" data-key="member.id">{{ i + 1 }}. {{ member.name }}</li>data-key
Section titled “data-key”Evaluated per copy with the item in scope. A key must be a string or a finite number, and 1 and "1" are different keys. A duplicate or invalid key drops the whole repeat to positional keying and reports a diagnostic. On a node without data-each it does nothing, and lint warns.
<li data-each="member in party" data-key="member.id"></li>{{ }}
Active only in a fill that sets "interpolate": true, and only in text nodes; an attribute value is never an interpolation site. The value renders with str and stays text, so it can never become markup. \{{ writes a literal {{.
<p>Health: {{ hp }}/{{ maxHp }}</p>Scope names
Section titled “Scope names”$index
Section titled “$index”The zero-based position of the current copy inside a data-each template. Bound in every copy whether or not the header names an index. Inside nested repeats it refers to the innermost one.