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 otherwised 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 restores stdin as the current input file.

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 restores stdout as the current output file.

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. When called without parameters, this function restores stdout as the current output file. This function returns 2 if the file already exists, 1 if it creates a new file, and nil on failure.

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.

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 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;
'>'
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.

debug ()

This function, when called, repeatedly presents a prompt lua_debug> in the error output stream (stderr), reads a line from the standard input, and executes (``dostring'') the line. The loop ends when the user types cont to the prompt. This function then returns and the execution of the program continues.

Next: 7 Some Examples Up: 6 Predefined Functions and Previous: 6.3 Mathematical Functions