documon
Version:
A documentation system for mortals. Use with any language.
1,409 lines (722 loc) • 40.4 kB
HTML
<html>
<head>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
<title>npath</title>
<meta name="description" content="A drop-in replacement for path, that provides cross-playform normalization. Easing the development of cross-platform modules.">
<!-- Normalize -->
<link rel="stylesheet" href="assets/vendor/normalize.css">
<!-- prettify -->
<link rel="stylesheet" href="assets/vendor/prettify/codamike.css">
<script src="assets/vendor/prettify/prettify.js"></script>
<!-- Documon Pages Info. (Used by various classes to identify this page.) -->
<script>
var pageCtx = {
id : "documon.npath",
name: "npath"
}
</script>
<!-- theme
<link rel="stylesheet" href="assets/fonts/Fira_Sans/FiraSans.css">
<link rel="stylesheet" href="assets/fonts/Inconsolata/inconsolata.css">
-->
<link rel="stylesheet" href="assets/css/pages.css">
<script src="assets/js/documon/Storage.js"></script>
<script src="assets/js/documon/Access.js"></script>
<script src="assets/js/documon/Pages.js"></script>
<script>
(function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
(i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
})(window,document,'script','https://www.google-analytics.com/analytics.js','ga');
ga('create', 'UA-106684927-1', 'auto');
ga('send', 'pageview');
</script>
</head>
<body>
<div class="page">
<div class="main-method">
<a name="methods"></a>
<div class="part-methods">
<a name="documon.npath"></a><a name="npath"></a>
<div class="member" >
<div class="member-name clearfix">
<span class="member-name-left">
npath ()
</span>
<span class="member-name-right">
<span class="member-file">documon/src/npath.js</span>
<span class="member-line-number">15</span>
</span>
</div>
<div class="member-description">
<div class="meta-block meta-block-klass">
<div class="meta-line"><span class="meta-label" >xpath</span> <span class="meta-target">documon.npath<span></div>
<div class="meta-line"><span class="meta-label" >file</span> <span class="meta-target">documon/src/npath.js<span></div>
</div>
<p>A drop-in replacement for path, that provides cross-playform normalization. Easing the development of cross-platform modules.</p>
<p>Essentially what we're doing is pre-processing all methods with a path normalization -- always enforcing forward slashes.</p>
</div>
</div>
</div>
</div>
<div class="parts">
<a name="properties"></a>
<div class="part-properties">
<div class="heading-part">Properties</div>
<div class="member">
<div class="member-block-group">
<div class="member-block" >
<div class="member-block-left">
<a name="documon.npath.delimiter"></a><a name="delimiter"></a>
<span class="member-name">delimiter</span>
</div>
<div class="member-block-center">
<span class="member-name-right">
<span class="member-file">documon/src/npath.js</span><span class="member-line-number" title="documon/src/npath.js">45</span>
</span>
<div class="param-description">
<span class="type">string</span>
<div class="member-description">
<p>Platform environment PATH delimiter.</p>
<p>Example of how PATH appears on Windows:</p>
<pre><code> 'C:\Windows\system32;C:\Windows;C:\Program Files\node\'</code></pre>
<p>Example of how PATH appears on POSIX systems (Mac Unix):</p>
<pre><code> '/usr/bin:/bin:/usr/sbin:/sbin:/usr/local/bin'</code></pre>
<p>Read the PATH with Node:</p>
<pre><code> console.log(process.env.PATH)
Windows = ;
POSIX = : </code></pre>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
<a name="methods"></a>
<div class="part-methods">
<div class="heading-part">Methods</div>
<a name="documon.npath.addTrailingSlash"></a><a name="addTrailingSlash"></a>
<div class="member" >
<div class="member-name clearfix">
<span class="member-name-left">
addTrailingSlash (<span class="method-arguments">path</span>)
</span>
<span class="member-name-right">
<span class="member-file">documon/src/npath.js</span>
<span class="member-line-number">321</span>
</span>
</div>
<div class="member-description">
<p>Adds a trailing slash from path (if doesn't exist).</p>
<div class="part-parameters">
<div class="heading-part">Parameters</div>
<div class="member">
<div class="member-block-group">
<div class="member-block" >
<div class="member-block-left">
<span class="member-name">path</span>
</div>
<div class="member-block-center">
<span class="member-name-right">
</span>
<div class="param-description">
<span class="type">string</span>
<div class="member-description">
<p>path</p>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="heading-returns">Returns
<span class="type">string</span>
</div>
<div class="member"></div>
</div>
</div>
<a name="documon.npath.basename"></a><a name="basename"></a>
<div class="member" >
<div class="member-name clearfix">
<span class="member-name-left">
basename (<span class="method-arguments">path</span>, <span class="method-arguments">ext</span>)
</span>
<span class="member-name-right">
<span class="member-file">documon/src/npath.js</span>
<span class="member-line-number">108</span>
</span>
</div>
<div class="member-description">
<p>npath.basename("/foo/bar/bob.txt") --> "bob.txt"<br />
npath.basename("/foo/bar/bob.txt", ".txt") --> "bob"</p>
<div class="part-parameters">
<div class="heading-part">Parameters</div>
<div class="member">
<div class="member-block-group">
<div class="member-block" >
<div class="member-block-left">
<span class="member-name">path</span>
</div>
<div class="member-block-center">
<span class="member-name-right">
</span>
<div class="param-description">
<span class="type">string</span>
<div class="member-description">
<p>The full path</p>
</div>
</div>
</div>
</div>
<div class="member-block" >
<div class="member-block-left">
<span class="member-name">ext</span>
</div>
<div class="member-block-center">
<span class="member-name-right">
</span>
<div class="param-description">
<span class="type">string</span>
<div class="member-description">
<p>Lops off the extension if it matches.</p>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="heading-returns">Returns
<span class="type">string</span>
</div>
<div class="member"><p>The last portion of a path, generally the "filename".</p></div>
</div>
</div>
<a name="documon.npath.clean"></a><a name="clean"></a>
<div class="member" >
<div class="member-name clearfix">
<span class="member-name-left">
clean (<span class="method-arguments">arg</span>)
</span>
<span class="member-name-right">
<span class="member-file">documon/src/npath.js</span>
<span class="member-line-number">59</span>
</span>
</div>
<div class="member-description">
<p>Normalizes slashes by converting double \ to single \ and / to \ or \ tp / based on the current platform requirements.</p>
<div class="part-parameters">
<div class="heading-part">Parameters</div>
<div class="member">
<div class="member-block-group">
<div class="member-block" >
<div class="member-block-left">
<span class="member-name">arg</span>
</div>
<div class="member-block-center">
<span class="member-name-right">
</span>
<div class="param-description">
<span class="type">string | array</span>
<div class="member-description">
<p>arg</p>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="heading-returns">Returns
<span class="type">string</span>
</div>
<div class="member"></div>
</div>
</div>
<a name="documon.npath.dirname"></a><a name="dirname"></a>
<div class="member" >
<div class="member-name clearfix">
<span class="member-name-left">
dirname (<span class="method-arguments">Vpath</span>)
</span>
<span class="member-name-right">
<span class="member-file">documon/src/npath.js</span>
<span class="member-line-number">123</span>
</span>
</div>
<div class="member-description">
<p>Returns the path to the parent folder that the item resides within.</p>
<pre><code> npath.dirname("/foo/bar/bob.txt") --> "/foo/bar"
npath.dirname("/foo/sally/yoyo/boob") --> "/foo/sally/yoyo"</code></pre>
<div class="part-parameters">
<div class="heading-part">Parameters</div>
<div class="member">
<div class="member-block-group">
<div class="member-block" >
<div class="member-block-left">
<span class="member-name">Vpath</span>
</div>
<div class="member-block-center">
<span class="member-name-right">
</span>
<div class="param-description">
<span class="type">string</span>
<div class="member-description">
<p>The path to parse.</p>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="heading-returns">Returns
<span class="type">string</span>
</div>
<div class="member"><p>The path to the file/folder.</p></div>
</div>
</div>
<a name="documon.npath.extname"></a><a name="extname"></a>
<div class="member" >
<div class="member-name clearfix">
<span class="member-name-left">
extname (<span class="method-arguments">Vpath</span>)
</span>
<span class="member-name-right">
<span class="member-file">documon/src/npath.js</span>
<span class="member-line-number">137</span>
</span>
</div>
<div class="member-description">
<p>Yes, this includes the dot.</p>
<pre><code> npath.extname("/foo/bar/bob.txt") --> ".txt"
npath.extname("/foo/sally/yoyo/boob") --> ""</code></pre>
<div class="part-parameters">
<div class="heading-part">Parameters</div>
<div class="member">
<div class="member-block-group">
<div class="member-block" >
<div class="member-block-left">
<span class="member-name">Vpath</span>
</div>
<div class="member-block-center">
<span class="member-name-right">
</span>
<div class="param-description">
<span class="type">string</span>
<div class="member-description">
<p>The path to parse.</p>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="heading-returns">Returns
<span class="type">string</span>
</div>
<div class="member"><p>The extension (if exists), including the dot.</p></div>
</div>
</div>
<a name="documon.npath.format"></a><a name="format"></a>
<div class="member" >
<div class="member-name clearfix">
<span class="member-name-left">
format (<span class="method-arguments">obj</span>)
</span>
<span class="member-name-right">
<span class="member-file">documon/src/npath.js</span>
<span class="member-line-number">247</span>
</span>
</div>
<div class="member-description">
<p>The opposite of path.parse().</p>
<p>Combines the elements of an object into a string. </p>
<p>Example:</p>
<pre><code> {
root : "/",
dir : "/home/user/dir",
base : "file.txt",
ext : ".txt",
name : "file"
}</code></pre>
<p>Is converted to</p>
<pre><code> /home/user/dir/file.txt</code></pre>
<div class="part-parameters">
<div class="heading-part">Parameters</div>
<div class="member">
<div class="member-block-group">
<div class="member-block" >
<div class="member-block-left">
<span class="member-name">obj</span>
</div>
<div class="member-block-center">
<span class="member-name-right">
</span>
<div class="param-description">
<span class="type">object</span>
<div class="member-description">
<p>The object containing some of the required keys to formulate a path.</p>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="heading-returns">Returns
<span class="type">type</span>
</div>
<div class="member"><p>The string representaiton of the object.</p></div>
</div>
</div>
<a name="documon.npath.isAbsolute"></a><a name="isAbsolute"></a>
<div class="member" >
<div class="member-name clearfix">
<span class="member-name-left">
isAbsolute (<span class="method-arguments">Vpath</span>)
</span>
<span class="member-name-right">
<span class="member-file">documon/src/npath.js</span>
<span class="member-line-number">149</span>
</span>
</div>
<div class="member-description">
<p>Determines if path is an absolute path.</p>
<div class="part-parameters">
<div class="heading-part">Parameters</div>
<div class="member">
<div class="member-block-group">
<div class="member-block" >
<div class="member-block-left">
<span class="member-name">Vpath</span>
</div>
<div class="member-block-center">
<span class="member-name-right">
</span>
<div class="param-description">
<span class="type">string</span>
<div class="member-description">
<p>The path to parse.</p>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="heading-returns">Returns
<span class="type">Boolean</span>
</div>
<div class="member"></div>
</div>
</div>
<a name="documon.npath.join"></a><a name="join"></a>
<div class="member" >
<div class="member-name clearfix">
<span class="member-name-left">
join (<span class="method-arguments">paths...</span>)
</span>
<span class="member-name-right">
<span class="member-file">documon/src/npath.js</span>
<span class="member-line-number">263</span>
</span>
</div>
<div class="member-description">
<p>Joins path segments and resolves relativity.</p>
<pre><code> path.join('/foo', 'bar', 'baz/asdf', 'quux', '..')
Returns: '/foo/bar/baz/asdf'</code></pre>
<div class="part-parameters">
<div class="heading-part">Parameters</div>
<div class="member">
<div class="member-block-group">
<div class="member-block" >
<div class="member-block-left">
<span class="member-name">paths...</span>
</div>
<div class="member-block-center">
<span class="member-name-right">
</span>
<div class="param-description">
<span class="type">string</span>
<div class="member-description">
<p>All arguments are evaluated as paths for construction</p>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="heading-returns">Returns
<span class="type">type</span>
</div>
<div class="member"><p>description description</p></div>
</div>
</div>
<a name="documon.npath.normalize"></a><a name="normalize"></a>
<div class="member" >
<div class="member-name clearfix">
<span class="member-name-left">
normalize (<span class="method-arguments">Vpath</span>)
</span>
<span class="member-name-right">
<span class="member-file">documon/src/npath.js</span>
<span class="member-line-number">168</span>
</span>
</div>
<div class="member-description">
<p>Resolves ".." and "." portions of a path.<br />
Reduces double slashes to single (e.g. // -> / )<br />
Forces back-slashes to forward slashes (e.g. \ -> / )</p>
<p>Retains trailing slash if exists.</p>
<pre><code> npath.normalize("/foo/////bar") --> "/foo/bar"
npath.normalize("/foo/bar/../boob") --> "/foo/boob"
npath.normalize("./foo/") --> "/current/working/dir/foo/"</code></pre>
<div class="part-parameters">
<div class="heading-part">Parameters</div>
<div class="member">
<div class="member-block-group">
<div class="member-block" >
<div class="member-block-left">
<span class="member-name">Vpath</span>
</div>
<div class="member-block-center">
<span class="member-name-right">
</span>
<div class="param-description">
<span class="type">string</span>
<div class="member-description">
<p>The path to parse.</p>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="heading-returns">Returns
<span class="type">string</span>
</div>
<div class="member"></div>
</div>
</div>
<a name="documon.npath.parse"></a><a name="parse"></a>
<div class="member" >
<div class="member-name clearfix">
<span class="member-name-left">
parse (<span class="method-arguments">Vpath</span>)
</span>
<span class="member-name-right">
<span class="member-file">documon/src/npath.js</span>
<span class="member-line-number">200</span>
</span>
</div>
<div class="member-description">
<p>Extracts basic path and file parts.</p>
<pre><code>path.parse('/home/user/dir/file.txt')
// Yeilds
{
root : "/",
dir : "/home/user/dir",
base : "file.txt",
ext : ".txt",
name : "file"
}</code></pre>
<div class="part-parameters">
<div class="heading-part">Parameters</div>
<div class="member">
<div class="member-block-group">
<div class="member-block" >
<div class="member-block-left">
<span class="member-name">Vpath</span>
</div>
<div class="member-block-center">
<span class="member-name-right">
</span>
<div class="param-description">
<span class="type">string</span>
<div class="member-description">
<p>The path to parse.</p>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="heading-returns">Returns
<span class="type">object</span>
</div>
<div class="member"><p>An object containing the following properties:</p>
<pre><code>{
root : "/",
dir : "/home/user/dir",
base : "file.txt",
ext : ".txt",
name : "file"
}</code></pre></div>
</div>
</div>
<a name="documon.npath.relative"></a><a name="relative"></a>
<div class="member" >
<div class="member-name clearfix">
<span class="member-name-left">
relative (<span class="method-arguments method-arg-optional">from</span>, <span class="method-arguments method-arg-optional">to</span>)
</span>
<span class="member-name-right">
<span class="member-file">documon/src/npath.js</span>
<span class="member-line-number">218</span>
</span>
</div>
<div class="member-description">
<p>Creates a relative path between <code>from</code> adn <code>to</code>.</p>
<pre><code> path.relative('/data/orandea/test/aaa', '/data/orandea/impl/bbb')
// Returns: '../../impl/bbb'</code></pre>
<div class="part-parameters">
<div class="heading-part">Parameters</div>
<div class="member">
<div class="member-block-group">
<div class="member-block" >
<div class="member-block-left">
<span class="member-name">from</span>
</div>
<div class="member-block-center">
<span class="member-name-right">
</span>
<div class="param-description">
<span class="type">string</span>
<span class="flag optional">optional</span>
<div class="member-description">
<p>When null, the cwd is used for this value.</p>
</div>
</div>
</div>
</div>
<div class="member-block" >
<div class="member-block-left">
<span class="member-name">to</span>
</div>
<div class="member-block-center">
<span class="member-name-right">
</span>
<div class="param-description">
<span class="type">string</span>
<span class="flag optional">optional</span>
<div class="member-description">
<p>When null, the cwd is used for this value.</p>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="heading-returns">Returns
<span class="type">string</span>
</div>
<div class="member"><p>The relative path between <code>from</code> and <code>to</code></p></div>
</div>
</div>
<a name="documon.npath.removeTrailingSlash"></a><a name="removeTrailingSlash"></a>
<div class="member" >
<div class="member-name clearfix">
<span class="member-name-left">
removeTrailingSlash (<span class="method-arguments">path</span>)
</span>
<span class="member-name-right">
<span class="member-file">documon/src/npath.js</span>
<span class="member-line-number">306</span>
</span>
</div>
<div class="member-description">
<p>Removes a trailing slash from path (if exists).</p>
<div class="part-parameters">
<div class="heading-part">Parameters</div>
<div class="member">
<div class="member-block-group">
<div class="member-block" >
<div class="member-block-left">
<span class="member-name">path</span>
</div>
<div class="member-block-center">
<span class="member-name-right">
</span>
<div class="param-description">
<span class="type">string</span>
<div class="member-description">
<p>path</p>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="heading-returns">Returns
<span class="type">string</span>
</div>
<div class="member"></div>
</div>
</div>
<a name="documon.npath.resolve"></a><a name="resolve"></a>
<div class="member" >
<div class="member-name clearfix">
<span class="member-name-left">
resolve (<span class="method-arguments method-arg-optional">path...</span>)
</span>
<span class="member-name-right">
<span class="member-file">documon/src/npath.js</span>
<span class="member-line-number">294</span>
</span>
</div>
<div class="member-description">
<p>Generates an absolute path based on thenprovided arguments.</p>
<p>Path construction occurs from right < to < left</p>
<pre><code> resolve("/a", "b", "c"); // yields: "/a/b/c"</code></pre>
<p>If an absolute path is resolved during construction, the items to the left are ignored.</p>
<pre><code> resolve("a", "/b", "c"); // yields: "/b/c" ("a" is ignored)</code></pre>
<p>If an absolute path is not resolved after constructing all arguments, the CWD is inserted.</p>
<pre><code> resolve("a", "b", "c"); // yields: "/current/working/dir/a/b/c"</code></pre>
<p>Relative paths are automatically resolved:</p>
<pre><code> resolve("/a", "../b", "c"); // yields "/a/c"</code></pre>
<div class="part-parameters">
<div class="heading-part">Parameters</div>
<div class="member">
<div class="member-block-group">
<div class="member-block" >
<div class="member-block-left">
<span class="member-name">path...</span>
</div>
<div class="member-block-center">
<span class="member-name-right">
</span>
<div class="param-description">
<span class="type">string</span>
<span class="flag optional">optional</span>
<div class="member-description">
<p>All arguments are evaluated as paths for construction.</p>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="heading-returns">Returns
<span class="type">string</span>
</div>
<div class="member"></div>
</div>
</div>
</div>
</div>
</div>
<div class="footer">Generated by <a href="http://www.documon.net" target="_blank">Documon</a></div>
</body>
</html>