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"))
FileAPI:delete
Deletes file or directory by specified path. Returns true if successful.
| Arguments | Return Type |
|---|---|
delete(path string)
|
boolean |
-- Directory foo is empty
print(file:delete("foo")) -- true
-- Directory bar has files inside
print(file:delete("bar")) -- false
-- foo.bar is not open by any program
print(file:delete("foo.bar")) -- true
-- bar.foo is open by some program
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("foo"))
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
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
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[]? |
local contents = file:list("path/to/dir")
Files
Methods related to files.
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()
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()
FileAPI:readString
Reads file at specified path and returns it's contents as a string.
| Arguments | Return Type |
|---|---|
readString(path string)
|
string |
readString(path string, encoding string)
|
string |
print(file:readString("foo.bar")) -- Hello, world!
FileAPI:writeString
Writes string in file by specified path.
| Arguments |
|---|
writeString(path string, contents string)
|
writeString(path string, contents string, encoding string)
|
print(file:writeString("foo.bar", "Hello, world!"))