io

Emulates Lua's standard io library.

stdinA file handle representing the "standard input".
stdoutA file handle representing the "standard output".
stderrA file handle representing the "standard error" stream.
close([file])Closes the provided file handle.
flush()Flushes the current output file.
input([file])Get or set the current input file.
lines([filename, ...])Opens the given file name in read mode and returns an iterator that, each time it is called, returns a new line from the file.
open(filename[, mode])Open a file with the given mode, either returning a new file handle or nil, plus an error message.
output([file])Get or set the current output file.
read(...)Read from the currently opened input file.
type(obj)Checks whether handle is a given file handle, and determine if it is open or not.
write(...)Write to the currently opened output file.
stdinSource

A file handle representing the "standard input". Reading from this file will prompt the user for input.

stdoutSource

A file handle representing the "standard output". Writing to this file will display the written text to the screen.

stderrSource

A file handle representing the "standard error" stream.

One may use this to display error messages, writing to it will display them on the terminal.

close([file])Source

Closes the provided file handle.

Parameters

  1. file? Handle The file handle to close, defaults to the current output file.

See also

flush()Source

Flushes the current output file.

See also

input([file])Source

Get or set the current input file.

Parameters

  1. file? Handle | string The new input file, either as a file path or pre-existing handle.

Returns

  1. Handle The current input file.

Throws

  • If the provided filename cannot be opened for reading.

lines([filename, ...])Source

Opens the given file name in read mode and returns an iterator that, each time it is called, returns a new line from the file.

This can be used in a for loop to iterate over all lines of a file:

for line in io.lines(filename) do print(line) end

Once the end of the file has been reached, nil will be returned. The file is automatically closed.

If no file name is given, the current input will be used instead. In this case, the handle is not used.

Parameters

  1. filename? string The name of the file to extract lines from
  2. ... The argument to pass to Handle:read for each line.

Returns

  1. function():string | nil The line iterator.

Throws

  • If the file cannot be opened for reading

See also

open(filename[, mode])Source

Open a file with the given mode, either returning a new file handle or nil, plus an error message.

The mode string can be any of the following:

  • "r": Read mode
  • "w": Write mode
  • "w": Append mode

The mode may also have a b at the end, which opens the file in "binary mode". This allows you to read binary files, as well as seek within a file.

Parameters

  1. filename string The name of the file to open.
  2. mode? string The mode to open the file with. This defaults to rb.

Returns

  1. Handle The opened file.

Or

  1. nil In case of an error.
  2. string The reason the file could not be opened.
output([file])Source

Get or set the current output file.

Parameters

  1. file? Handle | string The new output file, either as a file path or pre-existing handle.

Returns

  1. Handle The current output file.

Throws

  • If the provided filename cannot be opened for writing.

read(...)Source

Read from the currently opened input file.

This is equivalent to io.input():read(...). See the documentation there for full details.

Parameters

  1. ... string The formats to read, defaulting to a whole line.

Returns

  1. string | nil... The data read, or nil if nothing can be read.
type(obj)Source

Checks whether handle is a given file handle, and determine if it is open or not.

Parameters

  1. obj The value to check

Returns

  1. string | nil "file" if this is an open file, "closed file" if it is a closed file handle, or nil if not a file handle.
write(...)Source

Write to the currently opened output file.

This is equivalent to io.output():write(...). See the documentation there for full details.

Parameters

  1. ... string The strings to write

Types

Handle

A file handle which can be read or written to.

Handle.close()Source

Close this file handle, freeing any resources it uses.

Returns

  1. true If this handle was successfully closed.

Or

  1. nil If this file handle could not be closed.
  2. string The reason it could not be closed.

Throws

  • If this handle was already closed.

Handle.flush()Source

Flush any buffered output, forcing it to be written to the file

Throws

  • If the handle has been closed

Handle:lines(...)Source

Parameters

  1. ...
Handle:read(...)Source

Parameters

  1. ...
Handle:seek(whence, offset)Source

Parameters

  1. whence
  2. offset
Handle:setvbuf(mode, size)Source

Parameters

  1. mode
  2. size
Handle.write(...)Source

Write one or more values to the file

Parameters

  1. ... string | number The values to write.

Returns

  1. Handle The current file, allowing chained calls.

Or

  1. nil If the file could not be written to.
  2. string The error message which occurred while writing.