fs

The FS API allows you to manipulate files and the filesystem.

isDriveRoot(path)Returns true if a path is mounted to the parent filesystem.
complete(path, location[, include_files[, include_dirs]])Provides completion for a file or directory name, suitable for use with read.
copy(path, dest)Copies a file or directory to a new path.
attributes(path)Get attributes about a specific file or folder.
getDir(path)Returns the parent directory portion of a path.
isReadOnly(path)Returns whether a path is read-only.
move(path, dest)Moves a file or directory from one path to another.
getDrive(path)Returns the name of the mount that the specified path is located on.
getSize(path)Returns the size of the specified file.
getFreeSpace(path)Returns the amount of free space available on the drive the path is located on.
find(path)Searches for files matching a string with wildcards.
combine(pathA, pathB)Combines two parts of a path into one full path, adding separators as needed.
makeDir(path)Creates a directory, and any missing parents, at the specified path.
list(path)Returns a list of files in a directory.
getName(path)Returns the file name portion of a path.
isDir(path)Returns whether the specified path is a directory.
getCapacity(path)Returns true if a path is mounted to the parent filesystem.
exists(path)Returns whether the specified path exists.
delete(path)Deletes a file or directory.
open(path, mode)Opens a file for reading or writing at a path.
isDriveRoot(path)Source

Returns true if a path is mounted to the parent filesystem.

The root filesystem "/" is considered a mount, along with disk folders and the rom folder. Other programs (such as network shares) can exstend this to make other mount types by correctly assigning their return value for getDrive.

Parameters

  1. path string The path to check.

Returns

  1. boolean If the path is mounted, rather than a normal file/folder.

Throws

  • If the path does not exist.

See also

complete(path, location[, include_files[, include_dirs]])Source

Provides completion for a file or directory name, suitable for use with read.

When a directory is a possible candidate for completion, two entries are included - one with a trailing slash (indicating that entries within this directory exist) and one without it (meaning this entry is an immediate completion candidate). include_dirs can be set to false to only include those with a trailing slash.

Parameters

  1. path string The path to complete.
  2. location string The location where paths are resolved from.
  3. include_files? boolean When false, only directories will be included in the returned list.
  4. include_dirs? boolean When false, "raw" directories will not be included in the returned list.

Returns

  1. { string... } A list of possible completion candidates.
copy(path, dest)Source

Copies a file or directory to a new path.

Any parent directories are created as needed.

Parameters

  1. path string The file or directory to copy.
  2. dest string The path to the destination file or directory.

Throws

  • If the file or directory couldn't be copied.

attributes(path)Source

Get attributes about a specific file or folder.

The returned attributes table contains information about the size of the file, whether it is a directory, and when it was created and last modified.

The creation and modification times are given as the number of milliseconds since the UNIX epoch. This may be given to os.date in order to convert it to more usable form.

Parameters

  1. path string The path to get attributes for.

Returns

  1. { size = number, isDir = boolean, created = number, modified = number } The resulting attributes.

Throws

  • If the path does not exist.

See also

  • getSize If you only care about the file's size.
  • isDir If you only care whether a path is a directory or not.
getDir(path)Source

Returns the parent directory portion of a path.

Parameters

  1. path string The path to get the directory from.

Returns

  1. string The path with the final part removed (the parent directory).
isReadOnly(path)Source

Returns whether a path is read-only.

Parameters

  1. path string The path to check.

Returns

  1. boolean Whether the path cannot be written to.
move(path, dest)Source

Moves a file or directory from one path to another.

Any parent directories are created as needed.

Parameters

  1. path string The current file or directory to move from.
  2. dest string The destination path for the file or directory.

Throws

  • If the file or directory couldn't be moved.

getDrive(path)Source

Returns the name of the mount that the specified path is located on.

Parameters

  1. path string The path to get the drive of.

Returns

  1. string The name of the drive that the file is on; e.g. hdd for local files, or rom for ROM files.

Throws

  • If the path doesn't exist.

