classDocs / File

File

classsharedsource

Object → File

The file object.

A thin handle over a vfs path, the file is not opened or cached, every call goes to vfs, so the object can exist before its file.

Fields path, name and content are backed by vfs, assigning them moves, renames or writes the file, reading and writing are asynchronous inside of a coroutine and synchronous outside of it.

lua

local file = File( "/garrysmod/data/test.txt" )
file.content = "hello" -- write
print( file.content, file.size ) -- "hello" 5
file.name = "renamed.txt" -- rename
file.path = "/garrysmod/data/other/test.txt" -- move

Constructor

File(file_path: string, touch: boolean?): File

Fields

Name	Type	Description
`path`	`string`	The absolute virtual path of the file, assigning moves the file without overwriting, the target directory must exist.
`name`	`string`	The name of the file with its extension, assigning renames the file without overwriting.
`content`	`string`	The file data, reading reads the whole file, assigning replaces it.
`size`	`integer`	The size of the file in bytes, `0` if the file does not exist. Read-only.
`parent`	`Directory`	The directory the file is in, assigning moves the file into the directory without overwriting.

Static functions

#File.exists

sharednodiscardsource

function File.exists(file_path: string): boolean

Checks if a file exists.

Parameters

Name	Type	Description
`file_path`	`string`	The absolute path to the file.

Returns

Type	Name	Description
`boolean`	`exists`	`true` if the file exists, `false` otherwise.

Methods

`append`	Appends data to the end of the file, the file and missing directories are created, asynchronously inside of a coroutine.
`delete`	Deletes the file, the object stays usable and write or touch creates it again.
`exists`	Checks if the file exists.
`move`	Moves the file, the target directory must exist, asynchronously inside of a coroutine.
`read`	Reads the whole file, asynchronously inside of a coroutine.
`rename`	Renames the file, it stays in its directory, asynchronously inside of a coroutine.
`touch`	Like Linux touch: creates an empty file with missing directories, or updates the modification time keeping its content.
`write`	Replaces the file data, the file and missing directories are created, asynchronously inside of a coroutine.

#File:append

sharedasyncsource

async function File:append(data: string)

Appends data to the end of the file, the file and missing directories are created, asynchronously inside of a coroutine.

Parameters

Name	Type	Description
`data`	`string`	The data to append.

#File:delete

sharedsource

function File:delete(force?: boolean): boolean

Deletes the file, the object stays usable and write or touch creates it again.

Parameters

Name	Type	Description
`force`optional	`boolean`	If `true`, a missing file or a failed deletion are ignored instead of raising errors.

Returns

Type	Name	Description
`boolean`	`deleted`	`true` if the file was deleted, can be `false` only when `force` is `true`.

#File:exists

sharednodiscardsource

function File:exists(): boolean

Checks if the file exists.

Returns

Type	Name	Description
`boolean`	`exists`	`true` if the file exists, `false` otherwise.

#File:move

sharedasyncsource

async function File:move(target_path: string, overwrite?: boolean)

Moves the file, the target directory must exist, asynchronously inside of a coroutine.

The object follows the file, its path and name are updated.

Parameters

Name	Type	Description
`target_path`	`string`	The new absolute path of the file.
`overwrite`optional	`boolean`	If `true`, the existing file is replaced, otherwise the target must not exist.

#File:read

sharedasyncnodiscardsource

async function File:read(): string

Reads the whole file, asynchronously inside of a coroutine.

Returns

Type	Name	Description
`string`	`data`	The file data.

#File:rename

sharedasyncsource

async function File:rename(name: string, overwrite?: boolean)

Renames the file, it stays in its directory, asynchronously inside of a coroutine.

The object follows the file, its path and name are updated.

Parameters

Name	Type	Description
`name`	`string`	The new name of the file.
`overwrite`optional	`boolean`	If `true`, the existing file is replaced, otherwise the target must not exist.

#File:touch

sharedsource

function File:touch()

Like Linux touch: creates an empty file with missing directories, or updates the modification time keeping its content.

#File:write

sharedasyncsource

async function File:write(data: string)

Replaces the file data, the file and missing directories are created, asynchronously inside of a coroutine.

Parameters

Name	Type	Description
`data`	`string`	The new data.