2024-09-28T13:55:13Z

Lexize: Created page with "{{Host only|kind=API}} <code>FileAPI</code> allows your avatar to access files in isolated folder. FileAPI is available as global <code>file</code> variable. == Security == FileAPI is fully isolated in your data folder. It is located in your Figura folder, so, default path for it would be <code>figura/data</code>. 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 wi..."

{{Host only|kind=API}}

<code>FileAPI</code> allows your avatar to access files in isolated folder.

FileAPI is available as global <code>file</code> variable.

== Security ==
FileAPI is fully isolated in your data folder. It is located in your Figura folder, so, default path for it would be <code>figura/data</code>. 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.

==== <code>FileAPI:allowed</code> ====

Checks if FileAPI usage is allowed for this avatar.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>allowed()</code>
| {{type|boolean}}
|}

<syntaxhighlight lang="lua">
-- Prints false on non-host avatar.
print(file:allowed())
</syntaxhighlight>

==== <code>FileAPI:isPathAllowed</code> ====

Checks if path is allowed for usage.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>isPathAllowed(path {{type|string}})</code>
| {{type|boolean}}
|}

<syntaxhighlight lang="lua">
-- 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
</syntaxhighlight>

=== Common ===

Methods related both to files and directories.

==== <code>FileAPI:exists</code> ====

Checks if specified path exists.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>exists(path {{type|string}})</code>
| {{type|boolean}}
|}

<syntaxhighlight lang="lua">
print(file:exists("foo"))
</syntaxhighlight>

==== <code>FileAPI:delete</code> ====

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

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>delete(path {{type|string}})</code>
| {{type|boolean}}
|}

<syntaxhighlight lang="lua">
-- 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
</syntaxhighlight>

=== Directories ===

Directory related methods of FileAPI.

==== <code>FileAPI:isDirectory</code> ====

Checks if specified path is directory.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>isDirectory(path {{type|string}})</code>
| {{type|boolean}}
|}

<syntaxhighlight lang="lua">
print(file:isDirectory("foo"))
</syntaxhighlight>

==== <code>FileAPI:mkdir</code> ====

Creates directory by specified path. Returns true if successful.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>mkdir(path {{type|string}})</code>
| {{type|boolean}}
|}

<syntaxhighlight lang="lua">
print(file:exists("foo")) -- false
print(file:mkdir("foo")) -- true
print(file:exists("foo")) -- true
</syntaxhighlight>

==== <code>FileAPI:mkdirs</code> ====

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

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>mkdir(path {{type|string}})</code>
| {{type|boolean}}
|}

<syntaxhighlight lang="lua">
print(file:exists("foo/bar")) -- false
print(file:mkdir("foo/bar")) -- false
print(file:mkdirs("foo/bar")) -- true
print(file:exists("foo/bar")) -- true
</syntaxhighlight>

==== <code>FileAPI:list</code> ====

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

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>list(path {{type|string}})</code>
| {{type|string}}[]?
|}

<syntaxhighlight lang="lua">
local contents = file:list("path/to/dir")
</syntaxhighlight>

=== Files ===
Methods related to files.

==== <code>FileAPI:openReadStream</code> ====

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

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>openReadStream(path {{type|string}})</code>
| {{type|InputStream}}
|}

<syntaxhighlight lang="lua">
-- Opens an input stream.
local is = file:openReadStream("foo.bar")

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

==== <code>FileAPI:openWriteStream</code> ====

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

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>openWriteStream(path {{type|string}})</code>
| {{type|OutputStream}}
|}

<syntaxhighlight lang="lua">
-- Opens an output stream.
local os = file:openWriteStream("bar.foo")

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

==== <code>FileAPI:readString</code> ====

Reads file at specified path and returns it's contents as a string.

{| class="wikitable"
! Arguments !! Return Type
|-
| <code>readString(path {{type|string}})</code>
| {{type|string}}
|-
| <code>readString(path {{type|string}}, encoding {{type|string}})</code>
| {{type|string}}
|}

<syntaxhighlight lang="lua">
print(file:readString("foo.bar")) -- Hello, world!
</syntaxhighlight>

==== <code>FileAPI:writeString</code> ====

Writes string in file by specified path.

{| class="wikitable"
! Arguments
|-
| <code>writeString(path {{type|string}}, contents {{type|string}})</code>
|-
| <code>writeString(path {{type|string}}, contents {{type|string}}, encoding {{type|string}})</code>
|}

<syntaxhighlight lang="lua">
print(file:writeString("foo.bar", "Hello, world!"))
</syntaxhighlight>