Module: `nupp`

The always-available standard-library namespace.

nupp is a table the prelude declares, so its fields are in scope everywhere without a require; each implementation loads only if the checked program actually uses it. A binding called nupp shadows it deliberately, the way a binding called string would.

Its public namespaces are nupp.data (JSON, UTF-8, UUIDs, hashes and checksums), nupp.io (buffers, byte views, readers and writers), nupp.io.Path and nupp.io.URI (filesystem paths and resource identifiers), nupp.math (scalar helpers and two-dimensional vectors), nupp.peg (textual parsing-expression grammars compiled at either phase), and nupp.fieldcodec (reflection-driven keyed codecs).

The compiler-provided ownership operations also live under this global: nupp.drop, nupp.borrow, nupp.intoRaw, nupp.fromRaw, nupp.borrowFrom, and nupp.pin. The compiler implements them, so they type nothing like ordinary functions and are not values you can pass around. The old bare spellings remain aliases, but new code should use nupp.*.

This module's siblings are ordinary modules shipped with the compiler, reached with require and separate from the fields of the ambient global: nupp.bytes, nupp.profile, nupp.resources, nupp.zone, and nupp.compiler, which holds the self-hosted compiler implementation and is hidden from public API documentation by its @!internal namespace root.

Submodules

Module	Description
`nupp.bytes`	Typed binary reads and writes over a string.buffer.Buffer.
`nupp.data`	JSON, UTF-8, UUIDs, hashes and checksums.
`nupp.fieldcodec`	Type-directed keyed codecs materialized from semantic reflection.
`nupp.io`	Buffers, byte views, readers and writers.
`nupp.log`	Leveled logging over a swappable destination.
`nupp.math`	Scalar helpers and two-dimensional vectors.
`nupp.peg`	Compiles textual parsing-expression grammars into reusable matchers.
`nupp.profile`	Profiling, in two channels.
`nupp.resource_set`	—
`nupp.resources`	Owning wrappers for Lua's file handles.
`nupp.span`	Bounds-carrying borrowed pointer views.
`nupp.suspension`	Waiting, as an operation with an installable handler.
`nupp.workers`	Isolated worker threads.
`nupp.zone`	Gated LuaJIT profiler zones: the stack work is skipped until a profiler asks for it.

Module contents

Types

Type	Kind	Description
`Buffer`	interface	An owned growable byte sequence.
`ByteView`	interface	An immutable snapshot of bytes.
`Debug`	interface	Values with deterministic compiler-generated debug formatting.
`FieldCodec`	record	Types for materialized keyed field codecs.
`Files`	record	Filesystem metadata and directory contents.
`JSON`	interface	One independently configured JSON encoder and decoder.
`JSONEncodable`	interface	Values that can encode themselves as JSON text.
`Log`	record	Leveled logging over a swappable destination.
`Path`	record	An immutable platform-native UTF-8 filesystem path.
`Reader`	interface	A forward-only byte source.
`URI`	record	An immutable normalized absolute URI.
`Writer`	interface	A forward-only byte destination.

Types#

`Buffer`interface#

An owned growable byte sequence. All offsets are zero-based.

interface nupp.Buffer
    newReader: function(self: nupp.Buffer): nupp.Reader
    newWriter: function(self: nupp.Buffer): nupp.Writer
    length: function(self: nupp.Buffer): integer
    capacity: function(self: nupp.Buffer): integer
    clear: function(self: nupp.Buffer)
    ensureCapacity: function(self: nupp.Buffer, minimum: integer)
    resize: function(self: nupp.Buffer, length: integer)
    getString: function(self: nupp.Buffer, offset: integer?, count: integer?): string
    setString: function(self: nupp.Buffer, bytes: string, offset: integer?)
    view: function(self: nupp.Buffer, offset: integer?, count: integer?): nupp.ByteView
    isReleased: function(self: nupp.Buffer): boolean
    close: function(self: nupp.Buffer): (boolean, string?)
end

Methods

`newReader`

Opens a reader over a snapshot of the current bytes.

newReader: function(self: nupp.Buffer): nupp.Reader

Arguments

Name	Type	Description
`self`	`nupp.Buffer`	this buffer

Returns

Type	Description
`nupp.Reader`	the new reader

`newWriter`

Clears the buffer and opens a writer that targets it.

newWriter: function(self: nupp.Buffer): nupp.Writer

Arguments

Name	Type	Description
`self`	`nupp.Buffer`	this buffer

Returns

Type	Description
`nupp.Writer`	the new writer

`length`

Reports the logical byte length.

length: function(self: nupp.Buffer): integer

Arguments

Name	Type	Description
`self`	`nupp.Buffer`	this buffer

Returns

Type	Description
`integer`	the byte length

`capacity`

Reports the reserved byte capacity.

capacity: function(self: nupp.Buffer): integer

Arguments

Name	Type	Description
`self`	`nupp.Buffer`	this buffer

Returns

Type	Description
`integer`	the byte capacity

`clear`

Removes every byte without discarding reserved capacity.

clear: function(self: nupp.Buffer)

Arguments

Name	Type	Description
`self`	`nupp.Buffer`	this buffer

`ensureCapacity`

Reserves at least a byte capacity without changing the length.

ensureCapacity: function(self: nupp.Buffer, minimum: integer)

Arguments

