Skip to content
Lune

Files & Directories

Lune has a built-in library for interacting with the filesystem, fs. This library will let you read, write, move, copy files & directories, and more.

Example File Tree

Section titled “Example File Tree”

Let’s use this directory & file tree structure for our examples:

  • files.luau
  • dirs.luau
  • hello-world.json
  • Directoryfiles
    • coolstuff.toml
    • super.secret.txt
Show file contents
JSON
{
  "Hello": "World"
}

Files

Section titled “Files”

Reading and writing files using the fs library is very simple and only involves strings:

files.luau
local fs = require("@lune/fs")


--> Print out the contents of all of the files
print(fs.readFile("hello-world.json"))
print(fs.readFile("files/coolstuff.toml"))
print(fs.readFile("files/super.secret.txt"))


--> Create a new file in our "files" directory
fs.writeFile("files/My Favorite Numbers.txt", "2 4 6 8 0 😃")


--> Write to one of our files, overwriting any previous contents
fs.writeFile("files/super.secret.txt", "Super secret message")


--> Remove the new file we created in our "files" directory
fs.removeFile("files/My Favorite Numbers.txt")

Note that the filesystem library deals with raw strings for file contents, and does not differentiate between if the contents of the file are using binary, utf-8, or some other encoding. It is up to you to know how your files are structured and handle them appropriately.

Directories

Section titled “Directories”

Reading and creating directories has a very similar API, but slightly different parameters and return values:

dirs.luau
local fs = require("@lune/fs")


--[[
  Print out the entries found in our directory.
  The "." here means the current directory.


  This will output:
  * 📄 files.luau
  * 📄 dirs.luau
  * 📄 hello-world.json
  * 📁 files
]]
for _, entry in fs.readDir(".") do
  if fs.isDir(entry) then
    print("📁 " .. entry)
  elseif fs.isFile(entry) then
    print("📄 " .. entry)
  end
end


--> Create a new directory next to the above entries
fs.writeDir("myCoolDir")


--> Create a new directory in our "files" directory
fs.writeDir("files/myCoolSecondDir")


--> Remove the entire files directory
fs.removeDir("files")

In the above example:

  • fs.readDir returns a table (array) of strings, with file and directory names
  • fs.writeDir takes only the directory name (path) to create a directory at
  • fs.removeDir removes the directory and everything inside it - use with caution!

Resulting File Tree

Section titled “Resulting File Tree”

This is what our directory & file tree structure would look like after running the above examples:

  • files.luau
  • dirs.luau
  • hello-world.json
  • DirectorymyCoolDir/
    • …