Module: `nupp.io.files`

Filesystem metadata, directory contents, and the operations that move names rather than bytes.

Module contents

Functions

Function	Kind	Description
`append`	function	Adds to the end of a file, creating it when it does not exist.
`copy`	function	Copies a file's contents over a destination.
`createDirectory`	function	Creates a directory and every missing parent.
`createSymlink`	function	Creates a symbolic link.
`createTemporaryDirectory`	function	—
`createTemporaryFile`	function	—
`currentDirectory`	function	Reads the process's current working directory.
`exists`	function	Whether a path resolves to anything at all.
`glob`	function	Expands a filesystem pattern into matching paths.
`info`	function	Describes one path, following symbolic links.
`isDirectory`	function	Whether a path resolves to a directory.
`isFile`	function	Whether a path resolves to a regular file.
`isSymlink`	function	Whether a path is itself a symbolic link, without following it.
`lines`	function	Iterates a file's lines, closing it at the end.
`list`	function	Lists a directory's immediate children.
`open`	function	—
`pendingTransfers`	function	How many whole-file transfers this program is still holding.
`read`	function	Reads a whole file.
`readLink`	function	Reads a symbolic link's target without resolving it.
`remove`	function	Removes a file, a symbolic link, or a directory.
`rename`	function	Renames a path, replacing an existing destination.
`setReadOnly`	function	Sets or clears a path's read-only attribute.
`userFolder`	function	Answers a well-known user folder.
`write`	function	Writes a whole file, replacing its contents.
`writeAtomic`	function	Writes a whole file through a temporary beside it, so an interrupted write leaves the destination as it was rather...

Functions#

`append`function#

Adds to the end of a file, creating it when it does not exist.

local append: function(path: string | nupp.Path, bytes: string | nupp.ByteView): (boolean, string?)

Arguments

Name	Type	Description
`path`	`string \| nupp.Path`	the file to extend
`bytes`	`string \| nupp.ByteView`	what to add

Returns

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

`copy`function#

Copies a file's contents over a destination.

local copy: function(from: string | nupp.Path, to: string | nupp.Path): (boolean, string?)

Arguments

Name	Type	Description
`from`	`string \| nupp.Path`	the file to copy
`to`	`string \| nupp.Path`	where to copy it

Returns

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

`createDirectory`function#

Creates a directory and every missing parent. An existing directory succeeds.

local createDirectory: nosuspend function(path: string | nupp.Path): (boolean, string?)

Arguments

Name	Type	Description
`path`	`string \| nupp.Path`	the directory to create

Returns

Type	Description
`boolean`	whether the directory exists afterwards
`string?`	a failure reason, when unsuccessful

`createSymlink`function#

Creates a symbolic link.

kind selects Windows's directory link and is ignored elsewhere, because only Windows distinguishes the two.

local createSymlink: nosuspend function(
            target: string | nupp.Path,
            link: string | nupp.Path,
            kind: ("file" | "directory")?
        ): (boolean, string?)

Arguments

Name	Type	Description
`target`	`string \| nupp.Path`	what the link points at
`link`	`string \| nupp.Path`	where to create the link
`kind`	`("file" \| "directory")?`	the link kind, defaulting to a file link

Returns

Type	Description
`boolean`	whether the link was created
`string?`	a failure reason, when unsuccessful

`createTemporaryDirectory`function#

local createTemporaryDirectory: nosuspend function(
            options: nupp.Files.TemporaryOptions?
        ): (nupp.Files.TemporaryPath?, string?)

Arguments

Name	Type	Description
`options`	`nupp.Files.TemporaryOptions?`

Returns

Type	Description
`nupp.Files.TemporaryPath?`
`string?`

`createTemporaryFile`function#

local createTemporaryFile: nosuspend function(
            options: nupp.Files.TemporaryOptions?
        ): (nupp.Files.TemporaryPath?, string?)

Arguments

Name	Type	Description
`options`	`nupp.Files.TemporaryOptions?`

Returns

Type	Description
`nupp.Files.TemporaryPath?`
`string?`

`currentDirectory`function#

Reads the process's current working directory.

local currentDirectory: nosuspend function(): (string?, string?)

Returns

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

