# L4 Language Glossary

Complete reference index of all L4 language features. Links point to the consolidated reference pages which contain detailed documentation.

---

## Keywords

Keywords are reserved words that form the structure of L4 programs.

### Function Keywords

| Keyword                | Purpose                                                              | Reference                          |
| ---------------------- | -------------------------------------------------------------------- | ---------------------------------- |
| **AKA**                | Provides alternate names (aliases)                                   | [AKA](/l4/reference/functions/AKA.md)            |
| **DECIDE**             | Defines a decision function                                          | [DECIDE](/l4/reference/functions/DECIDE.md)      |
| **FUNCTION**           | Declares a function type                                             | [TYPE-KEYWORDS](/l4/reference/types/keywords.md) |
| **GIVEN**              | Introduces function parameters                                       | [GIVEN](/l4/reference/functions/GIVEN.md)        |
| **GIVETH** / **GIVES** | Specifies function return type                                       | [GIVETH](/l4/reference/functions/GIVETH.md)      |
| **IN**                 | Used with LET for scoped bindings                                    | [LET](/l4/reference/functions/LET.md)            |
| **LET**                | Introduces a local binding                                           | [LET](/l4/reference/functions/LET.md)            |
| **MEANS**              | Defines the body of a function, decision, or computed field (method) | [MEANS](/l4/reference/functions/MEANS.md)        |
| **WHERE**              | Introduces local declarations                                        | [WHERE](/l4/reference/functions/WHERE.md)        |
| **YIELD**              | Creates anonymous functions (lambdas)                                | [YIELD](/l4/reference/functions/YIELD.md)        |

### Control Flow Keywords

| Keyword       | Purpose                              | Reference                              |
| ------------- | ------------------------------------ | -------------------------------------- |
| **BRANCH**    | Alternative pattern matching keyword | [CONTROL-FLOW](/l4/reference/control-flow.md) |
| **CONSIDER**  | Pattern matching on values           | [CONSIDER](/l4/reference/control-flow/CONSIDER.md)   |
| **ELSE**      | Alternative branch of IF             | [CONTROL-FLOW](/l4/reference/control-flow.md) |
| **IF**        | Conditional expression               | [IF](/l4/reference/control-flow/IF.md)               |
| **THEN**      | Consequent branch of IF              | [CONTROL-FLOW](/l4/reference/control-flow.md) |
| **OTHERWISE** | Default case in CONSIDER             | [CONTROL-FLOW](/l4/reference/control-flow.md) |
| **WHEN**      | Introduces a pattern match case      | [CONSIDER](/l4/reference/control-flow/CONSIDER.md)   |

### Logical Keywords

| Keyword           | Purpose                    | Reference                       |
| ----------------- | -------------------------- | ------------------------------- |
| **AND** / **...** | Logical conjunction        | [AND](/l4/reference/operators/AND.md)         |
| **IMPLIES**       | Logical implication        | [IMPLIES](/l4/reference/operators/IMPLIES.md) |
| **NOT**           | Logical negation           | [NOT](/l4/reference/operators/NOT.md)         |
| **OR** / **..**   | Logical disjunction        | [OR](/l4/reference/operators/OR.md)           |
| **UNLESS**        | Exception clause (AND NOT) | [UNLESS](/l4/reference/operators/UNLESS.md)   |

### Comparison Keywords

| Keyword     | Purpose                     | Reference                                      |
| ----------- | --------------------------- | ---------------------------------------------- |
| **ABOVE**   | Synonym for GREATER THAN    | [COMPARISONS](/l4/reference/operators/comparisons.md) |
| **BELOW**   | Synonym for LESS THAN       | [COMPARISONS](/l4/reference/operators/comparisons.md) |
| **EQUALS**  | Equality test               | [COMPARISONS](/l4/reference/operators/comparisons.md) |
| **GREATER** | Greater than comparison     | [COMPARISONS](/l4/reference/operators/comparisons.md) |
| **LESS**    | Less than comparison        | [COMPARISONS](/l4/reference/operators/comparisons.md) |
| **THAN**    | Comparison conjunction word | [COMPARISONS](/l4/reference/operators/comparisons.md) |
| **LEAST**   | Used in "AT LEAST" (≥)      | [COMPARISONS](/l4/reference/operators/comparisons.md) |
| **MOST**    | Used in "AT MOST" (≤)       | [COMPARISONS](/l4/reference/operators/comparisons.md) |

### Type Keywords

