# Declarations and functions

> Type-first declarations, functions, the access modes wr and out that are repeated at the call, several results, variadic parameters and function types.

## Types go first

Declarations put the type first: `type name`. That holds for variables, fields, parameters and functions. Modifiers go in front of the type, never on the name: `*u8 p`, `[]f32 s`, `[4]f32 v`. A function is `returnType name(params) { }`; the return type is always written, and a function that returns nothing returns `nul`.

```lane
u32 fib(u32 n) { if n < 2 { ret n; } ret fib(n - 1) + fib(n - 2); }
```

Verified: part of a program that builds and runs. For the whole program, exit code 6765. No stdout.

One file is one module. Declarations may appear in any order and there are no headers or forward declarations. A program starts at `main` in its root file, declared `nul main()` or `i32 main()`; an `i32` result is the process exit code.

A variable declared without a value is zero: integers 0, `bool` false, pointers `nil`, slices empty, arrays all zero. `name := expr;` declares a variable whose type comes from the expression, which must have one.

```lane
        u64 n = 0;
        v := x;
        for v != 0 {
```

The example is a syntax example; `v` takes the type of `x`. The inferred form `a := 1;` is refused, because a bare literal has no type. See [Types and literals](/docs/types.md).

## Access modes: wr and out

A parameter has one of three access modes. With none it is read-only: it cannot be assigned, an element or field of it cannot be assigned, and its address cannot be taken. `wr` makes it readable and writable. `out` makes it write-only: it must be assigned on every path before the function returns, and the caller may pass a variable that has no value yet.

The call repeats the mode, so a reader sees at the call site which arguments are written.

```lane
i32 run([]Instr code, wr Vm vm) {
```

```lane
i32 result = run(code, wr vm);
```

An `out` parameter:

```lane
nul set(out Dir d, u32 n) { d = Dir(n); }
```

The checker enforces the modes. A read-only parameter cannot be written:

```lane
nul f(u32 a) { a += 1; } nul main() { }
```

Verified: the compiler refuses this program (exit code 1). Compiler output:

```text
main.ln:1:16: error: parameter `a` is read-only
```

The mode written at the call must equal the parameter's:

```lane
rec A { u8 a; } 
rec B { u8 a; } 
nul g(wr A a) { } 
nul main() { A r; g(r); }
```

Verified: the compiler refuses this program (exit code 1). Compiler output:

```text
main.ln:4:21: error: parameter `a` of `g` takes `wr`, but the argument has no access mode
```

```lane
rec A { u8 a; } 
rec B { u8 a; } 
nul g(A a) { } 
nul main() { A r; g(wr r); }
```

Verified: the compiler refuses this program (exit code 1). Compiler output:

```text
main.ln:4:24: error: parameter `a` of `g` takes no access mode, but the argument has `wr`
```

An `out` parameter that can reach the end of the function unassigned is an error:

```lane
nul f(u8 x, out u32 y) { match x { 1 { y = 1; } else { } } } 
nul main() { }
```

Verified: the compiler refuses this program (exit code 1). Compiler output:

```text
main.ln:1:1: error: `out` parameter `y` is not assigned on every path to the end of `f`
```

Two arguments of one call may not name the same storage if one of them is written:

```lane
rec A { u8 a; } 
rec B { u8 a; } 
nul g(A a, wr u8 v) { } 
nul main() { A r; g(r, wr r.a); }
```

Verified: the compiler refuses this program (exit code 1). Compiler output:

```text
main.ln:4:28: error: `r` is named by two arguments of one call, and one of them is passed as `wr`
```

How an argument travels: a slice without a mode or with `wr` is passed as a pointer and a length, so `wr` only makes its elements writable. A record or an array is passed by its address in every mode and nothing is copied. Any other type is passed by value without a mode and by address with `wr` or `out`. Section 5.4 of the specification has every rule, including the aliasing check.

## Several results

A return type may be a list of two or more types. The function returns the values in registers, `ret a, b;` returns them, and a call with several targets receives them. A target `_` discards a value.

```lane
(f32, bool) find([]u64 keys, u64 key) {
    for i in 0..keys.len {
        if keys[i] == key { ret f32(i), true; }
    }
    ret 0.0, false;
}
```

```lane
    pos, ok := find(keys, 7);
    pos, slots[1] = find(keys, 8);
    _, ok = find(keys, 9);
    slots[0], _ = find(keys, 10);
    r, g, b := split(0x00ff8040);
```

## Variadic parameters

The last parameter may be written `..[]T name`: the function accepts any number of trailing arguments of type `T`. The compiler builds the array on the caller's stack and passes a slice, so the function's type is the same as one with a plain `[]T` parameter. `f(..xs)` passes an existing slice.

```lane
f32 sum_all(f32 first, ..[]f32 rest) {
```

```lane
    a = sum_all(1.0, 2.0, 3.0);
    b = sum_all(0.0, ..xs);
```

## Function types

A function type puts the return type first: `f32 fn(f32, f32)`. It is a code address and nothing else. There are no closures; a callback that needs state takes it as a parameter. An indirect call inside a `vec` loop is a compile error. A function type carries the access mode of each parameter.

```lane
nul each(wr []f32 v, f32 fn(f32) op) {
```

```lane
nul hooks(nul fn(wr []f32, out u32) visit, (f32, bool) fn(u64) probe) { }
```

## Attributes

An attribute is `@name` or `@name(args)` in front of a declaration or a parameter: `@inline`, `@hot`, `@align(64)`, `@range(lo, hi)`, `@fp(...)`, `@lib("kernel32")`. See [Per-ISA code, hints and floats](/docs/targets-hints.md).
