gdDocumentation0.8.0

API reference

GD.file

Whole-file operations and streaming file I/O suspend only their caller. This entry also provides path operations and file-format readers; *_async returns Signals for concurrent starts.

res:// is the startup working directory, even when the entry script is in a subdirectory. A relative path that climbs above it is refused in either mode. Under --strict, absolute paths inside the startup directory pass the same read-only checks as res://; parent and sibling directories are denied, and links cannot leave the boundary. -A does not widen file access.

--mount and absolute paths are for Linux and macOS. Windows rejects them.

A mount name uses lowercase letters, digits, and -. These names are reserved: res, user, uid, pipe, local, libgodot, tcp, unix, http, https, file, data, cache.

Methods

open

open(path: String, mode: String = "read") -> GDFileStream, Err

Open a sequential file stream when the input or output should be processed in chunks. Keep the returned stream and close it after use.

Parameters

NameTypeDefaultDescription
pathStringRequiredFile to open.
modeString"read"read, write, append or read_write. The default read opens an existing file for reading.

Return value

GDFileStream, Err

A file stream object.

Suspends only the calling routine until the operation completes. No explicit await is needed.

Errors

The result carries a value and an Err. Check the error before using the value; a failure may retain partial progress. In a function returning value, Err, use ? to propagate failure to the caller. The ! operator terminates the program on failure; in serve it fails the current handler.

Opening and access checks can fail. Inspect Err before using the stream.

See also

open_async

open_async(path: String, mode: String = "read") -> await GDFileStream, Err

Open a sequential file stream when the input or output should be processed in chunks. Keep the returned stream and close it after use.

Parameters

NameTypeDefaultDescription
pathStringRequiredFile to open.
modeString"read"read, write, append or read_write. The default read opens an existing file for reading.

Return value

await GDFileStream, Err

A file stream object.

Returns a Signal. Use await to receive the completion value shown in the signature.

Errors

The result carries a value and an Err. Check the error before using the value; a failure may retain partial progress. In a function returning value, Err, use ? to propagate failure to the caller. The ! operator terminates the program on failure; in serve it fails the current handler.

Opening and access checks can fail. Inspect Err before using the stream.

See also

read_text

read_text(path: String) -> String, Err

Read an entire file as UTF-8 text. The file is opened, read and closed by this call. Filesystem access runs outside the event loop. Use read_bytes when bytes must be preserved exactly.

Parameters

NameTypeDefaultDescription
pathStringRequiredFile path, relative to the execution directory or an explicitly mounted path.

Return value

String, Err

The decoded file contents, including any line endings.

Suspends only the calling routine until the operation completes. No explicit await is needed.

Errors

The result carries a value and an Err. Check the error before using the value; a failure may retain partial progress. In a function returning value, Err, use ? to propagate failure to the caller. The ! operator terminates the program on failure; in serve it fails the current handler.

A missing file, denied permission or read failure is returned through Err. An empty string is valid for an empty file; do not use it as the error test.

Examples

func main():
    var text, err = GD.file.read_text("message.txt")
    if err != null:
        printerr(err)
        return 1
    print(text)
    return 0

See also

read_bytes

read_bytes(path: String, offset: int = 0, max: int = 0) -> PackedByteArray, Err

Read bytes from a file, optionally starting at an offset and limiting the amount returned. The file is closed after the operation.

Parameters

NameTypeDefaultDescription
pathStringRequiredFile to read.
offsetint0Zero-based byte offset.
maxint0Maximum byte count; zero reads the remaining contents.

Return value

PackedByteArray, Err

A PackedByteArray containing the bytes read.

Suspends only the calling routine until the operation completes. No explicit await is needed.

Errors

The result carries a value and an Err. Check the error before using the value; a failure may retain partial progress. In a function returning value, Err, use ? to propagate failure to the caller. The ! operator terminates the program on failure; in serve it fails the current handler.

Inspect Err for path, permission and I/O failures.

See also

write_text

write_text(path: String, body: String) -> Variant, Err

Replace the contents of a file with UTF-8 text. The file is opened and closed by this call.

Parameters

NameTypeDefaultDescription
pathStringRequiredDestination file.
bodyStringRequiredContent to write.

Return value

Variant, Err

Use the Err slot to determine success; the value slot is not a byte count.

Suspends only the calling routine until the operation completes. No explicit await is needed.

Errors

The result carries a value and an Err. Check the error before using the value; a failure may retain partial progress. In a function returning value, Err, use ? to propagate failure to the caller. The ! operator terminates the program on failure; in serve it fails the current handler.

Creation, write and permission failures are returned as Err. Parent directories are not created automatically.

See also

replace_text

replace_text(path: String, old: Variant, body: String) -> Variant, Err

Replace a file asynchronously only if its contents remain unchanged.

Parameters

NameTypeDefaultDescription
pathStringRequiredFilesystem path; relative paths use the execution directory and access follows configured permissions.
oldVariantRequiredExpected previous contents used for a conditional replacement.
bodyStringRequiredContent to write or include in the response.

Return value

Variant, Err

Suspends only the calling routine until the operation completes. No explicit await is needed.

Errors

The result carries a value and an Err. Check the error before using the value; a failure may retain partial progress. In a function returning value, Err, use ? to propagate failure to the caller. The ! operator terminates the program on failure; in serve it fails the current handler.

write_bytes

write_bytes(path: String, body: PackedByteArray) -> Variant, Err

