@antora/expand-path-helper
Advanced tools
Comparing version 1.0.0-rc.2 to 1.0.0-rc.3
@@ -19,33 +19,31 @@ 'use strict' | ||
* (~+), that segment is replaced with the current working directory of the | ||
* process. If path is relative, path is resolved based on the value of | ||
* defaultPrefix. If defaultPrefix is unspecified or '~+', path is resolved | ||
* starting from the current working directory of the process. If defaultPrefix | ||
* is '.', path is resolved starting from start, which defaults to the current | ||
* working directory of the process. If defaultPrefix is '~', path is resolved | ||
* starting from the home directory of the current user. | ||
* process. If path is relative, path is resolved starting from start. If path | ||
* has a leading dot (.) segment, that segment is replaced with dot after that | ||
* value is expanded. | ||
* | ||
* @param {String} path - The path to expand. | ||
* @param {String} [start=process.cwd()] - The absolute directory to use as a | ||
* starting point for a relative path. If not absolute, the value will first | ||
* be resolved starting from the current working directory of the process. | ||
* @param {String} [defaultPrefix='~+'] - The default prefix to use if path is | ||
* unanchored (i.e., first segment is not a fixed starting point). | ||
* @param {String} [start='~+'] - The path to use as a starting point for a | ||
* relative path. If not absolute, the value will first be resolved starting | ||
* from the current working directory of the process. | ||
* @param {String} [dot='.'] - The value used to replace a leading dot segment. | ||
* If the value is '.', then the start value is used. | ||
* | ||
* @returns {String} An absolute path. | ||
*/ | ||
function expandPath (path, start = cwd(), defaultPrefix = '~+') { | ||
if (!path) throw new TypeError('path must be a string. Received ' + path) | ||
function expandPath (path, start = '~+', dot = '.') { | ||
if (path === '.') { | ||
if (dot === '.') dot = start | ||
return dot === '~' ? homedir() : (dot === '~+' ? cwd() : resolve(dot)) | ||
} else if (path === '~') { | ||
return homedir() | ||
} else if (path === '~+') { | ||
return cwd() | ||
} else if (!path) { | ||
throw new TypeError('path must be a string. Received ' + path) | ||
} | ||
const ch0 = path.charAt() | ||
if (ch0 === '.') { | ||
if (path === '.') { | ||
return resolve(start) | ||
} else if (DOT_RELATIVE_RX.test(path)) { | ||
return resolve(start, path) | ||
} | ||
if (DOT_RELATIVE_RX.test(path) && dot !== '.') start = dot | ||
} else if (ch0 === '~') { | ||
if (path === '~') { | ||
return homedir() | ||
} else if (path === '~+') { | ||
return cwd() | ||
} else if (HOME_RELATIVE_RX.test(path)) { | ||
if (HOME_RELATIVE_RX.test(path)) { | ||
return join(homedir(), path.substr(2)) | ||
@@ -58,10 +56,6 @@ } else if (PWD_RELATIVE_RX.test(path)) { | ||
} | ||
switch (defaultPrefix) { | ||
case '~+': return join(cwd(), path) | ||
case '.': return resolve(start, path) | ||
case '~': return join(homedir(), path) | ||
default: throw new TypeError('defaultPrefix must be +~, ., or ~. Received ' + defaultPrefix) | ||
} | ||
if (start === '.') start = dot | ||
return start === '~+' ? join(cwd(), path) : (start === '~' ? join(homedir(), path) : resolve(start, path)) | ||
} | ||
module.exports = expandPath |
{ | ||
"name": "@antora/expand-path-helper", | ||
"version": "1.0.0-rc.2", | ||
"version": "1.0.0-rc.3", | ||
"description": "A helper function to expand a path to an absolute path, first resolving leading shorthands such as dot (.), tilde (~), and tilde plus (~+).", | ||
@@ -5,0 +5,0 @@ "license": "MPL-2.0", |
@@ -18,20 +18,27 @@ # @antora/expand-path-helper | ||
## Usage | ||
## API | ||
```js | ||
function expandPath (path, start = process.cwd(), defaultPrefix = '~+') { ... } | ||
function expandPath (path, start = process.cwd(), dot = '.') { ... } | ||
``` | ||
* The first parameter (`path`) is the path to expand. | ||
Converts path to an absolute path. | ||
* `path` - The path to expand. | ||
This parameter is required and must not be falsy. | ||
* The second parameter (`start`) is the starting directory to use to expand a leading '.' segment. | ||
* `start` - The starting directory from which to resolve a relative path. | ||
This parameter is optional. | ||
It defaults to the current working directory of the process. | ||
* The third parameter (`defaultPrefix`) is the prefix (first segment) to prepend to the path if the path is not anchored (e.g., `dir/file`). | ||
* `dot` - The value to use to replace a leading dot (`.`) segment. | ||
This parameter is optional. | ||
If the value of this parameter is itself `.`, which is the default, it uses the value of the start parameter. | ||
By default, a path which is not anchored is resolved starting from the current working directory of the process. | ||
This behavior can be changed by passing a different `defaultPrefix` value, such as `.` (uses the value of start), `~` (uses the user's home directory). | ||
The default is the equivalent of passing `~+`. | ||
The main purpose of this function is path expansion. | ||
If the first segment of the path, the value of the start parameter, or the value of the dot parameter matches `~` or `~+`, that value is expanded to the user's home directory or current working directory, respectively. | ||
If the first segment of the path matches `.`, that value is replaced with the value of the dot parameter after being expanded. | ||
## Usage | ||
The output of `expandPath` depends on the system on which it is run (specifically on the `path.sep` value). | ||
### *nix | ||
@@ -48,2 +55,5 @@ | ||
expandPath('./foo/bar') | ||
//=> /current/directory/foo/bar | ||
expandPath('~/foo/bar') | ||
@@ -55,6 +65,9 @@ //=> /home/user/foo/bar | ||
expandPath('foo/bar', '/start/dir') | ||
//=> /start/dir/foo/bar | ||
expandPath('./foo/bar', '/start/dir') | ||
//=> /start/dir/foo/bar | ||
expandPath('foo/bar', '/start/dir', '.') | ||
expandPath('./foo/bar', '~+', '/start/dir') | ||
//=> /start/dir/foo/bar | ||
@@ -74,2 +87,5 @@ ``` | ||
expandPath('.\\foo\\bar') | ||
//=> C:\current\directory\foo\bar | ||
expandPath('~\\foo\\bar') | ||
@@ -81,6 +97,9 @@ //=> C:\Users\user\foo\bar | ||
expandPath('foo\\bar', 'C:\\start\\dir') | ||
//=> C:\start\dir\foo\bar | ||
expandPath('.\\foo\\bar', 'C:\\start\\dir') | ||
//=> C:\start\dir\foo\bar | ||
expandPath('foo/bar', '/start/dir', '.') | ||
expandPath('.\\foo\\bar', '~+', 'C:\\start\\dir') | ||
//=> C:\start\dir\foo\bar | ||
@@ -87,0 +106,0 @@ ``` |
License Policy Violation
LicenseThis package is not allowed per your license policy. Review the package's license to ensure compliance.
Found 1 instance in 1 package
License Policy Violation
LicenseThis package is not allowed per your license policy. Review the package's license to ensure compliance.
Found 1 instance in 1 package
23359
110
55