Name	Type	Description
`self`	`nupp.Buffer`	this buffer
`minimum`	`integer`	the minimum capacity

`resize`

Changes the byte length, truncating or zero-filling as needed.

resize: function(self: nupp.Buffer, length: integer)

Arguments

Name	Type	Description
`self`	`nupp.Buffer`	this buffer
`length`	`integer`	the new byte length

`getString`

Copies a byte range into a string.

getString: function(self: nupp.Buffer, offset: integer?, count: integer?): string

Arguments

Name	Type	Description
`self`	`nupp.Buffer`	this buffer
`offset`	`integer?`	the zero-based start, or zero when omitted
`count`	`integer?`	the number of bytes, or the rest of the buffer when omitted

Returns

Type	Description
`string`	the copied bytes

`setString`

Overwrites bytes at an offset, growing and zero-filling any gap.

setString: function(self: nupp.Buffer, bytes: string, offset: integer?)

Arguments

Name	Type	Description
`self`	`nupp.Buffer`	this buffer
`bytes`	`string`	the bytes to write
`offset`	`integer?`	the zero-based start, or zero when omitted

`view`

Retains an immutable snapshot of a byte range.

view: function(self: nupp.Buffer, offset: integer?, count: integer?): nupp.ByteView

Arguments

Name	Type	Description
`self`	`nupp.Buffer`	this buffer
`offset`	`integer?`	the zero-based start, or zero when omitted
`count`	`integer?`	the number of bytes, or the rest of the buffer when omitted

Returns

Type	Description
`nupp.ByteView`	the retained byte view

`isReleased`

Reports whether this buffer has been released.

isReleased: function(self: nupp.Buffer): boolean

Arguments

Name	Type	Description
`self`	`nupp.Buffer`	this buffer

Returns

Type	Description
`boolean`	whether the buffer is released

`close`

Releases this buffer. Repeated calls are safe.

close: function(self: nupp.Buffer): (boolean, string?)

Arguments

Name	Type	Description
`self`	`nupp.Buffer`	this buffer

Returns

Type	Description
`boolean`	whether the release succeeded
`string?`	a failure reason, when unsuccessful

`ByteView`interface#

An immutable snapshot of bytes.

interface nupp.ByteView
    newReader: function(self: nupp.ByteView): nupp.Reader
    length: function(self: nupp.ByteView): integer
    getString: function(self: nupp.ByteView): string
    view: function(self: nupp.ByteView, offset: integer?, count: integer?): nupp.ByteView
    isReleased: function(self: nupp.ByteView): boolean
    close: function(self: nupp.ByteView): (boolean, string?)
end

Methods

`newReader`

Opens a reader over this snapshot.

newReader: function(self: nupp.ByteView): nupp.Reader

Arguments

Name	Type	Description
`self`	`nupp.ByteView`	this byte view

Returns

Type	Description
`nupp.Reader`	the new reader

`length`

Reports the number of bytes in this snapshot.

length: function(self: nupp.ByteView): integer

Arguments

Name	Type	Description
`self`	`nupp.ByteView`	this byte view

Returns

Type	Description
`integer`	the byte length

`getString`

Copies all bytes into a string.

getString: function(self: nupp.ByteView): string

Arguments

Name	Type	Description
`self`	`nupp.ByteView`	this byte view

Returns

Type	Description
`string`	the copied bytes

`view`

Retains an immutable subrange of this snapshot.

view: function(self: nupp.ByteView, offset: integer?, count: integer?): nupp.ByteView

Arguments

Name	Type	Description
`self`	`nupp.ByteView`	this byte view
`offset`	`integer?`	the zero-based start, or zero when omitted
`count`	`integer?`	the number of bytes, or the rest of the view when omitted

Returns

Type	Description
`nupp.ByteView`	the retained subrange

`isReleased`

Reports whether this snapshot has been released.

isReleased: function(self: nupp.ByteView): boolean

Arguments

Name	Type	Description
`self`	`nupp.ByteView`	this byte view

Returns

Type	Description
`boolean`	whether the view is released

`close`

Releases this snapshot. Repeated calls are safe.

close: function(self: nupp.ByteView): (boolean, string?)

Arguments

Name	Type	Description
`self`	`nupp.ByteView`	this byte view

Returns

Type	Description
`boolean`	whether the release succeeded
`string?`	a failure reason, when unsuccessful

`Debug`interface#

Values with deterministic compiler-generated debug formatting.

interface nupp.Debug
    debug: function(self): string
end

Methods

`debug`

debug: function(self): string

Arguments

Name	Type	Description
`?`	`self`

Returns

Type	Description
`string`

`FieldCodec`record#

Types for materialized keyed field codecs.

record nupp.FieldCodec
    record Blueprint
    end

    record KeyedCodec<T>
        encode: function(self, value: T): {[string]: any}
        decode: function(self, value: {[string]: any}): (T?, string?)
        fingerprint: string
    end

    record Library
        compile: function(info: TypeInfo): Blueprint
    end
end

Fields

Name	Type	Description
`Blueprint`	`recordDecl`
`KeyedCodec`	`recordDecl`
`Library`	`recordDecl`

`Files`record#

Filesystem metadata and directory contents.

Every operation here answers before a transfer could have started: it reads a name, a listing, or an attribute. Reading and writing a file's bytes is a separate layer.

