# Modules and the standard library

> One file is one module. use, pub, ext and @lib, and what io, fmt, mem, os and bufio contain.

## Modules

One file is one module. `use name;` imports the module in `name.ln` next to the importing file, or else the standard module of that name; its `pub` functions are called as `name.function(...)`. `pub` exports a declaration: a function, a constant, a record or an enum, reached from another module as `module.NAME` or `module.Type`, also in the type of a field or a parameter. A name that is not `pub` is refused, and a module's own errors are reported in that module.

A module with some public and some private declarations:

```lane
pub CAP :: 8;
HIDDEN :: 3;
pub enum Open { a }
enum Closed { a }
pub rec Pub { u8 a; }
rec Priv { u8 a; }
```

Verified: one module of a multi-module program.

Using a private name from another module is an error:

```lane
use limits; 
nul main() { limits.Priv p; }
```

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

```text
main.ln:2:14: error: `limits.Priv` is not `pub`
```

The module path and package layout are not decided yet.

## C imports and exports

`ext` with `;` imports a C-ABI symbol and `ext` with a body exports one. `@lib` names the library. A slice cannot cross the C ABI (pass a pointer and a length), neither can an array (pass a pointer), nor a record. An `ext` function takes no access modes; it takes pointers.

```lane
@lib("kernel32") ext *nul VirtualAlloc(*nul address, usz size, u32 kind, u32 protect);
@lib("kernel32") ext i32 VirtualFree(*nul address, usz size, u32 kind);
```

From the standard library module `mem`. It is written in Lane.

```lane
rec A { u32 x; } 
@lib("x") ext nul f(A a); 
nul main() { }
```

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

```text
main.ln:2:11: error: a record cannot cross the C ABI; pass a pointer
```

## The standard library

The standard library is embedded in the compiler and written in Lane on `ext` imports of the host operating system's API (`kernel32` on Windows). A std module may `use` another. Only these functions are `pub`; paths and text are `[]u8` without a terminator.

| Module | Contents |
|---|---|
| `io` | `print`, `eprint` (standard error), `println`, `print_u64` |
| `fmt` | `dec(u64, wr [20]u8)`, `dec_signed(i64, wr [20]u8)`, `hex(u64, wr [16]u8)`: the digits as the tail of the buffer; `hex` is lowercase without leading zeros |
| `mem` | `rec Arena`, `arena_init`, `alloc`, `reset`, `release`, `copy`, `eq`, `fill` |
| `os` | `exit`, `arg_count`, `arg`, `read_file`, `write_file`, `file_size`, `ticks`, `ticks_per_second` |
| `bufio` | `rec Writer`, `stdout_writer`, `stderr_writer`, `flush`, `write` |

### io

```lane
pub nul print([]u8 s) {
```

From the standard library module `io`. It is written in Lane.

```lane
pub nul println([]u8 s) {
```

From the standard library module `io`. It is written in Lane.

### fmt

`fmt` formats into a buffer the caller owns and returns the digits as the tail of it.

```lane
pub []u8 dec(u64 v, wr [DEC_DIGITS]u8 buf) {
```

From the standard library module `fmt`. It is written in Lane.

```lane
pub []u8 hex(u64 v, wr [HEX_DIGITS]u8 buf) {
```

From the standard library module `fmt`. It is written in Lane.

### mem

An `Arena` is a block from `VirtualAlloc` handed out in order. `alloc` returns zeroed memory aligned as asked (a power of two) or an empty slice when it does not fit, and `reset` zeroes what was used. `copy` takes `min(dst.len, src.len)` bytes and handles overlap. See [Memory](/docs/memory.md).

```lane
pub bool arena_init(out Arena a, usz cap) {
```

From the standard library module `mem`. It is written in Lane.

```lane
pub nul copy(wr []u8 dst, []u8 src) {
```

From the standard library module `mem`. It is written in Lane.

```lane
pub bool eq([]u8 a, []u8 b) {
```

From the standard library module `mem`. It is written in Lane.

```lane
pub nul fill(wr []u8 dst, u8 v) {
```

From the standard library module `mem`. It is written in Lane.

### os

`arg(0)` is the program name and `arg_count` counts it. Command-line arguments are ASCII: a character outside ASCII becomes the byte 0xff. Paths are ASCII, and a path with a byte above 0x7f or a zero byte is not usable. `read_file` stores the file in arena memory and sets its `out []u8` parameter; on any failure it returns false, sets the slice to empty and leaves the arena as it was. Only disk files are read.

```lane
pub nul exit(i32 code) {
```

From the standard library module `os`. It is written in Lane.

```lane
pub bool read_file([]u8 path, wr mem.Arena a, out []u8 data) {
```

From the standard library module `os`. It is written in Lane.

```lane
pub bool write_file([]u8 path, []u8 data) {
```

From the standard library module `os`. It is written in Lane.

```lane
pub u64 ticks() {
```

From the standard library module `os`. It is written in Lane.

### bufio

A `bufio.Writer` collects output in a buffer the caller owns, so that many small writes become few system calls. Nothing is written by itself at the end of the program: call `flush`.

```lane
pub rec Writer { bool to_error; *u8 buf; usz len; usz cap; }
```

From the standard library module `bufio`. It is written in Lane.

```lane
pub nul write(wr Writer w, []u8 s) {
```

From the standard library module `bufio`. It is written in Lane.

```lane
pub nul flush(wr Writer w) {
```

From the standard library module `bufio`. It is written in Lane.
