File I/O
Astra's file system runs every operation through a sandbox â a temporary copy of your file is made, all reads and writes happen there, and the result is flushed back to disk only when you call close(). No partial writes, no corruption on crash.
create() & close()
Every file operation starts with create(), which returns a file handle. Pass that handle to every subsequent operation. Always call close()when done â that's what actually writes changes back to disk.
close(f), your writes stay in the sandbox and are lost when the program ends.If the file doesn't exist yet, create() makes an empty one. If it already exists, it copies it into the sandbox for safe editing.
plus() â Writing to a File
Use plus(handle, text, mode) to write. There are three modes:
| Mode | Meaning |
|---|---|
| "la" | Line Append â adds text as a new line at the end |
| "fa" | First Append â inserts text as a new line at the top |
| "raw" | Overwrites the entire file with exactly the given text |
Append to end â "la"
Prepend to top â "fa"
Overwrite entire file â "raw"
"raw" is useful when writing JSON or config files where you want full control over every byte.read() â Reading from a File
Use read(handle, mode) to read content. Two modes are available:
| Mode | Meaning |
|---|---|
| "l" | Read the next line (advances an internal cursor) |
| "t" | Read the entire file as one string |
Read line by line
Read entire file at once
fetch() â Precise Fetching
fetch(handle, mode, pos1, pos2) lets you pull specific parts of a file without reading everything into memory.
| Mode | pos1 | pos2 | Returns |
|---|---|---|---|
| "l" | line number | â | The full line at that number |
| "c" | char count | â | First N characters of the file |
| "lc" | line number | char count | First N chars of that line |
| "count" | â | â | Total number of lines (as integer) |
Get a specific line
Count total lines
Get first N characters of a line
eof() â End of File Check
eof(handle) returns true when there are no more lines to read. Use it as the condition in a repeat loop.
eof() tracks the internal read cursor. It resets to the start each time you call create() on the same path.clear() & clearLine()
clear() â Erase the whole file
Wipes all content from the file. The handle stays open â you can keep writing after.
clearLine() â Remove lines containing text
Removes every line that contains the given string.
clearLine() removes all lines that contain the substring â not just the first match.Sandbox Safety
When you call create(), Astra copies your file into a temporary sandbox directory. All operations work on that copy. Your original file is only updated when you call close().
- If your program crashes before
close(), the original file is untouched. - The sandbox is automatically cleaned up after
close(). - Calling
create()on the same path twice returns the same handle â no duplicate copies.
create() / close() like a transaction â nothing is committed until you close.