record nupp.Files
    type Kind = "file" | "directory" | "symlink" | "other"
    type UserFolder = "home" | "documents" | "downloads" | "desktop" | "pictures" | "music" | "videos"
    record Info
        kind: nupp.Files.Kind
        size: integer
        modified: number
        readOnly: boolean
    end
    type Mode = "r" | "w" | "a" | "r+" | "w+" | "a+"
    type Origin = "set" | "current" | "end"
    type LineIterator = function(): string?
    record File
        newReader: nosuspend function(self: nupp.Files.File): nupp.Reader
        newWriter: nosuspend function(self: nupp.Files.File): nupp.Writer
        size: nosuspend function(self: nupp.Files.File): (integer?, string?)
        seek: nosuspend function(
            self: nupp.Files.File,
            offset: integer?,
            origin: nupp.Files.Origin?
        ): (integer?, string?)
        position: nosuspend function(self: nupp.Files.File): (integer?, string?)
        flush: nosuspend function(self: nupp.Files.File): (boolean, string?)
        isReleased: nosuspend function(self: nupp.Files.File): boolean
        @drop

        close: nosuspend function(takes self: nupp.Files.File): boolean
    end
    record TemporaryPath
        toString: nosuspend function(self: nupp.Files.TemporaryPath): string
        persist: nosuspend function(self: nupp.Files.TemporaryPath, destination: string | nupp.Path): (boolean, string?)
        isReleased: nosuspend function(self: nupp.Files.TemporaryPath): boolean
        @drop

        close: nosuspend function(takes self: nupp.Files.TemporaryPath): boolean
    end
    record Entry
        name: string
        kind: nupp.Files.Kind
    end
    record TemporaryOptions
        directory: (string | nupp.Path)?
        prefix: string?
        suffix: string?
    end
end

Fields

Name	Type	Description
`Kind`	`typeAlias`	What a resolved path refers to. A `symlink` answer only ever comes from `isSymlink`, since every other operation follows the link first.
`UserFolder`	`typeAlias`	A well-known user folder. Resolved from the environment, so a desktop that records its folders elsewhere is not consulted.
`Info`	`recordDecl`	One resolved path's attributes.
`Mode`	`typeAlias`	How an open file may be used. The three update modes read and write: `r+` needs an existing file, `w+` truncates one, and `a+` appends.
`Origin`	`typeAlias`	What a seek offset is measured from.
`LineIterator`	`typeAlias`	Answers each line in turn, and nil at the end of the file.
`File`	`recordDecl`	An open file, and the obligation to close it. Readers and writers opened from it satisfy the same `nupp.Reader` and `nupp.Writer` contracts a buffer's do, so code written against those works over a file without knowing one is there.
`TemporaryPath`	`recordDecl`	A created temporary path, and the obligation to settle it. Closing removes it. `persist` moves it somewhere permanent instead and discharges the obligation, which is the whole reason to make one: write to a name nobody else can take, then put it where it belongs.
`Entry`	`recordDecl`	One directory child, as the directory itself describes it.
`TemporaryOptions`	`recordDecl`	The generated part of a temporary name.

`JSON`interface#

One independently configured JSON encoder and decoder.

interface nupp.JSON
    encodeJSON: function(value: any): string
    decodeJSON: function(text: string): any
    null: any
    emptyArray: any
    arrayMt: metatable<{any}>
    emptyArrayMt: metatable<{any}>
    encodeEmptyTableAsObject: function(setting: boolean | string?): boolean
    decodeArrayWithArrayMt: function(setting: boolean | string?): boolean
    decodeAllowComment: function(setting: boolean | string?): boolean
    encodeSparseArray: function(convert: boolean?, ratio: integer?, safe: integer?): (boolean, integer, integer)
    encodeMaxDepth: function(depth: integer?): integer
    decodeMaxDepth: function(depth: integer?): integer
    encodeNumberPrecision: function(precision: integer?): integer
    encodeKeepBuffer: function(keep: boolean | string?): boolean
    encodeInvalidNumbers: function(setting: boolean | string?): boolean | string
    decodeInvalidNumbers: function(setting: boolean | string?): boolean
    encodeEscapeForwardSlash: function(setting: boolean | string?): boolean
    encodeSkipUnsupportedValueTypes: function(setting: boolean | string?): boolean
    encodeIndent: function(indent: string?): string
end

Methods

`encodeJSON`

Encodes a Lua value as JSON text.

encodeJSON: function(value: any): string

Arguments

Name	Type	Description
`value`	`any`	the value to encode

Returns

Type	Description
`string`	the encoded JSON document

`decodeJSON`

Decodes one JSON document into Lua values.

decodeJSON: function(text: string): any

Arguments

Name	Type	Description
`text`	`string`	the JSON document to decode

Returns

Type	Description
`any`	the decoded value

`encodeEmptyTableAsObject`

Sets whether an empty table encodes as an object, or reads the current setting when omitted.

encodeEmptyTableAsObject: function(setting: boolean | string?): boolean

Arguments

Name	Type	Description
`setting`	`boolean \| string?`	true or "on" for `{}`, false or "off" for `[]`

Returns

Type	Description
`boolean`	whether empty tables encode as objects

`decodeArrayWithArrayMt`

Sets whether decoded arrays carry arrayMt, or reads the current setting when omitted.

decodeArrayWithArrayMt: function(setting: boolean | string?): boolean

Arguments

