<a id="nupp"></a>
# `nupp`

`nupp` is an always available global table that declares the Nupp
standard library. It's available without a `require`.

```nupp
-- You can use nupp and nested modules without any `require` statements.
local text = nupp.codec.json.encode({ok = true})

nupp.log.info("wrote %d bytes", #text)
```

`nupp` and nested submodules within it are available using sub-property access
without the need to require anything. Submodules are loaded lazily on first
access.

See [Standard library](../../learn/runtime/data/standard-library/index.html) for what belongs here and what does not,
and [Modules](../../learn/language/modules/index.html) for how a declared module is reached.

## Submodules

| Module | Description |
| --- | --- |
| `nupp.bench` | Measuring Nupp code from inside an ordinary program. |
| `nupp.checksum` | Numeric checksums, for noticing that bytes got corrupted. |
| `nupp.cli` | Command-line arguments, from raw tokens up to a whole application. |
| `nupp.codec` | 4 modules |
| `nupp.compression` | Compressing and decompressing a stream of bytes. |
| `nupp.derive` | Generates checked members on a declaration while that declaration is checked. |
| `nupp.digest` | Cryptographic hashes: SHA-256 and the rest. |
| `nupp.events` | Addressed, synchronous events whose payloads are ordinary declarations. |
| `nupp.gpu` | nupp.gpu manages resident compute buffers over the selected GPU provider. |
| `nupp.host` | nupp.host asks whatever is running the program for something and waits for the answer: the page's JavaScript in a... |
| `nupp.hotreload` | Cooperative development hot reload, installed by nupp run --watch. |
| `nupp.io` | nupp.io is bytes: storage for them, and the readers and writers that move them. |
| `nupp.log` | nupp.log is leveled logging whose disabled path is the one it is designed around. |
| `nupp.mac` | Keyed hashes, for bytes somebody could have tampered with. |
| `nupp.math` | nupp.math adds the scalar, fixed-width and two-dimensional operations missing from Lua's built-in math table. |
| `nupp.mem` | C storage, and the checked views that make a raw pointer safe to index. |
| `nupp.peg` | nupp.peg compiles textual parsing-expression grammars into reusable typed matchers. |
| `nupp.profile` | Two profiling channels: one for where the time went, one for whether it went there compiled. |
| `nupp.random` | nupp.random provides unpredictable bytes and reproducible sequences. |
| `nupp.reflect` | Semantic type reflection and reflection-driven field codecs. |
| `nupp.serde` | A binding selects how a value is read and constructed, separately from the codec that chooses its wire representation. |
| `nupp.simd` | Explicit SIMD support. |
| `nupp.spi` | Discover implementations, then choose with ordinary module initialization code. |
| `nupp.suspension` | Waiting without blocking the thread. |
| `nupp.system` | nupp.system reports four fixed ABI facts and estimates available parallelism. |
| `nupp.tasks` | Structured concurrency: a scope owns the tasks spawned into it. |
| `nupp.test` | Assertions, for Nupp's own test runner and for project suites. |
| `nupp.text` | Working with text a byte at a time. |
| `nupp.time` | nupp.time provides clocks and waits from the current host. |
| `nupp.types` | Compiler-only type inspection and construction inside @comptime function declarations. |
| `nupp.util` | Small types that belong to no larger facility. |
| `nupp.workers` | Runs functions in parallel, on real threads. |

## Types

<a id="nupp.Affine"></a>
### `Affine` _interface_

```nupp
interface nupp.Affine<const cleanup: function>
```

Declares a consuming cleanup for an affine owner.

#### Type parameters

| Name | Description |
| --- | --- |
| `cleanup` |  |

<a id="nupp.AliasError"></a>
### `AliasError` _record_

```nupp
record nupp.AliasError ...
```

A failed operation on a managed alias.

#### Members

