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 _G.read. |
list(path) | Returns a list of files in a directory. |
combine(path, ...) | Combines several parts of a path into one full path, adding separators as needed. |
getName(path) | Returns the file name portion of a path. |
getDir(path) | Returns the parent directory portion of a path. |
getSize(path) | Returns the size of the specified file. |
exists(path) | Returns whether the specified path exists. |
isDir(path) | Returns whether the specified path is a directory. |
isReadOnly(path) | Returns whether a path is read-only. |
makeDir(path) | Creates a directory, and any missing parents, at the specified path. |
move(path, dest) | Moves a file or directory from one path to another. |
copy(path, dest) | Copies a file or directory to a new path. |
delete(path) | Deletes a file or directory. |
open(path, mode) | Opens a file for reading or writing at a path. |
getDrive(path) | Returns the name of the mount that the specified path is located on. |
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. |
getCapacity(path) | Returns true if a path is mounted to the parent filesystem. |
attributes(path) | Get attributes about a specific file or folder. |
- 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
- path string The path to check.
Returns
- 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 _G.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
- path string The path to complete.
- location string The location where paths are resolved from.
- include_files? boolean When false, only directories will be included in the returned list.
- include_dirs? boolean When false, "raw" directories will not be included in the returned list.
Returns
- { string... } A list of possible completion candidates.
- list(path)Source
Returns a list of files in a directory.
Parameters
- path string The path to list.
Returns
- { string... } A table with a list of files in the directory.
Throws
If the path doesn't exist.
- combine(path, ...)Source
Combines several parts of a path into one full path, adding separators as needed.
Parameters
- path string The first part of the path. For example, a parent directory path.
- ... string Additional parts of the path to combine.
Returns
- string The new path, with separators added between parts as needed.
Throws
On argument errors.
- getName(path)Source
Returns the file name portion of a path.
Parameters
- path string The path to get the name from.
Returns
- string The final part of the path (the file name).
- getDir(path)Source
Returns the parent directory portion of a path.
Parameters
- path string The path to get the directory from.
Returns
- string The path with the final part removed (the parent directory).
- getSize(path)Source
Returns the size of the specified file.
Parameters
- path string The file to get the file size of.
Returns
- number The size of the file, in bytes.
Throws
If the path doesn't exist.
- exists(path)Source
Returns whether the specified path exists.
Parameters
- path string The path to check the existence of.
Returns
- boolean Whether the path exists.
- isDir(path)Source
Returns whether the specified path is a directory.
Parameters
- path string The path to check.
Returns
- boolean Whether the path is a directory.
- isReadOnly(path)Source
Returns whether a path is read-only.
Parameters
- path string The path to check.
Returns
- boolean Whether the path cannot be written to.
- makeDir(path)Source
Creates a directory, and any missing parents, at the specified path.
Parameters
- path string The path to the directory to create.
Throws
If the directory couldn't be created.
- move(path, dest)Source
Moves a file or directory from one path to another.
Any parent directories are created as needed.
Parameters
- path string The current file or directory to move from.
- dest string The destination path for the file or directory.
Throws
If the file or directory couldn't be moved.
- copy(path, dest)Source
Copies a file or directory to a new path.
Any parent directories are created as needed.
Parameters
- path string The file or directory to copy.
- dest string The path to the destination file or directory.
Throws
If the file or directory couldn't be copied.
- 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
- 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), ora
to append (keeping contents). Ifb
is added to the end, the file will be opened in binary mode; otherwise, it's opened in text mode.Parameters
Returns
- table A file handle object for the file.
Or
- nil If the file does not exist, or cannot be opened.
- string | nil A message explaining why the file cannot be opened.
Throws
If an invalid mode was specified.
- getDrive(path)Source
Returns the name of the mount that the specified path is located on.
Parameters
- path string The path to get the drive of.
Returns
- string The name of the drive that the file is on; e.g.
hdd
for local files, orrom
for ROM files.
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
- path string The path to check the free space for.
Returns
- 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 withcommand
inside any subdirectory of/rom
.Parameters
- path string The wildcard-qualified path to search for.
Returns
- { string... } A list of paths that match the search string.
Throws
If the path doesn't exist.
- 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
- path string The path of the drive to get.
Returns
- 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.
- 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, when it was created and last modified, and whether it is read only.
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
- path string The path to get attributes for.
Returns
- { size = number, isDir = boolean, isReadOnly = boolean, created = number, modified = number } The resulting attributes.
Throws
If the path does not exist.
See also
Types
ReadHandle
A file handle opened with fs.open with the "r"
mode.
- ReadHandle.readLine([withTrailing])Source
Read a line from the file.
Parameters
- withTrailing? boolean Whether to include the newline characters with the returned string. Defaults to false.
Returns
- string | nil The read line or nil if at the end of the file.
Throws
If the file has been closed.
- ReadHandle.readAll()Source
Read the remainder of the file.
Returns
- nil | string The remaining contents of the file, or nil if we are at the end.
Throws
If the file has been closed.
- ReadHandle.read([count])Source
Read a number of characters from this file.
Parameters
- count? number The number of characters to read, defaulting to 1.
Returns
- 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.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
A file handle opened with fs.open with the "rb"
mode.
- BinaryReadHandle.read([count])Source
Read a number of bytes from this file.
Parameters
- count? 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
- nil If we are at the end of the file.
Or
- number The value of the byte read. This is returned when the
count
is absent.
Or
- 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.
- count? number
- BinaryReadHandle.readAll()Source
Read the remainder of the file.
Returns
- string | nil The remaining contents of the file, or nil if we are at the end.
Throws
If the file has been closed.
- BinaryReadHandle.readLine([withTrailing])Source
Read a line from the file.
Parameters
- withTrailing? boolean Whether to include the newline characters with the returned string. Defaults to false.
Returns
- string | nil The read line or nil if at the end of the file.
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.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 bywhence
:"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
- whence? string Where the offset is relative to.
- offset? number The offset to seek to.
Returns
- number The new position.
Or
- nil If seeking failed.
- string The reason seeking failed.
Throws
If the file has been closed.
WriteHandle
A file handle opened by fs.open using the "w"
or "a"
modes.
- WriteHandle.write(value)Source
Write a string of characters to the file.
Parameters
- value The value to write to the file.
Throws
If the file has been closed.
- WriteHandle.writeLine(value)Source
Write a string of characters to the file, follwing them with a new line character.
Parameters
- value 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.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.
BinaryWriteHandle
A file handle opened by fs.open using the "wb"
or "ab"
modes.
- BinaryWriteHandle.write(...)Source
Write a string or byte to the file.
Parameters
- The number byte to write.
Or
- 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.
- 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 bywhence
:"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
- whence? string Where the offset is relative to.
- offset? number The offset to seek to.
Returns
- number The new position.
Or
- nil If seeking failed.
- string The reason seeking failed.
Throws
If the file has been closed.