FileAPI

This API is only available on the host.

For more information, see Pings.

FileAPI allows your avatar to access files in isolated folder.

FileAPI is available as global file variable.

Security

FileAPI is fully isolated in your data folder. It is located in your Figura folder, so, default path for it would be figura/data. FileAPI can't access any files or directories out of this folder, even when using symbolic links. Attempt to access file or directory outside data folder will result in error. Every used path in methods is relative to data folder.

FileAPI methods

Security checks

Security related methods of FileAPI.

FileAPI:allowed

Checks if FileAPI usage is allowed for this avatar.

Arguments	Return Type
allowed()	boolean

-- Prints false on non-host avatar.
print(file:allowed())

FileAPI:isPathAllowed

Checks if path is allowed for usage.

Arguments	Return Type
isPathAllowed(path string)	boolean

-- Relative paths are always relative to data folder.
print(file:isPathAllowed("foo")) -- true
-- Relative paths that are pointing outside of data folder are not allowed.
print(file:isPathAllowed("../foo")) -- false
-- Absolute paths pointing to figura data folder are also allowed.
print(file:isPathAllowed("C:/path/to/figura/data/foo")) -- true
-- Absolute paths outside of data folder are not allowed.
print(file:isPathAllowed("C:/foo")) -- false

Common

Methods related both to files and directories.

FileAPI:exists

Checks if specified path exists.

Arguments	Return Type
exists(path string)	boolean

print(file:exists("foo.bar")) -- true

FileAPI:delete

Deletes file or directory by specified path. Returns true if successful.

Arguments	Return Type
delete(path string)	boolean

-- Directory fooBar is empty
print(file:delete("fooBar")) -- true
-- Directory barFoo has files inside
print(file:delete("barFoo")) -- false
-- foo.bar is not open by any program
print(file:delete("foo.bar")) -- true
-- bar.foo doesn't exist
print(file:delete("bar.foo")) -- false

Directories

Directory related methods of FileAPI.

FileAPI:isDirectory

Checks if specified path is directory.

Arguments	Return Type
isDirectory(path string)	boolean

print(file:isDirectory("fooBar")) -- true

FileAPI:mkdir

Creates directory by specified path. Returns true if successful.

Arguments	Return Type
mkdir(path string)	boolean

print(file:exists("foo")) -- false
print(file:mkdir("foo")) -- true
print(file:exists("foo")) -- true

@see exists

FileAPI:mkdirs

Creates directory by specified path, and all parent directories if they doesn't exist. Returns true if successful.

Arguments	Return Type
mkdir(path string)	boolean

print(file:exists("foo/bar")) -- false
print(file:mkdir("foo/bar")) -- false
print(file:mkdirs("foo/bar")) -- true
print(file:exists("foo/bar")) -- true

@see exists, mkdir

FileAPI:list

Lists files and directories by specified path. Returns table with paths, or null if path doesn't exist or not a directory.

Arguments	Return Type
list(path string)	string[] | nil

printTable(file:list("")) --[[{
"foo.bar",
"fooBar",
"barFoo"
}]]

Files

Methods related to files.

FileAPI:isFile

Checks if specified path is a file.

Arguments	Return Type
isFile(path string)	boolean

print(file:isFile("foo.bar")) -- true

FileAPI:openReadStream

Open input stream for file at specified path. Throws an error if file doesn't exist.

Arguments	Return Type
openReadStream(path string)	InputStream

-- Opens an input stream.
local is = file:openReadStream("foo.bar")

-- Stream must be closed when you finished working with it.
is:close()

@see InputStream:close

FileAPI:openWriteStream

Open output stream for file at specified path. Throws an error if unable to create a file.

Arguments	Return Type
openWriteStream(path string)	OutputStream

-- Opens an output stream.
local os = file:openWriteStream("bar.foo")

-- Stream must be closed when you finished working with it.
os:close()

@see OutputStream:close

FileAPI:readString

Reads file at specified path and returns it's contents as a string in specified encoding. Default encoding is utf8.

Arguments	Return Type
readString(path string)	string
readString(path string, encoding BufferEncoding)	string

print(file:readString("foo.bar")) -- Hello, world!

FileAPI:writeString

Writes string in specified encoding to file by specified path. Default encoding is utf8.

Arguments
writeString(path string, contents string)
writeString(path string, contents string, encoding BufferEncoding)

print(file:writeString("foo.bar", "Hello, world!"))