| Name | Kind | Description |
| --- | --- | --- |
| [`code`](#nupp.AliasError.code) | field |  |
| [`message`](#nupp.AliasError.message) | field |  |

<a id="nupp.AliasError.code"></a>
#### `code` _field_

```nupp
code: string
```

<a id="nupp.AliasError.message"></a>
#### `message` _field_

```nupp
message: string
```

<a id="nupp.Closeable"></a>
### `Closeable` _interface_

```nupp
interface nupp.Closeable is nupp.Affine<self.close> ...
```

A resource with a deterministic, consuming close operation.

Declaring `is nupp.Closeable` makes construction and bare type annotations carry the
close obligation automatically. A resource that publishes pending work declares
`flush` on its own contract; closing is the lifecycle common to all resources.

#### Members

| Name | Kind | Description |
| --- | --- | --- |
| [`close`](#nupp.Closeable.close) | method |  |

<a id="nupp.Closeable.close"></a>
#### `close` _method_

```nupp
close: function(takes self: nupp.Closeable): nil
```

##### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `takes self` | `nupp.Closeable` |  |

##### Returns

| Type | Description |
| --- | --- |
| `nil` |  |

<a id="nupp.Copyable"></a>
### `Copyable` _interface_

```nupp
interface nupp.Copyable
```

A value that carries neither an ownership obligation nor a scoped borrow.
Use this bound when a generic cache must return the same value repeatedly.

<a id="nupp.Debug"></a>
### `Debug` _interface_

```nupp
interface nupp.Debug ...
```

Values with deterministic compiler-generated debug formatting.

#### Members

| Name | Kind | Description |
| --- | --- | --- |
| [`debug`](#nupp.Debug.debug) | method |  |

<a id="nupp.Debug.debug"></a>
#### `debug` _method_

```nupp
debug: function(self): string
```

##### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `?` | `self` |  |

##### Returns

| Type | Description |
| --- | --- |
| `string` |  |

<a id="nupp.ManagedGroup"></a>
### `ManagedGroup` _interface_

```nupp
interface nupp.ManagedGroup is nupp.Closeable ...
```

A runtime-sized heterogeneous owner group.

`managedGroup` adopts independently managed cells and closes every remaining
resource in reverse adoption order. It is ordinary library code over aliases;
the compiler does not give the group special ownership privileges.

#### Members

| Name | Kind | Description |
| --- | --- | --- |
| [`flush`](#nupp.ManagedGroup.flush) | method | Cells publish no pending data of their own. |
| [`adopt`](#nupp.ManagedGroup.adopt) | method | Moves a managed cell into the group and returns its checked non-owning alias. |
| [`remove`](#nupp.ManagedGroup.remove) | method | Removes an adopted alias and restores its exact original owner. |

<a id="nupp.ManagedGroup.flush"></a>
#### `flush` _method_

```nupp
flush: function(exclusive self: nupp.ManagedGroup): nil
```

Cells publish no pending data of their own. Their payloads decide what close
publishes.

##### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `exclusive self` | `nupp.ManagedGroup` |  |

##### Returns

| Type | Description |
| --- | --- |
| `nil` |  |

<a id="nupp.ManagedGroup.adopt"></a>
#### `adopt` _method_

```nupp
adopt: function<T>(exclusive self: nupp.ManagedGroup, takes cell: managed(T)): alias(T)
```

Moves a managed cell into the group and returns its checked non-owning alias.

##### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `exclusive self` | `nupp.ManagedGroup` |  |
| `takes cell` | `managed(T)` |  |

##### Returns

| Type | Description |
| --- | --- |
| `alias(T)` |  |

<a id="nupp.ManagedGroup.remove"></a>
#### `remove` _method_

```nupp
remove: function<T>(exclusive self: nupp.ManagedGroup, handle: alias(T)): T
```

Removes an adopted alias and restores its exact original owner.

##### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `exclusive self` | `nupp.ManagedGroup` |  |
| `handle` | `alias(T)` |  |

##### Returns

| Type | Description |
| --- | --- |
| `T` |  |