`exists`function#

Whether a path resolves to anything at all.

local exists: nosuspend function(path: string | nupp.Path): boolean

Arguments

Name	Type	Description
`path`	`string \| nupp.Path`	the path to test

Returns

Type	Description
`boolean`	whether it resolves

`glob`function#

Expands a filesystem pattern into matching paths.

* and ? match within one path component, character classes use [abc] or [!abc], and ** crosses directory boundaries. The returned paths are sorted, and no matches is an empty list.

local glob: nosuspend function(pattern: string | nupp.Path): ({string}?, string?)

Arguments

Name	Type	Description
`pattern`	`string \| nupp.Path`	the filesystem pattern to expand

Returns

Type	Description
`{string}?`	the matching paths, or nil when the pattern or walk fails
`string?`	a failure reason, when unsuccessful

`info`function#

Describes one path, following symbolic links.

Examples#

Read a file's size:

local info: nosuspend function(path: string | nupp.Path): (nupp.Files.Info?, string?)

Arguments

Name	Type	Description
`path`	`string \| nupp.Path`	the path to describe

Returns

Type	Description
`nupp.Files.Info?`	the attributes, or nil when the path cannot be read
`string?`	a failure reason, when unsuccessful

`isDirectory`function#

Whether a path resolves to a directory.

local isDirectory: nosuspend function(path: string | nupp.Path): boolean

Arguments

Name	Type	Description
`path`	`string \| nupp.Path`	the path to test

Returns

Type	Description
`boolean`	whether it is a directory

`isFile`function#

Whether a path resolves to a regular file.

local isFile: nosuspend function(path: string | nupp.Path): boolean

Arguments

Name	Type	Description
`path`	`string \| nupp.Path`	the path to test

Returns

Type	Description
`boolean`	whether it is a file

`isSymlink`function#

Whether a path is itself a symbolic link, without following it.

local isSymlink: nosuspend function(path: string | nupp.Path): boolean

Arguments

Name	Type	Description
`path`	`string \| nupp.Path`	the path to test

Returns

Type	Description
`boolean`	whether it is a symbolic link

`lines`function#

Iterates a file's lines, closing it at the end.

A trailing carriage return is removed, so a file written on either platform reads the same. The iterator stops at the end of the file; abandoning it early leaves the file open until it is collected.

local lines: function(path: string | nupp.Path): (nupp.Files.LineIterator?, string?)

Arguments

Name	Type	Description
`path`	`string \| nupp.Path`	the file to read

Returns

Type	Description
`nupp.Files.LineIterator?`	an iterator answering each line, or nil on failure
`string?`	a failure reason, when unsuccessful

`list`function#

Lists a directory's immediate children.

Examples#

Count the modules beside a file:

local list: nosuspend function(path: string | nupp.Path): ({nupp.Files.Entry}?, string?)

Arguments

Name	Type	Description
`path`	`string \| nupp.Path`	the directory to list

Returns

Type	Description
`{nupp.Files.Entry}?`	the children in the platform's order, or nil on failure
`string?`	a failure reason, when unsuccessful

`open`function#

local open: function(path: string | nupp.Path, mode: nupp.Files.Mode?): (nupp.Files.File?, string?)

Arguments

Name	Type	Description
`path`	`string \| nupp.Path`
`mode`	`nupp.Files.Mode?`

Returns

Type	Description
`nupp.Files.File?`
`string?`

`pendingTransfers`function#

How many whole-file transfers this program is still holding.

Whole-file reads, writes and copies settle on worker threads, and the lane that runs them is bounded. This answers what it holds, which is what a program that submitted more than it consumed needs to see.

local pendingTransfers: nosuspend function(): integer

Returns

Type	Description
`integer`	the number of live transfers

`read`function#

Reads a whole file.

Examples#

Read a file's bytes, or report why not:

local read: function(path: string | nupp.Path): (string?, string?)

Arguments

Name	Type	Description
`path`	`string \| nupp.Path`	the file to read

Returns

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

`readLink`function#

Reads a symbolic link's target without resolving it.

local readLink: nosuspend function(path: string | nupp.Path): (string?, string?)

Arguments

Name	Type	Description
`path`	`string \| nupp.Path`	the link to read