Name	Type	Description
`setting`	`boolean \| string?`	the new setting

Returns

Type	Description
`boolean`	whether decoded arrays carry `arrayMt`

`decodeAllowComment`

Sets whether the decoder accepts comments, or reads the current setting when omitted.

decodeAllowComment: function(setting: boolean | string?): boolean

Arguments

Name	Type	Description
`setting`	`boolean \| string?`	the new setting

Returns

Type	Description
`boolean`	whether comments are accepted

`encodeSparseArray`

Configures how excessively sparse arrays are encoded, or reads the current settings when every argument is omitted.

encodeSparseArray: function(convert: boolean?, ratio: integer?, safe: integer?): (boolean, integer, integer)

Arguments

Name	Type	Description
`convert`	`boolean?`	whether sparse arrays become JSON objects instead of raising
`ratio`	`integer?`	the maximum ratio between the highest index and item count
`safe`	`integer?`	the array size below which sparsity is always accepted

Returns

Type	Description
`boolean`	whether sparse arrays are converted
`integer`	the current ratio limit
`integer`	the current safe size

`encodeMaxDepth`

Sets the maximum nested-container depth accepted by the encoder, or reads the current limit when omitted.

encodeMaxDepth: function(depth: integer?): integer

Arguments

Name	Type	Description
`depth`	`integer?`	the new maximum depth

Returns

Type	Description
`integer`	the current maximum depth

`decodeMaxDepth`

Sets the maximum nested-container depth accepted by the decoder, or reads the current limit when omitted.

decodeMaxDepth: function(depth: integer?): integer

Arguments

Name	Type	Description
`depth`	`integer?`	the new maximum depth

Returns

Type	Description
`integer`	the current maximum depth

`encodeNumberPrecision`

Sets the significant-digit precision used to encode numbers, or reads the current precision when omitted.

encodeNumberPrecision: function(precision: integer?): integer

Arguments

Name	Type	Description
`precision`	`integer?`	the new number of significant digits

Returns

Type	Description
`integer`	the current precision

`encodeKeepBuffer`

Sets whether the encoder reuses its internal buffer, or reads the current setting when omitted.

encodeKeepBuffer: function(keep: boolean | string?): boolean

Arguments

Name	Type	Description
`keep`	`boolean \| string?`	the new setting

Returns

Type	Description
`boolean`	whether the internal buffer is retained

`encodeInvalidNumbers`

Configures encoding of NaN and infinities, or reads the current setting when omitted.

encodeInvalidNumbers: function(setting: boolean | string?): boolean | string

Arguments

Name	Type	Description
`setting`	`boolean \| string?`	false to reject them, true to emit them, or "null" to emit null

Returns

Type	Description
`boolean \| string`	the active invalid-number setting

`decodeInvalidNumbers`

Sets whether the decoder accepts NaN and infinities, or reads the current setting when omitted.

decodeInvalidNumbers: function(setting: boolean | string?): boolean

Arguments

Name	Type	Description
`setting`	`boolean \| string?`	the new setting

Returns

Type	Description
`boolean`	whether invalid numbers are accepted

`encodeEscapeForwardSlash`

Sets whether / is escaped in JSON strings, or reads the current setting when omitted.

encodeEscapeForwardSlash: function(setting: boolean | string?): boolean

Arguments

Name	Type	Description
`setting`	`boolean \| string?`	the new setting

Returns

Type	Description
`boolean`	whether forward slashes are escaped

`encodeSkipUnsupportedValueTypes`

Sets whether unsupported values are skipped instead of raising, or reads the current setting when omitted.

encodeSkipUnsupportedValueTypes: function(setting: boolean | string?): boolean

Arguments

Name	Type	Description
`setting`	`boolean \| string?`	the new setting

Returns

Type	Description
`boolean`	whether unsupported values are skipped

`encodeIndent`

Sets the indentation used for encoded containers, or reads the current indentation when omitted.

encodeIndent: function(indent: string?): string

Arguments

Name	Type	Description
`indent`	`string?`	the indentation string

Returns

Type	Description
`string`	the current indentation string

Fields

Name	Type	Description
`null`	`any`	Sentinel that decodes from and encodes as JSON null.
`emptyArray`	`any`	Sentinel that always encodes as an empty JSON array.
`arrayMt`	`metatable<{any}>`	Metatable marking a table to encode as a JSON array.
`emptyArrayMt`	`metatable<{any}>`	Metatable marking a table to encode as an empty JSON array.

`JSONEncodable`interface#

Values that can encode themselves as JSON text.

interface nupp.JSONEncodable
    toJSON: function(self): string
end

Methods

`toJSON`

toJSON: function(self): string

Arguments

Name	Type	Description
`?`	`self`

Returns

Type	Description
`string`

`Log`record#

Leveled logging over a swappable destination.

The severity operations are compiler intrinsics. A call in statement position whose format is a literal compiles to a level test around a direct emit, so a filtered call evaluates none of its arguments. Every other spelling stays an ordinary call meaning the same thing, only slower: a value rather than a call, a computed format, a named argument, or a nupp some local has taken.