Replace the contents of a file with bytes. The file is opened and closed by this call.

Parameters

NameTypeDefaultDescription
pathStringRequiredDestination file.
bodyPackedByteArrayRequiredContent to write.

Return value

Variant, Err

Use the Err slot to determine success; the value slot is not a byte count.

Suspends only the calling routine until the operation completes. No explicit await is needed.

Errors

The result carries a value and an Err. Check the error before using the value; a failure may retain partial progress. In a function returning value, Err, use ? to propagate failure to the caller. The ! operator terminates the program on failure; in serve it fails the current handler.

Creation, write and permission failures are returned as Err. Parent directories are not created automatically.

See also

append_bytes

append_bytes(path: String, body: PackedByteArray) -> Variant, Err

Append to a file with bytes. The file is opened and closed by this call.

Parameters

NameTypeDefaultDescription
pathStringRequiredDestination file.
bodyPackedByteArrayRequiredContent to write.

Return value

Variant, Err

Use the Err slot to determine success; the value slot is not a byte count.

Suspends only the calling routine until the operation completes. No explicit await is needed.

Errors

The result carries a value and an Err. Check the error before using the value; a failure may retain partial progress. In a function returning value, Err, use ? to propagate failure to the caller. The ! operator terminates the program on failure; in serve it fails the current handler.

Creation, write and permission failures are returned as Err. Parent directories are not created automatically.

See also

append_text

append_text(path: String, body: String) -> Variant, Err

Append to a file with UTF-8 text. The file is opened and closed by this call.

Parameters

NameTypeDefaultDescription
pathStringRequiredDestination file.
bodyStringRequiredContent to write.

Return value

Variant, Err

Use the Err slot to determine success; the value slot is not a byte count.

Suspends only the calling routine until the operation completes. No explicit await is needed.

Errors

The result carries a value and an Err. Check the error before using the value; a failure may retain partial progress. In a function returning value, Err, use ? to propagate failure to the caller. The ! operator terminates the program on failure; in serve it fails the current handler.

Creation, write and permission failures are returned as Err. Parent directories are not created automatically.

See also

exists

exists(path: String) -> bool

Check path existence asynchronously.

Parameters

NameTypeDefaultDescription
pathStringRequiredFilesystem path; relative paths use the execution directory and access follows configured permissions.

Return value

bool

Suspends only the calling routine until the operation completes. No explicit await is needed.

Errors

This call has no Err return slot. Its return type and documented sentinel values determine how to inspect the result.

remove

remove(path: String) -> Variant, Err

Remove a file or empty directory asynchronously.

Parameters

NameTypeDefaultDescription
pathStringRequiredFilesystem path; relative paths use the execution directory and access follows configured permissions.

Return value

Variant, Err

Suspends only the calling routine until the operation completes. No explicit await is needed.

Errors

The result carries a value and an Err. Check the error before using the value; a failure may retain partial progress. In a function returning value, Err, use ? to propagate failure to the caller. The ! operator terminates the program on failure; in serve it fails the current handler.

size_of

size_of(path: String) -> int, Err

Get a file's byte count asynchronously.

Parameters

NameTypeDefaultDescription
pathStringRequiredFilesystem path; relative paths use the execution directory and access follows configured permissions.

Return value

int, Err

Suspends only the calling routine until the operation completes. No explicit await is needed.

Errors

The result carries a value and an Err. Check the error before using the value; a failure may retain partial progress. In a function returning value, Err, use ? to propagate failure to the caller. The ! operator terminates the program on failure; in serve it fails the current handler.

copy

copy(src: String, dst: String) -> Variant, Err

Copy a file to another path asynchronously.

Parameters

NameTypeDefaultDescription
srcStringRequiredSource input to read or transform; file operations interpret it as a source path.
dstStringRequiredDestination filesystem path.

Return value

Variant, Err

Suspends only the calling routine until the operation completes. No explicit await is needed.

Errors

The result carries a value and an Err. Check the error before using the value; a failure may retain partial progress. In a function returning value, Err, use ? to propagate failure to the caller. The ! operator terminates the program on failure; in serve it fails the current handler.

rename

rename(src: String, dst: String) -> Variant, Err

Rename a file or directory asynchronously.

Parameters

NameTypeDefaultDescription
srcStringRequiredSource input to read or transform; file operations interpret it as a source path.
dstStringRequiredDestination filesystem path.

Return value

Variant, Err

Suspends only the calling routine until the operation completes. No explicit await is needed.

Errors

The result carries a value and an Err. Check the error before using the value; a failure may retain partial progress. In a function returning value, Err, use ? to propagate failure to the caller. The ! operator terminates the program on failure; in serve it fails the current handler.

list_dir

list_dir(path: String) -> Array, Err

List immediate directory entries asynchronously.

Parameters

NameTypeDefaultDescription
pathStringRequiredFilesystem path; relative paths use the execution directory and access follows configured permissions.

Return value

Array, Err

Suspends only the calling routine until the operation completes. No explicit await is needed.

Errors

The result carries a value and an Err. Check the error before using the value; a failure may retain partial progress. In a function returning value, Err, use ? to propagate failure to the caller. The ! operator terminates the program on failure; in serve it fails the current handler.

make_dir

make_dir(path: String) -> Variant, Err

Create one directory asynchronously.

Parameters

NameTypeDefaultDescription
pathStringRequiredFilesystem path; relative paths use the execution directory and access follows configured permissions.

