mozilla
Your Search Results

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

    Attributes

    libDir string read only The full path to the directory containing the libraries of Firefox (libxul, libnss, etc.)
    profileDir string read only The full path to the directory containing the profile of the current user. Some operating systems have both a local profile directory and a roaming profile directory. On such operating systems, this is the roaming profile directory.
    tmpDir string read only The full path to the system temporary directory.
    homeDir string read only The full path to the user's home directory.
    desktopDir string read only The full path to the user's desktop directory.
    winAppDataDir string read only The full path to the user's application data directory.
    winStartMenuProgsDir string read only The full path to the "Programs" subdirectory in the user's start menu directory.
    macUserLibDir string read only The full path to the user's Library directory.
    macLocalApplicationsDir string read only The full path to the Applications directory.

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

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

    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
    }
    Arguments
    path
    A Windows path.
    Returns

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

    Document Tags and Contributors

    Tags: 
    Contributors to this page: jukbot, Noitidart, mar.castelluccio, Yoric, teoli, Cykesiopka, ilyakamens
    Last updated by: ilyakamens,