| Keyword        | Purpose                                                                 | Reference                          |
| -------------- | ----------------------------------------------------------------------- | ---------------------------------- |
| **A** / **AN** | Type articles                                                           | [ARTICLES](/l4/reference/types/A-AN.md)          |
| **ASSUME**     | Declares a variable of assumed type                                     | [ASSUME](/l4/reference/types/ASSUME.md)          |
| **DECLARE**    | Defines a type                                                          | [DECLARE](/l4/reference/types/DECLARE.md)        |
| **IS**         | Type assertion or definition                                            | [TYPE-KEYWORDS](/l4/reference/types/keywords.md) |
| **HAS**        | Record field declaration (supports computed fields / methods via MEANS) | [TYPE-KEYWORDS](/l4/reference/types/keywords.md) |
| **LIST**       | List type or list literal                                               | [TYPE-KEYWORDS](/l4/reference/types/keywords.md) |
| **ONE OF**     | Used for enum types                                                     | [TYPE-KEYWORDS](/l4/reference/types/keywords.md) |
| **OF**         | Type application or constructor pattern                                 | [TYPE-KEYWORDS](/l4/reference/types/keywords.md) |
| **TYPE**       | The kind of types                                                       | [TYPE-KEYWORDS](/l4/reference/types/keywords.md) |
| **WITH**       | Record construction with named fields                                   | [TYPE-KEYWORDS](/l4/reference/types/keywords.md) |
| **FOR ALL**    | Universal quantifier for polymorphism                                   | [FOR ALL](/l4/reference/types/for-all.md)        |

### Regulative Keywords

For expressing legal obligations, permissions, and prohibitions.

| Keyword       | Purpose                               | Reference                          |
| ------------- | ------------------------------------- | ---------------------------------- |
| **PARTY**     | Declares a legal party                | [PARTY](/l4/reference/regulative/PARTY.md)       |
| **MUST**      | Obligation (deontic necessity)        | [MUST](/l4/reference/regulative/MUST.md)         |
| **MAY**       | Permission (deontic possibility)      | [MAY](/l4/reference/regulative/MAY.md)           |
| **SHANT**     | Prohibition                           | [SHANT](/l4/reference/regulative/SHANT.md)       |
| **DO**        | Optionality (deontic possibility)     | [REGULATIVE](/l4/reference/regulative.md) |
| **DOES**      | Action verb in directive              | [REGULATIVE](/l4/reference/regulative.md) |
| **EXACTLY**   | Exact value matching on action        | [REGULATIVE](/l4/reference/regulative.md) |
| **WITHIN**    | Temporal deadline (relative)          | [REGULATIVE](/l4/reference/regulative.md) |
| **HENCE**     | Consequence on fulfillment            | [REGULATIVE](/l4/reference/regulative.md) |
| **LEST**      | Consequence on breach                 | [REGULATIVE](/l4/reference/regulative.md) |
| **BREACH**    | Terminal violation state              | [REGULATIVE](/l4/reference/regulative.md) |
| **FULFILLED** | Terminal success state                | [REGULATIVE](/l4/reference/regulative.md) |
| **BECAUSE**   | Justification or reason for breach    | [BECAUSE](/l4/reference/regulative/BECAUSE.md)   |
| **PROVIDED**  | Guard condition on action             | [REGULATIVE](/l4/reference/regulative.md) |
| **AT**        | Temporal specification                | [REGULATIVE](/l4/reference/regulative.md) |
| **RAND**      | Parallel AND of obligations           | [REGULATIVE](/l4/reference/regulative.md) |
| **ROR**       | Parallel OR of obligations            | [REGULATIVE](/l4/reference/regulative.md) |
| **BEFORE**    | Temporal deadline (absolute, planned) | [REGULATIVE](/l4/reference/regulative.md) |

### Arithmetic Keywords

| Keyword     | Purpose                   | Reference                                    |
| ----------- | ------------------------- | -------------------------------------------- |
| **PLUS**    | Addition                  | [ARITHMETIC](/l4/reference/operators/arithmetic.md) |
| **MINUS**   | Subtraction               | [ARITHMETIC](/l4/reference/operators/arithmetic.md) |
| **TIMES**   | Multiplication            | [ARITHMETIC](/l4/reference/operators/arithmetic.md) |
| **DIVIDED** | Division (use with BY)    | [ARITHMETIC](/l4/reference/operators/arithmetic.md) |
| **BY**      | Division conjunction word | [ARITHMETIC](/l4/reference/operators/arithmetic.md) |
| **MODULO**  | Modulus (remainder)       | [ARITHMETIC](/l4/reference/operators/arithmetic.md) |

### Other Keywords

