Next: 7 The Debugger Interface Up: 6 Predefined Functions and Previous: 6.3 Mathematical Functions

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 nil on failure and some value different from nil on success.

readfrom (filename)

This function may be called in three ways. When called with a file name, it opens the named file, sets it as the current input file, and returns a handle to the file (this handle is a user data containing the file stream FILE *). When called with a file handle, returned by a previous call, it restores the file as the current input. When called without parameters, it closes the current input file, and restores stdin as the current input file.

If this function fails, it returns nil, plus a string describing the error.

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

writeto (filename)

This function may be called in three ways. When called with a file name, it opens the named file, sets it as the current output file, and returns a handle to the file (this handle is a user data containing the file stream FILE *). Notice that, if the file already exists, it will be completely erased with this operation. When called with a file handle, returned by a previous call, it restores the file as the current output. When called without parameters, this function closes the current output file, and restores stdout as the current output file.

If this function fails, it returns nil, plus a string describing the error.

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. It returns the file handle, or nil in case of error. Unlike the writeto operation, this function does not erase any previous content of the file. If this function fails, it returns nil, plus a string describing the error.

Notice that function writeto is available to close a file.

remove (filename)

This function deletes the file with the given name. If this function fails, it returns nil, plus a string describing the error.

rename (name1, name2)

This function renames file name1 to name2. If this function fails, it returns nil, plus a string describing the error.

tmpname ()

This function returns a string with a file name that can safely be used for a temporary file.

read ([readpattern])

This function reads the current input according to a read pattern, that specifies how much to read; characters are read from the current input file until the read pattern fails or ends. The function read returns a string with the characters read, or nil if the read pattern fails and the result string would be empty. When called without parameters, it uses a default pattern that reads the next line (see below).

A read pattern is a sequence of read pattern items. An item may be a single character class or a character class followed by ? or by *. A single character class reads the next character from the input if it belongs to the class, otherwise it fails. A character class followed by ? reads the next character from the input if it belongs to the class; it never fails. A character class followed by * reads until a character that does not belong to the class, or end of file; since it can match a sequence of zero characteres, it never fails.*

A pattern item may contain sub-patterns enclosed in curly brackets, that describe skips. Characters matching a skip are read, but are not included in the resulting string.

Following are some examples of read patterns and their meanings:

write (value1, ...)

This function writes the value of each of its arguments to the current output file. The arguments must be strings or numbers. If this function fails, it returns nil, plus a string describing the error.

date ([format])

This function returns a string containing date and time formatted according to the given string format, following the same rules of the ANSI C function strftime. When called without arguments, it returns a reasonable date and time representation.

exit ([code])

This function calls the C function exit, with an optional code, to terminate the program.

getenv (varname)

Returns the value of the environment variable varname, or nil if the variable is not defined.

execute (command)

This function is equivalent to the C function system. It passes command to be executed by an Operating System Shell. It returns an error code, which is implementation-defined.


Next: 7 The Debugger Interface Up: 6 Predefined Functions and Previous: 6.3 Mathematical Functions