Skip to content

Latest commit

 

History

History
56 lines (43 loc) · 9.33 KB

io.md

File metadata and controls

56 lines (43 loc) · 9.33 KB

Files and standard I/O

Reference index · Official Lua 5.2 I/O library · C Lua 5.2.4 source · Library implementation · File methods

Install with state.OpenIOLibrary(). Operations use LuaPlatform.FileSystem and the standard-stream handles captured from LuaPlatform.StandardIO when the library opens. A custom provider can use memory, assets, or another storage system.

Library APIs

API / official reference Inputs and result Lua-CSharp implementation notes and differences
io.close([file]) Closes the supplied file, or the default output when no argument is supplied. Explicit nil is an error. Default console standard handles reject closing. File failures use managed messages/error codes; see below.
io.flush() Flushes the current default output. Calls the configured stream's flush operation; it is not necessarily an OS file stream.
io.input([file]) Gets the default input, selects an open handle, or opens a filename for reading and selects it. Host-dependent: filenames go through the filesystem provider. Omitted/nil input is a getter; invalid/closed handles are rejected before changing the default.
io.lines([filename, ...formats]) Iterates using read formats. A filename creates an automatically closed file; omitted/nil filename uses default input without automatic close. Default format is *l. A failed first read returns no values; successful earlier formats followed by a failure retain their results and the final nil. Closed default input is rejected when creating the iterator. Automatic close occurs when the first read fails, including a failed numeric conversion, as in Lua 5.2.
io.open(filename [, mode]) Opens a file, defaulting to r; returns a handle or nil, message, code for handled open failures. String mode, rather than b, determines the built-in stream's byte/text encoding. Errors include .NET messages/HResult codes. Custom providers can supply different storage semantics.
io.output([file]) Gets/selects default output, or opens a filename for writing and selects it. Switching output flushes the previous open output in this implementation. This is an additional effect of its explicit managed flush policy. Invalid/closed arguments are validated before that flush. It does not redirect print, which uses StandardIO.Output directly.
io.popen(command [, mode]) Officially opens a process pipe. Unavailable: not registered; the built-in I/O abstraction does not implement process pipes. A host can expose its own process/stream binding.
io.read(...) Reads from the selected default input using the formats below. Shares file:read semantics, including string units and provider error behavior.
io.stderr Initial standard error handle. Host-dependent: wraps the configured error stream; default console handles cannot be closed through Lua.
io.stdin Initial standard input handle. Host-dependent: wraps the configured input stream. Selecting another io.input does not replace this field.
io.stdout Initial standard output handle. Host-dependent: wraps the configured output stream. Selecting another io.output does not replace this field.
io.tmpfile() Creates a temporary read/write file handle, or returns nil, message, code for handled I/O/permission failures. The default provider uses a .NET FileStream with DeleteOnClose. Error messages/codes come from the managed provider; cancellation still propagates to the host. Close explicitly for deterministic deletion.
io.type(value) Returns file, closed file, or nil. Recognizes managed FileHandle objects and queries their provider's open state.
io.write(...) Writes string/number arguments to default output and returns that file on success. Numbers use NumberFormat; strings use the configured stream encoding.

File methods

API / official reference Inputs and result Lua-CSharp implementation notes and differences
file:close() Closes the underlying stream; reports success or handled I/O failure. Calls ILuaStream.CloseAsync; close behavior belongs to the provider. The default stream flushes and disposes the underlying .NET stream. Lua GC finalizers are not used to implement deterministic close.
file:flush() Flushes pending writes. Calls the provider's flush operation.
file:lines(...) Returns an iterator over the file using the given formats; does not automatically close the handle. A failed first read returns no values, as with io.lines. Closed handles fail at iterator creation.
file:read(...) Returns one value per successful format, stopping at the first failed conversion/EOF with nil. No formats means *l. Default streams decode UTF-8 to UTF-16, while byte-mode streams preserve raw bytes. Counts use the selected representation. Numeric scanning remains byte-based, even in UTF-16 mode.
file:seek([whence [, offset]]) Seeks using set, cur, or end; defaults are cur, 0. Coerces numeric strings but requires an integral offset representable by a managed long. Returns the resulting position or handled I/O failure. Offsets/positions are bytes in built-in streams, including UTF-16 mode. Buffered unread bytes are accounted for. If a counted read returned only the high surrogate of a supplementary character, its bytes have already been consumed; a position query retains the pending low surrogate. Underlying seek support is provider-dependent.
file:setvbuf(mode [, size]) Selects no, line, or full buffering policy; returns true when accepted. Limitation: built-in LuaStream changes flush policy, not the underlying .NET buffer allocation. no flushes each write; line flushes writes containing LF; full uses a per-write size threshold rather than a cumulative C stdio buffer. size does not resize the stream's buffer. Custom providers may implement their own policy.
file:write(...) Writes strings/numbers and returns the file on success. Default streams encode UTF-16 text as UTF-8; byte-mode streams write raw byte values. Numbers use NumberFormat.

Formats, modes, and errors

The supported read formats are *n, *a, *l, *L, and a numeric count. The format dispatcher also accepts *number, *all, and *line. Bare L is an additional accepted alias for *L; use *L for the Lua 5.2 spelling. *a returns an empty string at EOF; a count of zero probes EOF without consuming a character. Numeric counts are truncated and must fit a nonnegative managed int.

With built-in streams:

Operation Default UTF-16 mode Byte mode
read(n) Up to n UTF-16 units; supplementary characters can be split across results Up to n raw bytes
read('*l') CR, LF, and CRLF end a line; the ending is removed LF ends a line; a preceding CR remains in the result
read('*L') Keeps the original line ending Keeps LF and any preceding CR
Initial UTF-8 BOM in a text read Skipped only at the beginning Preserved as data
Invalid UTF-8 Replaced when decoded Preserved as bytes

*n scans decimal/hex numeric bytes and consumes incomplete numeric input items when a conversion fails. It does not decode Unicode whitespace or skip a UTF-8 BOM as a Unicode text read would. This is the numeric scanner's implementation boundary.

Recognized open modes are r, rb, r+, r+b, w, wb, w+, w+b, a, ab, a+, and a+b. The b marker does not change string mode: built-in LuaStream encoding was selected by its constructor/platform. Use a matching byte-mode platform for binary files, including string.dump output.

Handled failures generally return nil, message, code; closed-file misuse raises an error. Managed error codes are exception HResult values, not C errno values. Some provider exceptions propagate as Lua errors instead of becoming a result tuple. See shared cancellation behavior.