Module : filepath

Module overview

This module provides the utility functions for manipulating the file path in a way that is compatible with the target 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(<@untainted> "test.txt");
    io:println(absValue);

    // 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
    
}

Records

Detail Record type to hold the details of an error.

Functions

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.

matches

Reports whether all of filename matches the provided pattern, not just a substring. An error is returned if the pattern is malformed.

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.

resolve

Returns the filepath after the evaluation of any symbolic links. If path is relative, the result will be relative to the current directory, unless one of the components is an absolute symbolic link. Resolve calls normalize on the result.

split

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

Constants

FILE_NOT_FOUND_ERROR

Identifies file not found error.

Identifies no link error.

IO_ERROR

Identifies io error.

SECURITY_ERROR

Identifies security error.

INVALID_PATH_ERROR

Identifies invalid path error.

INVALID_PATTERN_ERROR

Identifies invalid pattern error.

RELATIVE_PATH_ERROR

Identifies relative path error.

UNC_PATH_ERROR

Identifies unc path error.

GENERIC_ERROR

Identifies generic error.

Types

Error

Represents filepath related errors.

Errors

FileNotFoundError

Represents error occur when the file/directory does not exist at the given filepath.

GenericError

Represents generic error for filepath

IOError

Represents IO error occur when trying to access the file at the given filepath.

InvalidPathError

Represents error occur when the given file path is invalid.

InvalidPatternError

Represent error occur when the given pattern is not a valid filepath pattern.

NotLinkError

Represents error occur when the file at the given filepath is not a symbolic link.

RelativePathError

Represents an error that occurs when the given target filepath cannot be derived relative to the base filepath.

SecurityError

Represents security error occur when trying to access the file at the given filepath.

UNCPathError

Represents error occur in the UNC path.