IO Directory

Table of Contents

• Directory
  • (constructor)
  • Directory.of
  • Directory.savedata
  • path
  • relative_path
  • name
  • parent
  • root
  • relativize
  • file
  • directory
  • files
  • directories
  • make_directories
  • exists
  • is_ancestor
  • delete

 

Directory

A class used to represent abstract directories 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 directory function, you receive a new, separate instance of Directory 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: Directory Directory(paths...)

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

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

Example:

local rootDirectory = Directory()
local modsDirectory = Directory("mods")
local localizationDirectory = Directory("scripts", "localization")

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

 

static Directory.of

Signature: Directory Directory.of(instance)

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

 

static Directory.savedata

Signature: Directory Directory.savedata()

Returns a Directory instance representing the save data directory, if it is found to exist in one of the known locations.

Example:

local savedataDirectory = Directory.savedata()

 

path

Signature: string path()

Returns the absolute path to this Directory.

Example:

local dir = Directory("some", "path", "..", "to", ".", "directory")
LOG(dir:path()) -- prints "<ITB_ROOT_PATH>/some/to/directory"

 

relative_path

Signature: string relative_path()

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

Example:

local dir = Directory("mods")
LOG(dir:path()) -- prints "<ITB_ROOT_PATH>/mods"
LOG(dir:relative_path()) -- prints "mods"

local dir = Directory.savedata():directory("profile")
LOG(dir:path()) -- prints "<ITB_SAVEDATA_PATH>/profile"
LOG(dir:relative_path()) -- prints "profile"

 

name

Signature: string name()

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

Example:

local dir = Directory("some", "path")
LOG(dir:name()) -- prints "path"

 

parent

Signature: Directory parent()

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

Example:

local dir = Directory("some", "path")
local parent = dir:parent()
LOG(parent:name()) -- prints "some"

 

root

Signature: Directory root()

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

Example:

local dir = Directory("some", "path")
local root = dir:root()
LOG(root:path()) -- prints "<ITB_ROOT_PATH>"

 

relativize

Signature: string relativize(path)

Argument name	Type	Description
path	string	Path relative to this directory

Relativizes the specified path relative to this directory. More generally, returns a string that can later be used to navigate to the specified path by invoking directory or file functions on this Directory instance.

Example:

Directory("some/path"):relativize("some/path/test")  -- returns "test"
Directory("some/path/test"):relativize("some/path")  -- returns ".."

 

file

Signature: File file(paths...)

Argument name	Type	Description
paths	string...	Path to the file, relative to this directory. Optional. Multiple strings can be provided, and will be concatenated together using /.

Returns 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 dir = Directory("some", "path")
local file = dir:file("file.txt")

 

directory

Signature: Directory directory(paths...)

Argument name	Type	Description
paths	string...	Path to the directory, relative to this directory. Optional. Multiple strings can be provided, and will be concatenated together using /.

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

Example:

local someDirectory = Directory("some")
local pathDirectory = someDirectory:directory("path")

 

files

Signature: table files()

Returns a list of File instances, representing all files that are direct children of this directory.

Example:

local dir = Directory()
for _, file in dir:files() do
    LOG(file:path())
end

 

directories

Signature: table directories()

Returns a list of Directory instances, representing all directories that are direct children of this directory.

Example:

local parentDir = Directory()
for _, dir in parentDir:directories() do
    LOG(dir:path())
end

 

make_directories

Signature: void make_directories()

Attempts to create missing directories in this Directory'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 dir = Directory("some", "path")
dir:make_directories() -- creates directory "some" within ITB's root directory, and "path" directory within "some".

 

exists

Signature: boolean exists()

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

Example:

local rootDir = Directory()
local someDir = rootDir:directory("some")

LOG(rootDir:exists()) -- prints "true"
LOG(someDir:exists()) -- prints "false"

 

is_ancestor

Signature: boolean is_ancestor(path)

Argument name	Type	Description
path	string	Absolute path to be converted to a relative path

Returns true if this directory is an ancestor to the specified path, false otherwise. More generally, checks whether the specified path starts with this directory's path.
Throws an error if path is not absolute.

Example:

local root = Directory()
local dir = root:directory("some/path")

LOG(root:is_ancestor(dir:path()))  -- prints "true"
LOG(dir:is_ancestor(root:path()))  -- prints "false"

LOG(dir:is_ancestor(dir:path()))  --  prints "true" - a directory is its own ancestor according to this logic :)

delete

Signature: void delete()

Deletes this directory and all its contents.