Return value

Variant, Err

Suspends only the calling routine until the operation completes. No explicit await is needed.

Errors

The result carries a value and an Err. Check the error before using the value; a failure may retain partial progress. In a function returning value, Err, use ? to propagate failure to the caller. The ! operator terminates the program on failure; in serve it fails the current handler.

ensure_dir

ensure_dir(path: String) -> Variant, Err

Create a directory and missing parents asynchronously.

Parameters

NameTypeDefaultDescription
pathStringRequiredFilesystem path; relative paths use the execution directory and access follows configured permissions.

Return value

Variant, Err

Suspends only the calling routine until the operation completes. No explicit await is needed.

Errors

The result carries a value and an Err. Check the error before using the value; a failure may retain partial progress. In a function returning value, Err, use ? to propagate failure to the caller. The ! operator terminates the program on failure; in serve it fails the current handler.

walk

walk(path: String, want_dirs: bool = false, hidden: bool = false) -> Array, Err

Enumerate a directory tree asynchronously.

Parameters

NameTypeDefaultDescription
pathStringRequiredFilesystem path; relative paths use the execution directory and access follows configured permissions.
want_dirsboolfalseWhether directory entries are included in the traversal result.
hiddenboolfalseWhether hidden entries are included in matching or traversal.

Return value

Array, Err

Suspends only the calling routine until the operation completes. No explicit await is needed.

Errors

The result carries a value and an Err. Check the error before using the value; a failure may retain partial progress. In a function returning value, Err, use ? to propagate failure to the caller. The ! operator terminates the program on failure; in serve it fails the current handler.

glob

glob(path: String, pattern: String, hidden: bool = false) -> Array, Err

Find paths matching a pattern asynchronously.

Parameters

NameTypeDefaultDescription
pathStringRequiredFilesystem path; relative paths use the execution directory and access follows configured permissions.
patternStringRequiredFilename glob pattern applied within the supplied directory.
hiddenboolfalseWhether hidden entries are included in matching or traversal.

Return value

Array, Err

Suspends only the calling routine until the operation completes. No explicit await is needed.

Errors

The result carries a value and an Err. Check the error before using the value; a failure may retain partial progress. In a function returning value, Err, use ? to propagate failure to the caller. The ! operator terminates the program on failure; in serve it fails the current handler.

remove_all

remove_all(path: String) -> Variant, Err

Remove a directory tree and its contents asynchronously.

Parameters

NameTypeDefaultDescription
pathStringRequiredFilesystem path; relative paths use the execution directory and access follows configured permissions.

Return value

Variant, Err

Suspends only the calling routine until the operation completes. No explicit await is needed.

Errors

The result carries a value and an Err. Check the error before using the value; a failure may retain partial progress. In a function returning value, Err, use ? to propagate failure to the caller. The ! operator terminates the program on failure; in serve it fails the current handler.

can_read

can_read(path: String) -> bool

Check path readability asynchronously.

Parameters

NameTypeDefaultDescription
pathStringRequiredFilesystem path; relative paths use the execution directory and access follows configured permissions.

Return value

bool

Suspends only the calling routine until the operation completes. No explicit await is needed.

Errors

This call has no Err return slot. Its return type and documented sentinel values determine how to inspect the result.

parse_path

parse_path(path: String) -> Dictionary

Parse a path into a component dictionary.

Parameters

NameTypeDefaultDescription
pathStringRequiredFilesystem path; relative paths use the execution directory and access follows configured permissions.

Return value

Dictionary

Errors

This call has no Err return slot. Its return type and documented sentinel values determine how to inspect the result.

format_path

format_path(parts: Dictionary) -> String

Format path components as text.

Parameters

NameTypeDefaultDescription
partsDictionaryRequiredComponents assembled by the operation, in the representation shown by the type.

Return value

String

Errors

This call has no Err return slot. Its return type and documented sentinel values determine how to inspect the result.

join

join(parts: PackedStringArray) -> String

Join path segments with separators.

Parameters

NameTypeDefaultDescription
partsPackedStringArrayRequiredComponents assembled by the operation, in the representation shown by the type.

Return value

String

Errors

This call has no Err return slot. Its return type and documented sentinel values determine how to inspect the result.

dirname

dirname(path: String) -> String

Return the parent directory of a path.

Parameters

NameTypeDefaultDescription
pathStringRequiredFilesystem path; relative paths use the execution directory and access follows configured permissions.

Return value

String

Errors

This call has no Err return slot. Its return type and documented sentinel values determine how to inspect the result.

basename

basename(path: String, suffix: String = "") -> String

Return the final path component with the specified suffix removed.

Parameters

NameTypeDefaultDescription
pathStringRequiredFilesystem path; relative paths use the execution directory and access follows configured permissions.
suffixString""Suffix to test or remove from the end of the input.

Return value

String

Errors

This call has no Err return slot. Its return type and documented sentinel values determine how to inspect the result.

extname

extname(path: String) -> String

Return a path's extension.

Parameters

NameTypeDefaultDescription
pathStringRequiredFilesystem path; relative paths use the execution directory and access follows configured permissions.

Return value

String

Errors

This call has no Err return slot. Its return type and documented sentinel values determine how to inspect the result.

is_absolute

is_absolute(path: String) -> bool

Check whether a path is absolute.

Parameters

NameTypeDefaultDescription
pathStringRequiredFilesystem path; relative paths use the execution directory and access follows configured permissions.

