@antora/expand-path-helper
Advanced tools
Comparing version 1.0.0 to 2.0.0
101
lib/index.js
| 'use strict' | ||
| const { cwd } = process | ||
| const { homedir } = require('os') | ||
| const { isAbsolute, join, normalize, resolve, sep } = require('path') | ||
| const { cwd: pwd } = process | ||
| const [getFirstSegment, isAbsolute, { join, normalize, resolve }] = ((path) => [ | ||
| path === path.posix | ||
| ? (str, idx) => (~(idx = str.indexOf('/')) ? str.substr(0, idx) : undefined) | ||
| : (str, idx) => (~(idx = str.indexOf('/')) || ~(idx = str.indexOf('\\')) ? str.substr(0, idx) : undefined), | ||
| path === path.posix ? () => false : path.isAbsolute, | ||
| path, | ||
| ])(require('path')) | ||
| const SEPARATOR_CC = sep === '\\' ? '[/\\\\]' : '/' | ||
| const DOT_RELATIVE_RX = new RegExp(`^\\.${SEPARATOR_CC}`) | ||
| const HOME_RELATIVE_RX = new RegExp(`^~${SEPARATOR_CC}`) | ||
| const PWD_RELATIVE_RX = new RegExp(`^~\\+${SEPARATOR_CC}`) | ||
| /** | ||
| * Converts path to an absolute path. | ||
| * Converts path to a normalized absolute path. | ||
| * | ||
| * If path is absolute, its value is normalized. If the first segment of path | ||
| * is a tilde (~), that segment is replaced with the home directory of the | ||
| * current user. If the first segment of path is a tilde followed by a plus | ||
| * (~+), that segment is replaced with the current working directory of the | ||
| * 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. | ||
| * If path is absolute, it is normalized. If the first segment of path is a tilde (~), that segment | ||
| * is replaced with the home directory of the current user. If the first segment of path is a tilde | ||
| * plus (~+), that segment is replaced with cwd, which defaults to the working directory of the | ||
| * process. If the first segment of path is a dot (.), that segment is replaced with dot after dot | ||
| * is expanded. Otherwise, path is relative and it is resolved from base. Path is then normalized. | ||
| * | ||
| * @param {String} path - The path to expand. | ||
| * @param {String} [start='~+'] - The path to use as a starting point for a | ||
| * relative path. Unless absolute, the value will first be expanded 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. | ||
| * @param {String} path - The path to expand. Must be a String. | ||
| * @param {Object} [context={}] - Named parameters that control how a path is resolved. Can also be | ||
| * specified as a String, in which case it is used as base. | ||
| * @param {String} [context.base='~+'] - The path to use as the base directory for a relative path. | ||
| * Unless absolute, the value will first be expanded starting from the current working directory of | ||
| * the process. | ||
| * @param {String} [context.cwd=undefined] - The absolute path to use as the working directory. If | ||
| * the value is falsy, it defaults to the current working directory. | ||
| * @param {String} [context.dot='.'] - The path to used to replace a leading dot segment. If value | ||
| * is '.', resolves to base. | ||
| * | ||
| * @returns {String} An absolute path. | ||
| * @returns {String} A normalized absolute 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) | ||
| function expandPath (path, context = {}) { | ||
| if (typeof path !== 'string') { | ||
| throw new TypeError(`The "path" argument must be of type string. Received type ${typeof path}`) | ||
| } | ||
| const ch0 = path.charAt() | ||
| if (ch0 === '.') { | ||
| if (DOT_RELATIVE_RX.test(path) && dot !== '.') start = dot | ||
| } else if (ch0 === '~') { | ||
| if (HOME_RELATIVE_RX.test(path)) { | ||
| return join(homedir(), path.substr(2)) | ||
| } else if (PWD_RELATIVE_RX.test(path)) { | ||
| return join(cwd(), path.substr(3)) | ||
| } | ||
| } else if (isAbsolute(path)) { | ||
| return normalize(path) | ||
| let { base = '~+', cwd, dot = '.' } = context.constructor === Object ? context : { base: context } | ||
| if (base === '.') base = dot | ||
| const getcwd = cwd === undefined ? pwd : () => cwd | ||
| switch (path) { | ||
| case '': | ||
| return base === '~+' ? getcwd() : base === '~' ? homedir() : resolve(base) | ||
| case '.': | ||
| if (dot === '.') dot = base | ||
| return dot === '~' ? homedir() : dot === '~+' ? getcwd() : resolve(dot) | ||
| case '~': | ||
| return homedir() | ||
| case '~+': | ||
| return getcwd() | ||
| default: | ||
| switch (getFirstSegment(path)) { | ||
| case '': | ||
| return normalize(path) | ||
| case '.': | ||
| if (dot !== '.') base = dot | ||
| break | ||
| case '~': | ||
| return join(homedir(), path.substr(2)) | ||
| case '~+': | ||
| return join(getcwd(), path.substr(3)) | ||
| default: | ||
| if (isAbsolute(path)) return normalize(path) | ||
| } | ||
| return base === '~+' ? join(getcwd(), path) : base === '~' ? join(homedir(), path) : resolve(base, path) | ||
| } | ||
| 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", | ||
| "description": "A helper function to expand a path to an absolute path, including expanding the first segment if it matches a shorthand expression, dot (.), tilde (~), or tilde plus (~+).", | ||
| "version": "2.0.0", | ||
| "description": "Provides a helper function to expand a path to a normalized absolute path. This function also expands dot, tilde, and tilde plus when used as the first path segment.", | ||
| "license": "MPL-2.0", | ||
@@ -11,19 +11,26 @@ "author": "OpenDevise Inc. (https://opendevise.com)", | ||
| "repository": "gitlab:antora/expand-path-helper", | ||
| "bugs": { | ||
| "url": "https://gitlab.com/antora/expand-path-helper/issues" | ||
| }, | ||
| "main": "lib/index.js", | ||
| "scripts": { | ||
| "test": "_mocha test", | ||
| "lint": "eslint **/*.js", | ||
| "lint": "eslint \"{lib,npm,test}/**/*.js\"", | ||
| "format": "prettier-eslint --write \"`pwd`/{lib,npm,test}/**/*.js\"", | ||
| "cov": "nyc _mocha test" | ||
| }, | ||
| "devDependencies": { | ||
| "chai": "^4.1.2", | ||
| "eslint": "^4.18.0", | ||
| "eslint-config-standard": "^11.0.0", | ||
| "eslint-plugin-import": "^2.8.0", | ||
| "eslint-plugin-node": "^6.0.0", | ||
| "eslint-plugin-promise": "^3.6.0", | ||
| "eslint-plugin-standard": "^3.0.1", | ||
| "mocha": "^5.0.1", | ||
| "nyc": "^11.5.0" | ||
| "chai": "~4.3", | ||
| "eslint": "~7.30", | ||
| "eslint-config-standard": "~16.0", | ||
| "eslint-plugin-import": "~2.23", | ||
| "eslint-plugin-node": "~11.1", | ||
| "eslint-plugin-promise": "~4.3", | ||
| "mocha": "~8.4", | ||
| "nyc": "~15.1", | ||
| "prettier-eslint-cli": "~5.0" | ||
| }, | ||
| "engines": { | ||
| "node": ">=10.17.0" | ||
| }, | ||
| "files": [ | ||
@@ -36,2 +43,3 @@ "lib/" | ||
| "relative", | ||
| "cwd", | ||
| "pwd", | ||
@@ -38,0 +46,0 @@ "home" |
| # @antora/expand-path-helper | ||
| A module for Node.js that provides a helper function to expand a path to an absolute path. | ||
| This function expands the first segment if it matches a shorthand expression, dot (`.`), tilde (`~`), or tilde plus (`~+`). | ||
| A Node.js module that provides a helper function to expand a path to a normalized absolute path. | ||
| This function also expands the following shorthand expressions when used as the first path segment: dot (`.`), tilde (`~`), or tilde plus (`~+`). | ||
| The expanded path is system dependent. | ||
@@ -23,19 +23,24 @@ Developed for use in Antora. | ||
| ```js | ||
| function expandPath (path, start = '~+', dot = '.') { ... } | ||
| function expandPath (path, { base = '~+', cwd, dot = '.' } = {}) { ... } | ||
| ``` | ||
| Converts path to an absolute path. | ||
| Expands the specified path to a normalized absolute path. | ||
| * `path` - The path to expand. | ||
| This parameter is required and must not be falsy. | ||
| * `start` - The starting directory from which to anchor a relative path. | ||
| This parameter is optional. | ||
| It defaults to the current working directory of the process (`~+`). | ||
| * `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. | ||
| * `path` `<string>` - The path to expand. | ||
| This parameter is required. | ||
| If the path is already absolute, the path is normalized and returned. | ||
| * `context` `<Object>` - Named parameters that control how the path is resolved. | ||
| All named parameters are optional. | ||
| This parameter can also be specified as a String, in which case it is used as the base argument. | ||
| * `context.base` `<string>` - The base directory from which to resolve a relative path instead of the working directory. | ||
| This named parameter is optional. | ||
| * `context.cwd` `<string>` - The absolute directory to use as the working directory instead of the current working directory. | ||
| This named parameter is optional. | ||
| * `context.dot` - The value to use to replace a leading dot (`.`) segment. | ||
| This named parameter is optional. | ||
| If the dot argument is `.`, which is the default value, the base argument is used instead. | ||
| 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. | ||
| The main purpose of this function is path expansion and normalization. | ||
| If the first segment of the path argument, the base argument, or the dot argument is `~` or `~+`, that value is expanded to the user's home directory or current working directory, respectively. | ||
| If the first segment of the path argument is `.`, that value is replaced with the dot argument after the dot argument is expanded. | ||
@@ -54,22 +59,31 @@ ## Usage | ||
| expandPath('/absolute/./path/..') | ||
| //=> /absolute | ||
| expandPath('foo/bar') | ||
| //=> /current/directory/foo/bar | ||
| //=> $PWD/foo/bar | ||
| expandPath('./foo/bar') | ||
| //=> /current/directory/foo/bar | ||
| //=> $PWD/foo/bar | ||
| expandPath('~/foo/bar') | ||
| //=> /home/user/foo/bar | ||
| //=> $HOME/foo/bar | ||
| expandPath('~+/foo/bar') | ||
| //=> /current/directory/foo/bar | ||
| //=> $PWD/foo/bar | ||
| expandPath('foo/bar', '/start/dir') | ||
| //=> /start/dir/foo/bar | ||
| expandPath('~+/foo/bar', { cwd: '/working/dir' }) | ||
| //=> /working/dir/foo/bar | ||
| expandPath('./foo/bar', '/start/dir') | ||
| //=> /start/dir/foo/bar | ||
| expandPath('foo/bar', '/base/dir') | ||
| //=> /base/dir/foo/bar | ||
| expandPath('./foo/bar', '~+', '/start/dir') | ||
| //=> /start/dir/foo/bar | ||
| expandPath('foo/bar', { base: '/base/dir' }) | ||
| //=> /base/dir/foo/bar | ||
| expandPath('./foo/bar', { base: '/base/dir' }) | ||
| //=> /base/dir/foo/bar | ||
| expandPath('./foo/bar', { dot: '/dot/dir' }) | ||
| //=> /dot/dir/foo/bar | ||
| ``` | ||
@@ -85,2 +99,5 @@ | ||
| expandPath('C:\\absolute\\.\\path\\..') | ||
| //=> C:\absolute | ||
| expandPath('foo\\bar') | ||
@@ -98,18 +115,24 @@ //=> C:\current\directory\foo\bar | ||
| expandPath('foo\\bar', 'C:\\start\\dir') | ||
| //=> C:\start\dir\foo\bar | ||
| expandPath('~+\\foo\\bar', { cwd: 'C:\\working\\dir' }) | ||
| //=> C:\working\dir\foo\bar | ||
| expandPath('.\\foo\\bar', 'C:\\start\\dir') | ||
| //=> C:\start\dir\foo\bar | ||
| expandPath('foo\\bar', 'C:\\base\\dir') | ||
| //=> C:\base\dir\foo\bar | ||
| expandPath('.\\foo\\bar', '~+', 'C:\\start\\dir') | ||
| //=> C:\start\dir\foo\bar | ||
| expandPath('foo\\bar', { base: 'C:\\base\\dir' }) | ||
| //=> C:\base\dir\foo\bar | ||
| expandPath('.\\foo\\bar', { base: 'C:\\base\\dir' }) | ||
| //=> C:\base\dir\foo\bar | ||
| expandPath('.\\foo\\bar', { dot: 'C:\\dot\\dir' }) | ||
| //=> C:\dot\dir\foo\bar | ||
| ``` | ||
| On Windows, the input path may contain forward slashes, but the expanded path will always have backslashes. | ||
| On Windows, the input path may use forward slashes, but the expanded path will always have backslashes. | ||
| ## Copyright and License | ||
| Copyright (C) 2018 OpenDevise Inc. and the Antora Project. | ||
| Copyright (C) 2018-present by OpenDevise Inc. and the individual contributors to Antora. | ||
| Use of this software is granted under the terms of the [Mozilla Public License Version 2.0](https://www.mozilla.org/en-US/MPL/2.0/) (MPL-2.0). |
Sorry, the diff of this file is not supported yet
Fixed alerts
No bug tracker
MaintenancePackage does not have a linked bug tracker in package.json.
Found 1 instance in 1 package
Improved metrics
- Total package byte prevSize
- increased by9.35%
26585
- Lines of code
- increased by21.82%
67
- Number of low maintenance alerts
- decreased by-100%
0
- Number of lines in readme file
- increased by20.54%
135
No dependency changes