record nupp.Log
    type Level = "off" | "error" | "warn" | "info" | "debug"
    type Severity = integer
    type Sink = function(level: Severity, module: string, line: integer, message: string): nil
    type Formatter = function(level: Severity, module: string, line: integer, message: string, stamp: string): string
    type Target = Sink | LuaFile
    record Logger
        readonly name: string
        debug: function<F is string>(self: Logger, fmt: F, ...: unpackof __NuppFormatArguments<F>): nil
        info: function<F is string>(self: Logger, fmt: F, ...: unpackof __NuppFormatArguments<F>): nil
        warn: function<F is string>(self: Logger, fmt: F, ...: unpackof __NuppFormatArguments<F>): nil
        error: function<F is string>(self: Logger, fmt: F, ...: unpackof __NuppFormatArguments<F>): nil
        enabled: function(self: Logger, level: Level): boolean
    end
end

Fields

Name	Type	Description
`Level`	`typeAlias`	The threshold, from silent to most verbose. Each level admits itself and everything above it, so "warn" emits warnings and errors.
`Severity`	`typeAlias`	A level as a sink sees it: 1 error, 2 warn, 3 info, 4 debug.
`Sink`	`typeAlias`	Receives one emitted line, already formatted. Replacing this replaces the back end, so a host logging through its own facility pays for nothing it discards -- no timestamp is passed, because a sink that wants one asks.
`Formatter`	`typeAlias`	Renders one line for a file-like destination. Only consulted when the target is file-like; a sink function formats however it likes.
`Target`	`typeAlias`	Where lines go: a sink function, or anything file-like to write to.
`Logger`	`recordDecl`	A logger carrying a fixed name, for subsystems and for call sites the intrinsic cannot rewrite. Changing the level or target restamps every logger, so a filtered call reaches an empty function rather than a test.

`Path`record#

An immutable platform-native UTF-8 filesystem path.

record nupp.Path
    toString: function(self: nupp.Path): string
    join: function(self: nupp.Path, ...: string | nupp.Path): nupp.Path
    normalize: function(self: nupp.Path): nupp.Path
    absolute: function(self: nupp.Path): (nupp.Path?, string?)
    resolve: function(self: nupp.Path, ...: string | nupp.Path): (nupp.Path?, string?)
    canonicalize: function(self: nupp.Path): (nupp.Path?, string?)
    relativeTo: function(self: nupp.Path, base: string | nupp.Path): (nupp.Path?, string?)
    parent: function(self: nupp.Path): nupp.Path?
    fileName: function(self: nupp.Path): string?
    stem: function(self: nupp.Path): string?
    extension: function(self: nupp.Path): string?
    withFileName: function(self: nupp.Path, name: string): nupp.Path
    withExtension: function(self: nupp.Path, extension: string): nupp.Path
    isAbsolute: function(self: nupp.Path): boolean
    isRelative: function(self: nupp.Path): boolean
end

Methods

`toString`

Returns the native UTF-8 path text.

toString: function(self: nupp.Path): string

Arguments

Name	Type	Description
`self`	`nupp.Path`	this path

Returns

Type	Description
`string`	the path text

`join`

Appends path components using the current platform's rules.

join: function(self: nupp.Path, ...: string | nupp.Path): nupp.Path

Arguments

Name	Type	Description
`self`	`nupp.Path`	this path
`...`	`string \| nupp.Path`	the components to append

Returns

Type	Description
`nupp.Path`	the joined path

`normalize`

Removes lexical . and .. components without accessing the filesystem.

normalize: function(self: nupp.Path): nupp.Path

Arguments

Name	Type	Description
`self`	`nupp.Path`	this path

Returns

Type	Description
`nupp.Path`	the normalized path

`absolute`

Resolves a relative path against the current working directory.

absolute: function(self: nupp.Path): (nupp.Path?, string?)

Arguments

Name	Type	Description
`self`	`nupp.Path`	this path

Returns

Type	Description
`nupp.Path?`	the absolute path, or nil on failure
`string?`	a failure reason, when unsuccessful

`resolve`

Makes this path absolute, appends components, and normalizes the result.

resolve: function(self: nupp.Path, ...: string | nupp.Path): (nupp.Path?, string?)

Arguments

Name	Type	Description
`self`	`nupp.Path`	this path
`...`	`string \| nupp.Path`	the components to append

Returns

Type	Description
`nupp.Path?`	the resolved path, or nil on failure
`string?`	a failure reason, when unsuccessful

`canonicalize`

Resolves filesystem links and returns the real path.

canonicalize: function(self: nupp.Path): (nupp.Path?, string?)

Arguments

Name	Type	Description
`self`	`nupp.Path`	this path

Returns

Type	Description
`nupp.Path?`	the canonical path, or nil on failure
`string?`	a failure reason, when unsuccessful

`relativeTo`

Computes this path relative to a compatible base path.

relativeTo: function(self: nupp.Path, base: string | nupp.Path): (nupp.Path?, string?)

Arguments

Name	Type	Description
`self`	`nupp.Path`	this path
`base`	`string \| nupp.Path`	the path to make this value relative to

Returns

Type	Description
`nupp.Path?`	the relative path, or nil on failure
`string?`	a failure reason, when unsuccessful

`parent`

Returns the parent path, when one exists.

parent: function(self: nupp.Path): nupp.Path?

Arguments

Name	Type	Description
`self`	`nupp.Path`	this path

Returns

Type	Description
`nupp.Path?`	the parent path

`fileName`

Returns the final path component, when one exists.

fileName: function(self: nupp.Path): string?

Arguments

Name	Type	Description
`self`	`nupp.Path`	this path

Returns