Return value

bool

Errors

This call has no Err return slot. Its return type and documented sentinel values determine how to inspect the result.

normalize

normalize(path: String) -> String

Normalize redundant separators and parent/current-directory segments.

Parameters

NameTypeDefaultDescription
pathStringRequiredFilesystem path; relative paths use the execution directory and access follows configured permissions.

Return value

String

Errors

This call has no Err return slot. Its return type and documented sentinel values determine how to inspect the result.

relative

relative(from: String, to: String) -> String

Return the relative route between two paths.

Parameters

NameTypeDefaultDescription
fromStringRequiredBase path from which to compute a relative path.
toStringRequiredTarget path expressed relative to the base.

Return value

String

Errors

This call has no Err return slot. Its return type and documented sentinel values determine how to inspect the result.

under

under(dir: String, name: String) -> String

Resolve a name safely within a directory.

Parameters

NameTypeDefaultDescription
dirStringRequiredDirectory used as the base of the operation.
nameStringRequiredName used to register or look up the corresponding entry.

Return value

String

Errors

This call has no Err return slot. Its return type and documented sentinel values determine how to inspect the result.

create_tar

create_tar(root: String) -> PackedByteArray, Err

Archive a directory tree as tar asynchronously.

Parameters

NameTypeDefaultDescription
rootStringRequiredRoot directory for packing or extracting an archive.

Return value

PackedByteArray, Err

Suspends only the calling routine until the operation completes. No explicit await is needed.

Errors

The result carries a value and an Err. Check the error before using the value; a failure may retain partial progress. In a function returning value, Err, use ? to propagate failure to the caller. The ! operator terminates the program on failure; in serve it fails the current handler.

extract_tar

extract_tar(data: PackedByteArray, root: String) -> int, Err

Extract a tar archive into a directory asynchronously.

Parameters

NameTypeDefaultDescription
dataPackedByteArrayRequiredInput data in the representation shown by the parameter type.
rootStringRequiredRoot directory for packing or extracting an archive.

Return value

int, Err

Suspends only the calling routine until the operation completes. No explicit await is needed.

Errors

The result carries a value and an Err. Check the error before using the value; a failure may retain partial progress. In a function returning value, Err, use ? to propagate failure to the caller. The ! operator terminates the program on failure; in serve it fails the current handler.

read_csv

read_csv(path: String, sep: String = ",") -> Array, Err

Read document files asynchronously and parse them on workers.

Parameters

NameTypeDefaultDescription
pathStringRequiredFilesystem path; relative paths use the execution directory and access follows configured permissions.
sepString","Separator used to split or join records or fields.

Return value

Array, Err

Suspends only the calling routine until the operation completes. No explicit await is needed.

Errors

The result carries a value and an Err. Check the error before using the value; a failure may retain partial progress. In a function returning value, Err, use ? to propagate failure to the caller. The ! operator terminates the program on failure; in serve it fails the current handler.

read_ini

read_ini(path: String) -> Dictionary, Err

Read an INI file on a worker and parse its dictionary.

Parameters

NameTypeDefaultDescription
pathStringRequiredFilesystem path; relative paths use the execution directory and access follows configured permissions.

Return value

Dictionary, Err

Suspends only the calling routine until the operation completes. No explicit await is needed.

Errors

The result carries a value and an Err. Check the error before using the value; a failure may retain partial progress. In a function returning value, Err, use ? to propagate failure to the caller. The ! operator terminates the program on failure; in serve it fails the current handler.

read_toml

read_toml(path: String) -> Dictionary, Err

Read a TOML file on a worker and parse its dictionary.

Parameters

NameTypeDefaultDescription
pathStringRequiredFilesystem path; relative paths use the execution directory and access follows configured permissions.

Return value

Dictionary, Err

Suspends only the calling routine until the operation completes. No explicit await is needed.

Errors

The result carries a value and an Err. Check the error before using the value; a failure may retain partial progress. In a function returning value, Err, use ? to propagate failure to the caller. The ! operator terminates the program on failure; in serve it fails the current handler.

read_yaml

read_yaml(path: String) -> Variant, Err

Read a YAML file on a worker and parse its value.

Parameters

NameTypeDefaultDescription
pathStringRequiredFilesystem path; relative paths use the execution directory and access follows configured permissions.

Return value

Variant, Err

Suspends only the calling routine until the operation completes. No explicit await is needed.

Errors

The result carries a value and an Err. Check the error before using the value; a failure may retain partial progress. In a function returning value, Err, use ? to propagate failure to the caller. The ! operator terminates the program on failure; in serve it fails the current handler.

read_jsonc

read_jsonc(path: String) -> Variant, Err

Read a commented JSON file on a worker and parse its value.

Parameters

NameTypeDefaultDescription
pathStringRequiredFilesystem path; relative paths use the execution directory and access follows configured permissions.

Return value

Variant, Err

Suspends only the calling routine until the operation completes. No explicit await is needed.

Errors

The result carries a value and an Err. Check the error before using the value; a failure may retain partial progress. In a function returning value, Err, use ? to propagate failure to the caller. The ! operator terminates the program on failure; in serve it fails the current handler.

read_jsonl

read_jsonl(path: String) -> Array, Err

Read a JSON Lines file on a worker and parse its values.

Parameters

NameTypeDefaultDescription
pathStringRequiredFilesystem path; relative paths use the execution directory and access follows configured permissions.

Return value

