nupp.io.files

ApplicationPathinterface#

sealed interface ApplicationPath ...

An opaque portable path rooted in this application's platform storage.

join: function(self, ...: string): ApplicationPath

toString: function(self): string

Capabilitiesrecord#

record Capabilities ...

The exact filesystem guarantees supplied by the selected provider.

available: boolean

arbitraryPaths: boolean

symbolicLinks: boolean

readOnlyAttributes: boolean

glob: boolean

rename: boolean

atomicWrite: boolean

temporaryPaths: boolean

concurrentOpenHandles: boolean

currentDirectory: boolean

userFolders: boolean

executableDirectory: boolean

persistentStorageRequest: boolean

Entryrecord#

record Entry ...

An immediate child returned by a directory listing.

name: string

kind: Kind

Fileinterface#

interface File is io.Reader, io.Writer ...

An affine open file, which is itself a reader and a writer over its one cursor.

size: function(borrows self: File): (integer?, io.Error?)

seek: function(exclusive self: File, offset: integer?, origin: messages.Origin?): (integer?, io.Error?)

position: function(exclusive self: File): (integer?, io.Error?)

flush: function(borrows self: File): (boolean, string?)

isReleased: function(borrows self: File): boolean

close: @nosuspend function(takes self: File): nil

Inforecord#

record Info ...

Metadata about one filesystem object.

kind: Kind

size: integer

modified: number

readOnly: boolean

Kindtype#

type Kind = "file" | "directory" | "symlink" | "other"

The kind of filesystem object described by metadata or a directory entry.

Modetype#

type Mode = "r" | "w" | "a" | "r+" | "w+" | "a+"

A file open mode: read, write, append, or an updating variant.

Origintype#

type Origin = "set" | "current" | "end"

The base used by a file seek.

Pathtype#

type Path = string | paths.Path | appPaths.ApplicationPath

A native path or an opaque application-owned path.

TemporaryOptionsrecord#

record TemporaryOptions ...

Naming and placement options for a native temporary path.

directory: (string | paths.Path)?

prefix: string?

suffix: string?

TemporaryPathinterface#

interface TemporaryPath is nupp.Closeable ...

A native temporary path removed when its owner closes unless persisted.

toString: function(self: TemporaryPath): string

path: function(self: TemporaryPath): paths.Path

persist: function(self: TemporaryPath, destination: any): (boolean, io.Error?)

isReleased: function(self: TemporaryPath): boolean

close: @nosuspend function(takes self: TemporaryPath): nil

UserFoldertype#

type UserFolder = "home" | "documents" | "downloads" | "desktop" | "pictures" | "music" | "videos"

A portable name for a conventional user directory.

appendfunction#

function append(path: Path, borrows bytes: string | io.ByteView): boolean, io.Error?

Appends bytes to a file, creating it when absent.

Arguments

Returns

applicationIdentityfunction#

function applicationIdentity(): string?, string?

Returns the selected application identity, or nil values before one is set.

Returns

cachePathfunction#

function cachePath(): appPaths.ApplicationPath?, io.Error?

Resolves and creates this application's platform cache directory.

Returns

configurationPathfunction#

function configurationPath(): appPaths.ApplicationPath?, io.Error?

Resolves and creates this application's platform configuration directory.

Configuration, data and cache are always three distinct directories, so clearing one with a recursive remove never reaches another.

Returns

copyfunction#

function copy(from: Path, to: Path): boolean, io.Error?

Copies a file over another.

Arguments

Returns

createDirectoryfunction#

function createDirectory(path: Path): boolean, io.Error?

Creates a directory and all missing parents.

Arguments

Returns

createSymlinkfunction#

function createSymlink(targetPath: Path, link: Path, kind: ("file" | "directory")?): boolean, io.Error?

Creates a symbolic link when the provider supports one.

Arguments

Returns

createTemporaryDirectoryfunction#

function createTemporaryDirectory(options: messages.TemporaryOptions?): affine(contracts.TemporaryPath?), io.Error?

Creates a native temporary directory owner when the provider supports one.

Arguments

Returns

createTemporaryFilefunction#

