This API documentation is for Ballerina 1.2.0. View API documentation for the latest release.

Functions - filepath

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.

filename

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

getPathListSeparator

Returns the path variable's separating character for paths of the underlying operating system.

getPathSeparator

Returns the path separator of the underlying operating system.

isAbsolute

Reports whether the path is absolute.

isReservedName

Reports whether the filename is reserved.

matches

Reports whether the complete filename (not just a substring of it) matches the provided Glob pattern.

normalize

Returns the shortest path name equivalent to the given path.

parent

Returns the enclosing parent directory.

relative

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

resolve

Returns the filepath after the evaluation of any symbolic links.

split

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

absolute

(string path)

returns string | Error

Retrieves the absolute path from the provided location.

  string|filepath:Error absolutePath = filepath:absolute(<@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 filepath:Error if the path cannot be derived

build

(string... parts)

returns string | Error

Joins any number of path elements into a single path.

  string|filepath:Error path = filepath:build("/", "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 filepath:Error if the parts are invalid

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 the path. It is empty if there is no dot.

  string|filepath:Error extension = filepath:extension("path.bal");

Parameters

  • path string
  • String value of the file path

  • Return Type

    (string | Error)
  • The extension of the file, an empty string if there is no extension, or else a filepath:Error if the path is invalid

filename

(string path)

returns string | Error

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.

  string|filepath:Error name = filepath:filename("/A/B/C.txt");

Parameters

  • path string
  • String value of file path

  • Return Type

    (string | Error)
  • The name of the file or else a filepath:Error if the path is invalid

getPathListSeparator

()

returns string

Returns the path variable's separating character for paths of the underlying operating system.

  string pathListSeparator = filepath:getPathListSeparator();
  • Return Type

    (string)
  • String value of the path list separator

getPathSeparator

()

returns string

Returns the path separator of the underlying operating system.

  string pathSeparator = filepath:getPathSeparator();
  • Return Type

    (string)
  • String value of the path separator

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.

  boolean|filepath:Error isAbsolute = filepath:isAbsolute("/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 filepath:Error occurred if the path is invalid

isReservedName

(string name)

returns boolean

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

  boolean|filepath:Error path = filepath:isReservedName("abc.txt");

Parameters

  • name string
  • Filename

  • Return Type

    (boolean)
  • True if the path is a Windows reserved name or else false otherwise

matches

(string path, string pattern)

returns boolean | Error

Reports whether the complete filename (not just a substring of it) matches the provided Glob pattern. An error is returned if the pattern is malformed.

  boolean|filepath:Error matches = filepath:matches("a/b/c.java", "glob:*.{java,class}");

Parameters

  • path string
  • String value of the file path

  • pattern string
  • String value of the target file path

  • Return Type

    (boolean | Error)
  • true if the filename of the path matches with the pattern, false otherwise, or else an filepath:Error if the path or pattern is invalid

normalize

(string path)

returns string | Error

Returns the shortest path name equivalent to the given path. Replace the multiple separator elements with a single one. Eliminate each "." path name element (the current directory). Eliminate each inner ".." path name element (the parent directory).

  string|filepath:Error normalizedPath = filepath:normalize("foo/../bar");

Parameters

  • path string
  • String value of the file path

  • Return Type

    (string | Error)
  • Normalized file path or else a filepath:Error if the path is invalid

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.

  string|filepath:Error parentPath = filepath:parent("/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 filepath:Error if an error occurred while getting the parent directory

relative

(string base, string target)

returns string | Error

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.

  string|filepath:Error relativePath = filepath:relative("a/b/c", "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 extension of the file, empty string otherwise, or else an filepath:Error occurred if at least one path is invalid

resolve

(string path)

returns string | Error

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

  string|filepath:Error resolvedPath = filepath:resolve("a/b/c");

Parameters

  • path string
  • Security-validated string value of the file path

  • Return Type

    (string | Error)
  • Resolved file path or else a filepath:Error if the path is invalid

split

(string path)

returns string[] | Error

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

  string[]|filepath:Error parts = filepath:split("/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 filepath:Error if the path is invalid