Skip to content

Commit

Permalink
doc: update path.format description and examples
Browse files Browse the repository at this point in the history
* removed pseudo-code
* added info on which properties have priority
* modified examples to show ignored properties

PR-URL: #10046
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Sam Roberts <vieuxtech@gmail.com>
  • Loading branch information
anoff authored and Fishrock123 committed Dec 13, 2016
1 parent a9d4bd7 commit ae53a6e
Showing 1 changed file with 13 additions and 27 deletions.
40 changes: 13 additions & 27 deletions doc/api/path.md
Original file line number Diff line number Diff line change
Expand Up @@ -182,37 +182,32 @@ 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'
});
// Returns: '/home/user/dir/file.txt'

// `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'

Expand All @@ -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'
```
Expand Down

0 comments on commit ae53a6e

Please sign in to comment.