Array, Err

Suspends only the calling routine until the operation completes. No explicit await is needed.

Errors

The result carries a value and an Err. Check the error before using the value; a failure may retain partial progress. In a function returning value, Err, use ? to propagate failure to the caller. The ! operator terminates the program on failure; in serve it fails the current handler.

read_front_matter

read_front_matter(path: String) -> Dictionary, Err

Read a front-matter file on a worker and parse its attributes and body.

Parameters

NameTypeDefaultDescription
pathStringRequiredFilesystem path; relative paths use the execution directory and access follows configured permissions.

Return value

Dictionary, Err

Suspends only the calling routine until the operation completes. No explicit await is needed.

Errors

The result carries a value and an Err. Check the error before using the value; a failure may retain partial progress. In a function returning value, Err, use ? to propagate failure to the caller. The ! operator terminates the program on failure; in serve it fails the current handler.

read_xml

read_xml(path: String) -> Dictionary, Err

Read an XML file on a worker and parse its dictionary.

Parameters

NameTypeDefaultDescription
pathStringRequiredFilesystem path; relative paths use the execution directory and access follows configured permissions.

Return value

Dictionary, Err

Suspends only the calling routine until the operation completes. No explicit await is needed.

Errors

The result carries a value and an Err. Check the error before using the value; a failure may retain partial progress. In a function returning value, Err, use ? to propagate failure to the caller. The ! operator terminates the program on failure; in serve it fails the current handler.

read_env

read_env(path: String = ".env") -> Dictionary, Err

Read a dotenv file on a worker and parse its environment dictionary.

Parameters

NameTypeDefaultDescription
pathString".env"Filesystem path; relative paths use the execution directory and access follows configured permissions.

Return value

Dictionary, Err

Suspends only the calling routine until the operation completes. No explicit await is needed.

Errors

The result carries a value and an Err. Check the error before using the value; a failure may retain partial progress. In a function returning value, Err, use ? to propagate failure to the caller. The ! operator terminates the program on failure; in serve it fails the current handler.

read_tar

read_tar(path: String) -> Array, Err

Read a tar file on a worker and decode its entries.

Parameters

NameTypeDefaultDescription
pathStringRequiredFilesystem path; relative paths use the execution directory and access follows configured permissions.

Return value

Array, Err

Suspends only the calling routine until the operation completes. No explicit await is needed.

Errors

The result carries a value and an Err. Check the error before using the value; a failure may retain partial progress. In a function returning value, Err, use ? to propagate failure to the caller. The ! operator terminates the program on failure; in serve it fails the current handler.

read_csv_async

read_csv_async(path: String, sep: String = ",") -> await Array, Err

Read document files asynchronously and parse them on workers.

Parameters

NameTypeDefaultDescription
pathStringRequiredFilesystem path; relative paths use the execution directory and access follows configured permissions.
sepString","Separator used to split or join records or fields.

Return value

await Array, Err

Returns a Signal. Use await to receive the completion value shown in the signature.

Errors

The result carries a value and an Err. Check the error before using the value; a failure may retain partial progress. In a function returning value, Err, use ? to propagate failure to the caller. The ! operator terminates the program on failure; in serve it fails the current handler.

read_ini_async

read_ini_async(path: String) -> await Dictionary, Err

Read an INI file on a worker and parse its dictionary.

Parameters

NameTypeDefaultDescription
pathStringRequiredFilesystem path; relative paths use the execution directory and access follows configured permissions.

Return value

await Dictionary, Err

Returns a Signal. Use await to receive the completion value shown in the signature.

Errors

The result carries a value and an Err. Check the error before using the value; a failure may retain partial progress. In a function returning value, Err, use ? to propagate failure to the caller. The ! operator terminates the program on failure; in serve it fails the current handler.

read_toml_async

read_toml_async(path: String) -> await Dictionary, Err

Read a TOML file on a worker and parse its dictionary.

Parameters

NameTypeDefaultDescription
pathStringRequiredFilesystem path; relative paths use the execution directory and access follows configured permissions.

Return value

await Dictionary, Err

Returns a Signal. Use await to receive the completion value shown in the signature.

Errors

The result carries a value and an Err. Check the error before using the value; a failure may retain partial progress. In a function returning value, Err, use ? to propagate failure to the caller. The ! operator terminates the program on failure; in serve it fails the current handler.

read_yaml_async

read_yaml_async(path: String) -> await Variant, Err

Read a YAML file on a worker and parse its value.

Parameters

NameTypeDefaultDescription
pathStringRequiredFilesystem path; relative paths use the execution directory and access follows configured permissions.

Return value

await Variant, Err

Returns a Signal. Use await to receive the completion value shown in the signature.

Errors

The result carries a value and an Err. Check the error before using the value; a failure may retain partial progress. In a function returning value, Err, use ? to propagate failure to the caller. The ! operator terminates the program on failure; in serve it fails the current handler.

read_jsonc_async

read_jsonc_async(path: String) -> await Variant, Err

Read a commented JSON file on a worker and parse its value.

Parameters

NameTypeDefaultDescription
pathStringRequiredFilesystem path; relative paths use the execution directory and access follows configured permissions.

Return value

await Variant, Err

Returns a Signal. Use await to receive the completion value shown in the signature.

Errors

The result carries a value and an Err. Check the error before using the value; a failure may retain partial progress. In a function returning value, Err, use ? to propagate failure to the caller. The ! operator terminates the program on failure; in serve it fails the current handler.