getSize(path)Source

Returns the size of the specified file.

Parameters

  1. path string The file to get the file size of.

Returns

  1. number The size of the file, in bytes.

Throws

  • If the path doesn't exist.

getFreeSpace(path)Source

Returns the amount of free space available on the drive the path is located on.

Parameters

  1. path string The path to check the free space for.

Returns

  1. number | "unlimited" The amount of free space available, in bytes, or "unlimited".

Throws

  • If the path doesn't exist.

find(path)Source

Searches for files matching a string with wildcards.

This string is formatted like a normal path string, but can include any number of wildcards (*) to look for files matching anything. For example, rom/* /command* will look for any path starting with command inside any subdirectory of /rom.

Parameters

  1. path string The wildcard-qualified path to search for.

Returns

  1. { string... } A list of paths that match the search string.

Throws

  • If the path doesn't exist.

combine(pathA, pathB)Source

Combines two parts of a path into one full path, adding separators as needed.

Parameters

  1. pathA string The first part of the path. For example, a parent directory path.
  2. pathB string The second part of the path. For example, a file name.

Returns

  1. string The new path, with separators added between parts as needed.
makeDir(path)Source

Creates a directory, and any missing parents, at the specified path.

Parameters

  1. path string The path to the directory to create.

Throws

  • If the directory couldn't be created.

list(path)Source

Returns a list of files in a directory.

Parameters

  1. path string The path to list.

Returns

  1. { string... } A table with a list of files in the directory.

Throws

  • If the path doesn't exist.

getName(path)Source

Returns the file name portion of a path.

Parameters

  1. path string The path to get the name from.

Returns

  1. string The final part of the path (the file name).
isDir(path)Source

Returns whether the specified path is a directory.

Parameters

  1. path string The path to check.

Returns

  1. boolean Whether the path is a directory.
getCapacity(path)Source

Returns true if a path is mounted to the parent filesystem.

The root filesystem "/" is considered a mount, along with disk folders and the rom folder. Other programs (such as network shares) can extend this to make other mount types by correctly assigning their return value for getDrive.

Parameters

  1. path string The path of the drive to get.

Returns

  1. number | nil This drive's capacity. This will be nil for "read-only" drives, such as the ROM or treasure disks.

Throws

  • If the capacity cannot be determined.

exists(path)Source

Returns whether the specified path exists.

Parameters

  1. path string The path to check the existence of.

Returns

  1. boolean Whether the path exists.
delete(path)Source

Deletes a file or directory.

If the path points to a directory, all of the enclosed files and subdirectories are also deleted.

Parameters

  1. path string The path to the file or directory to delete.

Throws

  • If the file or directory couldn't be deleted.

open(path, mode)Source

Opens a file for reading or writing at a path.

The mode parameter can be r to read, w to write (deleting all contents), or a to append (keeping contents). If b is added to the end, the file will be opened in binary mode; otherwise, it's opened in text mode.

Parameters

  1. path string The path to the file to open.
  2. mode string The mode to open the file with.

Returns

  1. table A file handle object for the file.

Or

  1. nil If the file does not exist, or cannot be opened.
  2. string | nil A message explaining why the file cannot be opened.

Throws

  • If an invalid mode was specified.

Types

BinaryReadHandle

A file handle opened with fs.open with the "rb" mode.

BinaryReadHandle.readLine([withTrailingArg])Source

Read a line from the file.

Parameters

  1. withTrailingArg? boolean Whether to include the newline characters with the returned string. Defaults to false.

Returns

  1. string | nil The read line or nil if at the end of the file.

Throws

  • If the file has been closed.

BinaryReadHandle.seek([whence[, offset]])Source

Seek to a new position within the file, changing where bytes are written to. The new position is an offset given by offset, relative to a start position determined by whence:

  • "set": offset is relative to the beginning of the file.
  • "cur": Relative to the current position. This is the default.
  • "end": Relative to the end of the file.

In case of success, seek returns the new file position from the beginning of the file.

Parameters

  1. whence? string Where the offset is relative to.
  2. offset? number The offset to seek to.

Returns

  1. number The new position.

Or

  1. nil If seeking failed.
  2. string The reason seeking failed.

Throws

  • If the file has been closed.

BinaryReadHandle.close()Source

Close this file, freeing any resources it uses.

Once a file is closed it may no longer be read or written to.

Throws

  • If the file has already been closed.

BinaryReadHandle.read([countArg])Source

Read a number of bytes from this file.

Parameters

  1. countArg? number

    The number of bytes to read. When absent, a single byte will be read as a number. This

                 may be 0 to determine we are at the end of the file.

Returns

  1. nil If we are at the end of the file.

Or

  1. number The value of the byte read. This is returned when the count is absent.

Or

  1. string The bytes read as a string. This is returned when the count is given.

Throws

  • When trying to read a negative number of bytes.

  • If the file has been closed.

BinaryReadHandle.readAll()Source

Read the remainder of the file.

Returns

  1. string | nil The remaining contents of the file, or nil if we are at the end.

Throws

  • If the file has been closed.

ReadHandle

A file handle opened with fs.open with the "r" mode.

ReadHandle.readLine([withTrailingArg])Source

Read a line from the file.

Parameters

  1. withTrailingArg? boolean Whether to include the newline characters with the returned string. Defaults to false.

Returns

  1. string | nil The read line or nil if at the end of the file.

Throws

  • If the file has been closed.

ReadHandle.read([countA])Source

Read a number of characters from this file.

Parameters

  1. countA? number The number of characters to read, defaulting to 1.

Returns

  1. string | nil The read characters, or nil if at the of the file.

Throws

  • When trying to read a negative number of characters.

  • If the file has been closed.

ReadHandle.readAll()Source

Read the remainder of the file.

Returns

  1. nil | string The remaining contents of the file, or nil if we are at the end.

Throws

  • If the file has been closed.

ReadHandle.close()Source

Close this file, freeing any resources it uses.

Once a file is closed it may no longer be read or written to.

Throws

  • If the file has already been closed.

WriteHandle

A file handle opened by fs.open using the "w" or "a" modes.

WriteHandle.close()Source

Close this file, freeing any resources it uses.

Once a file is closed it may no longer be read or written to.

Throws

  • If the file has already been closed.

WriteHandle.writeLine(The)Source

Write a string of characters to the file, follwing them with a new line character.

Parameters

  1. The value to write to the file.

Throws

  • If the file has been closed.

WriteHandle.flush()Source

Save the current file without closing it.

Throws

  • If the file has been closed.

WriteHandle.write(The)Source

Write a string of characters to the file.

Parameters

  1. The value to write to the file.

Throws

  • If the file has been closed.

BinaryWriteHandle

A file handle opened by fs.open using the "wb" or "ab" modes.

BinaryWriteHandle.seek([whence[, offset]])Source

Seek to a new position within the file, changing where bytes are written to. The new position is an offset given by offset, relative to a start position determined by whence:

  • "set": offset is relative to the beginning of the file.
  • "cur": Relative to the current position. This is the default.
  • "end": Relative to the end of the file.

In case of success, seek returns the new file position from the beginning of the file.

Parameters

  1. whence? string Where the offset is relative to.
  2. offset? number The offset to seek to.

Returns

  1. number The new position.

Or

  1. nil If seeking failed.
  2. string The reason seeking failed.

Throws

  • If the file has been closed.

BinaryWriteHandle.write(...)Source

Write a string or byte to the file.

Parameters

  1. The number byte to write.

Or

  1. The string string to write.

Throws

  • If the file has been closed.

BinaryWriteHandle.flush()Source

Save the current file without closing it.

Throws

  • If the file has been closed.

BinaryWriteHandle.close()Source

Close this file, freeing any resources it uses.

Once a file is closed it may no longer be read or written to.

Throws

  • If the file has already been closed.