# gizlang/expr

a lambda as a value. Where a parameter's type is `Expr<Row, T>`, a lambda literal `(r: Row) => ...` passed to it becomes an expression tree that a query engine reads and plans, not a closure that it calls. Its body may read the row's fields, write constants, and use `+ - * / %`, comparisons, `&& || !`, `??`, `? :`, the casts `i64()` and `f64()`, and the known pure calls of the language reference. A part that does not read the row (a captured value, an outer variable's field) is a slot: it is computed when the call runs, so a plan of the tree can be kept. Anything else is E_EXPR at the lambda.

```gizlang
import * as Expr from "gizlang/expr";
```

## Types

### `Constant`

```gizlang
type Constant = { kind: string; int: i64; real: f64; flag: bool; text: string; }
```

A constant's value: KIND is "null", "int", "real", "bool" or "text", and the field of that kind holds it.

- `kind`: `string`
- `int`: `i64`
- `real`: `f64`
- `flag`: `bool`
- `text`: `string`

### `Node`

```gizlang
type Node = { op: string; kids: Vec<Node>; field: i64; name: string; constant: Constant; }
```

A tree node. OP is "field" (FIELD indexes the row's fields in declaration order, NAME is the field), "constant"
(CONSTANT), "slot" (FIELD indexes Expr.slots), an operator (`+`, `<`, `&&`, `!`, `neg`, `??`, `?:`, `is null`), "cast"
(NAME is i64 or f64) or "call" (NAME is a known function; the receiver of a method is KIDS[0]).

- `op`: `string`
- `kids`: `Vec<gizlang_expr.Node>`
- `field`: `i64`
- `name`: `string`
- `constant`: `gizlang_expr.Constant`

### `Expr`

```gizlang
type Expr<Row, T> = { root: Node; slots: Vec<Constant>; at: (row: Row) => T; }
```

A lambda from a Row to a T as a tree: ROOT, the SLOTS its captured parts have in this call, and AT, the lambda
itself, which computes the same T of one row.

Opaque: create and use it through this module's functions.

### `Literal`

```gizlang
interface Literal { constant(self: Self): Constant; }
```

A type whose values a tree holds as constants: i64, f64, bool, string and their narrow types.

- `constant`

## Functions

### `column`

```gizlang
function column(name: string, index: i64): Node
```

The row's field NAME at its declaration index, supplied by lambda lowering.

Effects: fail, read, write, console, io, alloc.

### `constant`

```gizlang
function constant(c: Constant): Node
```

The constant C.

Effects: fail.

### `slot`

```gizlang
function slot(i: i64): Node
```

Slot I of the call.

Effects: fail, read, write, console, io, alloc.

### `apply`

```gizlang
function apply(op: string, kids: Vec<Node>): Node
```

Operator OP of KIDS.

Effects: fail, read, write, console, io, alloc.

### `cast`

```gizlang
function cast(name: string, x: Node): Node
```

The cast to NAME (i64 or f64) of X.

Effects: fail, read, write, console, io, alloc.

### `call`

```gizlang
function call(name: string, kids: Vec<Node>): Node
```

The known call NAME of KIDS (a method's receiver first).

Effects: fail, read, write, console, io, alloc.

### `named`

```gizlang
function named(name: string, x: Node): Node
```

The field NAME of a record the lambda makes (`{ total: sum(r.price) }`): op "as", X its value. A record is op "record",
its fields its kids.

Effects: fail, read, write, console, io, alloc.

### `count`

```gizlang
function count(): i64
```

The rows of the group.

### `sum`

```gizlang
function sum<T>(x: T): T
```

The sum of X over the group.

### `avg`

```gizlang
function avg<T extends Real>(x: T): f64
```

The mean of X over the group.

### `min`

```gizlang
function min<T>(x: T): T
```

The least X of the group.

### `max`

```gizlang
function max<T>(x: T): T
```

The greatest X of the group.

### `nothing`

```gizlang
function nothing(): Constant
```

The null constant.

Effects: fail, read, write, console, io, alloc.

### `slotted`

```gizlang
function slotted<V extends Literal>(v: V): Constant
```

V as a constant: a literal of the lambda, or a slot's value.

### `made`

```gizlang
function made<Row, T>(root: Node, slots: Vec<Constant>, at: (row: Row) => T): Expr<Row, T>
```

The tree ROOT with SLOTS and the lambda AT: what a lambda passed as an Expr becomes. Field indices are bound by
the compiler from the checked row type.

## Methods

### `i64.constant`

```gizlang
function i64.constant(self: i64): Constant
```

X as a constant.

### `f64.constant`

```gizlang
function f64.constant(self: f64): Constant
```

X as a constant.

### `bool.constant`

```gizlang
function bool.constant(self: bool): Constant
```

X as a constant.

### `string.constant`

```gizlang
function string.constant(self: string): Constant
```

X as a constant.

### `Node.text`

```gizlang
function Node.text(self: Node): string
```

The tree as one line of text, as a query plan shows it: `(r.price * 2.0) > $0`.

Effects: fail, alloc.

