Wizards of Lua

The Art of Spell Crafting

---

io - Doing File Operations

The io module (with lowercase letters I and O) is a standard Lua function library that provides functions for reading and writing files.

Please note that WoL interprets any path passed to the io functions as to be relative to the server’s world folder. To browse the server’s world folder please use the function “System.listFiles()”.

Here is an overview of the IO functions:

Functions

Below you find short descriptions about each of the functions and some examples about how to use them in your spells.

close (file) -> boolean

The ‘close’ function is equivalent to File.close(). Without a specified file it closes the default output file.

This function returns true if the file has been closed.

Example

Writing some text into the file “my-file.txt”.

io.output('my-file.txt')
io.write('some text')
io.close()

flush () -> boolean

The ‘flush’ function is equivalent to io.output():flush(). Saves any written data to the default output file.

This function returns true if the file has been flushed.

Example

Writing for ten seconds every second some text into the file “my-file.txt”.

io.output('my-file.txt')
for i=1,10 do
  io.write('line '..i)
  io.flush()
  sleep(20)
end
io.close()

input (file) -> File

The ‘input’ function defines the default input file. It returns the file that is currently defined as the default input file.

When called with a file name, it opens the named file (in text mode), and sets its handle as the default input file. When called with a file handle, it simply sets this file handle as the default input file. When called without arguments, it just returns the current default input file.

Example

Setting “my-file.txt” to be the default input file.

io.input('my-file.txt')

lines (filename, formats…) -> iterator

The ‘lines’ function is currently not supported!

open (filename, mode) -> File, string

The ‘open’ functions opens the file with the given filename in the specified mode. In case of success, it returns a new file handle. If it fails it returns nil and the error message.

The mode string can be any of the following:

• “r”: read mode (the default)
• “w”: write mode
• “a”: append mode
• “r+”: update mode, all previous data is preserved. Currently not supported!
• “w+”: update mode, all previous data is erased. Currently not supported!
• “a+”: append update mode, previous data is preserved, writing is only allowed at the end of file. Currently not supported!

The mode string can also have a ‘b’ at the end, which is needed in some systems to open the file in binary mode.

Example

Opening the file “my-file.txt” and reading all of its contents.

local f,err = io.open('my-file.txt','w')
if err then
  error(err)
end   
local contents = f:read("*a")
f:close()

output (file) -> File

The ‘output’ function defines the default output file. It returns the file that is currently defined as the default output file.

When called with a file name, it opens the named file (in text mode), and sets its handle as the default output file. When called with a file handle, it simply sets this file handle as the default output file. When called without arguments, it just returns the current default output file.

Example

Setting “my-file.txt” to be the default output file.

io.output('my-file.txt')

popen (prog, mode) -> File

The ‘popen’ function is currently not supported!

read (format…) -> any

The ‘read’ function is equivalent to io.input():read(...). See File.read().

Example

First setting “my-file.txt” to be the default input file. Then reading and printing it line by line.

io.input('my-file.txt')
while true do
  local line = io.read("*l")
  if not line then
    break
  end
  print(line)
end
io.close()

tmpfile () -> File

The ‘tmpfile’ function is currently not supported!

type (any) -> boolean

The ‘type’ function checks whether the given object is a valid File handle. Returns the string “file” if obj is an open file handle, “closed file” if obj is a closed file handle, or nil if obj is not a file handle.

Example

Checking the file handle of the player’s advancements file before and after the file has been closed.

local name ="advancements/"..spell.owner.uuid..".json"
local f = io.open(n,"r")
print(io.type(f))
f:close()
print(io.type(f))

write (any…) -> file, string

The ‘write’ function is equivalent to io.output:write().