io.read()

Type Function
Library io.*
Return value String, Number, or nil
Revision Release 2024.3703
Keywords io, read, file
See also io.open()
io.input()

Overview

Reads the file set by io.input(), according to the given formats which specify what to read. For each format, the function returns a string or a number with the characters read, or nil if it cannot read data with the specified format. When called without formats, it uses a default format that reads the entire next line ("*l").

If you are reading data from a file, file:read() should be used instead of io.read().

Syntax

io.read( [fmt1] [, fmt2] [, ...] )
fmt1, fmt2, ... (optional)

String or Number. Determines the type/amount of data to read. The available formats are:

  • "*l" — Reads the next line (skipping the end of line), returning nil on end of file (EOF). This is the default format.
  • "*n" — Reads a number; this is the only format that returns a number instead of a string.
  • "*a" — Reads the whole file, starting at the current position. On end of file, it returns the empty string.
  • Number — Reads up to this number of characters, returning nil on end of file. If this number is 0, it reads nothing and returns an empty string, or nil on end of file.