Fs API

The Fs API allows you to mess around with the filesystem. All the methods of this API are listed below.

Note: All of these functions except for fs.combine refer solely to absolute paths.
This means that the current working directory, as set by the cd command or the shell.setDir function, is ignored. Each path name consists of a list of nonempty path components separated by forward slashes, and those path components are taken one by one with the first being contained in the root directory of the computer.

If you need to deal with paths provided by the user that may be absolute or may be relative to the current working directory, use shell.resolve.

Unlike most real-world operating systems, ComputerCraft's absolute path name system does not need to be started with a forward slash ( / ). Making the directory "a/b/c" is the same as making "/a/b/c". Leaving the slashes is just a matter of preference to the coder.

fs.list

Function fs.list
Syntax	fs.list(string path)
Returns	table list of files and folders in path, which must be a directory
Description	Returns a list of all the files contained in a directory, in table format

Examples

Description	Displays a list of all files and folders in the root directory of a computer
Code	local FileList = fs.list("") --Table with all the files and directories available for _,file in ipairs( FileList ) do --Loop. Underscore because we don't use the key, ipairs so it's in order print( file ) --Print the file name end --End the loop
Output	A list of all files and folders in the root directory as a table. Note that fs.list() could also be inserted directly into ipairs() or pairs()

fs.exists

Function fs.exists
Syntax	fs.exists(string path)
Returns	boolean true if path is an existing file or directory, or false if not
Description	Checks whether a file or directory exists

Examples

Description	Checks that the "rom" directory exists
Code	print(fs.exists("rom"))
Output	true

fs.isDir

