{
"id": "fn-file-read",
"dataComponent": "file",
"heading": {
"title": "read",
"badges": [
"FileIO",
"PARTIAL"
]
},
"synopsis": "Reads the contents of a file from disk. If given one argument, returns all contents as a single string. If a second callback argument is provided, streams the file in chunks.",
"codeBlocks": [
"# 1) Basic usage (one argument): read an entire file at once.\n\nextend(\"file\")\n\ncontents = file:read(\"/path/to/myfile.txt\")\nsput(contents)\n\n# => Prints all text from that file as a single string.\n# If the file doesn't exist or is unreadable, raises an error.\n",
"# 2) Streaming usage (two arguments: path, chunkCallback)\n\nfile:read(\"/path/to/largefile.bin\", chunk => {\n # chunk is a string (or binary data) for the next part of the file.\n # This callback is invoked repeatedly until EOF.\n\n # Example: Collect chunk lengths\n slog(string:concat(\"Received chunk of \", string:to_string(string:length(chunk)), \" bytes\"))\n})\n\n# => The function returns immediately with a boolean (true) or a handle.\n# Meanwhile, the callback is called for each chunk read.\n# If you need partial usage, see the placeholders below.\n",
"# 3) Partial usage => placeholders\n\n# You can supply just the path, leaving a placeholder for the callback:\nmyPartialRead = file:read(\"/path/data.log\", _)\n\n# Then call that function with the chunk callback:\nmyPartialRead(chunk => {\n # handle chunk here\n})\n\n# Or supply the callback first, leaving the path as a placeholder.\n"
],
"notes": [
"Argument patterns:\n- If called with 1 argument (path:string), the entire file is read at once and returned as a single string.\n- If called with 2 arguments (path:string, chunkCallback:function), the function processes the file in streaming mode. It returns immediately (e.g. true), then repeatedly calls your callback with each chunk of data until EOF.\n",
"In streaming mode, the callback takes exactly one argument: the chunk (as a string or bytes). If an error occurs, file:read typically raises an exception or passes an error string to the callback (implementation‐dependent).",
"You can use partial usage. For example, `file:read(path, _)` returns a function that waits for the callback. Or `_` for the path, if you want to fix the callback first.",
"If your environment does not support streaming, these second-argument references may be ignored or raise an error."
]
}