FileAPI

From FiguraMC
(Redirected from File)
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.

allowed


Checks if FileAPI usage is allowed for this avatar.

Arguments Return Type
allowed() boolean
-- Prints false on non-host avatar.
print(file:allowed())

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.

exists


Checks if specified path exists.

Arguments Return Type
exists(path string) boolean
print(file:exists("foo.bar")) -- true

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.

isDirectory


Checks if specified path is directory.

Arguments Return Type
isDirectory(path string) boolean
print(file:isDirectory("fooBar")) -- true

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

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

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.

isFile


Checks if specified path is a file.

Arguments Return Type
isFile(path string) boolean
print(file:isFile("foo.bar")) -- true

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


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

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!

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!"))

Navigation

Documentation
Globals
APIs (Types)
Visuals (Types)
Other Types
Enums