> For the complete documentation index, see [llms.txt](https://docs.dbnetsoft.com/dbnetsoft/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.dbnetsoft.com/dbnetsoft/finalscore/expressions.md).

# Expressions

How to work out values per athlete, team or list - in lists, rankings, formulas, rules and PDF headers.

Wherever FinalScore needs a value worked out for an athlete, a team or a list, you write an **expression**: a list column, a filter, a sort order, a ranking, a formula result, a started / finished rule, a PDF header. Expressions are short scripts in the Scriban language, with FinalScore's own names (fields) and functions.

A few examples:

| You want                         | Expression                    |
| -------------------------------- | ----------------------------- |
| The last name in capitals        | `lastName \| string.upcase`   |
| The class rank with a dot ("3.") | `ordinal(ranks.class)`        |
| The time with one decimal        | `formatTime(timeValue, 1)`    |
| Only finished athletes (filter)  | `finished && status == "OK"`  |
| The speed at 10 km               | `splits.km10.speedSinceStart` |

The pages in this section:

* [Fields](https://docs.dbnetsoft.com/dbnetsoft/finalscore/expressions/fields.md) - every name you can read: athlete data, results, ranks, splits, special results, heats and rounds, teams, the event and the list.
* [Functions](https://docs.dbnetsoft.com/dbnetsoft/finalscore/expressions/functions.md) - FinalScore's functions (`iif`, `formatTime`, `countWhere`, ...) and the general functions for text, numbers, times and lists.
* [Custom functions and fields](https://docs.dbnetsoft.com/dbnetsoft/finalscore/expressions/custom-functions-and-fields.md) - your own functions and additional athlete fields (Setup → Fields).
* [Examples](https://docs.dbnetsoft.com/dbnetsoft/finalscore/expressions/examples.md) - ready-made expressions for common tasks.

## Expression or template

* Text **without** `{{` is an **expression**: it is worked out to one value - a number, a text, true / false or an object. Example: `lastName | string.upcase`.
* Text **with** `{{` is a **template**: the text is kept as it is and every `{{ ... }}` in it is replaced by its value. Example: `{{ lastName | string.upcase }} {{ firstName }}`.

Some inputs are always templates: a list's title and sub title, group headers, the HTML layout, the PDF header and footer cells and the bracket's round and heat headers. A PDF cell without `{{` is plain text.

Templates can also hold conditions and loops:

```
{{ if finished }}{{ time }}{{ else }}{{ status }}{{ end }}
{{ for m in members }}{{ m.name }} {{ m.time }}; {{ end }}
```

## Where expressions are used

| Page → input                                                  | Kind                                                                                                                                   | What it can read                                                       |
| ------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
| Lists → Title, Sub title                                      | template                                                                                                                               | `event`, `competition`, `heat`, `now`                                  |
| Lists → Filter                                                | expression, true = the row is shown                                                                                                    | the list's row fields                                                  |
| Lists → Sorting (each line, with Desc.)                       | expression                                                                                                                             | row fields - empty values always sort last                             |
| Lists → Grouping: Group by, Header, Order by, Max. rows       | expression / template / expression / number or expression                                                                              | row fields; the header sees the group's first row and the list's names |
| Lists → Columns → Expression                                  | expression or template                                                                                                                 | row fields                                                             |
| Lists → Columns → ⋯ → Text colour, Background                 | expression giving `#rgb`, `#rrggbb` or a colour name (`red`, `lightblue`); anything else = none                                        | row fields, e.g. `laneColor`                                           |
| Lists → Columns → ⋯ → Bold, Italic, Underline, Strike through | expression, true / false                                                                                                               | row fields, e.g. `ranks.overall <= 3`                                  |
| Lists → HTML layout                                           | template                                                                                                                               | `list`, `defaultHtml`, `event`, `competition`, `heat`, `now`           |
| Lists (bracket) → Round header, Heat header                   | template                                                                                                                               | `round`, `heat`, `event`, `competition`, `now`                         |
| Setup → Event → PDF layout: header and footer cells           | template                                                                                                                               | `list`, `event`, `page`, `pages`                                       |
| Setup → Event → Started when, Finished when                   | expression, true / false; empty = by the passings                                                                                      | the formula fields                                                     |
| Setup → Competitions → Started when, Finished when            | the same - the competition's rule wins over the event's, an athlete set by hand wins over both                                         | the formula fields                                                     |
| Setup → Results → Formula                                     | expression: a number is seconds (or the number itself for number results), a time its seconds, a text a run time, true / false = 1 / 0 | the formula fields and the results calculated before it                |
| Setup → Results → offset (after / before)                     | a time (`2:00`) or an expression: a number is seconds, a text a run time                                                               | the formula fields, e.g. `competition.minLapTime`                      |
| Setup → Ranks → Filter, Groups, Sort layers                   | expressions                                                                                                                            | the formula fields and the ranks already calculated                    |
| Setup → Heats → Add athletes → Filter, Order                  | expressions                                                                                                                            | athlete list fields, e.g. `heats.q1.rank <= 4`                         |
| Setup → Fields → Functions                                    | expression                                                                                                                             | the row it is used for and its parameters                              |

{% hint style="info" %}
**Lists and calculations see slightly different fields.** Rankings, formulas, started / finished rules and offsets are worked out while the results are calculated; they see a smaller set of fields, and some of them as numbers in seconds instead of formatted text. See [Fields → Formulas, rankings and rules](https://docs.dbnetsoft.com/dbnetsoft/finalscore/expressions/fields.md#formulas-rankings-and-rules).
{% endhint %}

## Names

* **Case does not matter**: `lastName`, `LastName` and `lastname` are the same.
* **Functions** can also be written in PascalCase or snake\_case: `formatTime`, `FormatTime` and `format_time` all work. Fields cannot be written in snake\_case: `splits.km10.timeValue`, not `time_value`.
* This documentation and the editor write every name in **camelCase**.
* **Keys** you choose in the setup (splits, results, rankings, heats, rounds, additional fields) are used in lower case: a split `KM10` is `splits.km10`, a ranking `M40` is `ranks.m40`.

## Numbers and text

* Numbers with decimals (`1.5`) are exact decimals.
* `/` divides with decimals (`10 / 4` = `2.5`), `//` gives whole numbers (`10 // 4` = `2`), `%` the remainder.
* Bibs are **text**. Use `bib | string.toInt` to calculate with one.
* `+` with a text joins: `"12" + 1` is `"121"`.
* A text compared with a number is converted (`"105" > 100` is true); two texts compare as text (`"105" > "99"` is false).
* Text comparison is case-sensitive: `lastName == "müller"` is false for "Müller" - use `string.equalsIgnoreCase(lastName, "müller")`.

## Empty values, true and false

* **Filters, rules, styles, `iif` and `countTrue`** treat `null`, `false`, `""`, `"false"`, `"0"` and `0` as false; everything else is true.
* **Inside an expression** (`&&`, `||`, `!`, `if`, `? :`) only `null` and `false` are false - an empty text and `0` are true. To test for an empty text write `x != ""` or `string.empty(x)`.
* Comparisons with an empty value are false: `ranks.overall <= 3` is false for an athlete without a rank.
* Calculating with an empty value gives an empty value: `timeValue - null` is empty.
* `ifEmpty(value, fallback)` gives the fallback for an empty value (`null` or `""`); `a ?? b` only for `null`.

{% hint style="warning" %}
**Use `?.` on things an athlete may not have.** Reading a member of something empty is an error: `team.name` for an athlete without a team gives `#ERR`. Write `team?.name`, `class?.name`, `lastSplit?.order`, `heat?.name` - these give an empty value instead.
{% endhint %}

## Errors

An expression that fails gives **`#ERR`**:

* in a list cell it is shown as `#ERR`;
* a list or ranking filter leaves the row out;
* a ranking group gives the athlete no rank in that ranking;
* a started / finished rule falls back to the passings;
* a formula result stays empty with the error "The formula failed for this athlete".

A syntax error in a ranking, a formula, a rule, an offset or a function cannot be saved. While you type, unknown names are marked (amber border).

## Operators

| Operator                      | Meaning                                                              |
| ----------------------------- | -------------------------------------------------------------------- |
| `==` `!=` `<` `<=` `>` `>=`   | compare                                                              |
| `&&` `\|\|` `!`               | and, or, not (the words `and` / `not` do not work)                   |
| `+` `-` `*` `/` `//` `%`      | arithmetic                                                           |
| `condition ? a : b`           | a or b                                                               |
| `a ?? b`                      | b when a is null                                                     |
| `a?.b`                        | b of a - empty instead of an error when a is empty                   |
| `x \| f arg`                  | pipe: the same as `f(x, arg)`, e.g. `timeValue \| math.format "0.0"` |
| `a[0]`, `a.size`              | an item of a list, the number of items                               |
| `x = 5; x * 2`                | variables and several statements - the last value counts             |
| `if ...; ...; else; ...; end` | conditions, in expressions too                                       |

## Line breaks

You can spread an expression over several lines; the large editor keeps your formatting. A line break ends a statement (like `;`), but inside brackets, after an operator or before a line starting with an operator or a pipe it just continues - so this works:

```
lastName
  | string.upcase
```

## The editor

Every expression input has completion (**Ctrl+Space**) and checks names while you type. The expand button opens a large editor with all names and the value for a bib you enter; **Ctrl+Enter** applies it.
