nupp.types

affinecomptime function#

local affine: @comptime function(representation: type): type
& @comptime function(representation: type, const terminal: function): type

An affine resource over representation: used at most once, and never copied.

With a terminal, that const function is the operation consuming the resource, the way close consumes a file. Without one the resource is transfer-only, so ownership may move but nothing ends it.

Arguments

Returns

Raises

argumentscomptime function#

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

Returns

arraycomptime function#

local array: @comptime function(element: type): type

The Lua array {element}, with integer keys and no fixed length.

Arguments

Returns

borrowedcomptime function#

local borrowed: @comptime function(inner: type): type

A borrow of inner, valid for the region that borrows it and not stored.

Arguments

Returns

carraycomptime function#

local carray: @comptime function(element: type, count: integer?): type

A C array of element, sized when count is given and unsized when it is not.

Arguments

Returns

Raises

constofcomptime function#

local constof: @comptime function(inner: type): type

inner behind a const capability, which permits reads and refuses writes.

Arguments

Returns

constructioncomptime function#

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

Returns

Raises

describecomptime function#

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?
}

Every fact about one handle at once, as a record whose members are populated according to its kind.

Reach for it when a generator needs several facts about the same handle, or a fact no single accessor exposes, such as a pack's tail or a C array's count. A member that does not apply to the handle's kind is nil.

Arguments

Returns

elementscomptime function#

local elements: @comptime function(value: type | typepack): {type}

The fixed elements of a composite type, or a pack's fixed head.

Arguments

Returns

errorcomptime function#

local error: @comptime function(message: string): never

Rejects this type application deliberately, with an authored message.

Distinct from an evaluator crash or a timeout: the message is reported at the application, with a bounded comptime call trace. It returns never, so a generator may call it in a branch that has no type to return.

Arguments

Returns

fieldscomptime function#

local fields: @comptime function(value: type): {{
    @readonly name: string,
    @readonly read: type?,
    @readonly write: type?
}}

The public fields of a shape or of a nominal record, interface, or struct.

A nominal keeps its declaration identity: reading its fields does not expand it into a structural type. Each descriptor carries a name and whichever of read and write the field has. describe(T).fields reports the same descriptors.

Arguments

Returns

Raises

formatArgumentscomptime function#

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

Returns

function_comptime function#

local function_: @comptime function(parameters: typepack, results: typepack): type

A function type from its parameter and result packs. Spelled with a trailing underscore because function is a keyword.

Arguments

Returns

indexercomptime function#

local indexer: @comptime function(
    readKey: type?,
    readValue: type?,
    writeKey: type?,
    writeValue: type?
): type

A type indexed by computed keys rather than by named fields.

Each capability is a key/value pair: supply both halves or neither. At least one capability is required, and a read-only or write-only indexer is the point of taking them separately. map is the shorthand for the common case where both sides agree.

Arguments

Returns

Raises

intersectioncomptime function#

local intersection: @comptime function(members: {type}): type

The intersection of its members, as a set, flattened and deduplicated the way union is. An intersection of function types is an overload set.

Arguments

Returns

kindcomptime function#

local kind: @comptime function(value: type | typepack): string

What a handle is, as a string, which is the usual way to branch on one.

The answer is the handle's own kind, not the builder that made it: map returns "indexer", optional returns "union", pointer returns "ptr", and constof returns "const". A nominal declaration returns "reference", and describe(T).declarationKind says which category it declares.

Arguments

Returns

lengthcomptime function#

local length: @comptime function(base: type, min: integer, max: integer): type

base narrowed to the byte lengths from min through max, both included.

Bytes, matching Nupp's own string length: not code points, not graphemes. An embedded NUL counts like any other byte. The base is string or a constrained alias of it.

Arguments

Returns

Raises

literalcomptime function#

local literal: @comptime function(value: string | boolean | integer): type

The singleton type inhabited by a value.

A number must be an exact integer, since a literal type names a value the checker compares for equality.

Arguments

Returns

Raises

mapcomptime function#

local map: @comptime function(readKey: type, readValue: type, writeKey: type?, writeValue: type?): type

An indexer whose write side mirrors its read side unless stated otherwise.

Equivalent to indexer(readKey, readValue, writeKey or readKey, writeValue or readValue), and it returns a handle of kind "indexer".

Arguments

Returns

nonExhaustivecomptime function#

local nonExhaustive: @comptime function(): type

The member that keeps a union open, so a switch over it stays inexhaustive.

No name resolves to this type, so calling for it is the only way to place it in a union. That is what makes a non-exhaustive union a written decision rather than an inferred one. It may be written directly in a type as well as inside a generator.

Returns

Raises

optionalcomptime function#

local optional: @comptime function(inner: type): type

inner | nil.

Built as a union, so it is idempotent: optional(optional(T)) and optional(T) are one handle.

Arguments

Returns

packcomptime function#

local pack: @comptime function(head: {type}, tail: type?, modes: {string}?): typepack

