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(path: String, mode: String = "read") -> GDFileStream, Erropen_async(path: String, mode: String = "read") -> await GDFileStream, Errread_text(path: String) -> String, Errread_bytes(path: String, offset: int = 0, max: int = 0) -> PackedByteArray, Errwrite_text(path: String, body: String) -> Variant, Errreplace_text(path: String, old: Variant, body: String) -> Variant, Errwrite_bytes(path: String, body: PackedByteArray) -> Variant, Errappend_bytes(path: String, body: PackedByteArray) -> Variant, Errappend_text(path: String, body: String) -> Variant, Errexists(path: String) -> boolremove(path: String) -> Variant, Errsize_of(path: String) -> int, Errcopy(src: String, dst: String) -> Variant, Errrename(src: String, dst: String) -> Variant, Errlist_dir(path: String) -> Array, Errmake_dir(path: String) -> Variant, Errensure_dir(path: String) -> Variant, Errwalk(path: String, want_dirs: bool = false, hidden: bool = false) -> Array, Errglob(path: String, pattern: String, hidden: bool = false) -> Array, Errremove_all(path: String) -> Variant, Errcan_read(path: String) -> boolparse_path(path: String) -> Dictionaryformat_path(parts: Dictionary) -> Stringjoin(parts: PackedStringArray) -> Stringdirname(path: String) -> Stringbasename(path: String, suffix: String = "") -> Stringextname(path: String) -> Stringis_absolute(path: String) -> boolnormalize(path: String) -> Stringrelative(from: String, to: String) -> Stringunder(dir: String, name: String) -> Stringcreate_tar(root: String) -> PackedByteArray, Errextract_tar(data: PackedByteArray, root: String) -> int, Errread_csv(path: String, sep: String = ",") -> Array, Errread_ini(path: String) -> Dictionary, Errread_toml(path: String) -> Dictionary, Errread_yaml(path: String) -> Variant, Errread_jsonc(path: String) -> Variant, Errread_jsonl(path: String) -> Array, Errread_front_matter(path: String) -> Dictionary, Errread_xml(path: String) -> Dictionary, Errread_env(path: String = ".env") -> Dictionary, Errread_tar(path: String) -> Array, Errread_csv_async(path: String, sep: String = ",") -> await Array, Errread_ini_async(path: String) -> await Dictionary, Errread_toml_async(path: String) -> await Dictionary, Errread_yaml_async(path: String) -> await Variant, Errread_jsonc_async(path: String) -> await Variant, Errread_jsonl_async(path: String) -> await Array, Errread_front_matter_async(path: String) -> await Dictionary, Errread_xml_async(path: String) -> await Dictionary, Errread_env_async(path: String = ".env") -> await Dictionary, Errread_tar_async(path: String) -> await Array, Errread_text_async(path: String) -> await String, Errread_bytes_async(path: String, offset: int = 0, max: int = 0) -> await PackedByteArray, Errwrite_text_async(path: String, body: String) -> await Variant, Errwrite_bytes_async(path: String, body: PackedByteArray) -> await Variant, Errappend_text_async(path: String, body: String) -> await Variant, Errappend_bytes_async(path: String, body: PackedByteArray) -> await Variant, Errcopy_async(src: String, dst: String) -> await Variant, Errreplace_text_async(path: String, old: Variant, body: String) -> await Variant, Errexists_async(path: String) -> await boolremove_async(path: String) -> await Variant, Errsize_of_async(path: String) -> await int, Errrename_async(src: String, dst: String) -> await Variant, Errlist_dir_async(path: String) -> await Array, Errmake_dir_async(path: String) -> await Variant, Errensure_dir_async(path: String) -> await Variant, Errwalk_async(path: String, want_dirs: bool = false, hidden: bool = false) -> await Array, Errglob_async(path: String, pattern: String, hidden: bool = false) -> await Array, Errremove_all_async(path: String) -> await Variant, Errcan_read_async(path: String) -> await boolcreate_tar_async(root: String) -> await PackedByteArray, Errextract_tar_async(data: PackedByteArray, root: String) -> await int, Err
open
open(path: String, mode: String = "read") -> GDFileStream, ErrOpen a sequential file stream when the input or output should be processed in chunks. Keep the returned stream and close it after use.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
path | String | Required | File to open. |
mode | String | "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, ErrOpen a sequential file stream when the input or output should be processed in chunks. Keep the returned stream and close it after use.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
path | String | Required | File to open. |
mode | String | "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, ErrRead 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
| Name | Type | Default | Description |
|---|---|---|---|
path | String | Required | File 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 0See also
read_bytes
read_bytes(path: String, offset: int = 0, max: int = 0) -> PackedByteArray, ErrRead bytes from a file, optionally starting at an offset and limiting the amount returned. The file is closed after the operation.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
path | String | Required | File to read. |
offset | int | 0 | Zero-based byte offset. |
max | int | 0 | Maximum 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, ErrReplace the contents of a file with UTF-8 text. The file is opened and closed by this call.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
path | String | Required | Destination file. |
body | String | Required | Content 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, ErrReplace a file asynchronously only if its contents remain unchanged.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
path | String | Required | Filesystem path; relative paths use the execution directory and access follows configured permissions. |
old | Variant | Required | Expected previous contents used for a conditional replacement. |
body | String | Required | Content 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, ErrReplace the contents of a file with bytes. The file is opened and closed by this call.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
path | String | Required | Destination file. |
body | PackedByteArray | Required | Content 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, ErrAppend to a file with bytes. The file is opened and closed by this call.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
path | String | Required | Destination file. |
body | PackedByteArray | Required | Content 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, ErrAppend to a file with UTF-8 text. The file is opened and closed by this call.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
path | String | Required | Destination file. |
body | String | Required | Content 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) -> boolCheck path existence asynchronously.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
path | String | Required | Filesystem 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, ErrRemove a file or empty directory asynchronously.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
path | String | Required | Filesystem 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, ErrGet a file's byte count asynchronously.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
path | String | Required | Filesystem 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, ErrCopy a file to another path asynchronously.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
src | String | Required | Source input to read or transform; file operations interpret it as a source path. |
dst | String | Required | Destination 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, ErrRename a file or directory asynchronously.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
src | String | Required | Source input to read or transform; file operations interpret it as a source path. |
dst | String | Required | Destination 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, ErrList immediate directory entries asynchronously.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
path | String | Required | Filesystem 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, ErrCreate one directory asynchronously.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
path | String | Required | Filesystem 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, ErrCreate a directory and missing parents asynchronously.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
path | String | Required | Filesystem 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, ErrEnumerate a directory tree asynchronously.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
path | String | Required | Filesystem path; relative paths use the execution directory and access follows configured permissions. |
want_dirs | bool | false | Whether directory entries are included in the traversal result. |
hidden | bool | false | Whether 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, ErrFind paths matching a pattern asynchronously.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
path | String | Required | Filesystem path; relative paths use the execution directory and access follows configured permissions. |
pattern | String | Required | Filename glob pattern applied within the supplied directory. |
hidden | bool | false | Whether 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, ErrRemove a directory tree and its contents asynchronously.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
path | String | Required | Filesystem 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) -> boolCheck path readability asynchronously.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
path | String | Required | Filesystem 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) -> DictionaryParse a path into a component dictionary.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
path | String | Required | Filesystem 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) -> StringFormat path components as text.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
parts | Dictionary | Required | Components 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) -> StringJoin path segments with separators.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
parts | PackedStringArray | Required | Components 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) -> StringReturn the parent directory of a path.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
path | String | Required | Filesystem 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 = "") -> StringReturn the final path component with the specified suffix removed.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
path | String | Required | Filesystem path; relative paths use the execution directory and access follows configured permissions. |
suffix | String | "" | 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) -> StringReturn a path's extension.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
path | String | Required | Filesystem 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) -> boolCheck whether a path is absolute.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
path | String | Required | Filesystem 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) -> StringNormalize redundant separators and parent/current-directory segments.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
path | String | Required | Filesystem 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) -> StringReturn the relative route between two paths.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
from | String | Required | Base path from which to compute a relative path. |
to | String | Required | Target 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) -> StringResolve a name safely within a directory.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
dir | String | Required | Directory used as the base of the operation. |
name | String | Required | Name 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, ErrArchive a directory tree as tar asynchronously.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
root | String | Required | Root 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, ErrExtract a tar archive into a directory asynchronously.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
data | PackedByteArray | Required | Input data in the representation shown by the parameter type. |
root | String | Required | Root 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, ErrRead document files asynchronously and parse them on workers.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
path | String | Required | Filesystem path; relative paths use the execution directory and access follows configured permissions. |
sep | String | "," | 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, ErrRead an INI file on a worker and parse its dictionary.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
path | String | Required | 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_toml
read_toml(path: String) -> Dictionary, ErrRead a TOML file on a worker and parse its dictionary.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
path | String | Required | 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_yaml
read_yaml(path: String) -> Variant, ErrRead a YAML file on a worker and parse its value.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
path | String | Required | Filesystem 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, ErrRead a commented JSON file on a worker and parse its value.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
path | String | Required | Filesystem 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, ErrRead a JSON Lines file on a worker and parse its values.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
path | String | Required | Filesystem 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, ErrRead a front-matter file on a worker and parse its attributes and body.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
path | String | Required | 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_xml
read_xml(path: String) -> Dictionary, ErrRead an XML file on a worker and parse its dictionary.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
path | String | Required | 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_env
read_env(path: String = ".env") -> Dictionary, ErrRead a dotenv file on a worker and parse its environment dictionary.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
path | String | ".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, ErrRead a tar file on a worker and decode its entries.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
path | String | Required | Filesystem 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, ErrRead document files asynchronously and parse them on workers.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
path | String | Required | Filesystem path; relative paths use the execution directory and access follows configured permissions. |
sep | String | "," | 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, ErrRead an INI file on a worker and parse its dictionary.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
path | String | Required | 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_toml_async
read_toml_async(path: String) -> await Dictionary, ErrRead a TOML file on a worker and parse its dictionary.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
path | String | Required | 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_yaml_async
read_yaml_async(path: String) -> await Variant, ErrRead a YAML file on a worker and parse its value.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
path | String | Required | Filesystem 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, ErrRead a commented JSON file on a worker and parse its value.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
path | String | Required | Filesystem 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, ErrRead a JSON Lines file on a worker and parse its values.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
path | String | Required | Filesystem 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, ErrRead a front-matter file on a worker and parse its attributes and body.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
path | String | Required | 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_xml_async
read_xml_async(path: String) -> await Dictionary, ErrRead an XML file on a worker and parse its dictionary.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
path | String | Required | 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_env_async
read_env_async(path: String = ".env") -> await Dictionary, ErrRead a dotenv file on a worker and parse its environment dictionary.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
path | String | ".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, ErrRead a tar file on a worker and decode its entries.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
path | String | Required | Filesystem 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, ErrRead 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
| Name | Type | Default | Description |
|---|---|---|---|
path | String | Required | File 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 0See also
read_bytes_async
read_bytes_async(path: String, offset: int = 0, max: int = 0) -> await PackedByteArray, ErrRead bytes from a file, optionally starting at an offset and limiting the amount returned. The file is closed after the operation.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
path | String | Required | File to read. |
offset | int | 0 | Zero-based byte offset. |
max | int | 0 | Maximum 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, ErrReplace the contents of a file with UTF-8 text. The file is opened and closed by this call.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
path | String | Required | Destination file. |
body | String | Required | Content 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, ErrReplace the contents of a file with bytes. The file is opened and closed by this call.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
path | String | Required | Destination file. |
body | PackedByteArray | Required | Content 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, ErrAppend to a file with UTF-8 text. The file is opened and closed by this call.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
path | String | Required | Destination file. |
body | String | Required | Content 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, ErrAppend to a file with bytes. The file is opened and closed by this call.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
path | String | Required | Destination file. |
body | PackedByteArray | Required | Content 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, ErrCopy a file to another path asynchronously.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
src | String | Required | Source input to read or transform; file operations interpret it as a source path. |
dst | String | Required | Destination 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, ErrReplace a file asynchronously only if its contents remain unchanged.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
path | String | Required | Filesystem path; relative paths use the execution directory and access follows configured permissions. |
old | Variant | Required | Expected previous contents used for a conditional replacement. |
body | String | Required | Content 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 boolCheck path existence asynchronously.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
path | String | Required | Filesystem 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, ErrRemove a file or empty directory asynchronously.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
path | String | Required | Filesystem 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, ErrGet a file's byte count asynchronously.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
path | String | Required | Filesystem 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, ErrRename a file or directory asynchronously.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
src | String | Required | Source input to read or transform; file operations interpret it as a source path. |
dst | String | Required | Destination 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, ErrList immediate directory entries asynchronously.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
path | String | Required | Filesystem 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, ErrCreate one directory asynchronously.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
path | String | Required | Filesystem 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, ErrCreate a directory and missing parents asynchronously.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
path | String | Required | Filesystem 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, ErrEnumerate a directory tree asynchronously.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
path | String | Required | Filesystem path; relative paths use the execution directory and access follows configured permissions. |
want_dirs | bool | false | Whether directory entries are included in the traversal result. |
hidden | bool | false | Whether 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, ErrFind paths matching a pattern asynchronously.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
path | String | Required | Filesystem path; relative paths use the execution directory and access follows configured permissions. |
pattern | String | Required | Filename glob pattern applied within the supplied directory. |
hidden | bool | false | Whether 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, ErrRemove a directory tree and its contents asynchronously.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
path | String | Required | Filesystem 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 boolCheck path readability asynchronously.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
path | String | Required | Filesystem 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, ErrArchive a directory tree as tar asynchronously.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
root | String | Required | Root 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, ErrExtract a tar archive into a directory asynchronously.
Parameters
| Name | Type | Default | Description |
|---|---|---|---|
data | PackedByteArray | Required | Input data in the representation shown by the parameter type. |
root | String | Required | Root 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.