Type	Description
`string?`	the file name

`stem`

Returns the file name without its final extension, when one exists.

stem: function(self: nupp.Path): string?

Arguments

Name	Type	Description
`self`	`nupp.Path`	this path

Returns

Type	Description
`string?`	the file stem

`extension`

Returns the final file-name extension without its separator.

extension: function(self: nupp.Path): string?

Arguments

Name	Type	Description
`self`	`nupp.Path`	this path

Returns

Type	Description
`string?`	the extension

`withFileName`

Replaces the final path component.

withFileName: function(self: nupp.Path, name: string): nupp.Path

Arguments

Name	Type	Description
`self`	`nupp.Path`	this path
`name`	`string`	the replacement file name, without path separators

Returns

Type	Description
`nupp.Path`	the modified path

`withExtension`

Replaces the final file-name extension.

withExtension: function(self: nupp.Path, extension: string): nupp.Path

Arguments

Name	Type	Description
`self`	`nupp.Path`	this path
`extension`	`string`	the replacement extension, without path separators

Returns

Type	Description
`nupp.Path`	the modified path

`isAbsolute`

Reports whether this path is absolute.

isAbsolute: function(self: nupp.Path): boolean

Arguments

Name	Type	Description
`self`	`nupp.Path`	this path

Returns

Type	Description
`boolean`	whether the path is absolute

`isRelative`

Reports whether this path is relative.

isRelative: function(self: nupp.Path): boolean

Arguments

Name	Type	Description
`self`	`nupp.Path`	this path

Returns

Type	Description
`boolean`	whether the path is relative

`Reader`interface#

A forward-only byte source. An empty read or zero-byte readInto is EOF.

interface nupp.Reader
    read: function(self: nupp.Reader, count: integer): (string?, string?)
    readInto: function(
        self: nupp.Reader,
        destination: nupp.Buffer,
        offset: integer?,
        count: integer?
    ): (integer?, string?)
    transferTo: function(self: nupp.Reader, destination: nupp.Writer): (integer?, string?)
    close: function(self: nupp.Reader): (boolean, string?)
end

Methods

`read`

Reads the next bytes, returning an empty string at EOF.

read: function(self: nupp.Reader, count: integer): (string?, string?)

Arguments

Name	Type	Description
`self`	`nupp.Reader`	this reader
`count`	`integer`	the maximum number of bytes; non-positive values still read one

Returns

Type	Description
`string?`	the bytes, or nil on failure
`string?`	a failure reason, when unsuccessful

`readInto`

Reads bytes into a buffer, returning zero at EOF.

readInto: function(
        self: nupp.Reader,
        destination: nupp.Buffer,
        offset: integer?,
        count: integer?
    ): (integer?, string?)

Arguments

Name	Type	Description
`self`	`nupp.Reader`	this reader
`destination`	`nupp.Buffer`	the buffer to append to or overwrite
`offset`	`integer?`	the zero-based destination offset, or zero when omitted
`count`	`integer?`	the maximum bytes to read, or 64 KiB when omitted

Returns

Type	Description
`integer?`	the number of bytes read, or nil on failure
`string?`	a failure reason, when unsuccessful

`transferTo`

Copies all remaining bytes into a writer.

transferTo: function(self: nupp.Reader, destination: nupp.Writer): (integer?, string?)

Arguments

Name	Type	Description
`self`	`nupp.Reader`	this reader
`destination`	`nupp.Writer`	the writer to receive the bytes

Returns

Type	Description
`integer?`	the number of bytes copied, or nil on failure
`string?`	a failure reason, when unsuccessful

`close`

Closes this reader. Repeated calls are safe.

close: function(self: nupp.Reader): (boolean, string?)

Arguments

Name	Type	Description
`self`	`nupp.Reader`	this reader

Returns

Type	Description
`boolean`	whether the close succeeded
`string?`	a failure reason, when unsuccessful

`URI`record#

An immutable normalized absolute URI.

record nupp.URI
    record Components
        scheme: string
        userInfo: string?
        host: string?
        port: integer?
        path: string?
        query: string?
        fragment: string?
    end
    toString: function(self: nupp.URI): string
    scheme: function(self: nupp.URI): string
    authority: function(self: nupp.URI): string?
    username: function(self: nupp.URI): string
    password: function(self: nupp.URI): string?
    host: function(self: nupp.URI): string?
    port: function(self: nupp.URI): integer?
    path: function(self: nupp.URI): string
    query: function(self: nupp.URI): string?
    fragment: function(self: nupp.URI): string?
    userInfo: function(self: nupp.URI): string?
    withScheme: function(self: nupp.URI, scheme: string): nupp.URI
    withUserInfo: function(self: nupp.URI, userInfo: string?): nupp.URI
    withHost: function(self: nupp.URI, host: string?): nupp.URI
    withPort: function(self: nupp.URI, port: integer?): nupp.URI
    withPath: function(self: nupp.URI, path: string): nupp.URI
    withQuery: function(self: nupp.URI, query: string?): nupp.URI
    withFragment: function(self: nupp.URI, fragment: string?): nupp.URI
    concatPath: function(self: nupp.URI, path: string): nupp.URI
    withEndpoint: function(self: nupp.URI, endpoint: nupp.URI): nupp.URI
    resolve: function(self: nupp.URI, reference: string): (nupp.URI?, string?)
end

Methods

