6.4 I/O Facilities

All I/O operations in Lua are done over two current files, one for reading and one for writing. Initially, the current input file is stdin, and the current output file is stdout.

Unless otherwise stated, all I/O functions return 1 on success and nil on failure.

readfrom (filename)

This function opens a file named filename and sets it as the current input file. When called without parameters, this function closes the current input file, and restores stdin as the current input file.

System dependent: if filename starts with a |, then a piped input is open, via function popen.

writeto (filename)

This function opens a file named filename and sets it as the current output file. Notice that, if the file already exists, it is completely erased with this operation. When called without parameters, this function closes the current output file, and restores stdout as the current output file.

System dependent: if filename starts with a |, then a piped output is open, via function popen.

appendto (filename)

This function opens a file named filename and sets it as the current output file. Unlike the writeto operation, this function does not erase any previous content of the file. This function returns 2 if the file already exists, 1 if it creates a new file, and nil on failure.

remove (filename)

This function deletes the file with the given name.

read ([format])

This function returns a value read from the current input. An optional string argument specifies the way the input is interpreted.

Without a format argument, read first skips blanks, tabs and newlines. Then it checks whether the current character is " or '. If so, it reads a string up to the ending quotation mark, and returns this string, without the quotation marks. Otherwise it reads up to a blank, tab or newline.

The format string can have the following format:

   ?[n]

's' or 'S'

to read a string;

'f' or 'F'

to read a real number;

'i' or 'I'

to read an integer.

readuntil (char)

Reads the current input until the first ocurrence of the given character. Returns the string read. The character itself is not read.

write (value, [format])

This function writes the value of its first argument to the current output. An optional second argument specifies the format to be used. This format is given as a string, composed of four parts. The first part is the only one not optional, and must be one of the following characters:

's' or 'S'

to write strings;

'f' or 'F'

to write floats;

'i' or 'I'

to write integers.

   [?][m][.n]

?

indicates justification inside the field.

'<'
right justification (default);
'>'
left justification;
'|'
center justification.

m

Indicates the field size in characters.

.n

For reals, indicates the number of digital places. For integers, it is the minimum number of digits. This option has no meaning for strings.

When called without a format string, this function writes numbers using the %g format and strings with %s.