Expression engine grammar
The exact definition of what you can write in an expression. It accepts two ways of writing the same thing: C# style and Python style. If you are looking for examples and not the definition, start with the quick guide or the manual.
Principles
- Level 1 (Expression): everything in this document except the ‘Level 2’ section. No statements, no assignments → guaranteed termination.
- Identifiers, keywords and function names are case-insensitive (
Upper,upperandUPPERare the same). String content: case-sensitive. - Text is always stored in invariant culture: decimal point, ISO dates.
- Comments:
// lineand/* block */(useful in scripts; also valid in expressions). Python’s#comment doesn’t exist:#delimits date literals (#2026-06-10#).
Tokens
| Token | Form | Example |
|---|---|---|
| Number | digits with optional . decimal (no thousands separator) | 123, 0.5, 1234.56 |
| String | "..." or '...'; escapes \\ \" \' \n \t | "IVA", '21%' |
| Date | #yyyy-MM-dd#, #yyyy-MM-dd HH:mm#, #... HH:mm:ss# | #2026-06-10# |
| Boolean | true, false | |
| Null | null or None (alias) | |
| Field | [Field Name] (allows spaces and accents) | [Total Línea] |
| Identifier | letter or _ + letters/digits/_ | PageNumber, tipoIva |
| Aggregate | AGG(identifier) — special form, reports compatibility | AGG(totalVentas) |
Grammar (EBNF) — Level 1
expresion := condicional
condicional := coalesce ( '?' expresion ':' expresion
| 'if' coalesce 'else' condicional )? // Python form
coalesce := logicaOr ('??' logicaOr)*
logicaOr := logicaAnd (('||' | 'or') logicaAnd)*
logicaAnd := igualdad (('&&' | 'and') igualdad)*
igualdad := relacional (('==' | '!=' | '<>') relacional)*
relacional := aditiva (('<' | '<=' | '>' | '>=') aditiva)*
aditiva := multiplicativa (('+' | '-') multiplicativa)*
multiplicativa := unaria (('*' | '/' | '%') unaria)*
unaria := ('-' | '!' | 'not') unaria | postfija
postfija := primaria ('.' identificador argumentos?)* // allowed members only
primaria := numero | cadena | fecha | 'true' | 'false' | 'null'
| '[' nombreCampo ']'
| 'AGG' '(' identificador ')'
| identificador argumentos? // allowed symbol or function
| '(' expresion ')'
argumentos := '(' (expresion? (',' expresion?)*)? ')' // a gap between commas is null
and/or/notare friendly aliases for&&/||/!;<>is an alias for!=;Nonefornull.- Python conditional form:
value if condition else other≡condition ? value : other. Same node and same semantics (lazy evaluation; null condition → false branch). Right-associative:a if c1 else b if c2 else c=a if c1 else (b if c2 else c).if/elseare contextual: they only trigger the form after a complete expression. =is neither comparison nor assignment in expressions. Parser error with a teaching message: ‘Para comparar use ==’ (‘To compare, use ==’). It stops an expression changing meaning when pasted into a script (where=is assignment).- A bare identifier is resolved by going up the environment’s scope chain (script variables → row → group → report parameters → globals such as
PageNumber,TotalPages). Symbol not found = binding error with a suggestion.
Types and conversions
Language types: Null, Boolean, Decimal, String, DateTime.
- Every number is
decimal. No visibledoubleorint. +with two numbers adds; with at least one string it concatenates (the other operand is formatted in invariant culture)."Total: " + 12.5→"Total: 12.5".- Other arithmetic only between numbers; incompatible type = evaluation error.
- Comparison between numbers: numeric. Between strings: ordinal, case-sensitive (PostgreSQL-compatible; to ignore capitals:
Upper(a) == Upper(b)). Between dates: chronological. Different non-comparable types = error. - Division or modulo by zero = evaluation error (the same as both databases).
- Conversions always explicit through functions (
ToDecimal,ToString,ToDate). No implicit coercion except the concatenation described.
Null semantics (three-valued logic, compatible with MS SQL / PostgreSQL)
| Operation | Result | ||
|---|---|---|---|
null + 5, null * x, -null | null (all arithmetic propagates) | ||
"a" + null | null (like +/`\ | \ | in SQL; Concat` ignores null) |
a == b with a null at runtime | null (unknown) | ||
x == null / x != null (literal) | true/false — acts as IS [NOT] NULL | ||
true or null | true | ||
false or null | null | ||
true and null | null | ||
false and null | false | ||
not null | null | ||
Condition of ?: (or if) = null | the false branch is taken (as in SQL WHERE) | ||
null ?? x | x (equivalent to Coalesce(null, x)) |
Allowed functions
English names in SQL/C# style (the ones SQL users already know); case-insensitive.
- Null:
Coalesce(a, b, ...)·IsNull(a, b)(alias ofCoalescewith 2) ·IIf(cond, ifTrue, ifFalse) - Maths:
Abs·Round(x[, decimals])(away-from-zero, as in SQL) ·Floor·Ceiling·Min(a, b)·Max(a, b) - Strings:
Upper·Lower·Trim·Len·Substring(s, start[, length])(start at 1, as in SQL) ·Replace·Contains·StartsWith·EndsWith·PadLeft(s, width[, char])·PadRight·Concat(a, b, ...)(ignores nulls) - Dates:
Today()·Now()(fixed when the root environment is created: constant throughout the report) ·Year·Month·Day·NombreMes(‘Enero’, ‘Febrero’…) ·AddDays·AddMonths·AddYears·DateDiffDays(a, b) - Conversion:
ToDecimal(x)·ToString(x)·ToDate(x)(invariant/ISO parsing; failure = error) - Format:
Format(value, "format")— .NET formats ("N2","dd/MM/yyyy"...). The only culture-sensitive function: it uses the environment’s display culture (es-ES by default), because its output is for showing, not for storing.
Adding a function = an entry in the function registry (name, arity, types, purity). Level 1 functions are pure (no side effects); Now/Today are pure thanks to the fixed clock.
Errors
Four categories, all with position (index and excerpt) and a message in Spanish:
- Parse (
ExpressionParseException): unexpected/expected token. Includes the=case → ‘use ==’. - Binding (
ExpressionBindException): unknown symbol or function; suggestion by edit distance (‘¿Quiso decir [TotalLinea]?’, ‘Did you mean [TotalLinea]?’). - Permissions (
ExpressionPermissionException): symbol from an area the user can’t access. - Runtime (
ExpressionRuntimeException): division by zero, failed conversion, incompatible type, step budget exhausted (scripts).
Level 2 — Script
It reuses the expression grammar in full. It only adds statements:
script := sentencia+
sentencia := declaracion | asignacion | si | mientras | porCada | devolver
| bloque | expresion ';'
declaracion := 'var' identificador '=' expresion ';'
asignacion := identificador '=' expresion ';'
si := 'if' '(' expresion ')' sentencia ('else' sentencia)?
mientras := 'while' '(' expresion ')' sentencia
porCada := 'foreach' '(' 'var' identificador 'in' expresion ')' sentencia
devolver := 'return' expresion? ';'
bloque := '{' sentencia* '}' // opens a child scope
Rules:
- Statement keywords (
var,if,else,while,foreach,in,return) are contextual: only reserved in statement position; in expressions they are still ordinary identifiers. Case-insensitive like the whole language. - In scripts
=is assignment (in expressions it is still the teaching error ‘use ==’). - Each
bloqueopens a child scope;vardeclares in the current scope (it shadows the outer one; redeclaring in the same block is an error). Assignment only goes up through script scopes: the environment’s symbols (fields, parameters) are read-only. - The script returns the value of the first
returnreached; withoutreturn(orreturn;) → null. foreachiterates over lists (IEnumerablevalues from the environment, opaque to the rest of the language); over null it doesn’t iterate (friendly propagation); over any other type → runtime error.- Step budget (
CompileOptions.MaxSteps, 1.000.000 by default) deducted on each statement and iteration; exhausted =ExpressionRuntimeException(‘posible bucle infinito’, ‘possible infinite loop’).CancellationTokenchecked on every backward jump of a loop. - Environment level: running a script against a
LanguageLevel.Expressionenvironment (report ones, always) =ExpressionPermissionException. - ERP API: if the environment exposes the capabilities, the
QueryandCommandsymbols exist in the script’s root scope; if it doesn’t, resolving them is a binding error (unknown symbol). Their members are the surface of the future API: today they are DUMMY interfaces and anyQuery.X(...)/Command.X(...)gives a clear ‘API aún sin miembros’ (‘API has no members yet’) error. Command is never in report environments (by design). - Only an interpreted backend for scripts; the compiled backend is for expressions.