Returns

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

`remove`function#

Removes a file, a symbolic link, or a directory.

local remove: nosuspend function(path: string | nupp.Path, recursive: boolean?): (boolean, string?)

Arguments

Name	Type	Description
`path`	`string \| nupp.Path`	the path to remove
`recursive`	`boolean?`	whether to remove a directory's contents with it

Returns

Type	Description
`boolean`	whether the path was removed
`string?`	a failure reason, when unsuccessful

`rename`function#

Renames a path, replacing an existing destination.

local rename: nosuspend function(from: string | nupp.Path, to: string | nupp.Path): (boolean, string?)

Arguments

Name	Type	Description
`from`	`string \| nupp.Path`	the path to rename
`to`	`string \| nupp.Path`	the new path

Returns

Type	Description
`boolean`	whether the rename happened
`string?`	a failure reason, when unsuccessful

`setReadOnly`function#

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

local setReadOnly: nosuspend function(path: string | nupp.Path, readOnly: boolean): (boolean, string?)

Arguments

Name	Type	Description
`path`	`string \| nupp.Path`	the path to change
`readOnly`	`boolean`	whether to refuse writes

Returns

Type	Description
`boolean`	whether the attribute was set
`string?`	a failure reason, when unsuccessful

`userFolder`function#

Answers a well-known user folder.

local userFolder: nosuspend function(which: nupp.Files.UserFolder): (string?, string?)

Arguments

Name	Type	Description
`which`	`nupp.Files.UserFolder`	the folder to locate

Returns

Type	Description
`string?`	the folder, or nil when the platform has no such folder
`string?`	a failure reason, when unsuccessful

`write`function#

Writes a whole file, replacing its contents.

local write: function(path: string | nupp.Path, bytes: string | nupp.ByteView): (boolean, string?)

Arguments

Name	Type	Description
`path`	`string \| nupp.Path`	the file to write
`bytes`	`string \| nupp.ByteView`	the contents

Returns

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

`writeAtomic`function#

Writes a whole file through a temporary beside it, so an interrupted write leaves the destination as it was rather than half replaced.

local writeAtomic: function(path: string | nupp.Path, bytes: string | nupp.ByteView): (boolean, string?)

Arguments

Name	Type	Description
`path`	`string \| nupp.Path`	the file to write
`bytes`	`string \| nupp.ByteView`	the contents

Returns

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

Module: nupp.io.files

Module contents

Functions

Functions#

appendfunction#

Arguments

Returns

copyfunction#

Arguments

Returns

createDirectoryfunction#

Arguments

Returns

createSymlinkfunction#

Arguments

Returns

createTemporaryDirectoryfunction#

Arguments

Returns

createTemporaryFilefunction#

Arguments

Returns

currentDirectoryfunction#

Returns

existsfunction#

Arguments

Returns

globfunction#

Arguments

Returns

infofunction#

Examples#

Arguments

Returns

isDirectoryfunction#

Arguments

Returns

isFilefunction#

Arguments

Returns

isSymlinkfunction#

Arguments

Returns

linesfunction#

Arguments

Returns

listfunction#

Examples#

Arguments

Returns

openfunction#

Arguments

Returns

pendingTransfersfunction#

Returns

readfunction#

Examples#

Arguments

Returns

readLinkfunction#

Arguments

Returns

removefunction#

Arguments

Returns

renamefunction#

Arguments

Returns

setReadOnlyfunction#

Arguments

Returns

userFolderfunction#

Arguments

Returns

writefunction#

Arguments

Returns

writeAtomicfunction#

Arguments

Returns

Module: `nupp.io.files`

`append`function#

`copy`function#

`createDirectory`function#

`createSymlink`function#

`createTemporaryDirectory`function#

`createTemporaryFile`function#

`currentDirectory`function#

`exists`function#

`glob`function#

`info`function#

`isDirectory`function#

`isFile`function#

`isSymlink`function#

`lines`function#

`list`function#

`open`function#

`pendingTransfers`function#

`read`function#

`readLink`function#

`remove`function#

`rename`function#

`setReadOnly`function#

`userFolder`function#

`write`function#

`writeAtomic`function#