Expressions

Applies to: BarcoderX Basic and Ultimate

Status: Planned. Nothing is released yet and there is nothing to download. This page describes the expression language at the level of concepts. Function names are fixed before the first release, and the full list will appear in the function reference.

An expression is a short formula inside a template. It works out a value for each label: the text to print, the data of a barcode, whether an element shows, or the value of almost any property of an element.

Where you use expressions

Content. The text of a text element or the data of a barcode can be an expression instead of fixed text or a plain field.
Print when. An element carries an expression that decides whether it appears. A false result skips the element.
Properties. Almost any property of an element can be set by an expression: position, size, rotation, colors, font, symbology and options. BarcoderX checks that the result fits the property.
Macros. A macro is an expression that you name and reuse. See below.

What an expression looks like

You write	It means
`{Order.Number}`	The field `Order.Number` of the current record
`#shipTo.Value`	The value of another element, named `shipTo`
`$name`	A variable of the template, or of the job
`@name`	A counter
`"(00)" & {Sscc}`	Joins text and a field. The `&` sign joins.
`Upper({ShipTo.Name})`	Calls a function
`{Qty} * 2 + 1`, `{Qty} >= 10`	Arithmetic and comparison
`Not`, `And`, `Or`	Logic

Text goes in double quotes. To put a double quote inside text, write it twice. Numbers, true, false and null are written as they are. Parentheses group parts of a formula. Names of functions and operators do not depend on upper or lower case.

Some variables are built in and cannot be changed: $pageWidth and $pageHeight (in the page unit), $jobLabelIndex (the number of the label in the job, starting at 1) and $jobLabelTotal. Inside the caption of a barcode, $humanReadable gives the text that BarcoderX generated for the barcode.

A value is one of: nothing (null), true or false, a number (exact decimal), text, a date and time, or a list.

Functions

BarcoderX plans at least 100 built-in functions for the first release. The aim is 120. They are grouped like this:

Group	What they do
Text	Change case, trim, cut, pad, find, replace, split, join and match patterns.
Numeric	Round, find the smallest or largest value, add up, average, raise to a power, and the usual mathematical functions.
Date and time	Read the parts of a date, add to a date, find the difference between dates, and give month and weekday names in a culture.
Logical	Choose a value by a condition, handle null and empty values, and test types.
Conversion and formatting	Turn values into text or numbers, format numbers, dates, currency and percentages, and convert between number bases.
GS1 and check digits	Calculate check digits, build GTIN and SSCC numbers, build and read GS1 element strings, and check GS1 data. Check digits for other schemes are included.
Encoding	Convert text to and from hexadecimal and base64, encode for a web address, and compute checksums and a SHA-256 hash.
Collections	Build lists, count, take items, take slices, remove duplicates and sort.

Function names are in English and the same in every language. Their descriptions and error messages are in English and Spanish.
Culture is always explicit. A formatting function takes a culture, or uses the culture of the job. The culture of the computer is never read.
The clock is the job's clock. Now, Today and UtcNow give the same time everywhere in one job.
Functions are pure. They cannot read or write files, call the network, or reach the host application.
Label text in several languages. The function Localize takes a key and returns the text for the language of the job.

Safe by design

Expressions run on shared infrastructure, so BarcoderX limits them. The limits are published by the web API.

Limit	Value
Length of an expression	4 KB
Nesting depth	64 levels
Parts of an expression	2,000
Work for one label	100,000 steps
Length of the result	64 KB

Pattern matching uses an engine that cannot be made to run for a very long time, and it stops after a short time limit.

An expression error never stops a job and never throws an error into your application. It becomes a diagnostic that shows where in the expression the problem is. You choose what the label shows instead: nothing, an error text, or a failed label.

BarcoderX also detects a circle of dependencies, for example when #a.Value and #b.Value refer to each other, and reports it.

Your own functions and macros

In the SDK, you can register your own .NET functions.
In the web API, nobody can upload code. Instead, you can store named macros on your server. A macro cannot call itself, and it runs within the same step budget as every other expression.

BarcoderX is a product of P4 Software.

Was this page helpful?

Previous Templates and data Next Text, fonts and pictures