# `nupp.types`
Compiler-only type inspection and construction inside `comptime function`
declarations. Every member is an ordinary checked compile-time value; none has
a runtime representation.
## Functions
### `affine` _comptime function_
```nupp
local affine: comptime function(representation: type): type
& comptime function(representation: type, const terminal: function): type
```
#### Arguments
| Name | Type | Description |
| --- | --- | --- |
| `representation` | `type` | |
| `terminal` | `any` | |
#### Returns
| Type | Description |
| --- | --- |
| `type` | |
### `arguments` _comptime function_
```nupp
local arguments: comptime function(value: type): {type}
```
The type arguments a generic declaration was applied to.
Empty for a type that is not a generic application, so a caller may ask
without knowing which it has.
#### Arguments
| Name | Type | Description |
| --- | --- | --- |
| `value` | `type` | the applied type to inspect |
#### Returns
| Type | Description |
| --- | --- |
| `{type}` | one handle per argument, in declaration order |
### `array` _comptime function_
```nupp
local array: comptime function(element: type): type
```
#### Arguments
| Name | Type | Description |
| --- | --- | --- |
| `element` | `type` | |
#### Returns
| Type | Description |
| --- | --- |
| `type` | |
### `borrowed` _comptime function_
```nupp
local borrowed: comptime function(inner: type): type
```
#### Arguments
| Name | Type | Description |
| --- | --- | --- |
| `inner` | `type` | |
#### Returns
| Type | Description |
| --- | --- |
| `type` | |
### `carray` _comptime function_
```nupp
local carray: comptime function(element: type, count: integer?): type
```
#### Arguments
| Name | Type | Description |
| --- | --- | --- |
| `element` | `type` | |
| `count` | `integer?` | |
#### Returns
| Type | Description |
| --- | --- |
| `type` | |
### `constof` _comptime function_
```nupp
local constof: comptime function(inner: type): type
```
#### Arguments
| Name | Type | Description |
| --- | --- | --- |
| `inner` | `type` | |
#### Returns
| Type | Description |
| --- | --- |
| `type` | |
### `construction` _comptime function_
```nupp
local construction: comptime function(value: type): typepack
```
The parameters a record or struct is constructed with, as a pack whose
slots carry their names.
The one declared constructor's parameters, or the stored fields in
declaration order when the declaration has no constructor; a field with a
default, or one that admits nil, is an optional slot. Written as
`...: unpackof nupp.types.construction(E)`, the pack is a parameter list a
call binds by position or by name, the way it would for `new E(...)`.
#### Arguments
| Name | Type | Description |
| --- | --- | --- |
| `value` | `type` | the record or struct to inspect |
#### Returns
| Type | Description |
| --- | --- |
| `typepack` | its construction contract |
#### Raises
- when the declaration has several constructors, which is no single contract
### `describe` _comptime function_
```nupp
local describe: comptime function(value: type | typepack): {
readonly kind: string,
readonly sourceKind: string?,
--- Reports the nominal declaration category without expanding a reference.
readonly declarationKind: string?,
readonly name: string?,
readonly value: (string | boolean | integer)?,
readonly element: type?,
readonly members: {type}?,
readonly fields: {{
readonly name: string,
readonly read: type?,
readonly write: type?
}}?,
readonly indexer: type?,
readonly readKey: type?,
readonly readValue: type?,
readonly writeKey: type?,
readonly writeValue: type?,
readonly nominal: boolean?,
readonly head: {type}?,
readonly tail: type?,
readonly modes: {string}?,
readonly count: integer?,
readonly parameters: typepack?,
readonly results: typepack?
}
```
#### Arguments
| Name | Type | Description |
| --- | --- | --- |
| `value` | `type | typepack` | |
#### Returns
| Type | Description |
| --- | --- |
| `{
readonly kind: string,
readonly sourceKind: string?,
--- Reports the nominal declaration category without expanding a reference.
readonly declarationKind: string?,
readonly name: string?,
readonly value: (string | boolean | integer)?,
readonly element: type?,
readonly members: {type}?,
readonly fields: {{
readonly name: string,
readonly read: type?,
readonly write: type?
}}?,
readonly indexer: type?,
readonly readKey: type?,
readonly readValue: type?,
readonly writeKey: type?,
readonly writeValue: type?,
readonly nominal: boolean?,
readonly head: {type}?,
readonly tail: type?,
readonly modes: {string}?,
readonly count: integer?,
readonly parameters: typepack?,
readonly results: typepack?
}` | |
### `elements` _comptime function_
```nupp
local elements: comptime function(value: type | typepack): {type}
```
The fixed elements of a composite type, or a pack's fixed head.
#### Arguments
| Name | Type | Description |
| --- | --- | --- |
| `value` | `type | typepack` | the type or type pack to take apart |
#### Returns
| Type | Description |
| --- | --- |
| `{type}` | one handle per element, in declaration order |
### `error` _comptime function_
```nupp
local error: comptime function(message: string): never
```
#### Arguments
| Name | Type | Description |
| --- | --- | --- |
| `message` | `string` | |
#### Returns
| Type | Description |
| --- | --- |
| `never` | |
### `fields` _comptime function_
```nupp
local fields: comptime function(value: type): {{
readonly name: string,
readonly read: type?,
readonly write: type?
}}
```
#### Arguments
| Name | Type | Description |
| --- | --- | --- |
| `value` | `type` | |
#### Returns
| Type | Description |
| --- | --- |
| `{{
readonly name: string,
readonly read: type?,
readonly write: type?
}}` | |
### `formatArguments` _comptime function_
```nupp
local formatArguments: comptime function(format: type): typepack
```
Computes the arguments consumed by a literal Lua format string.
A broad string produces an open `any` pack. `%?` is reserved for
compiler-lowered formatting APIs.
#### Arguments
| Name | Type | Description |
| --- | --- | --- |
| `format` | `type` | the format-string type to inspect |
#### Returns
| Type | Description |
| --- | --- |
| `typepack` | the argument pack consumed by its directives |
### `function_` _comptime function_
```nupp
local function_: comptime function(parameters: typepack, results: typepack): type
```
#### Arguments
| Name | Type | Description |
| --- | --- | --- |
| `parameters` | `typepack` | |
| `results` | `typepack` | |
#### Returns
| Type | Description |
| --- | --- |
| `type` | |
### `indexer` _comptime function_
```nupp
local indexer: comptime function(readKey: type?, readValue: type?, writeKey: type?, writeValue: type?): type
```
#### Arguments
| Name | Type | Description |
| --- | --- | --- |
| `readKey` | `type?` | |
| `readValue` | `type?` | |
| `writeKey` | `type?` | |
| `writeValue` | `type?` | |
#### Returns
| Type | Description |
| --- | --- |
| `type` | |
### `intersection` _comptime function_
```nupp
local intersection: comptime function(members: {type}): type
```
#### Arguments
| Name | Type | Description |
| --- | --- | --- |
| `members` | `{type}` | |
#### Returns
| Type | Description |
| --- | --- |
| `type` | |
### `kind` _comptime function_
```nupp
local kind: comptime function(value: type | typepack): string
```
#### Arguments
| Name | Type | Description |
| --- | --- | --- |
| `value` | `type | typepack` | |
#### Returns
| Type | Description |
| --- | --- |
| `string` | |
### `literal` _comptime function_
```nupp
local literal: comptime function(value: string | boolean | integer): type
```
#### Arguments
| Name | Type | Description |
| --- | --- | --- |
| `value` | `string | boolean | integer` | |
#### Returns
| Type | Description |
| --- | --- |
| `type` | |
### `map` _comptime function_
```nupp
local map: comptime function(readKey: type, readValue: type, writeKey: type?, writeValue: type?): type
```
#### Arguments
| Name | Type | Description |
| --- | --- | --- |
| `readKey` | `type` | |
| `readValue` | `type` | |
| `writeKey` | `type?` | |
| `writeValue` | `type?` | |
#### Returns
| Type | Description |
| --- | --- |
| `type` | |
### `nonExhaustive` _comptime function_
```nupp
local nonExhaustive: comptime function(): type
```
#### Returns
| Type | Description |
| --- | --- |
| `type` | |
### `optional` _comptime function_
```nupp
local optional: comptime function(inner: type): type
```
#### Arguments
| Name | Type | Description |
| --- | --- | --- |
| `inner` | `type` | |
#### Returns
| Type | Description |
| --- | --- |
| `type` | |
### `pack` _comptime function_
```nupp
local pack: comptime function(head: {type}, tail: type?, modes: {string}?): typepack
```
#### Arguments
| Name | Type | Description |
| --- | --- | --- |
| `head` | `{type}` | |
| `tail` | `type?` | |
| `modes` | `{string}?` | |
#### Returns
| Type | Description |
| --- | --- |
| `typepack` | |
### `parameters` _comptime function_
```nupp
local parameters: comptime function(callable: type): typepack
```
#### Arguments
| Name | Type | Description |
| --- | --- | --- |
| `callable` | `type` | |
#### Returns
| Type | Description |
| --- | --- |
| `typepack` | |
### `pinned` _comptime function_
```nupp
local pinned: comptime function(inner: type): type
```
#### Arguments
| Name | Type | Description |
| --- | --- | --- |
| `inner` | `type` | |
#### Returns
| Type | Description |
| --- | --- |
| `type` | |
### `pointer` _comptime function_
```nupp
local pointer: comptime function(inner: type): type
```
#### Arguments
| Name | Type | Description |
| --- | --- | --- |
| `inner` | `type` | |
#### Returns
| Type | Description |
| --- | --- |
| `type` | |
### `readAt` _comptime function_
```nupp
local readAt: comptime function(value: type, key: type): type
```
#### Arguments
| Name | Type | Description |
| --- | --- | --- |
| `value` | `type` | |
| `key` | `type` | |
#### Returns
| Type | Description |
| --- | --- |
| `type` | |
### `readKeys` _comptime function_
```nupp
local readKeys: comptime function(value: type): {type}
```
#### Arguments
| Name | Type | Description |
| --- | --- | --- |
| `value` | `type` | |
#### Returns
| Type | Description |
| --- | --- |
| `{type}` | |
### `results` _comptime function_
```nupp
local results: comptime function(callable: type): typepack
```
#### Arguments
| Name | Type | Description |
| --- | --- | --- |
| `callable` | `type` | |
#### Returns
| Type | Description |
| --- | --- |
| `typepack` | |
### `sameNominal` _comptime function_
```nupp
local sameNominal: comptime function(left: type, right: type): boolean
```
Whether two types name the same nominal declaration, ignoring its arguments.
Aliases and ownership wrappers are transparent. Structural types and two
different nominal declarations answer false even when their shapes match.
#### Arguments
| Name | Type | Description |
| --- | --- | --- |
| `left` | `type` | |
| `right` | `type` | |
#### Returns
| Type | Description |
| --- | --- |
| `boolean` | |
### `shape` _comptime function_
```nupp
local shape: comptime function(fields: const{{
readonly name: string,
readonly read: type?,
readonly write: type?
}}, indexer: type?): type
```
#### Arguments
| Name | Type | Description |
| --- | --- | --- |
| `fields` | `const{{
readonly name: string,
readonly read: type?,
readonly write: type?
}}` | |
| `indexer` | `type?` | |
#### Returns
| Type | Description |
| --- | --- |
| `type` | |
### `tuple` _comptime function_
```nupp
local tuple: comptime function(elements: {type}): type
```
#### Arguments
| Name | Type | Description |
| --- | --- | --- |
| `elements` | `{type}` | |
#### Returns
| Type | Description |
| --- | --- |
| `type` | |
### `union` _comptime function_
```nupp
local union: comptime function(members: {type}): type
```
#### Arguments
| Name | Type | Description |
| --- | --- | --- |
| `members` | `{type}` | |
#### Returns
| Type | Description |
| --- | --- |
| `type` | |
### `writeAt` _comptime function_
```nupp
local writeAt: comptime function(value: type, key: type): type
```
#### Arguments
| Name | Type | Description |
| --- | --- | --- |
| `value` | `type` | |
| `key` | `type` | |
#### Returns
| Type | Description |
| --- | --- |
| `type` | |
### `writeKeys` _comptime function_
```nupp
local writeKeys: comptime function(value: type): {type}
```
#### Arguments
| Name | Type | Description |
| --- | --- | --- |
| `value` | `type` | |
#### Returns
| Type | Description |
| --- | --- |
| `{type}` | |
## Values
### `any` _comptime type_
```nupp
local any: comptime type
```
### `boolean` _comptime type_
```nupp
local boolean: comptime type
```
### `cdata` _comptime type_
```nupp
local cdata: comptime type
```
### `cstring` _comptime type_
```nupp
local cstring: comptime type
```
### `float` _comptime type_
```nupp
local float: comptime type
```
### `int16` _comptime type_
```nupp
local int16: comptime type
```
### `int32` _comptime type_
```nupp
local int32: comptime type
```
### `int64` _comptime type_
```nupp
local int64: comptime type
```
### `int8` _comptime type_
```nupp
local int8: comptime type
```
### `integer` _comptime type_
```nupp
local integer: comptime type
```
### `never` _comptime type_
```nupp
local never: comptime type
```
### `nil_` _comptime type_
```nupp
local nil_: comptime type
```
### `number` _comptime type_
```nupp
local number: comptime type
```
### `string` _comptime type_
```nupp
local string: comptime type
```
### `table_` _comptime type_
```nupp
local table_: comptime type
```
### `thread` _comptime type_
```nupp
local thread: comptime type
```
### `uint16` _comptime type_
```nupp
local uint16: comptime type
```
### `uint32` _comptime type_
```nupp
local uint32: comptime type
```
### `uint64` _comptime type_
```nupp
local uint64: comptime type
```
### `uint8` _comptime type_
```nupp
local uint8: comptime type
```
### `unknown` _comptime type_
```nupp
local unknown: comptime type
```
### `userdata` _comptime type_
```nupp
local userdata: comptime type
```
### `voidptr` _comptime type_
```nupp
local voidptr: comptime type
```