`toString`

Returns the complete normalized URI text.

toString: function(self: nupp.URI): string

Arguments

Name	Type	Description
`self`	`nupp.URI`	this URI

Returns

Type	Description
`string`	the URI text

`scheme`

Returns the normalized URI scheme.

scheme: function(self: nupp.URI): string

Arguments

Name	Type	Description
`self`	`nupp.URI`	this URI

Returns

Type	Description
`string`	the scheme

`authority`

Returns the complete authority component, when present.

authority: function(self: nupp.URI): string?

Arguments

Name	Type	Description
`self`	`nupp.URI`	this URI

Returns

Type	Description
`string?`	the authority

`username`

Returns the username component, or an empty string when absent.

username: function(self: nupp.URI): string

Arguments

Name	Type	Description
`self`	`nupp.URI`	this URI

Returns

Type	Description
`string`	the username

`password`

Returns the password component, when present.

password: function(self: nupp.URI): string?

Arguments

Name	Type	Description
`self`	`nupp.URI`	this URI

Returns

Type	Description
`string?`	the password

`host`

Returns the normalized host, when present.

host: function(self: nupp.URI): string?

Arguments

Name	Type	Description
`self`	`nupp.URI`	this URI

Returns

Type	Description
`string?`	the host

`port`

Returns the port, when explicitly present.

port: function(self: nupp.URI): integer?

Arguments

Name	Type	Description
`self`	`nupp.URI`	this URI

Returns

Type	Description
`integer?`	the port

`path`

Returns the URI path component.

path: function(self: nupp.URI): string

Arguments

Name	Type	Description
`self`	`nupp.URI`	this URI

Returns

Type	Description
`string`	the path

`query`

Returns the query without its leading ?, when present.

query: function(self: nupp.URI): string?

Arguments

Name	Type	Description
`self`	`nupp.URI`	this URI

Returns

Type	Description
`string?`	the query

`fragment`

Returns the fragment without its leading #, when present.

fragment: function(self: nupp.URI): string?

Arguments

Name	Type	Description
`self`	`nupp.URI`	this URI

Returns

Type	Description
`string?`	the fragment

`userInfo`

Returns the complete user-information component, when present.

userInfo: function(self: nupp.URI): string?

Arguments

Name	Type	Description
`self`	`nupp.URI`	this URI

Returns

Type	Description
`string?`	the user information

`withScheme`

Returns a copy with a replacement scheme.

withScheme: function(self: nupp.URI, scheme: string): nupp.URI

Arguments

Name	Type	Description
`self`	`nupp.URI`	this URI
`scheme`	`string`	the replacement scheme

Returns

Type	Description
`nupp.URI`	the modified URI

`withUserInfo`

Returns a copy with replacement or removed user information.

withUserInfo: function(self: nupp.URI, userInfo: string?): nupp.URI

Arguments

Name	Type	Description
`self`	`nupp.URI`	this URI
`userInfo`	`string?`	the replacement, or nil to remove it

Returns

Type	Description
`nupp.URI`	the modified URI

`withHost`

Returns a copy with a replacement or removed host.

withHost: function(self: nupp.URI, host: string?): nupp.URI

Arguments

Name	Type	Description
`self`	`nupp.URI`	this URI
`host`	`string?`	the replacement, or nil to remove it

Returns

Type	Description
`nupp.URI`	the modified URI

`withPort`

Returns a copy with a replacement or removed port.

withPort: function(self: nupp.URI, port: integer?): nupp.URI

Arguments

Name	Type	Description
`self`	`nupp.URI`	this URI
`port`	`integer?`	the replacement from 0 through 65535, or nil to remove it

Returns

Type	Description
`nupp.URI`	the modified URI

`withPath`

Returns a copy with a replacement path.

withPath: function(self: nupp.URI, path: string): nupp.URI

Arguments

Name	Type	Description
`self`	`nupp.URI`	this URI
`path`	`string`	the replacement path

Returns

Type	Description
`nupp.URI`	the modified URI

`withQuery`

Returns a copy with a replacement or removed query.

withQuery: function(self: nupp.URI, query: string?): nupp.URI

Arguments

Name	Type	Description
`self`	`nupp.URI`	this URI
`query`	`string?`	the replacement without `?`, or nil to remove it

Returns

Type	Description
`nupp.URI`	the modified URI

`withFragment`

Returns a copy with a replacement or removed fragment.

withFragment: function(self: nupp.URI, fragment: string?): nupp.URI

Arguments

Name	Type	Description
`self`	`nupp.URI`	this URI
`fragment`	`string?`	the replacement without `#`, or nil to remove it

Returns

Type	Description
`nupp.URI`	the modified URI

`concatPath`

Appends path text without interpreting it as a URI reference.

concatPath: function(self: nupp.URI, path: string): nupp.URI

Arguments

Name	Type	Description
`self`	`nupp.URI`	this URI
`path`	`string`	the path text to append

Returns

Type	Description
`nupp.URI`	the modified URI

`withEndpoint`

Replaces the scheme and authority while retaining resource components.

withEndpoint: function(self: nupp.URI, endpoint: nupp.URI): nupp.URI

Arguments

Name	Type	Description
`self`	`nupp.URI`	this URI
`endpoint`	`nupp.URI`	the URI supplying the scheme and authority

Returns

Type	Description
`nupp.URI`	the endpoint-rerouted URI