Function fs.isDir
Syntax	fs.isDir(string path)
Returns	boolean true if path is an existing directory, or false if not (if it doesn't exist or if it is a regular file)
Description	Checks whether a directory exists

Examples

Description	Checks that the "rom" directory is, in fact, a directory
Code	print(fs.isDir("rom"))
Output	true

fs.isReadOnly

Function fs.isReadOnly
Syntax	fs.isReadOnly(string path)
Returns	boolean false if path can be written to, or true if not
Description	Checks whether a path can be written to (the path need not exist in order to perform this test)

Examples

Description	Checks that the "rom" directory is read-only, as its name implies
Code	print(fs.isReadOnly("rom"))
Output	true

fs.getName

Function fs.getName
Syntax	fs.getName(string path)
Returns	string the last path component of the path, or the string "root" if the path refers to the root directory
Description	Returns the last path component (forward-slash-separated) component of a path (which need not exist)

Examples

Description	Gets the last path component of a file
Code	print(fs.getName("rom/apis/colors"))
Output	colors

fs.getDrive

Function fs.getDrive
Syntax	fs.getDrive(string path)
Returns	string the type of storage medium holding the path, as of ComputerCraft 1.3 one of "rom" or "hdd"[1]
Description	Returns the storage medium holding a path, or nil if the path does not exist

Examples

Description	Checks that the standard "startup" file is stored in ROM
Code	print(fs.getDrive("rom/startup"))
Output	rom

fs.getSize

Function fs.getSize
Syntax	fs.getSize(string path)
Returns	bytes
Description	Gets the size of a file

Examples

Description	Get the size of the shell from the ROM and print it
Code	print( fs.getSize("/rom/programs/shell") )

fs.makeDir

Function fs.makeDir
Syntax	fs.makeDir(string path)
Returns	nil
Description	Creates a directory (fails if the location already exists as a file; silently does nothing if the location or a parent already exists as a directory; recursively creates directories if a parent is also missing)

Examples

Description	Create a directory called "efgh" inside a directory called "abcd" ("abcd" need not exist; it will be created)
Code	fs.makeDir("abcd/efgh")

fs.move

Function fs.move
Syntax	fs.move(string fromPath, string toPath)
Returns	nil
Description	Moves a file or directory to a new location (the parent of the new location must be a directory, toPath must include the target filename and cannot be only a directory to move the file into, and toPath itself must not already exist)

Examples

Description	Renames a file from "test1" to "test2" and moves it from the root directory into a directory called "mydir"
Code	fs.move("test1", "mydir/test2")

fs.copy

Function fs.copy
Syntax	fs.copy(string fromPath, string toPath)
Returns	nil
Description	Copies a file or directory to a new location (the parent of the new location must be a directory, toPath must include the target filename and cannot be only a directory to move the file into, and toPath itself must not already exist)

Examples

Description	Makes a copy of a file "test1" in the root directory, calling it "test2" and storing the copy in a directory called "mydir"
Code	fs.copy("test1", "mydir/test2")

fs.delete

Function fs.delete
Syntax	fs.delete(string path)
Returns	nil
Description	Deletes a file or directory (a nonexistent target is ignored; a directory will be deleted along with all its contents)

Examples

Description	Deletes a file or directory called "test1" in the root directory
Code	fs.delete("test1")

fs.combine

Function fs.combine
Syntax	fs.combine(string basePath, string localPath)
Returns	string the combined path
Description	Combines two paths, such that the new path consists of all the components of localPath inside all the components of basePath (neither path needs to exist; this function only manipulates strings and does not touch the filesystem)

Examples

Description	Computes the absolute path to a file called "d" inside a directory called "c", where "c" is itself inside a directory "b" which is inside a directory "a"
Code	print(fs.combine("a/b", "c/d"))
Output	a/b/c/d

Description	An empty first path refers to the root directory, so the second path is returned
Code	print(fs.combine("", "c/d"))
Output	c/d

Description	An empty second path refers to the first path directly, so the first path is returned
Code	print(fs.combine("a/b", ""))
Output	a/b

Description	The last two examples make sense combined, returning the empty string (referring to the root directory)
Code	print(fs.combine("", ""))

fs.open

Function fs.open
Syntax	fs.open(string path, string mode)
Returns	table the file handle, or nil if the mode was read-only or the file did not exist
Description	Opens a file; mode consists of a first character which is one of "r" to open the file read-only, "w" to open it for writing and remove any existing data, or "a" to open for writing but keep existing data and append any writes to the end of the file, plus optionally the second character "b" to open the file for binary access instead of text access (text mode will perform end-of-line conversions necessary to move text files between Windows, Linux, and Mac OS systems; binary files should not have these conversions applied as they will be corrupted)

Examples

Description	Creates the file "abcd" and holds a file handle to it
Code	h = fs.open("abcd", "w")

File Handles

A file handle allows access to a file. A file handle is a table; the functions within the table are accessed with the dot operator (not the colon operator, as may be more intuitive!). The examples below assume a file has already been opened and the handle stored in the variable h.

Files opened in text read mode

A file opened in mode "r" (text read mode) exposes the following functions.

Function h.readLine
Syntax	h.readLine()
Returns	string the next line read from the file, with the end-of-line character stripped; or nil if there are no more lines in the file
Description	Reads the next line from the file

Function h.readAll
Syntax	h.readAll()
Returns	string the entire rest of the file, with the end-of-line character on the very last line (if present) stripped
Description	Reads the rest of the text in the file

Function h.close
Syntax	h.close()
Returns	nil
Description	Closes the file handle, after which it can no longer be used

Files opened in text write/append mode

A file opened in mode "w" (text write mode) or "a" (text append mode) exposes the following functions:

Function h.write
Syntax	h.write(string data)
Returns	nil
Description	Writes a string of characters to the file exactly as they appear in the string data

Function h.writeLine
Syntax	h.writeLine(string data)
Returns	nil
Description	Writes a string of characters to the file, then appends an end-of-line character

Function h.close
Syntax	h.close()
Returns	nil
Description	Closes the file handle, after which it can no longer be used

Files opened in binary read mode

A file opened in mode "rb" (binary read mode) exposes the following functions:

Function h.read
Syntax	h.read()
Returns	int the byte read from the file, or nil if there are no more bytes
Description	Reads a single byte from the file and returns it

Function h.close
Syntax	h.close()
Returns	nil
Description	Closes the file handle, after which it can no longer be used

Files opened in binary write/append mode

A file opened in mode "wb" (binary write mode) or "ab" (binary append mode) exposes the following functions:

Function h.write
Syntax	h.write(int byte)
Returns	nil
Description	Writes a single byte into the file

Function h.close
Syntax	h.close()
Returns	nil
Description	Closes the file handle, after which it can no longer be used