function createTemporaryFile(options: messages.TemporaryOptions?): affine(contracts.TemporaryPath?), io.Error?

Creates a native temporary file owner when the provider supports one.

Arguments

Returns

dataPathfunction#

function dataPath(): appPaths.ApplicationPath?, io.Error?

Resolves and creates this application's platform data directory.

Returns

executableDirectoryfunction#

function executableDirectory(): paths.Path?, io.Error?

Returns the native running executable's directory.

Returns

existsfunction#

function exists(path: Path): boolean

Reports whether a path resolves.

Any failure reads as false, a refused permission or an I/O error as much as a missing name. Ask info when the reason matters.

Arguments

Returns

globfunction#

function glob(pattern: string): {paths.Path}?, io.Error?

Expands a native filesystem glob.

Arguments

Returns

infofunction#

function info(path: Path): messages.Info?, io.Error?

Describes the filesystem object at a path.

Arguments

Returns

isDirectoryfunction#

function isDirectory(path: Path): boolean

Reports whether a path resolves to a directory.

Any failure reads as false; ask info when the reason matters.

Arguments

Returns

isFilefunction#

function isFile(path: Path): boolean

Reports whether a path resolves to a file.

Any failure reads as false; ask info when the reason matters.

Arguments

Returns

isSymlinkfunction#

function isSymlink(path: Path): boolean

Reports whether a path itself is a symbolic link.

Any failure reads as false, and so does a provider with no links at all; capabilities().symbolicLinks says which that is.

Arguments

Returns

linesfunction#

function lines(path: Path, limit: integer?): affine(io.Lines)?, io.Error?

Opens a file as a line reader, which takes the file and closes it with itself.

A line is read without its terminator, \n or \r\n. A read that fails partway through returns nil and the reason from Lines:read, which is what tells it apart from the end of the file, where the reason is nil.

local log = assert(nupp.io.files.lines("access.log"))
while true do
    local line, reason = log:read()
    if line == nil then
        assert(reason == nil, reason)
        break
    end
    print(line)
end

Arguments

Returns

Raises

listfunction#

function list(path: Path): {messages.Entry}?, io.Error?

Lists a directory's immediate children.

Arguments

Returns

openfunction#

function open(path: Path, mode: messages.Mode?): affine(contracts.File?), io.Error?

Opens a file in one of the six standard read, write, append, or update modes.

Arguments

Returns

readfunction#

function read(path: Path): string?, io.Error?

Reads an entire file as bytes.

Arguments

Returns

readLinkfunction#

function readLink(path: Path): paths.Path?, io.Error?

Reads a symbolic link target without resolving it.

Arguments

Returns

removefunction#

function remove(path: Path, recursive: boolean?): boolean, io.Error?

Removes a file, link, or directory.

Arguments

Returns

renamefunction#

function rename(from: Path, to: Path): boolean, io.Error?

Renames a path, replacing an existing destination when supported.

Arguments

Returns

requestPersistentStoragefunction#

function requestPersistentStorage(): boolean, io.Error?

Requests non-evictable browser storage; native providers succeed without work.

Returns

setApplicationIdentityfunction#

function setApplicationIdentity(newOrganization: string, newApplication: string): nil

Selects the identity used to resolve configuration, data, and cache roots.

Arguments

Returns

setReadOnlyfunction#

function setReadOnly(path: Path, readOnly: boolean): boolean, io.Error?

Sets or clears a path's native read-only attribute.

Arguments

Returns

userFolderfunction#

function userFolder(which: messages.UserFolder): paths.Path?, io.Error?

Resolves a conventional native user folder.

Arguments

Returns

writefunction#

function write(path: Path, borrows bytes: string | io.ByteView): boolean, io.Error?

Replaces a file with the supplied bytes.

Arguments

Returns

writeAtomicfunction#

function writeAtomic(path: Path, borrows bytes: string | io.ByteView): boolean, io.Error?

Atomically replaces a file when the provider supports it.

Arguments

Returns

capabilitiesvariable#

const capabilities

Reports the exact guarantees of the selected filesystem provider.

pendingTransfersvariable#

const pendingTransfers

Reports whole-file transfers that have not settled.