| Keyword         | Purpose                               | Reference                          |
| --------------- | ------------------------------------- | ---------------------------------- |
| **IMPORT**      | Imports definitions from another file | [IMPORT](/l4/reference/libraries/IMPORT.md)      |
| **TIMEZONE IS** | Sets document timezone (IANA name)    | [timezone](/l4/reference/libraries/timezone.md)  |
| **TO**          | Function type return separator        | [SYNTAX](/l4/reference/syntax.md)         |
| **OF**          | Positional argument / type syntax     | [TYPE-KEYWORDS](/l4/reference/types/keywords.md) |

---

## Types

L4's type system includes primitive types, algebraic types, and polymorphic types.

For complete documentation, see **[Types Reference](/l4/reference/types.md)**.

### Primitive Types

| Type         | Description                             |
| ------------ | --------------------------------------- |
| **NUMBER**   | Numeric values (integers and rationals) |
| **STRING**   | Text strings                            |
| **BOOLEAN**  | Truth values (TRUE, FALSE)              |
| **DATE**     | Calendar dates                          |
| **TIME**     | Wall-clock time-of-day (no timezone)    |
| **DATETIME** | Absolute point in time with timezone    |

### Polymorphic Types

| Type       | Description                               |
| ---------- | ----------------------------------------- |
| **LIST**   | Ordered collection of elements            |
| **MAYBE**  | Optional values (JUST x or NOTHING)       |
| **EITHER** | Choice between two values (LEFT or RIGHT) |

### Special Types

| Type         | Description       |
| ------------ | ----------------- |
| **TYPE**     | The kind of types |
| **FUNCTION** | Function types    |

---

## Operators

For complete documentation, see **[Operators Reference](/l4/reference/operators.md)**.

### Symbolic Operators

| Operator | Textual Form         | Description           |
| -------- | -------------------- | --------------------- |
| `*`      | TIMES                | Multiplication        |
| `+`      | PLUS                 | Addition              |
| `-`      | MINUS                | Subtraction           |
| `/`      | DIVIDED BY           | Division              |
| `>=`     | AT LEAST             | Greater than or equal |
| `<=`     | AT MOST              | Less than or equal    |
| `>`      | GREATER THAN / ABOVE | Greater than          |
| `<`      | LESS THAN / BELOW    | Less than             |
| `=`      | EQUALS               | Equality              |
| `&&`     | AND                  | Logical conjunction   |
| `\|\|`   | OR                   | Logical disjunction   |
| `=>`     | IMPLIES              | Logical implication   |

### List Operators

| Operator        | Description                 |
| --------------- | --------------------------- |
| **FOLLOWED BY** | List cons (prepend element) |
| **EMPTY**       | Empty list                  |

### String Operators

| Operator   | Description                  |
| ---------- | ---------------------------- |
| **CONCAT** | String concatenation         |
| **APPEND** | String concatenation (infix) |

### Temporal Operators

| Operator   | Description              |
| ---------- | ------------------------ |
| **AT**     | Point in time            |
| **WITHIN** | Time duration constraint |

---

## Syntax Patterns

Special syntax features and patterns in L4.

For complete documentation, see **[Syntax Reference](/l4/reference/syntax.md)**.

| Feature             | Description                                   |
| ------------------- | --------------------------------------------- |
| **Layout Rules**    | Indentation-based grouping                    |
| **Comments**        | `--` line comments and `{- -}` block comments |
| **Identifiers**     | Backtick-quoted identifiers                   |
| **Annotations**     | `@desc`, `@nlg`, `@ref`, `@export`            |
| **Directives**      | `#EVAL`, `#TRACE`, `#CHECK`, `#ASSERT`        |
| **Ditto**           | `^` copy from previous line                   |
| **Asyndetic**       | `...` (AND) and `..` (OR) implicit operators  |
| **Computed Fields** | Derived attributes / methods via MEANS in HAS |
| **Genitive**        | `'s` for record field access                  |
| **Section Markers** | `§` for document sections                     |

---

## Symbols

| Symbol | Name            | Purpose                    |
| ------ | --------------- | -------------------------- |
| `()`   | Parentheses     | Grouping, tuples           |
| `{}`   | Braces          | Block comments             |
| `[]`   | Square brackets | NLG inline annotations     |
| `<<>>` | Double angles   | Reference annotations      |
| `§`    | Section symbol  | Document sections          |
| `^`    | Caret           | Ditto (copy above)         |
| `,`    | Comma           | Separator                  |
| `;`    | Semicolon       | Statement separator        |
| `.`    | Dot             | Decimal point, punctuation |
| `...`  | Ellipsis        | Asyndetic AND              |
| `..`   | Double dot      | Asyndetic OR               |
| `:`    | Colon           | Type signature separator   |
| `%`    | Percent         | Percentage, NLG delimiter  |
| `'s`   | Genitive        | Possession/field access    |

