Fs API

Revision as of 01:13, 25 December 2012 by Mastergalen (talk | contribs) (1 revision)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)

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
Cookies help us deliver our services. By using our services, you agree to our use of cookies.

Need wiki hosting?

Do you need a wiki for your Minecraft mod/gaming wiki? We'll host it for free! Contact us.

Other wikis

Indie-game wikis
Powered by Indie Wikis