Standard Libraryfile

functions

Functions

basename
I

Retrieves the base name of the file from the provided location, which is the last element of the path.

copy
I

Copy the file/directory in the old path to the new path.

create
I

Creates a file in the specified file path.

createDir
I

Creates a new directory with the specified name.

createTemp
I

Creates a temporary file.

createTempDir
I

Creates a temporary directory.

getAbsolutePath
I

Retrieves the absolute path from the provided location.

getCurrentDir
I

Returns the current working directory.

getMetaData
I

Returns the metadata information of the file specified in the file path.

isAbsolutePath
I

Reports whether the path is absolute.

joinPath
I

Joins any number of path elements into a single path.

normalizePath
I

Normalizes a path value.

parentPath
I

Returns the enclosing parent directory.

readDir
I

Reads the directory and returns a list of metadata of files and directories inside the specified directory.

relativePath
I

Returns a relative path, which is logically equivalent to the target path when joined to the base path with an intervening separator.

remove
I

Removes the specified file or directory.

rename
I

Renames(Moves) the old path with the new path.

splitPath
I

Splits a list of paths joined by the OS-specific path separator.

test
I

Tests a file path against a test condition .

basename 

function basename(string path) returns string | Error
Isolated Function

Retrieves the base name of the file from the provided location, which is the last element of the path. Trailing path separators are removed before extracting the last element.

1 string name = check file:basename("/A/B/C.txt");

Parameters

  • path string

    • String value of file path

Return Type

(string | Error)

The name of the file or else a file:Error if the path is invalid

copy 

function copy(string sourcePath, string destinationPath, CopyOption... options) returns Error?
Isolated Function

Copy the file/directory in the old path to the new path.

1check file:copy("/A/B/C", "/A/B/D", true);

Parameters

  • sourcePath string

    • String value of the old file path

  • destinationPath string

    • String value of the new file path

  • options CopyOption...

    • Parameter to denote how the copy operation should be done. Supported options are, REPLACE_EXISTING - Replace the target path if it already exists, COPY_ATTRIBUTES - Copy the file attributes as well to the target, NO_FOLLOW_LINKS - If source is a symlink, only the link is copied, not the target of the link.

Return Type

(Error?)

An file:Error if failed to copy

create 

function create(string path) returns Error?
Isolated Function

Creates a file in the specified file path. Truncates if the file already exists in the given path.

1check file:create("bar.txt");

Parameters

  • path string

    • String value of the file path

Return Type

(Error?)

A file:Error if file creation failed

createDir 

function createDir(string dir, DirOption option) returns Error?
Isolated Function

Creates a new directory with the specified name.

1check file:createDir("foo/bar");

Parameters

  • option DirOption (default NON_RECURSIVE)

    • Indicates whether the createDir should create non-existing parent directories. The default is only to create the given current directory.

Return Type

(Error?)

A file:Error if the directory creation failed

createTemp 

function createTemp(string? suffix, string? prefix, string? dir) returns string | Error
Isolated Function

Creates a temporary file.

1string tmpFile = check file:createTemp();

Parameters

  • suffix string? (default ())

    • Optional file suffix

  • prefix string? (default ())

    • Optional file prefix

  • dir string? (default ())

    • The directory path where the temp file should be created. If not specified, temp file will be created in the default temp directory of the OS.

Return Type

(string | Error)

Temporary file path or else a file:Error if there is an error

createTempDir 

function createTempDir(string? suffix, string? prefix, string? dir) returns string | Error
Isolated Function

Creates a temporary directory.

1string tmpDir = check file:createTempDir();

Parameters

  • suffix string? (default ())

    • Optional directory suffix

  • prefix string? (default ())

    • Optional directory prefix

  • dir string? (default ())

    • The directory path where the temp directory should be created. If not specified, temp directory will be created in the default temp directory of the OS.

Return Type

(string | Error)

Temporary directory path or else a file:Error if there is an error

getAbsolutePath 

function getAbsolutePath(string path) returns string | Error
Isolated Function

Retrieves the absolute path from the provided location.

1 string absolutePath = check file:getAbsolutePath(<@untainted> "test.txt");

Parameters

  • path string

    • String value of the file path free from potential malicious codes

Return Type

(string | Error)

The absolute path reference or else a file:Error if the path cannot be derived

getCurrentDir 

function getCurrentDir() returns string
Isolated Function

Returns the current working directory.

1string dirPath = file:getCurrentDir();

Return Type

(string)

Current working directory or else an empty string if the current working directory cannot be determined

getMetaData 

function getMetaData(string path) returns (MetaData & readonly) | Error
Isolated Function

Returns the metadata information of the file specified in the file path.

1file:MetaData result = check file:getMetaData("foo/bar.txt");