read_jsonl_async

read_jsonl_async(path: String) -> await Array, Err

Read a JSON Lines file on a worker and parse its values.

Parameters

NameTypeDefaultDescription
pathStringRequiredFilesystem path; relative paths use the execution directory and access follows configured permissions.

Return value

await Array, Err

Returns a Signal. Use await to receive the completion value shown in the signature.

Errors

The result carries a value and an Err. Check the error before using the value; a failure may retain partial progress. In a function returning value, Err, use ? to propagate failure to the caller. The ! operator terminates the program on failure; in serve it fails the current handler.

read_front_matter_async

read_front_matter_async(path: String) -> await Dictionary, Err

Read a front-matter file on a worker and parse its attributes and body.

Parameters

NameTypeDefaultDescription
pathStringRequiredFilesystem path; relative paths use the execution directory and access follows configured permissions.

Return value

await Dictionary, Err

Returns a Signal. Use await to receive the completion value shown in the signature.

Errors

The result carries a value and an Err. Check the error before using the value; a failure may retain partial progress. In a function returning value, Err, use ? to propagate failure to the caller. The ! operator terminates the program on failure; in serve it fails the current handler.

read_xml_async

read_xml_async(path: String) -> await Dictionary, Err

Read an XML file on a worker and parse its dictionary.

Parameters

NameTypeDefaultDescription
pathStringRequiredFilesystem path; relative paths use the execution directory and access follows configured permissions.

Return value

await Dictionary, Err

Returns a Signal. Use await to receive the completion value shown in the signature.

Errors

The result carries a value and an Err. Check the error before using the value; a failure may retain partial progress. In a function returning value, Err, use ? to propagate failure to the caller. The ! operator terminates the program on failure; in serve it fails the current handler.

read_env_async

read_env_async(path: String = ".env") -> await Dictionary, Err

Read a dotenv file on a worker and parse its environment dictionary.

Parameters

NameTypeDefaultDescription
pathString".env"Filesystem path; relative paths use the execution directory and access follows configured permissions.

Return value

await Dictionary, Err

Returns a Signal. Use await to receive the completion value shown in the signature.

Errors

The result carries a value and an Err. Check the error before using the value; a failure may retain partial progress. In a function returning value, Err, use ? to propagate failure to the caller. The ! operator terminates the program on failure; in serve it fails the current handler.

read_tar_async

read_tar_async(path: String) -> await Array, Err

Read a tar file on a worker and decode its entries.

Parameters

NameTypeDefaultDescription
pathStringRequiredFilesystem path; relative paths use the execution directory and access follows configured permissions.

Return value

await Array, Err

Returns a Signal. Use await to receive the completion value shown in the signature.

Errors

The result carries a value and an Err. Check the error before using the value; a failure may retain partial progress. In a function returning value, Err, use ? to propagate failure to the caller. The ! operator terminates the program on failure; in serve it fails the current handler.

read_text_async

read_text_async(path: String) -> await String, Err

Read an entire file as UTF-8 text. The file is opened, read and closed by this call. Filesystem access runs outside the event loop. Use read_bytes when bytes must be preserved exactly.

Parameters

NameTypeDefaultDescription
pathStringRequiredFile path, relative to the execution directory or an explicitly mounted path.

Return value

await String, Err

The decoded file contents, including any line endings.

Returns a Signal. Use await to receive the completion value shown in the signature.

Errors

The result carries a value and an Err. Check the error before using the value; a failure may retain partial progress. In a function returning value, Err, use ? to propagate failure to the caller. The ! operator terminates the program on failure; in serve it fails the current handler.

A missing file, denied permission or read failure is returned through Err. An empty string is valid for an empty file; do not use it as the error test.

Examples

func main():
    var text, err = GD.file.read_text("message.txt")
    if err != null:
        printerr(err)
        return 1
    print(text)
    return 0

See also

read_bytes_async

read_bytes_async(path: String, offset: int = 0, max: int = 0) -> await PackedByteArray, Err

Read bytes from a file, optionally starting at an offset and limiting the amount returned. The file is closed after the operation.

Parameters

NameTypeDefaultDescription
pathStringRequiredFile to read.
offsetint0Zero-based byte offset.
maxint0Maximum byte count; zero reads the remaining contents.

Return value

await PackedByteArray, Err

A PackedByteArray containing the bytes read.

Returns a Signal. Use await to receive the completion value shown in the signature.

Errors

The result carries a value and an Err. Check the error before using the value; a failure may retain partial progress. In a function returning value, Err, use ? to propagate failure to the caller. The ! operator terminates the program on failure; in serve it fails the current handler.

Inspect Err for path, permission and I/O failures.

See also

write_text_async

write_text_async(path: String, body: String) -> await Variant, Err

Replace the contents of a file with UTF-8 text. The file is opened and closed by this call.

Parameters

NameTypeDefaultDescription
pathStringRequiredDestination file.
bodyStringRequiredContent to write.

Return value

await Variant, Err

Use the Err slot to determine success; the value slot is not a byte count.

Returns a Signal. Use await to receive the completion value shown in the signature.

Errors

The result carries a value and an Err. Check the error before using the value; a failure may retain partial progress. In a function returning value, Err, use ? to propagate failure to the caller. The ! operator terminates the program on failure; in serve it fails the current handler.

Creation, write and permission failures are returned as Err. Parent directories are not created automatically.

