DominScript — fileio

6 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");
printf("%s\n", $t);

What to know about every function (the basics)

Exists returns 1 if the file can be opened for reading, 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 exists at the given path.

Parameters

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

Return value

1 if the file exists and can be opened for reading; otherwise 0.

Example

printf("%d\n", fileio.Exists("/tmp/none.txt"));

Output after running

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");
printf("%s\n", $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

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

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

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.

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