Parameters

  • path string

    • String value of the file path.

Return Type

((MetaData & readonly) | Error)

The MetaData instance with the file metadata or else a file:Error

isAbsolutePath 

function isAbsolutePath(string path) returns boolean | Error
Isolated Function

Reports whether the path is absolute. A path is absolute if it is independent of the current directory. On Unix, a path is absolute if it starts with the root. On Windows, a path is absolute if it has a prefix and starts with the root: c:\windows.

1 boolean isAbsolute = check file:isAbsolutePath("/A/B/C");

Parameters

  • path string

    • String value of the file path

Return Type

(boolean | Error)

true if path is absolute, false otherwise, or else an file:Error occurred if the path is invalid

joinPath 

function joinPath(string... parts) returns string | Error
Isolated Function

Joins any number of path elements into a single path.

1 string path = check file:joinPath("/", "foo", "bar");

Parameters

  • parts string...

    • String values of the file path parts

Return Type

(string | Error)

String value of the file path or else a file:Error if the parts are invalid

normalizePath 

function normalizePath(string path, NormOption option) returns string | Error
Isolated Function

Normalizes a path value.

1 string normalizedPath = check file:normalizePath("foo/../bar", file:CLEAN);

Parameters

  • path string

    • String value of the file path

  • option NormOption

    • Normalization option. Supported options are, CLEAN - Get the shortest path name equivalent to the given path by eliminating multiple separators, '.', and '..', SYMLINK - Evaluate a symlink, NORMCASE - Normalize the case of a pathname. On windows, all the characters are converted to lowercase and "/" is converted to "\".

Return Type

(string | Error)

Normalized file path or else a file:Error if the path is invalid

parentPath 

function parentPath(string path) returns string | Error
Isolated Function

Returns the enclosing parent directory. If the path is empty, parent returns ".". The returned path does not end in a separator unless it is the root directory.

1 string parentPath = check file:parentPath("/A/B/C.txt");

Parameters

  • path string

    • String value of the file/directory path

Return Type

(string | Error)

Path of the parent directory or else a file:Error if an error occurred while getting the parent directory

readDir 

function readDir(string path) returns (MetaData[ ] & readonly) | Error
Isolated Function

Reads the directory and returns a list of metadata of files and directories inside the specified directory.

1file:MetaData[] results = check file:readDir("foo/bar");

Parameters

  • path string

    • String value of the directory path.

Return Type

((MetaData[ ] & readonly) | Error)

The MetaData array or else a file:Error if there is an error

relativePath 

function relativePath(string base, string target) returns string | Error
Isolated Function

Returns a relative path, which is logically equivalent to the target path when joined to the base path with an intervening separator. An error is returned if the target path cannot be made relative to the base path.

1 string relative = check file:relativePath("a/b/e", "a/c/d");

Parameters

  • base string

    • String value of the base file path

  • target string

    • String value of the target file path

Return Type

(string | Error)

The target path relative to the base path, or else an file:Error if target path cannot be made relative to the base path

remove 

function remove(string path, DirOption option) returns Error?
Isolated Function

Removes the specified file or directory.

1check file:remove("foo/bar.txt");

Parameters

  • path string

    • String value of the file/directory path

  • option DirOption (default NON_RECURSIVE)

    • Indicates whether the remove should recursively remove all the files inside the given directory

Return Type

(Error?)

An file:Error if failed to remove

rename 

function rename(string oldPath, string newPath) returns Error?
Isolated Function

Renames(Moves) the old path with the new path. If the new path already exists and it is not a directory, this replaces the file.

1check file:rename("/A/B/C", "/A/B/D");

Parameters

  • oldPath string

    • String value of the old file path

  • newPath string

    • String value of the new file path

Return Type

(Error?)

An file:Error if failed to rename

splitPath 

function splitPath(string path) returns string[ ] | Error
Isolated Function

Splits a list of paths joined by the OS-specific path separator.

1 string[] parts = check file:splitPath("/A/B/C");

Parameters

  • path string

    • String value of the file path

Return Type

(string[ ] | Error)

String array of the part components or else a file:Error if the path is invalid

test 

function test(string path, TestOption testOption) returns boolean | Error
Isolated Function

Tests a file path against a test condition .

1boolean result = check file:test("foo/bar.txt", file:EXISTS);

Parameters

  • path string

    • String value of the file path

  • testOption TestOption

    • The option to be tested upon the path. Supported options are, EXISTS - Test whether a file path exists, IS_DIR - Test whether a file path is a directory, IS_SYMLINK - Test whether a file path is a symlink, READABLE - Test whether a file path is readable, WRITABLE - Test whether a file path is writable.

Return Type

(boolean | Error)

True/false depending on the option to be tested or else a file:Error if there is an error