> ## Documentation Index
> Fetch the complete documentation index at: https://docs.penbox.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Operator reference

> Complete lookup of every penscript operator

A complete lookup of every penscript operator, organized by category. Each entry shows the operator name, what it does, and a minimal example. For full documentation and detailed examples, follow the link to the dedicated page.

## Logic & conditions

→ Full reference: [Logic & comparisons](/penscript/logic)

| Operator                    | Description                            | Example                                                                |
| --------------------------- | -------------------------------------- | ---------------------------------------------------------------------- |
| `:if` / `:then` / `:else`   | Conditional branching                  | `{ ":if": "{active}", ":then": "Yes", ":else": "No" }`                 |
| `:case` / `:when` / `:else` | Switch-style matching                  | `{ ":case": "{status}", ":when": [["a", "Alpha"]], ":else": "Other" }` |
| `:cmp`                      | Comparison with thresholds             | `{ ":cmp": "{x}", ":gt": 0, ":lt": 100 }`                              |
| `:eq`                       | Equality test (all values equal)       | `{ ":eq": ["{a}", "{b}", 42] }`                                        |
| `:distinct`                 | Uniqueness test (all values different) | `{ ":distinct": [1, 2, 3] }`                                           |
| `:in`                       | Value exists in list                   | `{ ":in": ["{role}", ["admin", "manager"]] }`                          |
| `:nin`                      | Value does not exist in list           | `{ ":nin": ["{role}", ["banned"]] }`                                   |
| `:not`                      | Boolean negation                       | `{ ":not": "{flag}" }`                                                 |
| `:every`                    | All items satisfy condition            | `{ ":every": ["{arr}", { ":cmp": "@item", ":gt": 0 }] }`               |
| `:some`                     | At least one item satisfies condition  | `{ ":some": ["{arr}", { ":eq": ["@item", "x"] }] }`                    |

### Comparison Modifiers (used with `:cmp`)

| Modifier       | Meaning                  |
| -------------- | ------------------------ |
| `:eq`          | Equal to                 |
| `:neq`         | Not equal to             |
| `:gt`          | Greater than             |
| `:gte` / `:ge` | Greater than or equal to |
| `:lt`          | Less than                |
| `:lte` / `:le` | Less than or equal to    |

### Constants

| Operator     | Result      |
| ------------ | ----------- |
| `:true`      | `true`      |
| `:false`     | `false`     |
| `:null`      | `null`      |
| `:undefined` | `undefined` |

## Numbers

→ Full reference: [Numbers & calculations](/penscript/numbers)

| Operator         | Description              | Example                                              |
| ---------------- | ------------------------ | ---------------------------------------------------- |
| `:sum`           | Addition                 | `{ ":sum": [1, 2, 3] }` → `6`                        |
| `:substract`     | Subtraction              | `{ ":substract": [100, 30] }` → `70`                 |
| `:product`       | Multiplication           | `{ ":product": [5, 3] }` → `15`                      |
| `:multiply`      | Multiplication (alias)   | `{ ":multiply": [5, 3] }` → `15`                     |
| `:divide`        | Division                 | `{ ":divide": [100, 4] }` → `25`                     |
| `:power`         | Exponentiation           | `{ ":power": [2, 3] }` → `8`                         |
| `:max`           | Maximum value from array | `{ ":max": [3, 7, 9, 1] }` → `9`                     |
| `:min`           | Minimum value from array | `{ ":min": [3, 7, 9, 1] }` → `1`                     |
| `:to-fixed`      | Fixed decimal places     | `{ ":to-fixed": 123.456, ":digits": 1 }` → `"123.5"` |
| `:number`        | Coerce to number         | `{ ":number": "123" }` → `123`                       |
| `:format-number` | Number formatting        | With `:digits` for decimal precision                 |

## Arrays & collections

→ Full reference: [Loops & arrays](/penscript/arrays)

