diff options
author | anoff <offenhaeuser@gmail.com> | 2016-12-01 20:54:46 +0300 |
---|---|---|
committer | Rich Trott <rtrott@gmail.com> | 2016-12-08 09:54:33 +0300 |
commit | 2d0ce510e8e3d03ad3d45f5ba52dd061e1fd9497 (patch) | |
tree | db782e4e176c1f376ffca7222c960c72909b6138 /doc/api/path.md | |
parent | 1e4b9a1450d94bb7e45bcecc772e69638b6f10a3 (diff) |
doc: update `path.format` description and examples
* removed pseudo-code
* added info on which properties have priority
* modified examples to show ignored properties
PR-URL: https://github.com/nodejs/node/pull/10046
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Sam Roberts <vieuxtech@gmail.com>
Diffstat (limited to 'doc/api/path.md')
-rw-r--r-- | doc/api/path.md | 40 |
1 files changed, 13 insertions, 27 deletions
diff --git a/doc/api/path.md b/doc/api/path.md index fdd3063e69b..a9c72c2e2e7 100644 --- a/doc/api/path.md +++ b/doc/api/path.md @@ -182,26 +182,20 @@ added: v0.11.15 The `path.format()` method returns a path string from an object. This is the opposite of [`path.parse()`][]. -The following process is used when constructing the path string: - -* `output` is set to an empty string. -* If `pathObject.dir` is specified, `pathObject.dir` is appended to `output` - followed by the value of `path.sep`; -* Otherwise, if `pathObject.root` is specified, `pathObject.root` is appended - to `output`. -* If `pathObject.base` is specified, `pathObject.base` is appended to `output`; -* Otherwise: - * If `pathObject.name` is specified, `pathObject.name` is appended to `output` - * If `pathObject.ext` is specified, `pathObject.ext` is appended to `output`. -* Return `output` +When providing properties to the `pathObject` remember that there are +combinations where one property has priority over another: + +* `pathObject.root` is ignored if `pathObject.dir` is provided +* `pathObject.ext` and `pathObject.name` are ignored if `pathObject.base` exists For example, on POSIX: ```js -// If `dir` and `base` are provided, +// If `dir`, `root` and `base` are provided, // `${dir}${path.sep}${base}` -// will be returned. +// will be returned. `root` is ignored. path.format({ + root: '/ignored', dir: '/home/user/dir', base: 'file.txt' }); @@ -209,10 +203,11 @@ path.format({ // `root` will be used if `dir` is not specified. // If only `root` is provided or `dir` is equal to `root` then the -// platform separator will not be included. +// platform separator will not be included. `ext` will be ignored. path.format({ root: '/', - base: 'file.txt' + base: 'file.txt', + ext: 'ignored' }); // Returns: '/file.txt' @@ -223,23 +218,14 @@ path.format({ ext: '.txt' }); // Returns: '/file.txt' - -// `base` will be returned if `dir` or `root` are not provided. -path.format({ - base: 'file.txt' -}); -// Returns: 'file.txt' ``` On Windows: ```js path.format({ - root : "C:\\", - dir : "C:\\path\\dir", - base : "file.txt", - ext : ".txt", - name : "file" + dir : "C:\\path\\dir", + base : "file.txt" }); // Returns: 'C:\\path\\dir\\file.txt' ``` |