How to use files with Lua^rt

By Samir Tine, published on December 2021

In the Lua standard library, input / output functionalities are gathered within the io module.
In Lua^rt, they are grouped together within the sys module, and more particularly the File object.

Creating a File value

At this point, it's important to understand that a File object represents an abstraction of a file that may *or may not* physically exist.
For example, when creating a new file, only the call to the File:open() method will physically create the file on the computer storage:


local newfile = sys.File("hello.txt") -- newfile holds a File value
print(newfile.exists) -- outputs false
newfile:open("write") -- creates the file physically on the disk 
newfile:close()       -- closes the opened File
print(newfile.exists) -- now outputs true

File operations

Once created, a File instance can be used to perform file operations:


local file = sys.File("test.txt") 
file:copy("test_copy.txt")   -- copies file
file:move("C:\")             -- moves file
file:remove()                -- deletes the file

Opening and closing a File

A File can be opened to read or write its content. This is done by calling the File:open() method. By default, the file is open in "read" mode. The file encoding can be specified as a second argument or autodetected using Byte Mark Order :


local file = sys.File("test.bin")
-- opens the file "test.bin" in read mode (encoding is autodetected)
file:open()   
-- closes the file
file:close()                   
-- open the file in write mode (erasing its previous content), using "binary" encoding(ie raw binary)
file:open("write", "binary")

Sticky note

Do not forget to close a file after the transaction on this one ended. This is done automatically when the File object is garbage collected, but that cannot be predicted.

Reading and writing Files

Once the File object has been created, and the File:open() method called, you can write and/or read on the File (depending on the open mode used). These methods return Buffer objects in "binary" mode (containing in memory binary data) or strings in "utf8" or "unicode" mode.

Reading file content

There are two methods for reading the content of a file: File:read() and File:readln()


local file = sys.File("README.TXT"):open()  -- opens the File for reading
print(file:read())  -- reads and prints all the file content

The File:read() method reads a certain number of characters (when using "utf8" or "unicode" mode) or bytes (in "binary" mode) specified as argument, or all the content of the file if no argument is provided.
The File:readln() method reads a line, until end of line characters "\r\n" or "\n" are encountered. You can iterate through lines of the file with the File.lines iterator.

Writing to files

There are two methods for writing data to a file: File:write() and File:writeln().
Each method take one argument, converted to a string to be written to the file. In "binary" mode, Buffer objects can be used.
File:writeln() writes a line to the file, appending "\r\n" (the End Of Line marker on Windows platform).

File position

The File.position property get or set the current file position, as a number. File position always starts at 1 (as for all indexed/positioned values in Lua).
File position interpretation depends on the file encoding :

In "binary" encoding : the position is expressed in bytes.
In "utf8" or "unicode" encoding : the position is expressed in characters.

The File.eof property checks if the end of the file have been reached.

File timestamps

The File.accessed, File.modified and File.created properties permits to set or get File timestamps using a Datetime object.


-- Create File instance representing the Windows notepad.exe executable
local file = sys.File(sys.env.WINDIR.."/notepad.exe")
-- prints when notepad.exe was created on your system
print(file.created)

File attributes

The File.hidden, File.temporary and File.readonly permits to set or get the corresponding File attributes :


-- Create File instance representing the Windows notepad.exe executable
local file = sys.File(sys.env.WINDIR.."/notepad.exe")
-- prints if notepad.exe is readonly (should be false)
print(file.readonly)

Managing File path and names

The File.fullpath, File.name, File.extension, File.path properties ease filename parsing. Please note that you can use "/" or "\" for path separators.


local file = sys.File("test.lua")
if file.extension == ".lua" then
    print("It's a Lua script file !")
else
    print("Don't know what kind of file it is...")
end

As you can see, File objects provide easy access to all of the functionality related to creating, reading, writing and manipulating files in Lua^rt.
These features go beyond the capabilities offered by the standard Lua library on the Windows platform.

How to use files with Luart