<a id="nupp.io.files"></a>
# Module: `nupp.io.files`

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

## Functions

<a id="nupp.io.files.append"></a>
### `append` _function_

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

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

#### Arguments

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

#### Returns

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

<a id="nupp.io.files.copy"></a>
### `copy` _function_

Copies a file's contents over a destination.

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

#### Arguments

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

#### Returns

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

<a id="nupp.io.files.createDirectory"></a>
### `createDirectory` _function_

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

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

#### Arguments

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

#### Returns

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

<a id="nupp.io.files.createSymlink"></a>
### `createSymlink` _function_

Creates a symbolic link.

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

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

#### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `target` | `string | nupp.io.Path` | what the link points at |
| `link` | `string | nupp.io.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 |

<a id="nupp.io.files.createTemporaryDirectory"></a>
### `createTemporaryDirectory` _function_

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

#### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `options` | `TemporaryOptions?` |  |

#### Returns

| Type | Description |
| --- | --- |
| `TemporaryPath?` |  |
| `string?` |  |

<a id="nupp.io.files.createTemporaryFile"></a>
### `createTemporaryFile` _function_

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

#### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `options` | `TemporaryOptions?` |  |

#### Returns

| Type | Description |
| --- | --- |
| `TemporaryPath?` |  |
| `string?` |  |

<a id="nupp.io.files.currentDirectory"></a>
### `currentDirectory` _function_

Reads the process's current working directory.

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

#### Returns

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

<a id="nupp.io.files.exists"></a>
### `exists` _function_

Whether a path resolves to anything at all.

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

#### Arguments

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

#### Returns

| Type | Description |
| --- | --- |
| `boolean` | whether it resolves |

<a id="nupp.io.files.glob"></a>
### `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.

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

#### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `pattern` | `string | nupp.io.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 |

<a id="nupp.io.files.info"></a>
### `info` _function_

Describes one path, following symbolic links.

#### Examples

Read a file's size:

```nupp
local info = assert(nupp.io.files.info("nupp.lua"))
assert(info.kind == "file" and info.size > 0)
```

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

#### Arguments

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

#### Returns

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

<a id="nupp.io.files.isDirectory"></a>
### `isDirectory` _function_

Whether a path resolves to a directory.

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

#### Arguments

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

#### Returns

| Type | Description |
| --- | --- |
| `boolean` | whether it is a directory |

<a id="nupp.io.files.isFile"></a>
### `isFile` _function_

Whether a path resolves to a regular file.

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

#### Arguments

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

#### Returns

| Type | Description |
| --- | --- |
| `boolean` | whether it is a file |

<a id="nupp.io.files.isSymlink"></a>
### `isSymlink` _function_

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

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

#### Arguments

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

#### Returns

| Type | Description |
| --- | --- |
| `boolean` | whether it is a symbolic link |

<a id="nupp.io.files.lines"></a>
### `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.

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

#### Arguments

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

#### Returns

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

<a id="nupp.io.files.list"></a>
### `list` _function_

Lists a directory's immediate children.

#### Examples

Count the modules beside a file:

```nupp
local entries = assert(nupp.io.files.list("src"))
for _, entry in ipairs(entries) do
    print(entry.kind, entry.name)
end
```

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

#### Arguments

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

#### Returns

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

<a id="nupp.io.files.open"></a>
### `open` _function_

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

#### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `path` | `string | nupp.io.Path` |  |
| `mode` | `Mode?` |  |

#### Returns

| Type | Description |
| --- | --- |
| `File?` |  |
| `string?` |  |

<a id="nupp.io.files.pendingTransfers"></a>
### `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.

```nupp
local pendingTransfers: nosuspend function(): integer
```

#### Returns

| Type | Description |
| --- | --- |
| `integer` | the number of live transfers |

<a id="nupp.io.files.read"></a>
### `read` _function_

Reads a whole file.

#### Examples

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

```nupp
local text, reason = nupp.io.files.read("nupp.lua")
assert(text, reason)
```

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

#### Arguments

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

#### Returns

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

<a id="nupp.io.files.readLink"></a>
### `readLink` _function_

Reads a symbolic link's target without resolving it.

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

#### Arguments

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

#### Returns

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

<a id="nupp.io.files.remove"></a>
### `remove` _function_

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

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

#### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `path` | `string | nupp.io.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 |

<a id="nupp.io.files.rename"></a>
### `rename` _function_

Renames a path, replacing an existing destination.

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

#### Arguments

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

#### Returns

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

<a id="nupp.io.files.setReadOnly"></a>
### `setReadOnly` _function_

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

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

#### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `path` | `string | nupp.io.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 |

<a id="nupp.io.files.userFolder"></a>
### `userFolder` _function_

Answers a well-known user folder.

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

#### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `which` | `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 |

<a id="nupp.io.files.write"></a>
### `write` _function_

Writes a whole file, replacing its contents.

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

#### Arguments

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

#### Returns

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

<a id="nupp.io.files.writeAtomic"></a>
### `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.

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

#### Arguments

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

#### Returns

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