See also

write_bytes_async

write_bytes_async(path: String, body: PackedByteArray) -> await Variant, Err

Replace the contents of a file with bytes. The file is opened and closed by this call.

Parameters

NameTypeDefaultDescription
pathStringRequiredDestination file.
bodyPackedByteArrayRequiredContent to write.

Return value

await Variant, Err

Use the Err slot to determine success; the value slot is not a byte count.

Returns a Signal. Use await to receive the completion value shown in the signature.

Errors

The result carries a value and an Err. Check the error before using the value; a failure may retain partial progress. In a function returning value, Err, use ? to propagate failure to the caller. The ! operator terminates the program on failure; in serve it fails the current handler.

Creation, write and permission failures are returned as Err. Parent directories are not created automatically.

See also

append_text_async

append_text_async(path: String, body: String) -> await Variant, Err

Append to a file with UTF-8 text. The file is opened and closed by this call.

Parameters

NameTypeDefaultDescription
pathStringRequiredDestination file.
bodyStringRequiredContent to write.

Return value

await Variant, Err

Use the Err slot to determine success; the value slot is not a byte count.

Returns a Signal. Use await to receive the completion value shown in the signature.

Errors

The result carries a value and an Err. Check the error before using the value; a failure may retain partial progress. In a function returning value, Err, use ? to propagate failure to the caller. The ! operator terminates the program on failure; in serve it fails the current handler.

Creation, write and permission failures are returned as Err. Parent directories are not created automatically.

See also

append_bytes_async

append_bytes_async(path: String, body: PackedByteArray) -> await Variant, Err

Append to a file with bytes. The file is opened and closed by this call.

Parameters

NameTypeDefaultDescription
pathStringRequiredDestination file.
bodyPackedByteArrayRequiredContent to write.

Return value

await Variant, Err

Use the Err slot to determine success; the value slot is not a byte count.

Returns a Signal. Use await to receive the completion value shown in the signature.

Errors

The result carries a value and an Err. Check the error before using the value; a failure may retain partial progress. In a function returning value, Err, use ? to propagate failure to the caller. The ! operator terminates the program on failure; in serve it fails the current handler.

Creation, write and permission failures are returned as Err. Parent directories are not created automatically.

See also

copy_async

copy_async(src: String, dst: String) -> await Variant, Err

Copy a file to another path asynchronously.

Parameters

NameTypeDefaultDescription
srcStringRequiredSource input to read or transform; file operations interpret it as a source path.
dstStringRequiredDestination filesystem path.

Return value

await Variant, Err

Returns a Signal. Use await to receive the completion value shown in the signature.

Errors

The result carries a value and an Err. Check the error before using the value; a failure may retain partial progress. In a function returning value, Err, use ? to propagate failure to the caller. The ! operator terminates the program on failure; in serve it fails the current handler.

replace_text_async

replace_text_async(path: String, old: Variant, body: String) -> await Variant, Err

Replace a file asynchronously only if its contents remain unchanged.

Parameters

NameTypeDefaultDescription
pathStringRequiredFilesystem path; relative paths use the execution directory and access follows configured permissions.
oldVariantRequiredExpected previous contents used for a conditional replacement.
bodyStringRequiredContent to write or include in the response.

Return value

await Variant, Err

Returns a Signal. Use await to receive the completion value shown in the signature.

Errors

The result carries a value and an Err. Check the error before using the value; a failure may retain partial progress. In a function returning value, Err, use ? to propagate failure to the caller. The ! operator terminates the program on failure; in serve it fails the current handler.

exists_async

exists_async(path: String) -> await bool

Check path existence asynchronously.

Parameters

NameTypeDefaultDescription
pathStringRequiredFilesystem path; relative paths use the execution directory and access follows configured permissions.

Return value

await bool

Returns a Signal. Use await to receive the completion value shown in the signature.

Errors

This call has no Err return slot. Its return type and documented sentinel values determine how to inspect the result.

remove_async

remove_async(path: String) -> await Variant, Err

Remove a file or empty directory asynchronously.

Parameters

NameTypeDefaultDescription
pathStringRequiredFilesystem path; relative paths use the execution directory and access follows configured permissions.

Return value

await Variant, Err

Returns a Signal. Use await to receive the completion value shown in the signature.

Errors

The result carries a value and an Err. Check the error before using the value; a failure may retain partial progress. In a function returning value, Err, use ? to propagate failure to the caller. The ! operator terminates the program on failure; in serve it fails the current handler.

size_of_async

size_of_async(path: String) -> await int, Err

Get a file's byte count asynchronously.

Parameters

NameTypeDefaultDescription
pathStringRequiredFilesystem path; relative paths use the execution directory and access follows configured permissions.

Return value

await int, Err

Returns a Signal. Use await to receive the completion value shown in the signature.

Errors

The result carries a value and an Err. Check the error before using the value; a failure may retain partial progress. In a function returning value, Err, use ? to propagate failure to the caller. The ! operator terminates the program on failure; in serve it fails the current handler.

rename_async

rename_async(src: String, dst: String) -> await Variant, Err

Rename a file or directory asynchronously.

Parameters

NameTypeDefaultDescription
srcStringRequiredSource input to read or transform; file operations interpret it as a source path.
dstStringRequiredDestination filesystem path.

Return value

await Variant, Err

Returns a Signal. Use await to receive the completion value shown in the signature.

Errors