---

## Literals

| Literal Type | Syntax                    | Example         |
| ------------ | ------------------------- | --------------- |
| **Integer**  | Digits                    | `42`, `-17`     |
| **Rational** | Digits with decimal point | `3.14`, `-0.5`  |
| **String**   | Double quotes             | `"hello world"` |
| **Boolean**  | TRUE or FALSE             | `TRUE`, `FALSE` |
| **List**     | LIST or FOLLOWED BY       | `LIST 1, 2, 3`  |

---

## Core Libraries

Libraries shipped with L4.

For complete documentation, see **[Libraries Reference](/l4/reference/libraries.md)**.

| Library           | Purpose                              |
| ----------------- | ------------------------------------ |
| **prelude**       | Standard functions (always imported) |
| **daydate**       | Date calculations and temporal logic |
| **time**          | Wall-clock time-of-day operations    |
| **datetime**      | Absolute points in time (with tz)    |
| **timezone**      | IANA timezone constants              |
| **actus**         | ACTUS financial contract standards   |
| **excel-date**    | Excel date compatibility             |
| **math**          | Mathematical functions               |
| **currency**      | ISO 4217 currency handling           |
| **legal-persons** | Legal entity types                   |
| **jurisdiction**  | Jurisdiction definitions             |
| **llm**           | LLM API integration                  |

### Built-in Functions

These are built into the compiler (not a library):

#### Type Coercion

| Function       | Purpose             |
| -------------- | ------------------- |
| **TOSTRING**   | Convert to STRING   |
| **TONUMBER**   | Convert to NUMBER   |
| **TODATE**     | Convert to DATE     |
| **TOTIME**     | Convert to TIME     |
| **TODATETIME** | Convert to DATETIME |
| **TRUNC**      | Truncate number     |

See [coercions documentation](/l4/reference/types/coercions.md) for details.

#### HTTP and JSON

| Function       | Purpose                      |
| -------------- | ---------------------------- |
| **FETCH**      | HTTP GET request             |
| **POST**       | HTTP POST request            |
| **ENV**        | Read environment variable    |
| **JSONENCODE** | Convert value to JSON string |
| **JSONDECODE** | Parse JSON string to value   |

See [HTTP and JSON documentation](/l4/reference/builtins/http-json.md) for details.

---

## Directives

Compiler directives for testing and evaluation.

| Directive    | Purpose                       |
| ------------ | ----------------------------- |
| `#EVAL`      | Evaluate and print expression |
| `#EVALTRACE` | Evaluate with execution trace |
| `#TRACE`     | Contract/state graph tracing  |
| `#CHECK`     | Type check expression         |
| `#ASSERT`    | Assert truth value            |

---

## Annotations

Metadata annotations for documentation and generation.

| Annotation | Purpose                          |
| ---------- | -------------------------------- |
| `@desc`    | Human-readable description       |
| `@nlg`     | Natural language generation hint |
| `@ref`     | Cross-reference to legal source  |
| `@ref-src` | Source reference                 |
| `@ref-map` | Reference mapping                |
| `@export`  | Mark for export                  |

---

## Built-in Constants

| Constant        | Type           | Description                                                   |
| --------------- | -------------- | ------------------------------------------------------------- |
| **TRUE**        | BOOLEAN        | Boolean true value                                            |
| **FALSE**       | BOOLEAN        | Boolean false value                                           |
| **NOTHING**     | MAYBE a        | Absence of value                                              |
| **JUST**        | a → MAYBE a    | Present value constructor                                     |
| **LEFT**        | a → EITHER a b | Left alternative                                              |
| **RIGHT**       | b → EITHER a b | Right alternative                                             |
| **EMPTY**       | LIST a         | Empty list                                                    |
| **TODAY**       | DATE           | Current date (requires `TIMEZONE IS`)                         |
| **NOW**         | DATETIME       | Current date and time (defaults to UTC without `TIMEZONE IS`) |
| **CURRENTTIME** | TIME           | Current local time (requires `TIMEZONE IS`)                   |
| **TIMEZONE**    | STRING         | Document timezone (requires `TIMEZONE IS`)                    |

---

## Navigation

- **[Reference Home](/l4/reference.md)** - Reference documentation overview
- **[Main Documentation](/l4/.md)** - Return to docs home
- **[Courses](/l4/courses.md)** - Learning paths
- **[Tutorials](/l4/tutorials.md)** - Task-oriented guides
- **[Concepts](/l4/concepts.md)** - Understanding L4's design
- **[Specifications](https://github.com/smucclaw/l4-ide/tree/main/specs)** - Technical specifications