| Operator           | Description                | Example                                       |
| ------------------ | -------------------------- | --------------------------------------------- |
| `:array`           | Normalize to array         | `{ ":array": "x" }` → `["x"]`                 |
| `:array` + `:fill` | Generate array of length N | `{ ":array": 3, ":fill": "{@index}" }`        |
| `:map` / `:to`     | Transform each item        | `{ ":map": [arr], ":to": expr }`              |
| `:filter`          | Remove items by condition  | Wraps `:map` with `:if` returning `false`     |
| `:find`            | First matching item        | `{ ":find": [arr, condition] }`               |
| `:includes`        | Array contains value       | `{ ":includes": [arr, val] }`                 |
| `:intersects`      | Arrays share elements      | `{ ":intersects": [arr1, arr2] }`             |
| `:count`           | Count items                | `{ ":count": arr }` with `:where` / `:unless` |
| `:range-array`     | Generate integer range     | `{ ":range-array": [0, 5] }` → `[0,1,2,3,4]`  |
| `:flatten`         | Deep flatten nested arrays | `{ ":flatten": [[1,[2]]] }` → `[1,2]`         |
| `:increasing`      | Strictly increasing check  | `{ ":increasing": [1,2,3] }` → `true`         |

### Context Variables (available inside loops)

| Variable      | Description                             |
| ------------- | --------------------------------------- |
| `{@item}`     | The current item value                  |
| `{@index}`    | Current index (0, 1, 2...)              |
| `{@position}` | Current position (1, 2, 3...)           |
| `{@first}`    | `true` if the current item is the first |
| `{@last}`     | `true` if the current item is the last  |

## Dates & time

→ Full reference: [Dates & time](/penscript/dates)

| Operator       | Description              | Example                          |
| -------------- | ------------------------ | -------------------------------- |
| `:date`        | Create / parse a date    | `{ ":date": "now" }`             |
| `:format-date` | Format date with pattern | With `:pattern`: `"D/M/Y"`       |
| `:diff`        | Difference between dates | With `:comparator`: `"day"`      |
| `:sum` (dates) | Date arithmetic          | `{ ":sum": ["{$today}", "2d"] }` |

### Inline Pipes (dates)

| Pipe                | Description          | Example                                         |
| ------------------- | -------------------- | ----------------------------------------------- |
| `\| age`            | Age calculation      | `"{data.birthdate \| age}"` → `34`              |
| `\| formatDdMmYyyy` | Format as DD/MM/YYYY | `"{$today \| formatDdMmYyyy}"` → `"27/01/2026"` |

### Date Pattern Characters

| Character | Description             |
| --------- | ----------------------- |
| `Y`       | Year, 4 digits          |
| `y`       | Year, 2–4 digits        |
| `M`       | Month, 2 digits         |
| `m`       | Month, 1–2 digits       |
| `D`       | Day, 2 digits           |
| `d`       | Day, 1–2 digits         |
| `x`       | Any non-digit separator |

### Duration Units (for date arithmetic)

| Unit  | Example         |
| ----- | --------------- |
| Days  | `"2d"`, `"30d"` |
| Hours | `"72h"`         |
| Years | `"2y"`          |

Raw numbers = milliseconds. Numeric strings = seconds.

## Dynamic evaluation

→ Full reference: [Dynamic evaluation & scope](/penscript/dynamic_evaluation)

| Operator          | Description                  | Example                                   |
| ----------------- | ---------------------------- | ----------------------------------------- |
| `:define` / `:in` | Local variable scope         | `{ ":define": [{"x": 1}], ":in": "{x}" }` |
| `:with`           | Inline local bindings        | `{ ":with": [{"x": 1}, "{x}"] }`          |
| `:raw`            | Capture without evaluating   | `{ ":raw": "{expr}" }`                    |
| `:eval`           | Evaluate captured expression | `{ ":eval": "{stored_expr}" }`            |
| `:using`          | Define named expressions     | Combined with `:eval`                     |
| `:pipe`           | Sequential transformation    | `{ ":pipe": [val, step1, step2] }`        |

## Internationalization

→ Full reference: [Internationalization](/penscript/internationalization)

| Operator | Description         | Example                                           |
| -------- | ------------------- | ------------------------------------------------- |
| `:i18n`  | Locale-based string | `{ ":i18n": { "fr": "Bonjour", "en": "Hello" } }` |

## System variables

| Variable   | Description      |
| ---------- | ---------------- |
| `{$today}` | The current date |

***

## Related

<CardGroup cols={2}>
  <Card title="What is penscript" icon="book" href="/penscript/introduction">
    Introduction to penscript
  </Card>

  <Card title="How penscript works" icon="gears" href="/penscript/how_it_works">
    Expression modes and composition
  </Card>
</CardGroup>