Path manipulation

  • Revision slug: JavaScript_OS.File/OS.Path
  • Revision title: Path manipulation
  • Revision id: 320957
  • Created:
  • Creator: Yoric
  • Is current revision? No
  • Comment

Revision Content

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 assumption regarding the path of special files and directories. Module OS.Constants.Path provides constants for a few well-known special paths.

Performance note

This functions detailed in this document work purely 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.

Global Object OS.Path

Methods Overview

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

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

OS.Path.join(OS.Constants.Path.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.

Revision Source

<p>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, <a href="http://dutherenverseauborddelatable.wordpress.com/2012/06/19/fun-with-windows-paths/" title="http://dutherenverseauborddelatable.wordpress.com/2012/06/19/fun-with-windows-paths/">the same operating system will even employ distinct and incompatible conventions for file paths</a>. For this reason, developers should avoid manipulating paths directly. Module <code>OS.Path</code> provides functions designed to manipulate paths in a cross-platform manner.</p>
<p>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 <code>C:\Temp</code>, others in <code>C:\Windows\Temp</code>, <code>Local Settings\Temp</code>, <code>C:\Users\%USER%\AppData\Local\Temp</code> ... For this reason, developers should not make assumption regarding the path of special files and directories. Module <code>OS.Constants.Path</code> provides constants for a few well-known special paths.</p>
<div class="note">
  <p><strong>Performance note</strong></p>
  <p>This functions detailed in this document work purely on paths, without performing any I/O. You can therefore use them from any thread without fear of blocking I/O.</p>
</div>
<h2 id="Global_Object_OS.Constants.Path">Global Object OS.Constants.Path</h2>
<h3 id="Attributes">Attributes</h3>
<table>
  <tbody>
    <tr>
      <td>libDir</td>
      <td>string</td>
      <td><strong>read only</strong> The full path to the directory containing the libraries of Firefox (libxul, libnss, etc.)</td>
    </tr>
    <tr>
      <td>profileDir</td>
      <td>string</td>
      <td><strong>read only</strong> 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 <em>roaming profile</em> directory.</td>
    </tr>
    <tr>
      <td>tmpDir</td>
      <td>string</td>
      <td><strong>read only</strong> The full path to the system temporary directory.</td>
    </tr>
  </tbody>
</table>
<h2 id="Global_Object_OS.Path">Global Object OS.Path</h2>
<h3 id="Methods_Overview">Methods Overview</h3>
<table>
  <tbody>
    <tr>
      <td>string <a href="#OS.Path.basename" title="#OS.Path.basename">basename</a>(in string path)</td>
    </tr>
    <tr>
      <td>string <a href="#OS.Path.dirname" title="#OS.Path.dirname">dirname</a>(in string path)</td>
    </tr>
    <tr>
      <td>string <a href="#OS.Path.normalize" title="#OS.Path.normalize">join</a>(in string path1, in string path2, ...)</td>
    </tr>
    <tr>
      <td>string <a href="#OS.Path.normalize" title="#OS.Path.normalize">normalize</a>(in string path)</td>
    </tr>
    <tr>
      <td>object <a href="#OS.Path.split" title="#OS.Path.split">split</a>(in string path)</td>
    </tr>
    <tr>
      <td>string winGetDrive(in string path) (TBD)</td>
    </tr>
    <tr>
      <td>bool winIsAbsolute(in string path) (TBD)</td>
    </tr>
  </tbody>
</table>
<h3 id="Methods">Methods</h3>
<h4 id="OS.Path.basename">OS.Path.basename<a name="OS.Path.basename"></a></h4>
<p>Return the final component of a path.</p>
<p>For instance:</p>
<ul>
  <li>under Unix, <code>basename("/home/user/bashrc")</code> will produce <code>"bashrc"</code>;</li>
  <li>under Windows, <code>basename("C:\\Windows\\Temp")</code> will produce <code>"Temp"</code>.</li>
</ul>
<pre class="brush: js">
string basename(
  in string path
)
</pre>
<h5 id="Arguments">Arguments</h5>
<dl>
  <dt>
    path</dt>
  <dd>
    A valid path</dd>
</dl>
<h5 id="Returns">Returns</h5>
<p>The final component of <code>path</code>. This is everything after the last "/" (under Unix) or "\" (under Windows).</p>
<h4 id="OS.Path.dirname">OS.Path.dirname<a name="OS.Path.dirname"></a></h4>
<p>Return the directory part of the path.</p>
<p>For instance:</p>
<ul>
  <li>under Unix, <code>dirname("/home/user/bashrc")</code> will produce <code>"/home/user"</code>;</li>
  <li>under Windows, <code>dirname("C:\\Windows\\Temp")</code> will produce <code>"C:\\Windows"</code>.</li>
</ul>
<pre class="brush: js">
string dirname(
  in string path
)
</pre>
<h5 id="Arguments">Arguments</h5>
<dl>
  <dt>
    path</dt>
  <dd>
    A valid path</dd>
</dl>
<h5 id="Returns">Returns</h5>
<p>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 ".".<br />
  &nbsp;</p>
<h4 id="OS.Path.join">OS.Path.join<a name="OS.Path.join"></a></h4>
<p>Join path components. This file is the recommended manner of getting the path of a file or a subdirectory contained in a directory.</p>
<p>Example:</p>
<pre class="brush: js">
OS.Path.join(OS.Constants.Path.tmpDir, "foo", "bar")</pre>
<p>will return</p>
<ul>
  <li><code>"/tmp/foo/bar</code>" on most versions of Unix;</li>
  <li><code>"C:\\Windows\\Temp\\foo\\bar</code>" on versions of Windows that place the temporary directory in C:\Windows\Temp;</li>
  <li>etc.</li>
</ul>
<pre class="brush: js">
string join(
  in string path,
  ...in string subpaths
)
</pre>
<h5 id="Arguments">Arguments</h5>
<dl>
  <dt>
    path</dt>
  <dd>
    A path</dd>
  <dt>
    subpaths</dt>
  <dd>
    Zero, one or more paths that must be appended to path</dd>
</dl>
<h5 id="Returns">Returns</h5>
<p>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.</p>
<h4 id="OS.Path.normalize">OS.Path.normalize<a name="OS.Path.normalize"></a></h4>
<p>Normalize a path by removing unneeded <code>.</code>, <code>..</code>, <code>/</code>, <code>\</code>.</p>
<p>For instance:</p>
<ul>
  <li>under Unix, <code>normalize("/a/..//b")</code> will produce <code>"/b"</code>;</li>
  <li>under Windows <code>normalize("C:\\A\\..\\\\B")</code> will produce <code>"C:\\B"</code></li>
</ul>
<pre class="brush: js">
string normalize(
  in string path
) throws Error</pre>
<h5 id="Arguments">Arguments</h5>
<dl>
  <dt>
    path</dt>
  <dd>
    A path</dd>
</dl>
<h5 id="Returns">Returns</h5>
<p>A path equivalent to <code>path</code>, but in which needless occurrences of ".", "..", "/" and "\" have been removed.</p>
<h5 id="Throws">Throws</h5>
<dl>
  <dt>
    Error</dt>
  <dd>
    If path is an invalid <code>path</code>, in particular if it is an absolute path that contains too many occurrences of ".."</dd>
</dl>
<h4>OS.Path.split<a name="OS.Path.split"></a></h4>
<p>Split a path into its components.</p>
<p>Examples:</p>
<ul>
  <li>Under Unix, <code>split("/tmp/a/b")</code> will produce <code>{ absolute: true, components: ["tmp", "a", "b"] }</code>;</li>
  <li>Under Windows, <code>split("C:\\Windows\\Temp")</code> will produce <code>{ absolute: true, components: ["Windows", "Temp"], winDrive: "C" }</code></li>
</ul>
<pre class="brush: js">
object split(
  in string path
)</pre>
<h5>Arguments</h5>
<dl>
  <dt>
    path</dt>
  <dd>
    A path. Generally, it should be normalized (see <a href="#OS.Path.normalize" title="#OS.Path.normalize">OS.Path.normalize</a>).</dd>
</dl>
<h5>Returns</h5>
<p>An object with the following fields:</p>
<dl>
  <dt>
    absolute</dt>
  <dd>
    <code>true</code> if <code>path</code> is absolute, <code>false</code> otherwise</dd>
  <dt>
    components</dt>
  <dd>
    An array containing the components that define <code>path</code>. Under Windows, this array will <em>not</em> contain the drive name.</dd>
  <dt>
    winDrive</dt>
  <dd>
    (Windows only) The drive name. If <code>path</code> did not start with a drive name, <code>null</code>.</dd>
</dl>
Revert to this revision