A type pack: a fixed head of slots, then an optional tail standing for however many values remain.

modes align with the head one for one and default to "plain"; the others are "affine", "borrowed", "exclusive", and "pinned".

Arguments

Returns

Raises

parameterscomptime function#

local parameters: @comptime function(callable: type): typepack

The parameter pack of a function type.

Arguments

Returns

Raises

pinnedcomptime function#

local pinned: @comptime function(inner: type): type

inner pinned to its address, so the collector may not move it.

Arguments

Returns

pointercomptime function#

local pointer: @comptime function(inner: type): type

A pointer to inner.

Arguments

Returns

rangecomptime function#

local range: @comptime function(base: type, min: integer, max: integer): type

base narrowed to the values from min through max, both included.

A constrained type is a subtype of its base: it goes wherever the base goes. Entering one is admission rather than subtyping, so a value the checker cannot prove is refused and nupp.admit is how the program says it meant it. A literal is decided here and needs nothing written.

The base is integer, int32, uint32, or a constrained alias of one, which narrows further by intersecting. Representation is unchanged: this converts nothing.

Arguments

Returns

Raises

readAtcomptime function#

local readAt: @comptime function(value: type, key: type): type

The type read at a key: the named field when the key is a string literal naming a readable one, and otherwise the indexer's read value.

Arguments

Returns

Raises

readKeyscomptime function#

local readKeys: @comptime function(value: type): {type}

Every key a type can be read at: one string literal per readable field, plus the indexer's read key when it has one.

Arguments

Returns

Raises

resultscomptime function#

local results: @comptime function(callable: type): typepack

The result pack of a function type.

Arguments

Returns

Raises

sameNominalcomptime function#

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

Returns

shapecomptime function#

local shape: @comptime function(fields: const{{
    @readonly name: string,
    @readonly read: type?,
    @readonly write: type?
}}, indexer: type?): type

A structural type with named fields, and optionally an indexer for the keys the names do not cover.

Each descriptor needs a non-empty name unique within the shape, and at least one of read and write: a field with only read is readonly, one with only write is writeonly. Field order does not affect identity, so two shapes with the same fields are one handle however they were listed.

Arguments

Returns

Raises

tuplecomptime function#

local tuple: @comptime function(elements: {type}): type

A fixed-length positional type, one slot per element in the order given.

Arguments

Returns

unioncomptime function#

local union: @comptime function(members: {type}): type

The union of its members, as a set.

Nested unions are flattened, duplicates dropped, and the rest ordered canonically, so union{A, union{A, B}} and union{A, B} are one handle.

Arguments

Returns

writeAtcomptime function#

local writeAt: @comptime function(value: type, key: type): type

The type written at a key: the named field when the key is a string literal naming a writable one, and otherwise the indexer's write value.

Arguments

Returns

Raises

writeKeyscomptime function#

local writeKeys: @comptime function(value: type): {type}

Every key a type can be written at: one string literal per writable field, plus the indexer's write key when it has one.

Arguments

Returns

Raises

anycomptime type#

local any: @comptime type

The dynamic type; compatible with everything, checked at neither end.

booleancomptime type#

local boolean: @comptime type

true or false.

cdatacomptime type#

local cdata: @comptime type

Any cdata value.

cstringcomptime type#

local cstring: @comptime type

const char *.

floatcomptime type#

local float: @comptime type

An established binary32 Lua number; widens to number.

int16comptime type#

local int16: @comptime type

Signed physical storage; loads as int32.

int32comptime type#

local int32: @comptime type

An established signed 32-bit Lua integer.

int64comptime type#

local int64: @comptime type

A boxed 64-bit signed cdata integer, as LuaJIT's 1LL.

int8comptime type#

local int8: @comptime type

Signed physical storage; loads as int32.

integercomptime type#

local integer: @comptime type

A number known to be integral.

nevercomptime type#

local never: @comptime type

The bottom type; fits everything, nothing fits it.

nil_comptime type#

local nil_: @comptime type

The nil singleton, spelled nil_ because nil is a keyword.

numbercomptime type#

local number: @comptime type

A LuaJIT double.

stringcomptime type#

local string: @comptime type

A Lua string.

table_comptime type#

local table_: @comptime type

Any table shape, compatible with every table type in both directions, spelled table_ because table names the standard library namespace.

threadcomptime type#

local thread: @comptime type

A coroutine.

uint16comptime type#

local uint16: @comptime type

Unsigned physical storage; loads as uint32.

uint32comptime type#

local uint32: @comptime type

An established unsigned 32-bit Lua integer.

uint64comptime type#

local uint64: @comptime type

A boxed 64-bit unsigned cdata integer, as LuaJIT's 1ULL.

uint8comptime type#

local uint8: @comptime type

Unsigned physical storage; loads as uint32.

unknowncomptime type#

local unknown: @comptime type

The top type; everything fits it, it fits nothing else.

userdatacomptime type#

local userdata: @comptime type

Userdata.

voidptrcomptime type#

local voidptr: @comptime type

void *.