Lua io functions
Lua io functions

These are the functions in the "io" table.

Implicit operations (eg. io.read, io.write) use the standard file descriptors io.stdin, io.stdout, and io.stderr.

You can operate on other files by getting a "file descriptor" from io.open, io.input, or io.output, and using that.

Note the syntactical difference, that you follow a file descriptor by a colon, eg. f:close ()

Also see the description for the "os" table for operating system functions that do things like remove and rename files.



io.close (f)

Equivalent to f:close (). Without f supplied closes the default output file.


io.close (f) -- closes the file descriptor f



io.flush ()

Equivalent to f:flush () for the default output file. Flushes outstanding data to disk.


f = io.input (filename)

Opens filename for input in text mode. Raises an error if it cannot.
If opened OK returns a handle to the opened file, and makes it the default input file.

If called with no argument, returns the handle to the default input file.
If called with a file handle, sets the default input file to that handle.


prev = io.input ()  -- save current input file
f = io.input ("test.txt") --> handle to new file
f:close ()  -- close that file now
io.input (prev) -- restore previous input file



io.lines (filename)

Opens filename for input in text mode. Raises an error if it cannot.
If opened OK returns an iterator function that reads the file line-by-line.
At end of file, returns nil and closes the file.
If filename not supplied, uses the default input file.


for line in io.lines ("test.txt") do
  print (line)
end 

 --> Entire contents of file listed



f = io.open (filename, mode)

Opens a file and returns a file handle for working with it.

Modes can be a string which is:


  • r - read mode
  • w - write mode (overwrites existing)
  • a - append mode (appends to existing)
  • b - binary mode
  • r+ - update mode (existing data preserved)
  • w+ - update mode (existing data erased)
  • a+ - append update mode (existing data preserved, append at end of file only)


If the file cannot be opened this function does not raise an error (unlike io.input and io.output) but returns 3 things:


  • nil
  • An error message (string)
  • An error code (number)



f = io.open ("test.txt", "r")  -- open it
s = f:read ("*a")  -- read all of it
print (s)  -- print out
f:close ()  -- close it



f = io.output (filename)

Same behaviour as io.input, except it operates over the default output file.


f = io.output ("test.txt") --> handle to new file
f:write ("some data here") -- write to it
f:close ()  -- close that file now



io.popen (command, mode)

Creates a pipe and executes a command. Mode can be one of:


  • "r" - The calling process can read the spawned command’s standard output via the returned stream. This is the default.

  • "w" - The calling process can write to the spawned command’s standard input via the returned stream.

  • "b" - Open in binary mode.

  • "t" - Open in text mode.


However io.popen is not supported under the version compiled into MUSHclient, so don't get too excited. :)

This is an example of using popen under the Linux Lua executable:


 f = assert (io.popen ("ls -l"))
  
 for line in f:lines() do
   print(line)
 end -- for loop
   
 f:close()


An alternative to using pipes, if you want to capture operating system output, is to redirect command output to a temporary file, like this:


-- get a temporary file name
n = os.tmpname ()

-- execute a command
os.execute ("dir > " .. n)

-- display output
for line in io.lines (n) do
  print (line)
end

-- remove temporary file
os.remove (n)




io.read ()

Equivalent to io.input ():read. See below for a description.



f = io.tmpfile ()

Returns a handle to a temporary file, opened in update mode. Automatically removed when the program ends.



f = io.tmpfile () -- open temporary file
f:write ("some data here")  -- write to it
f:seek ("set", 0) -- back to start
s = f:read ("*a")  -- read all of it back in
print (s)  -- print out
f:close ()  -- close file

-->

some data here



io.stdin

A file descriptor representing the current stdin (input) file handle.


io.stdout

A file descriptor representing the current stdout (output) file handle.


io.stderr

A file descriptor representing the current stderr (error) file handle.



io.type ()

Returns a string which is one of:


  • file - an open file handle
  • closed file - a closed file handle
  • nil - not a file handle



f = io.tmpfile ()
print (io.type (f))
f:close ()
print (io.type (f))

-->

file
closed file



io.write ()

Equivalent to io.output ():write. See below for a description.




The operations below depend on having an open file handle returned from io.open, io.input, or io.output.



f:close ()

Closes the file f.



f:close () -- closes the file descriptor f



f:flush ()

Flushes outstanding data to disk.


f:flush () -- save everything



f:lines (filename)

Returns an iterator function that reads the file line-by-line.
At end of file, returns nil.
It does not close the file.


f = io.input ("test.txt")
for line in f:lines () do
  print (line)
end 
f:close ()  -- close that file now

 --> Entire contents of file listed



f:read (format1, format2, ...)

Reads the file f according to the given formats. Each format returns a string, a number, or nil if it fails. The formats are:


  • *n - reads a number and returns it
  • *a - reads the entire file from the current position
  • *l - (default) - reads the next line, returns nil on EOF
  • number - returns a string with up that many characters in it, or nil on EOF



f = io.input ("test.txt")
repeat
  s = f:read ("*l") -- read one line
  if s then  -- if not end of file (EOF)
   print (s) -- print that line
  end
until not s  -- until end of file

f:close ()  -- close that file now




f:seek (whence, offset)

Sets and gets the current file position.

f:seek () --> returns the current file position

When setting a position you can supply a string which is one of:


  • set - from beginning of file
  • cur - from current position
  • end - from end of file


The offset is a number from the base position.



f:seek ("set", 0)     -- go to start of file
f:seek ("end", -100)  -- go to 100 bytes from end of file
f:seek ("cur", 50)    -- go forwards 50 bytes


file:setvbuf (mode, size)

Sets the buffering mode for an output file. There are three available modes, which are supplied as strings:


  • "no": no buffering; the result of any output operation appears immediately.

  • "full": full buffering; output operation is performed only when the buffer is full (or when you explicitly flush the file (see io.flush)).

  • "line": line buffering; output is buffered until a newline is output or there is any input from some special files (such as a terminal device).



For the last two cases, size specifies the size of the buffer, in bytes. The default is an appropriate size.


f:write (v1, v2, v3, ...)

Writes arguments to the file. They must be strings or numbers.


f:write ("hi there", 42, "some more data")


See Also ...

Topics

DOC_lua_base Lua base functions
DOC_lua_coroutines Lua coroutine functions
DOC_lua_debug Lua debug functions
DOC_lua_math Lua math functions
DOC_lua_os Lua os functions
DOC_lua_package Lua package functions
DOC_lua Lua script extensions
DOC_lua_string Lua string functions
DOC_lua_tables Lua table functions

(Help topic: general=lua_io)

DOC_contents Documentation contents page