# 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.

Performance note

The functions detailed in this document work on paths without performing any I/O. You can therefore use them from any thread without fear of blocking I/O.

## Global Object OS.Path

### Methods Overview

 string basename(in string path) string dirname(in string path) string fromFileURI (in string path) string join(in string path1, in string path2, ...) string normalize(in string path) object split(in string path) string toFileURI (in string path) string winGetDrive(in string path) bool winIsAbsolute(in string path)

### 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
)

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
)

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
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.

If the following characters are found in the supplied path argument, they are returned in encoded form:

• ; becomes %3b
• ? becomes %3F
• ' becomes %27
• # becomes %23

#### OS.Path.winGetDrive

Return the drive letter(s) from a path.

string winGetDrive(
in string path
)

Platform-specific

This function is defined only on Windows platforms. Before attempting to use it, you should perform feature detection, as follows:

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

path
##### 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
)

Platform-specific

This function is defined only on Windows platforms. Before attempting to use it, you should perform feature detection, as follows:

if ("winIsAbsolute" in OS.Path) {
// The function can be used
} else {
// The function cannot be used
}
path
A Windows path.
##### Returns

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

Tags: