Under development — the help is being filled in plugin by plugin.
Docs/Plugin reference/fileio
Plugin reference

fileio

Read and write whole files (text or binary), test existence, and delete.

7 functionsnamespace fileiosource plugins/file_io/FileIoPlugin.c

Written from a line-by-line source review; every example output is from a real run.

Introduction

The fileio plugin provides simple, whole-file operations: you can read a whole file as text or as a blob, write text or binary data to a file, check whether a file exists, and delete one. The plugin opens no persistent file handles: every call opens, processes, and closes the file on its own — so there is nothing to free, and no state between calls.

Text and blob

There are two data forms. The text variants (ReadFileText / WriteFileText) work with strings and are for text files. The blob variants (ReadFileBlob / WriteFileBlob) work with raw bytes and can be used for any — even binary — content, where the 0 byte must be preserved. ReadFileText explicitly rejects a file containing a NUL byte (use ReadFileBlob in that case).

Writing overwrites

WriteFileText and WriteFileBlob always create or OVERWRITE the file with the full new content (they do not append). If the file already existed, its old content is lost. Both write functions return the number of bytes actually written.

Loading the plugin

plugin "../plugins/print/PrintPlugin";
plugin "../plugins/file_io/FileIoPlugin";

A typical flow — write and read back

string $t[256];
fileio.WriteFileText("data.txt", "Hello!");
$t = fileio.ReadFileText("data.txt");
print.Line($t);

What to know about every function (the basics)

  • Exists returns 1 if the path is a readable file or a directory, otherwise 0 (it does not fail).

  • Delete returns 1 if the deletion succeeded, 0 if the file did not exist or cannot be deleted (it does not fail).

  • WriteFileText and WriteFileBlob return the number of bytes written, and overwrite the existing file.

  • ReadFileText raises a runtime error on a file containing a NUL byte — use ReadFileBlob for binary content.

  • An error (stopping the script) is caused by a wrong argument count or type, an empty path, and an open/read/write failure (except Exists and Delete, which return a neutral 0).

  • The plugin keeps no file open: after every call the file is closed, there is no handle and no state.

How to read the signatures

filePath is the path of the file, and the type after the -> arrow is the return type. For example, fileio.WriteFileText(filePath, text) -> int takes a path and a text and returns the number of bytes written.

Query

Checking whether a file exists.

fileio.Exists

fileio.Exists(filePath) -> int

Tells whether a readable file or a directory exists at the given path (the same answer on Linux and Windows).

Parameters
Parameter Type Description
filePath string The path of the file to check.
Return value

1 if the path is a file that can be opened for reading, or an existing directory; otherwise 0.

Example
printf("%d\n", fileio.Exists("/tmp/none.txt"));
Output after running
0
When to use

For a check before processing a file — for example whether a config file exists before you try to read it.

Reading

Reading a file's whole content as text or as a raw blob.

fileio.ReadFileText

fileio.ReadFileText(filePath) -> string

Reads the file's whole content as text.

Parameters
Parameter Type Description
filePath string The path of the file to read.
Return value

The file's content as text. If the file contains a NUL byte, or is unreadable, a runtime error.

Example
string $t[256];
fileio.WriteFileText("/tmp/p.txt", "Hello, fileio!");
$t = fileio.ReadFileText("/tmp/p.txt");
print.Line($t);
fileio.Delete("/tmp/p.txt");
Output after running
Hello, fileio!
When to use

For reading text files (a config, a log, source code). If the file may be binary (may contain 0 bytes), ReadFileBlob is correct, since it does not reject it.

fileio.ReadFileBlob

fileio.ReadFileBlob(filePath) -> blob

Reads the file's whole content as a raw blob.

Parameters
Parameter Type Description
filePath string The path of the file to read.
Return value

The file's content as a blob (the 0 byte is preserved). On an unreadable file, a runtime error.

Example
blob $b[256];
fileio.WriteFileText("/tmp/p.txt", "Hello, fileio!");
$b = fileio.ReadFileBlob("/tmp/p.txt");
printf("%d\n", $b.Length);
fileio.Delete("/tmp/p.txt");
Output after running
14
When to use

For reading binary files (an image, audio, compressed data), or for any content where the 0 byte also matters. The exact size is given by the blob's .Length field.

Writing and deleting

Writing text or binary data to a file (overwriting), and deleting a file.

fileio.WriteFileText

fileio.WriteFileText(filePath, text) -> int

Writes the text to the file, overwriting the existing content.

Parameters
Parameter Type Description
filePath string The target file's path (created or overwritten).
text string The text to write.
Return value

The number of bytes written. On an open or write failure, a runtime error.

Example
printf("%d\n", fileio.WriteFileText("/tmp/p.txt", "Hello,
fileio!"));
fileio.Delete("/tmp/p.txt");
Output after running
14
When to use

For saving text content (a log, a config, a report) to a file. CAUTION: it overwrites the existing file — if you need to append, read the old content first and write it out together with the new.

fileio.WriteFileBlob

fileio.WriteFileBlob(filePath, data) -> int

Writes the blob's raw bytes to the file, overwriting the existing content.

Parameters
Parameter Type Description
filePath string The target file's path (created or overwritten).
data blob The binary data to write.
Return value

The number of bytes written. On an open or write failure, a runtime error.

Example
blob $d[64];
$d = blob.FromText("ABC");
printf("%d\n", fileio.WriteFileBlob("/tmp/p.bin", $d));
fileio.Delete("/tmp/p.bin");
Output after running
3
When to use

For saving binary content (an image, downloaded data, a serialized byte stream) to a file, where the 0 byte must be preserved. The counterpart of WriteFileText for binary data.

fileio.Delete

fileio.Delete(filePath) -> int

Deletes the given file.

Parameters
Parameter Type Description
filePath string The path of the file to delete.
Return value

1 if the deletion succeeded; 0 if the file did not exist or cannot be deleted.

Example
fileio.WriteFileText("/tmp/p.txt", "x");
printf("%d\n", fileio.Delete("/tmp/p.txt"));
printf("%d\n", fileio.Delete("/tmp/none.txt"));
Output after running
1
0
When to use

For removing temporary or stale files. A return of 0 is not an error — it simply means there was nothing to delete, so it can be called safely without a check.

fileio.ListDir

fileio.ListDir(dirPath) -> string

Lists the entries of a directory as text: one name per line, separated by "\n", sorted in byte order, with directories marked by a trailing /. The . and .. entries are omitted. The result is identical on Linux and Windows for the same tree, so a script can walk a directory the same way everywhere.

Parameters
Parameter Type Description
dirPath string The directory to list.
Return value

The newline-separated entry list; an empty string for an empty directory. A missing or unreadable directory is a runtime error, so probe with fileio.Exists first when the directory is optional.

Example
string $L[4096] = fileio.ListDir("Examples");
i32 $N = str.SplitCount($L, "\n");
printf("%d entries\n", $N);
i32 $I = 0;
while ($I < 3) { printf("%s\n", str.SplitGet($L, "\n", $I)); $I += 1; }
Output after running
67 entries
_test2x2.bmp
abi_reference_probe.dom
asyncmeta_reference_probe.dom
When to use

For iterating a folder of inputs, cleaning a temp tree, or discovering plugins and scripts at run time. Pair it with str.SplitCount / str.SplitGet for the loop, and with the trailing / to recurse into subdirectories.

Practical notes

What the fileio plugin is good for

  • Reading and saving config, log, and data files from the script.

  • Handling binary files (an image, audio, compressed data) with the blob variants.

  • A quick check of a file's presence before processing or overwriting.

  • Creating and cleaning up temporary files.

Text vs blob

For text content, ReadFileText / WriteFileText are convenient (they work with strings). For binary content — or if the file may contain 0 bytes — ReadFileBlob / WriteFileBlob are correct, since they preserve the raw bytes. ReadFileText deliberately rejects a file containing a NUL byte, so that truncated text does not cause a silent error.

Writing always overwrites

WriteFileText and WriteFileBlob create or overwrite the file with the full new content; there is no append. If you want to extend the file, read its existing content first (ReadFileText/ReadFileBlob), append the new, and write the whole thing out at once.

No handle, no state

The plugin opens no persistent file handles: every call opens, processes, and closes the file on its own. So there is nothing to free, and the calls are independent of each other — this makes it simple to use, but it also means every read/write touches the whole file (this plugin is not for partial reads/writes).

Error handling

A wrong argument count or type, an empty path, a file that cannot be opened, a read/write failure, and ReadFileText's NUL-byte file are reported by the runtime as a runtime error, and the script stops. Two functions deliberately do NOT fail: Exists and Delete return a neutral 0 (the absence of the file is not an error), so they can be called safely without a check.

The path path-handling plugin

Joining, decomposing, and normalizing file paths — complete function reference