docs/pages/getting-started/2-introduction/6-files-and-directories.mdx

import { FileTree, Tabs, Tab } from 'nextra/components'

# Files & Directories

Lune has a built-in library for interacting with the filesystem, [`fs`](../../api-reference/fs.md).
This library will let you read, write, move, copy files & directories, and more.

## Example File Tree

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

<FileTree>
	<FileTree.Folder name="-" defaultOpen>
		<FileTree.File name="files.luau" />
		<FileTree.File name="dirs.luau" />
		<FileTree.File name="hello-world.json" />
		<FileTree.Folder name="files" defaultOpen>
			<FileTree.File name="coolstuff.toml" />
			<FileTree.File name="super.secret.txt" />
		</FileTree.Folder>
	</FileTree.Folder>
</FileTree>

<details>
<summary>Show file contents</summary>

<Tabs items={['hello-world.json', 'files/coolstuff.toml', 'files/super.secret.txt']}>
	<Tab>
	```json copy filename="hello-world.json"
	{
		"Hello": "World"
	}
    ```
    </Tab>
    <Tab>
	```toml copy filename="coolstuff.toml"
	[you]
	cool = true
	awesome = "yep"
    ```
    </Tab>
    <Tab>
	```txt copy filename="super.secret.txt"
	Hey you're not supposed to be in here!
    ```
    </Tab>
</Tabs>

</details>

## Files

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

```lua copy filename="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

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

```lua copy filename="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

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

<FileTree>
	<FileTree.Folder name="-" defaultOpen>
		<FileTree.File name="files.luau" />
		<FileTree.File name="dirs.luau" />
		<FileTree.File name="hello-world.json" />
		<FileTree.Folder name="myCoolDir" />
	</FileTree.Folder>
</FileTree>