`resolve`

Resolves a URI reference according to RFC reference-resolution rules.

resolve: function(self: nupp.URI, reference: string): (nupp.URI?, string?)

Arguments

Name	Type	Description
`self`	`nupp.URI`	this URI
`reference`	`string`	the URI reference to resolve

Returns

Type	Description
`nupp.URI?`	the resolved URI, or nil on failure
`string?`	a failure reason, when unsuccessful

Fields

Name	Type	Description
`Components`	`recordDecl`	Components accepted when constructing an absolute URI.

`Writer`interface#

A forward-only byte destination.

interface nupp.Writer
    write: function(self: nupp.Writer, bytes: string): (boolean, string?)
    writeFrom: function(self: nupp.Writer, source: nupp.Buffer, offset: integer?, count: integer?): (integer?, string?)
    writeView: function(
        self: nupp.Writer,
        source: nupp.ByteView,
        offset: integer?,
        count: integer?
    ): (integer?, string?)
    flush: function(self: nupp.Writer): (boolean, string?)
    close: function(self: nupp.Writer): (boolean, string?)
end

Methods

`write`

Writes a string of bytes.

write: function(self: nupp.Writer, bytes: string): (boolean, string?)

Arguments

Name	Type	Description
`self`	`nupp.Writer`	this writer
`bytes`	`string`	the bytes to write

Returns

Type	Description
`boolean`	whether the write succeeded
`string?`	a failure reason, when unsuccessful

`writeFrom`

Copies bytes from a mutable buffer.

writeFrom: function(self: nupp.Writer, source: nupp.Buffer, offset: integer?, count: integer?): (integer?, string?)

Arguments

Name	Type	Description
`self`	`nupp.Writer`	this writer
`source`	`nupp.Buffer`	the source buffer
`offset`	`integer?`	the zero-based start, or zero when omitted
`count`	`integer?`	the number of bytes, or the rest of the buffer when omitted

Returns

Type	Description
`integer?`	the number of bytes written, or nil on failure
`string?`	a failure reason, when unsuccessful

`writeView`

Copies bytes from an immutable view.

writeView: function(
        self: nupp.Writer,
        source: nupp.ByteView,
        offset: integer?,
        count: integer?
    ): (integer?, string?)

Arguments

Name	Type	Description
`self`	`nupp.Writer`	this writer
`source`	`nupp.ByteView`	the source byte view
`offset`	`integer?`	the zero-based start, or zero when omitted
`count`	`integer?`	the number of bytes, or the rest of the view when omitted

Returns

Type	Description
`integer?`	the number of bytes written, or nil on failure
`string?`	a failure reason, when unsuccessful

`flush`

Flushes any buffered output.

flush: function(self: nupp.Writer): (boolean, string?)

Arguments

Name	Type	Description
`self`	`nupp.Writer`	this writer

Returns

Type	Description
`boolean`	whether the flush succeeded
`string?`	a failure reason, when unsuccessful

`close`

Closes this writer. Repeated calls are safe.

close: function(self: nupp.Writer): (boolean, string?)

Arguments

Name	Type	Description
`self`	`nupp.Writer`	this writer

Returns

Type	Description
`boolean`	whether the close succeeded
`string?`	a failure reason, when unsuccessful

Module: nupp

Submodules

Module contents

Types

Types#

Bufferinterface#

Methods

newReader

Arguments

Returns

newWriter

Arguments

Returns

length

Arguments

Returns

capacity

Arguments

Returns

clear

Arguments

ensureCapacity

Arguments

resize

Arguments

getString

Arguments

Returns

setString

Arguments

view

Arguments

Returns

isReleased

Arguments

Returns

close

Arguments

Returns

ByteViewinterface#

Methods

newReader

Arguments

Returns

length

Arguments

Returns

getString

Arguments

Returns

view

Arguments

Returns

isReleased

Arguments

Returns

close

Arguments

Returns

Debuginterface#

Methods

debug

Arguments

Returns

FieldCodecrecord#

Fields

Filesrecord#

Fields

JSONinterface#

Methods

encodeJSON

Arguments

Returns

decodeJSON

Arguments

Returns

encodeEmptyTableAsObject

Arguments

Returns

decodeArrayWithArrayMt

Module: `nupp`

`Buffer`interface#

`newReader`

`newWriter`

`length`

`capacity`

`clear`

`ensureCapacity`

`resize`

`getString`

`setString`

`view`

`isReleased`

`close`

`ByteView`interface#

`newReader`

`length`

`getString`

`view`

`isReleased`

`close`

`Debug`interface#

`debug`

`FieldCodec`record#

`Files`record#

`JSON`interface#

`encodeJSON`

`decodeJSON`

`encodeEmptyTableAsObject`

`decodeArrayWithArrayMt`

`decodeAllowComment`

`encodeSparseArray`

`encodeMaxDepth`

`decodeMaxDepth`

`encodeNumberPrecision`

`encodeKeepBuffer`

`encodeInvalidNumbers`

`decodeInvalidNumbers`

`encodeEscapeForwardSlash`

`encodeSkipUnsupportedValueTypes`

`encodeIndent`

`JSONEncodable`interface#

`toJSON`

`Log`record#

`Path`record#

`toString`

`join`

`normalize`

`absolute`

`resolve`

`canonicalize`

`relativeTo`

`parent`

`fileName`