The result carries a value and an Err. Check the error before using the value; a failure may retain partial progress. In a function returning value, Err, use ? to propagate failure to the caller. The ! operator terminates the program on failure; in serve it fails the current handler.

list_dir_async

list_dir_async(path: String) -> await Array, Err

List immediate directory entries asynchronously.

Parameters

NameTypeDefaultDescription
pathStringRequiredFilesystem path; relative paths use the execution directory and access follows configured permissions.

Return value

await Array, Err

Returns a Signal. Use await to receive the completion value shown in the signature.

Errors

The result carries a value and an Err. Check the error before using the value; a failure may retain partial progress. In a function returning value, Err, use ? to propagate failure to the caller. The ! operator terminates the program on failure; in serve it fails the current handler.

make_dir_async

make_dir_async(path: String) -> await Variant, Err

Create one directory asynchronously.

Parameters

NameTypeDefaultDescription
pathStringRequiredFilesystem path; relative paths use the execution directory and access follows configured permissions.

Return value

await Variant, Err

Returns a Signal. Use await to receive the completion value shown in the signature.

Errors

The result carries a value and an Err. Check the error before using the value; a failure may retain partial progress. In a function returning value, Err, use ? to propagate failure to the caller. The ! operator terminates the program on failure; in serve it fails the current handler.

ensure_dir_async

ensure_dir_async(path: String) -> await Variant, Err

Create a directory and missing parents asynchronously.

Parameters

NameTypeDefaultDescription
pathStringRequiredFilesystem path; relative paths use the execution directory and access follows configured permissions.

Return value

await Variant, Err

Returns a Signal. Use await to receive the completion value shown in the signature.

Errors

The result carries a value and an Err. Check the error before using the value; a failure may retain partial progress. In a function returning value, Err, use ? to propagate failure to the caller. The ! operator terminates the program on failure; in serve it fails the current handler.

walk_async

walk_async(path: String, want_dirs: bool = false, hidden: bool = false) -> await Array, Err

Enumerate a directory tree asynchronously.

Parameters

NameTypeDefaultDescription
pathStringRequiredFilesystem path; relative paths use the execution directory and access follows configured permissions.
want_dirsboolfalseWhether directory entries are included in the traversal result.
hiddenboolfalseWhether hidden entries are included in matching or traversal.

Return value

await Array, Err

Returns a Signal. Use await to receive the completion value shown in the signature.

Errors

The result carries a value and an Err. Check the error before using the value; a failure may retain partial progress. In a function returning value, Err, use ? to propagate failure to the caller. The ! operator terminates the program on failure; in serve it fails the current handler.

glob_async

glob_async(path: String, pattern: String, hidden: bool = false) -> await Array, Err

Find paths matching a pattern asynchronously.

Parameters

NameTypeDefaultDescription
pathStringRequiredFilesystem path; relative paths use the execution directory and access follows configured permissions.
patternStringRequiredFilename glob pattern applied within the supplied directory.
hiddenboolfalseWhether hidden entries are included in matching or traversal.

Return value

await Array, Err

Returns a Signal. Use await to receive the completion value shown in the signature.

Errors

The result carries a value and an Err. Check the error before using the value; a failure may retain partial progress. In a function returning value, Err, use ? to propagate failure to the caller. The ! operator terminates the program on failure; in serve it fails the current handler.

remove_all_async

remove_all_async(path: String) -> await Variant, Err

Remove a directory tree and its contents asynchronously.

Parameters

NameTypeDefaultDescription
pathStringRequiredFilesystem path; relative paths use the execution directory and access follows configured permissions.

Return value

await Variant, Err

Returns a Signal. Use await to receive the completion value shown in the signature.

Errors

The result carries a value and an Err. Check the error before using the value; a failure may retain partial progress. In a function returning value, Err, use ? to propagate failure to the caller. The ! operator terminates the program on failure; in serve it fails the current handler.

can_read_async

can_read_async(path: String) -> await bool

Check path readability asynchronously.

Parameters

NameTypeDefaultDescription
pathStringRequiredFilesystem path; relative paths use the execution directory and access follows configured permissions.

Return value

await bool

Returns a Signal. Use await to receive the completion value shown in the signature.

Errors

This call has no Err return slot. Its return type and documented sentinel values determine how to inspect the result.

create_tar_async

create_tar_async(root: String) -> await PackedByteArray, Err

Archive a directory tree as tar asynchronously.

Parameters

NameTypeDefaultDescription
rootStringRequiredRoot directory for packing or extracting an archive.

Return value

await PackedByteArray, Err

Returns a Signal. Use await to receive the completion value shown in the signature.

Errors

The result carries a value and an Err. Check the error before using the value; a failure may retain partial progress. In a function returning value, Err, use ? to propagate failure to the caller. The ! operator terminates the program on failure; in serve it fails the current handler.

extract_tar_async

extract_tar_async(data: PackedByteArray, root: String) -> await int, Err

Extract a tar archive into a directory asynchronously.

Parameters

NameTypeDefaultDescription
dataPackedByteArrayRequiredInput data in the representation shown by the parameter type.
rootStringRequiredRoot directory for packing or extracting an archive.

Return value

await int, Err

Returns a Signal. Use await to receive the completion value shown in the signature.

Errors

The result carries a value and an Err. Check the error before using the value; a failure may retain partial progress. In a function returning value, Err, use ? to propagate failure to the caller. The ! operator terminates the program on failure; in serve it fails the current handler.