ExpressionEngine
public sealed class ExpressionEngineSmall expression language for label items, e.g.
Reference with every function, operator precedence, type conversion, empty values, cultures and number/date formats, job variables, errors and recipes: zplcore.com/docs/expressions; try expressions with your own data in the expression builder.
Upper([Name]) + " / " + Format(Now(), "dd.MM.yyyy") or If([Qty] > 10, "BULK", "SINGLE"). - Fields:
[Field Name](data record), or item names ([TextItem1]= text of another item) - Literals: numbers, "strings", true/false
- Operators: + - * / % (+ concatenates if either side is text), = <> < <= > >=, and/or/not, unary -
- Variables: LABEL_INDEX, LABEL_NUMBER; in data bindings also LABEL_WIDTH, LABEL_HEIGHT (label units), RECORD_INDEX, PAGE_NUMBER and TOTAL_PAGES (when the record count is known); plus custom ones via
ExpressionEngine.Variables - Conversions use
ExpressionEngine.Culture(invariant by default); Format/ToString/ToNumber accept a culture name argument. - Functions: see
ExpressionEngine.Functions; add your own.
Reference with every function, operator precedence, type conversion, empty values, cultures and number/date formats, job variables, errors and recipes: zplcore.com/docs/expressions; try expressions with your own data in the expression builder.
Thread safety:
ExpressionEngine.Evaluate may be called concurrently once configured (the member cache is static and concurrent); configuration (ExpressionEngine.Variables, ExpressionEngine.Functions, AddTypeReference) is not thread-safe.Constructors
| Signature | Description |
|---|---|
# ExpressionEngine() |
Properties
| Property | Type | Description |
|---|---|---|
Clock { get; set; } | Func<DateTime> | Clock for Now()/Today() (tests, reprints with the original date). |
Culture { get; set; } | CultureInfo | Culture used for number/date text conversion, Upper/Lower and Format. Defaults to CultureInfo.InvariantCulture so labels don't change with the server's regional settings. A culture name argument of Format/ToString (3rd), ToNumber/IsNumeric (2nd) and ToDate (3rd), e.g. Format([price], "C", [culture]), overrides it for that call; a missing, empty or non-text argument means this culture. Not part of label JSON: templates loaded from JSON pass cultures as argument. Dates use the culture's standard calendar from a fixed table (ExpressionEngine.StandardCalendar), the same on every operating system; a culture whose ICU data defaults to another calendar is replaced by a read-only copy. |
Functions { get; } | Dictionary<string, Func<object[], object>> | Functions callable as Name(args) (case-insensitive); add or replace entries, or use ExpressionEngine.SetCustomFunction. A function gets its arguments evaluated (missing ones are not passed; read them as null) and returns a number (Double; other numeric types are converted), text, Boolean, DateTime or null. Built in:
Left/Right/Mid/Substring clamp their counts (never an error); Contains/StartsWith/EndsWith/IndexOf ignore case, Replace does not; Repeat stops at 10,000 copies; If evaluates both branches; Round takes 0–15 decimals; ToDate returns 0001-01-01 for text that is no date and Num/ToNumber return 0 for text that is no number (thousands separators are not read, except by ToNumber/IsNumeric with a culture argument); Format formats text that is a number when a format is given (D/X take whole numbers) and throws for formats a value rejects and for culture names .NET does not know. Comparisons are numeric when one side is a number or both are number texts. Every function with examples: function reference. |
static StandardCalendar { get; } | IReadOnlyDictionary<string, Type> | Standard calendars of the cultures that do not date in the Gregorian calendar (the defaults of Windows): ar-SA Umm al-Qura, th Thai Buddhist, Persian for fa, ps, ckb-IR, lrc, mzn and uz-Arab. Every other culture formats and reads dates in the Gregorian calendar – also where the ICU data of an operating system defaults to another one. The same table applies to every culture-dependent formatting of zplCore (bound fields with LabelItem.DataFieldFormat, table cells, clock fields). |
TypeReferences { get; } | IReadOnlyDictionary<string, Type> | Registered types (name → type) whose public static and instance members may be used, e.g. Math.Max(1, [Qty]). |
Variables { get; } | Dictionary<string, object> | Custom variables usable by name in expressions (case-insensitive), e.g. [Price] * VAT. |
Fields & Constants
| Field | Type | Description |
|---|---|---|
const MaxNesting = 256 | int | Deepest nesting of parentheses, calls and unary operators the parser accepts (it recurses per level). |
Methods
| Method Signature | Returns | Description |
|---|---|---|
# AddTypeReference<TRef>(string? alias = default) | ExpressionEngine | Allows expressions to call public members of TRef (see ExpressionEngine.AddTypeReference). |
# AddTypeReference(Type type, string? alias = default) | ExpressionEngine | Allows expressions to call public members of type: static members via the type name (Math.Max(1, [Qty]), DateTime.Now.AddDays(3)) and instance members on values of registered types. Only registered types are accessible. |
static # Bool(object v) | bool | Truth value of the engine (conditions, and/or/not): null → false; text → true unless "", "0" or "false" (any case); numbers → true unless 0. |
# Evaluate(string expression, Func<string, object>? fieldResolver = default) | object | Evaluates an expression to its value. expression: The expression, e.g. If([qty] > 10, "BULK", "SINGLE"). · fieldResolver: Value of a field: gets the name inside […] (and bare names that are neither functions nor variables); null = every field is empty. Int32, Int64, Single and Decimal values of […] fields are read as Double. Returns A Double, text, Boolean, DateTime, null, or what a custom function or type member returned. · Throws FormatException: Syntax error, unknown function, malformed culture name, a format the value rejects, or an invalid GS1(…) value. |
# EvaluateToString(string expression, Func<string, object>? fieldResolver = default) | string | Evaluates to a display string: the value of ExpressionEngine.Evaluate converted with ExpressionEngine.ToText – what a label prints. expression: The expression, e.g. Format([price], "C", "de-DE"). · fieldResolver: Value of a field: gets the name inside […] (and bare names that are neither functions nor variables); null = every field is empty. Returns The result as text; empty for a null result. · Throws FormatException: Syntax error, unknown function, malformed culture name, a format the value rejects, or an invalid GS1(…) value. |
static # Num(object v) | double | Culture-invariant number conversion (use ExpressionEngine.ToNum for the engine's ExpressionEngine.Culture). |
static # Num(object v, IFormatProvider culture) | double | Number conversion of the engine: null → 0, booleans → 1/0, text read with culture and then invariant (NumberStyles.Float: no thousands separators), else 0. |
# SetCustomFunction(string name, Func<object[], object> function) | ExpressionEngine | Adds or replaces a function callable as Name(args). |
# SetCustomVariable(string name, object value) | ExpressionEngine | Adds or replaces a variable usable by name in expressions. |
static # Str(object v) | string | Culture-invariant text conversion (use ExpressionEngine.ToText for the engine's ExpressionEngine.Culture). |
static # Str(object v, IFormatProvider culture) | string | Text conversion of the engine: null → "", booleans → "True"/"False", formattable values with culture (its standard calendar, special spaces as plain spaces – the same on every operating system). |
# ToNum(object v) | double | Converts a value to a number with ExpressionEngine.Culture (falls back to invariant parsing). |
# ToText(object v) | string | Converts a value to text with ExpressionEngine.Culture. |