Path manipulation

Different operating systems employ distinct conventions for file paths. Some operating systems insists that a path starts with a disk, while others only have directories. Some use "/" separators, while others use "\", some ":", etc. Sometimes, the same operating system will even employ distinct and incompatible conventions for file paths. For this reason, developers should avoid manipulating paths directly. Module OS.Path provides functions designed to manipulate paths in a cross-platform manner.

Similarly, both Firefox and the operating system will store special files and directories in different places. For instance, some versions of Windows place temporary directories in C:\Temp, others in C:\Windows\Temp, Local Settings\Temp, C:\Users\%USER%\AppData\Local\Temp ... For this reason, developers should not make assumptions regarding the path of special files and directories. Module OS.Constants.Path provides constants for a few well-known special paths.

Global Object OS.Constants.Path

Attributes

Global Object OS.Path

Methods Overview

Methods

OS.Path.basename

Return the final component of a path.

For instance:

• under Unix, basename("/home/user/bashrc") will produce "bashrc";
• under Windows, basename("C:\\Windows\\Temp") will produce "Temp".

string basename(
  in string path
)

Arguments

path

A valid path

Returns

The final component of path. This is everything after the last "/" (under Unix) or "\" (under Windows).

OS.Path.dirname

Return the directory part of the path.

For instance:

• under Unix, dirname("/home/user/bashrc") will produce "/home/user";
• under Windows, dirname("C:\\Windows\\Temp") will produce "C:\\Windows".

string dirname(
  in string path
)

Arguments

path

A valid path

Returns

Everything before the last "/" (under Unix) or "\" (under Windows). If the last few characters are also "/" (respectively "\"), they are ignored. If the path contains no directory, return ".".
 

OS.Path.fromFileURI

Converts a File URI to system path. See also to acheive opposite result: OS.Path.toFileURI

string fromFileURI(
  in string path
)

Arguments

path

A string that is in the form of a File URI. For example on windows: file:///C:/Users

Returns

A string in system path format. For example on windows file:///C:/Users is converted to C:\Users.

OS.Path.join

Join path components. This file is the recommended manner of getting the path of a file or a subdirectory contained in a directory.

Example:

var tmpDir = OS.Constants.Path.tmpDir;
var path = OS.Path.join(tmpDir, "foo", "bar");

will return

• "/tmp/foo/bar" on most versions of Unix;
• "C:\\Windows\\Temp\\foo\\bar" on versions of Windows that place the temporary directory in C:\Windows\Temp;
• etc.

string join(
  in string path,
  ...in string subpaths
)

Arguments

path

A path

subpaths

Zero, one or more paths that must be appended to path

Returns

The result of concatenaging the paths. If any of the subpaths is absolute, anything before this subpath is ignored. The path may not be normalized.

OS.Path.normalize

Normalize a path by removing unneeded ., .., /, \.

For instance:

• under Unix, normalize("/a/..//b") will produce "/b";
• under Windows normalize("C:\\A\\..\\\\B") will produce "C:\\B"

string normalize(
  in string path
) throws Error

Arguments

path

A path

Returns

A path equivalent to path, but in which needless occurrences of ".", "..", "/" and "\" have been removed.

Throws

Error

If path is an invalid path, in particular if it is an absolute path that contains too many occurrences of ".."

OS.Path.split

Split a path into its components.

Examples:

• Under Unix, split("/tmp/a/b") will produce { absolute: true, components: ["tmp", "a", "b"] };
• Under Windows, split("C:\\Windows\\Temp") will produce { absolute: true, components: ["Windows", "Temp"], winDrive: "C" }

object split(
  in string path
)

Arguments

path

A path. Generally, it should be normalized (see OS.Path.normalize).

Returns

An object with the following fields:

absolute

true if path is absolute, false otherwise

components

An array containing the components that define path. Under Windows, this array will not contain the drive name.

winDrive

(Windows only) The drive name. If path did not start with a drive name, null.

OS.Path.toFileURI

Converts an absolute system path to a File URI. See also to acheive opposite result: OS.Path.fromFileURI

string toFileURI(
  in string path
)

Arguments

path

A path that is in the form of an absolute system path. For example on windows: C:\Users

Returns

A string in File URI format. For example on windows C:\Users is converted to file:///C:/Users.

OS.Path.winGetDrive

Return the drive letter(s) from a path.

string winGetDrive(
   in string path
)

if ("winGetDrive" in OS.Path) {
  // The function can be used
} else {
  // The function cannot be used
}

Arguments

path

A Windows path. It may start with a drive name.

Returns

null

If path does not start with a drive name.

string

The drive name of path, if there is one. In the current implementation, the drive name is everything before the first occurrence of ":".

OS.Path.winIsAbsolute

Determine if a path is absolute.

bool winIsAbsolute(
  in string path
)

if ("winIsAbsolute" in OS.Path) {
  // The function can be used
} else {
  // The function cannot be used
}

Arguments

path

A Windows path.

Returns

true if the path is absolute, i.e. if it starts with a drive letter, false otherwise