fopen
result = fopen(path, mode)
Input: path, mode · Output: result
What it is
Opens a file for reading, writing, or appending. path (string) is the filesystem path. mode (string) is one of "r" (read, errors if the file doesn't exist), "w" (write, truncate-or-create), "a" (append, create-if-missing), or the same three with a "b" suffix ("rb"/"wb"/"ab") for binary — text and binary modes behave identically at the byte level.
Overloads
One call shape — this function is not overloaded.
| Code | Input | Output | Description |
result = fopen(path, mode) | path stringpath (string) is the filesystem path.mode stringmode (string) is one of "r" (read, errors if the file doesn't exist), "w" (write, truncate-or-create), "a" (append, create-if-missing), or the same three with a "b" suffix ("rb"/"wb"/"ab") for binary — text and binary modes behave identically at the byte level. | result — | Returns an opaque Value::File handle to pass to every other builtin in this chapter. |
Examples
From the documentation, and run by the build -- the output and the figure below are what the engine actually produced. Simplest first.
n = fopen("notes.txt", "w")
write_line(n, "line one")
write_line(n, "line two")
close(n)
print(read_all_text("notes.txt"))
# line one
# line two
line one line two
from file-io
write("a", 1, "b")
print("")
f = fopen("scratch_write_demo.txt", "w")
write(f, "hello file")
close(f)
g = fopen("scratch_write_demo.txt", "r")
print(read_all(g))
close(g)
a 1 b hello file
from repl-diagnostics
f = fopen("log.txt", "r")
for i = 0 to 1
print(read_line(f))
end for
close(f)
g = fopen("log.txt", "r")
print(read_all(g))
close(g)
run started value = 42 run started value = 42
from file-io
f = fopen("log.txt", "w")
write_line(f, "run started")
write_line(f, "value = " + str(42))
close(f)
print(file_size("log.txt")) # 23 -- "run started\n" + "value = 42\n"
23
from file-io
How it works
fopen(path, mode) — a real, general-purpose file-handling library (§ file I/O, 2026-08-24, asked for directly: grepped first and confirmed there was no existing file I/O besides savefig/save/load, none of them general-purpose text/ binary file access). mode follows MATLAB's own fopen convention: "r" (read, errors if the file doesn't exist), "w" (write, truncate-or-create), "a" (append, create-if-missing), each with an optional "b" suffix ("rb"/"wb"/"ab") for binary — accepted for MATLAB- familiar scripts but text/binary are treated identically at the byte level (see FileHandleState's doc comment). Returns a Value::File handle; see read_line/read_all/etc. and write/write_line/etc. below for the full read/write set, and close(f) to release it. § real streaming reads (2026-08-31): the read side used to eagerly std::fs::read(&path) the ENTIRE file into memory right here, before any read builtin was ever called — see FileHandleState's own doc comment for the full story. Now just opens the file and records its length; not a single byte is read from disk until a read_*/seek builtin actually asks for one. Body lives in open_file_handle (see its own doc comment), shared verbatim with StreamFile below.
From the note above this builtin in the interpreter, where the reasoning was written down as it was built.