ballerina/filepath module

Module overview

The file path module implements the utility functions for manipulating the file path in a way that is compatible with the target operating system. This module uses either forward slashes or backslashes, depending on the operating system.

Sample

The sample given below uses a few functions that are in the ballerina/filepath module.

import ballerina/filepath;
import ballerina/io;

public function main() {
    // Get the absolute representation of the path.
    string absValue = checkpanic filepath:absolute(untaint "test.txt");

    // Check whether the path is absolute.
    boolean isAbs = checkpanic filepath:isAbsolute("/A/B/C");
    io:println(isAbs); // On Unix : returns true
    
    // Get the base name of the path.
    string name = checkpanic filepath:filename("/A/B/C");
    io:println(name); // returns C

    // Get the enclosing parent directory.
    string parentPath = checkpanic filepath:parent("/A/B/C");
    io:println(parentPath); // returns B
    
    // Get the shortest path name equivalent to path purely via lexical processing.
    string normalizedPath = checkpanic filepath:normalize("foo/../bar");
    io:println(normalizedPath); // returns bar
    
    // Get the list of path elements joined by the OS-specific Path Separator.
    string[] parts = checkpanic filepath:split("/A/B/C");
    io:println(parts); // returns {"A", "B", "C"} 
    
    // Join any number of path elements into a single path.
    string path = checkpanic filepath:build("/", "foo", "bar");
    io:println(path); // On Unix : returns /foo/bar
    
    // Get the extension of the file path.
    string ext = checkpanic filepath:extension("path.bal");
    io:println(ext); // returns bal
    
    // Returns a relative path that is logically equivalent to the target path when joined to the base path.
    string relPath = checkpanic filepath:relative("a/b/c", "a/c/d");
    io:println(relPath); // On Unix : returns ../../c/d
    
}

Module Detail

Functions

Function Description
absolute

Retrieves the absolute path from the provided location.

build

Joins any number of path elements into a single path

extension

Retrieves the extension of the file path. The extension is the suffix beginning at the final dot in the final element of path. it is empty if there is no dot.

filename

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

getPathListSeparator

Returns path list separator of underline operating system.

getPathSeparator

Returns path separator of underline operating system.

isAbsolute

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 is absolute

isReservedName

Reports whether the filename is reserved. Reserved words only exist in windows.

normalize

Returns the shortest path name equivalent to path by purely lexical processing. Replace multiple Separator elements with a single one. Eliminate each . path name element (the current directory). Eliminate each inner .. path name element (the parent directory)

parent

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.

relative

Returns a relative path that is logically equivalent to target path when joined to base path with an intervening separator. An error is returned if target path can't be made relative to base path.

split

Splits a list of paths joined by the OS-specific Path Separator.

public function absolute(string path) returns (string|error<>)

Retrieves the absolute path from the provided location.

Parameter Name Data Type Default Value Description
path string

String value of file path.

Return Type Description
string|error<>

The absolute path reference or an error if the path cannot be derived

public function build(string[] parts) returns (string|error<>)

Joins any number of path elements into a single path

Parameter Name Data Type Default Value Description
parts string[]

String values of file path parts.

Return Type Description
string|error<>

String value of file path.

public function extension(string path) returns (string|error<>)

Retrieves the extension of the file path. The extension is the suffix beginning at the final dot in the final element of path. it is empty if there is no dot.

Parameter Name Data Type Default Value Description
path string

String value of file path.

Return Type Description
string|error<>

Returns the extension of the file. Empty string if no extension.

public function filename(string path) returns (string|error<>)

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

Parameter Name Data Type Default Value Description
path string

String value of file path.

Return Type Description
string|error<>

Returns the name of the file

public function getPathListSeparator() returns (string)

Returns path list separator of underline operating system.

Return Type Description
string

String value of path list separator

public function getPathSeparator() returns (string)

Returns path separator of underline operating system.

Return Type Description
string

String value of path separator

public function isAbsolute(string path) returns (boolean|error<>)

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 is absolute

Parameter Name Data Type Default Value Description
path string

String value of file path.

Return Type Description
boolean|error<>

True if path is absolute, else false

public function isReservedName(string name) returns (boolean)

Reports whether the filename is reserved. Reserved words only exist in windows.

Parameter Name Data Type Default Value Description
name string

filename

Return Type Description
boolean

true, if path is Windows reserved name.

public function normalize(string path) returns (string|error<>)

Returns the shortest path name equivalent to path by purely lexical processing. Replace multiple Separator elements with a single one. Eliminate each . path name element (the current directory). Eliminate each inner .. path name element (the parent directory)

Parameter Name Data Type Default Value Description
path string

String value of file path.

Return Type Description
string|error<>

Normalized file path

public function parent(string path) returns (string|error<>)

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.

Parameter Name Data Type Default Value Description
path string

String value of file path.

Return Type Description
string|error<>

Path of parent folder or error occurred while getting parent directory

public function relative(string base, string target) returns (string|error<>)

Returns a relative path that is logically equivalent to target path when joined to base path with an intervening separator. An error is returned if target path can't be made relative to base path.

Parameter Name Data Type Default Value Description
base string

String value of the base file path.

target string

String value of the target file path.

Return Type Description
string|error<>

Returns the extension of the file. Empty string if no extension.

public function split(string path) returns (string[]|error<>)

Splits a list of paths joined by the OS-specific Path Separator.

Parameter Name Data Type Default Value Description
path string

String value of file path.

Return Type Description
string[]|error<>

String array of part components