Table of Contents

• File
  • (constructor)
  • File.of
  • path
  • relative_path
  • name
  • name_without_extension
  • extension
  • parent
  • root
  • read_to_string
  • read_to_byte_array
  • write_string
  • write_byte_array
  • append
  • copy
  • move
  • make_directories
  • exists
  • delete

 

File

A class used to represent abstract files on the file system, providing functions to make file system navigation easier, and reduce the need for string concatenations to represent paths.

Instances of this class validate their paths and ensure that Lua code never accesses directories or files that are not relevant to the game, ie. are located outside of the game's installation directory or save data directory. If such a path if provided, an error is thrown.

Instances of this class should be considered immutable, meaning that they always represent the same location, and are not supposed to change once created. Each time you navigate to a different location, for example by invoking the move function, you receive a new, separate instance of File class to represent that location.

Instances of this class are thin wrappers around a string path that do not hold any file system resources, and should therefore be cheap to create, and do not need to be manually cleaned up.

 

(constructor)

Signature: File File(paths...)

Argument name	Type	Description
paths	string...	Path to the file, either absolute or relative to the game's root directory. Optional.Multiple strings can be provided, and will be concatenated together using /.

Creates a File instance representing the specified file. If the path points to a location outside of the game's root directory or save data directory, an error is thrown.

Example:

local errorFile = File("error.txt")
local scriptsFile = File("scripts", "scripts.lua")
local textFile = File("scripts/text.lua")

local error = File("../somefile.txt") -- throws an error due to attempting to navigate to the parent of ITB's installation directory

 

static File.of

Signature: File File.of(instance)

Internal implementation detail. Should not be used anywhere outside of ITB_IO's internal code.

 

path

Signature: string path()

Returns the absolute path to this File.

Example:

local file = File("some/path/../to/./file.txt")
LOG(file:path()) -- prints "<ITB_ROOT_PATH>/some/to/file.txt"

 

relative_path

Signature: string relative_path()

Returns the relative path to this File from its root ancestor Directory (either the game's installation directory or the savedata directory).

Example:

local file = File("error.txt")
LOG(file:path()) -- prints "<ITB_ROOT_PATH>/error.txt"
LOG(file:relative_path()) -- prints "error.txt"

local file = File("scripts/scripts.lua")
LOG(file:path()) -- prints "<ITB_ROOT_PATH>/scripts/scripts.lua"
LOG(file:relative_path()) -- prints "scripts/scripts.lua"

local file = Directory.savedata():file("settings.lua")
LOG(file:path()) -- prints "<ITB_SAVEDATA_PATH>/settings.lua"
LOG(file:relative_path()) -- prints "settings.lua"

 

name

Signature: string name()

Returns the last component of the path to this File, ie. its name.

Example:

local file = File("some/file.txt")
LOG(file:name()) -- prints "file.txt"

 

name_without_extension

Signature: string name_without_extension()

Returns part of this File's name before the last dot, ie. its name without the extension.

Example:

local file = File("some/other.file.txt")
LOG(file:name_without_extension()) -- prints "other.file"

 

extension

Signature: string extension()

Returns part of this File's name after the last dot, ie. its extension.

Example:

local file = File("some/other.file.txt")
LOG(file:extension()) -- prints "txt"

 

parent

Signature: Directory parent()

Returns a Directory instance representing this File's parent directory.

Example:

local file = File("some/file.txt")
local parent = file:parent()
LOG(parent:name()) -- prints "some"

 

root

Signature: Directory root()

Returns a Directory instance representing this File's root directory - either the game's installation directory or the save data directory.

Example:

local file = File("some/file.txt")
local root = file:root()
LOG(root:path()) -- prints "<ITB_ROOT_PATH>"

 

read_to_string

Signature: string read_to_string()

Returns contents of the File as string.

Example:

local file = File("scripts/scripts.lua")
LOG(file:read_to_string()) -- prints contents of the file

 

read_to_byte_array

Signature: table read_to_byte_array()

Returns contents of the File as a byte array

Example:

local file = File("scripts/scripts.lua")
local byte_array = file:read_to_byte_array()
LOG(save_table(byte_array)) -- prints contents of the file as a byte array

 

write_string

Signature: void write_string(content)

Argument name	Type	Description
content	string	String that will replace the file's content

Replaces the file's content with the specified string content.

Example:

local file = File("test.txt")
file:write_string("some text that will end up inside the file")

 

write_byte_array

Signature: void write_byte_array(content)

Argument name	Type	Description
content	table	Byte array table that will replace the file's content

Replaces the file's content with the specified byte array content.

Example:

local file = File("test.bin")
file:write_byte_array({ 127, 13, 6 })

 

append

Signature: void append(content)

Argument name	Type	Description
content	string	String content

Appends the specified string content at the end of the file.

Example:

local file = File("test.txt")
file:append("some text that is ")
file:append("split across two appends.")

 

copy

Signature: File copy(destination)

Argument name	Type	Description
destination	string	Path to copy the file to

Copies this File to the specified destination path. Returns a new File instance for the destination path.

Example:

local file = File("error.txt")
file:copy("error2.txt")

 

move

Signature: File move(destination)

Argument name	Type	Description
destination	string	Path to move the file to

Moves this File to the specified destination path. Moving a file to a different location within the same directory is functionally the same as renaming it. Returns a new File instance for the destination path.

Example:

local file = File("error.txt")
file:move("error2.txt")

 

make_directories

Signature: void make_directories()

Attempts to create missing directories in this File's abstract path, ensuring that they actually exist on the file system.

Most of the time you do not need to call this function. Attempting to write to a file using File functions will automatically create the file and all its missing ancestors.

Example:

local file = File("some", "path", "file.txt")
file:make_directories() -- creates directory "some" within ITB's root directory, and "path" directory within "some".

 

exists

Signature: boolean exists()

Returns true if this File actually exists on the file system, false otherwise.

Example:

local errorFile = File("error.txt")
local randomFile = File("non_existing_file.txt")

LOG(errorFile:exists()) -- prints "true"
LOG(randomFile:exists()) -- prints "false"

 

delete

Signature: void delete()

Deletes this file.