diff options
author | guybedford <guybedford@gmail.com> | 2018-08-24 19:13:32 +0300 |
---|---|---|
committer | guybedford <guybedford@gmail.com> | 2018-09-04 17:08:21 +0300 |
commit | eef072fa083f05f84fa6ca1908472eb228095a38 (patch) | |
tree | 3fd3bc972b893bd49616bba2808e449743f55ee9 /doc/api/url.md | |
parent | 0d3da39f575afba5ab6a5a34f4e88a798a66dc6d (diff) |
url: provide pathToFileURL and fileURLToPath
PR-URL: https://github.com/nodejs/node/pull/22506
Reviewed-By: John-David Dalton <john.david.dalton@gmail.com>
Reviewed-By: Tiancheng "Timothy" Gu <timothygu99@gmail.com>
Reviewed-By: Matteo Collina <matteo.collina@gmail.com>
Reviewed-By: Bradley Farias <bradley.meck@gmail.com>
Reviewed-By: Joyee Cheung <joyeec9h3@gmail.com>
Reviewed-By: Gus Caplan <me@gus.host>
Diffstat (limited to 'doc/api/url.md')
-rw-r--r-- | doc/api/url.md | 43 |
1 files changed, 43 insertions, 0 deletions
diff --git a/doc/api/url.md b/doc/api/url.md index 571c3bdfdbf..cd817bf304b 100644 --- a/doc/api/url.md +++ b/doc/api/url.md @@ -880,6 +880,28 @@ console.log(url.domainToUnicode('xn--iñvalid.com')); // Prints an empty string ``` +### url.fileURLToPath(url) + +* `url` {URL | string} The file URL string or URL object to convert to a path. +* Returns: {string} The fully-resolved platform-specific Node.js file path. + +This function ensures the correct decodings of percent-encoded characters as +well as ensuring a cross-platform valid absolute path string. + +```js +new URL('file:///C:/path/').pathname; // Incorrect: /C:/path/ +fileURLToPath('file:///C:/path/'); // Correct: C:\path\ (Windows) + +new URL('file://nas/foo.txt').pathname; // Incorrect: /foo.txt +fileURLToPath('file://nas/foo.txt'); // Correct: \\nas\foo.txt (Windows) + +new URL('file:///你好.txt').pathname; // Incorrect: /%E4%BD%A0%E5%A5%BD.txt +fileURLToPath('file:///你好.txt'); // Correct: /你好.txt (POSIX) + +new URL('file:///hello world').pathname; // Incorrect: /hello%20world +fileURLToPath('file:///hello world'); // Correct: /hello world (POSIX) +``` + ### url.format(URL[, options]) <!-- YAML added: v7.6.0 @@ -919,6 +941,27 @@ console.log(url.format(myURL, { fragment: false, unicode: true, auth: false })); // Prints 'https://你好你好/?abc' ``` +### url.pathToFileURL(path) + +* `path` {string} The path to convert to a File URL. +* Returns: {URL} The file URL object. + +This function ensures that `path` is resolved absolutely, and that the URL +control characters are correctly encoded when converting into a File URL. + +```js +new URL(__filename); // Incorrect: throws (POSIX) +new URL(__filename); // Incorrect: C:\... (Windows) +pathToFileURL(__filename); // Correct: file:///... (POSIX) +pathToFileURL(__filename); // Correct: file:///C:/... (Windows) + +new URL('/foo#1', 'file:'); // Incorrect: file:///foo#1 +pathToFileURL('/foo#1'); // Correct: file:///foo%231 (POSIX) + +new URL('/some/path%.js', 'file:'); // Incorrect: file:///some/path% +pathToFileURL('/some/path%.js'); // Correct: file:///some/path%25 (POSIX) +``` + ## Legacy URL API ### Legacy `urlObject` |