Skip to content

Commit

Permalink
path: deprecate internal _makeLong, replace
Browse files Browse the repository at this point in the history 
Replace the internal `path._makeLong()` with a public
`path.toLongUNCPath()` method. Add documentation.

PR-URL: #14956
Ref: standard-things/esm#66
Reviewed-By: Matteo Collina <[email protected]>
Reviewed-By: Refael Ackermann <[email protected]>
Reviewed-By: Anna Henningsen <[email protected]>
  • Loading branch information
@jasnell
jasnell committed Oct 2, 2017
1 parent 7069e63 commit 1f8d527
Show file tree
Hide file tree
Showing 7 changed files with 116 additions and 83 deletions.
10 changes: 10 additions & 0 deletions doc/api/deprecations.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -710,6 +710,16 @@ function for [`util.inspect()`][] is deprecated. Use [`util.inspect.custom`][]
instead. For backwards compatibility with Node.js prior to version 6.4.0, both
may be specified.
<a id="DEP00XX"></a>

This comment has been minimized.

Sign in to view

Copy link
@refack

refack Oct 2, 2017 •
edited
Loading

Contributor

Weren't you supposed to assign an actual number?
NM just saw #15741
### DEP00XX: path.\_makeLong()
Type: Documentation-only
The internal `path._makeLong()` was not intended for public use. However,
userland modules have found it useful. The internal API has been deprecated
and replaced with an identical, public `path.toNamespacedPath()` method.
[`Buffer.allocUnsafeSlow(size)`]: buffer.html#buffer_class_method_buffer_allocunsafeslow_size
[`Buffer.from(array)`]: buffer.html#buffer_class_method_buffer_from_array
[`Buffer.from(buffer)`]: buffer.html#buffer_class_method_buffer_from_buffer
Expand Down
16 changes: 16 additions & 0 deletions doc/api/path.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -543,6 +543,21 @@ On Windows:
accepted as path segment separators; however, the `path` methods only add
backward slashes (`\`).

## path.toNamespacedPath(path)
<!-- YAML
added: REPLACEME
-->

* `path` {string}
* Returns: {string}

On Windows systems only, returns an equivalent [namespace-prefixed path][] for
the given `path`. If `path` is not a string, `path` will be returned without
modifications.

This method is meaningful only on Windows system. On posix systems, the
method is non-operational and always returns `path` without modifications.

## path.win32
<!-- YAML
added: v0.11.15
Expand All @@ -559,3 +574,4 @@ of the `path` methods.
[`path.sep`]: #path_path_sep
[`path.win32`]: #path_path_win32
[MSDN-Rel-Path]: https://msdn.microsoft.com/en-us/library/windows/desktop/aa365247.aspx#fully_qualified_vs._relative_paths
[namespace-prefixed path]: https://msdn.microsoft.com/library/windows/desktop/aa365247(v=vs.85).aspx#namespaces
88 changes: 45 additions & 43 deletions lib/fs.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -293,7 +293,7 @@ fs.access = function(path, mode, callback) {
mode = mode | 0;
var req = new FSReqWrap();
req.oncomplete = makeCallback(callback);
binding.access(pathModule._makeLong(path), mode, req);
binding.access(pathModule.toNamespacedPath(path), mode, req);
};

fs.accessSync = function(path, mode) {
Expand All @@ -305,7 +305,7 @@ fs.accessSync = function(path, mode) {
else
mode = mode | 0;

binding.access(pathModule._makeLong(path), mode);
binding.access(pathModule.toNamespacedPath(path), mode);
};

fs.exists = function(path, callback) {
Expand All @@ -314,7 +314,7 @@ fs.exists = function(path, callback) {
if (!nullCheck(path, cb)) return;
var req = new FSReqWrap();
req.oncomplete = cb;
binding.stat(pathModule._makeLong(path), req);
binding.stat(pathModule.toNamespacedPath(path), req);
function cb(err) {
if (callback) callback(err ? false : true);
}
Expand All @@ -333,7 +333,7 @@ fs.existsSync = function(path) {
try {
handleError((path = getPathFromURL(path)));
nullCheck(path);
binding.stat(pathModule._makeLong(path));
binding.stat(pathModule.toNamespacedPath(path));
return true;
} catch (e) {
return false;
Expand Down Expand Up @@ -362,7 +362,7 @@ fs.readFile = function(path, options, callback) {
return;
}

binding.open(pathModule._makeLong(path),
binding.open(pathModule.toNamespacedPath(path),
stringToFlags(options.flag || 'r'),
0o666,
req);
Expand Down Expand Up @@ -646,7 +646,7 @@ fs.open = function(path, flags, mode, callback_) {
var req = new FSReqWrap();
req.oncomplete = callback;

binding.open(pathModule._makeLong(path),
binding.open(pathModule.toNamespacedPath(path),
stringToFlags(flags),
mode,
req);
Expand All @@ -656,7 +656,8 @@ fs.openSync = function(path, flags, mode) {
mode = modeNum(mode, 0o666);
handleError((path = getPathFromURL(path)));
nullCheck(path);
return binding.open(pathModule._makeLong(path), stringToFlags(flags), mode);
return binding.open(pathModule.toNamespacedPath(path),
stringToFlags(flags), mode);
};

fs.read = function(fd, buffer, offset, length, position, callback) {
Expand Down Expand Up @@ -766,8 +767,8 @@ fs.rename = function(oldPath, newPath, callback) {
if (!nullCheck(newPath, callback)) return;
var req = new FSReqWrap();
req.oncomplete = callback;
binding.rename(pathModule._makeLong(oldPath),
pathModule._makeLong(newPath),
binding.rename(pathModule.toNamespacedPath(oldPath),
pathModule.toNamespacedPath(newPath),
req);
};

Expand All @@ -776,8 +777,8 @@ fs.renameSync = function(oldPath, newPath) {
handleError((newPath = getPathFromURL(newPath)));
nullCheck(oldPath);
nullCheck(newPath);
return binding.rename(pathModule._makeLong(oldPath),
pathModule._makeLong(newPath));
return binding.rename(pathModule.toNamespacedPath(oldPath),
pathModule.toNamespacedPath(newPath));
};

fs.truncate = function(path, len, callback) {
Expand Down Expand Up @@ -850,13 +851,13 @@ fs.rmdir = function(path, callback) {
if (!nullCheck(path, callback)) return;
var req = new FSReqWrap();
req.oncomplete = callback;
binding.rmdir(pathModule._makeLong(path), req);
binding.rmdir(pathModule.toNamespacedPath(path), req);
};

fs.rmdirSync = function(path) {
handleError((path = getPathFromURL(path)));
nullCheck(path);
return binding.rmdir(pathModule._makeLong(path));
return binding.rmdir(pathModule.toNamespacedPath(path));
};

fs.fdatasync = function(fd, callback) {
Expand Down Expand Up @@ -887,15 +888,15 @@ fs.mkdir = function(path, mode, callback) {
if (!nullCheck(path, callback)) return;
var req = new FSReqWrap();
req.oncomplete = callback;
binding.mkdir(pathModule._makeLong(path),
binding.mkdir(pathModule.toNamespacedPath(path),
modeNum(mode, 0o777),
req);
};

fs.mkdirSync = function(path, mode) {
handleError((path = getPathFromURL(path)));
nullCheck(path);
return binding.mkdir(pathModule._makeLong(path),
return binding.mkdir(pathModule.toNamespacedPath(path),
modeNum(mode, 0o777));
};

Expand All @@ -907,14 +908,14 @@ fs.readdir = function(path, options, callback) {
if (!nullCheck(path, callback)) return;
var req = new FSReqWrap();
req.oncomplete = callback;
binding.readdir(pathModule._makeLong(path), options.encoding, req);
binding.readdir(pathModule.toNamespacedPath(path), options.encoding, req);
};

fs.readdirSync = function(path, options) {
options = getOptions(options, {});
handleError((path = getPathFromURL(path)));
nullCheck(path);
return binding.readdir(pathModule._makeLong(path), options.encoding);
return binding.readdir(pathModule.toNamespacedPath(path), options.encoding);
};

fs.fstat = function(fd, callback) {
Expand All @@ -930,7 +931,7 @@ fs.lstat = function(path, callback) {
if (!nullCheck(path, callback)) return;
var req = new FSReqWrap();
req.oncomplete = callback;
binding.lstat(pathModule._makeLong(path), req);
binding.lstat(pathModule.toNamespacedPath(path), req);
};

fs.stat = function(path, callback) {
Expand All @@ -940,7 +941,7 @@ fs.stat = function(path, callback) {
if (!nullCheck(path, callback)) return;
var req = new FSReqWrap();
req.oncomplete = callback;
binding.stat(pathModule._makeLong(path), req);
binding.stat(pathModule.toNamespacedPath(path), req);
};

fs.fstatSync = function(fd) {
Expand All @@ -951,14 +952,14 @@ fs.fstatSync = function(fd) {
fs.lstatSync = function(path) {
handleError((path = getPathFromURL(path)));
nullCheck(path);
binding.lstat(pathModule._makeLong(path));
binding.lstat(pathModule.toNamespacedPath(path));
return statsFromValues();
};

fs.statSync = function(path) {
handleError((path = getPathFromURL(path)));
nullCheck(path);
binding.stat(pathModule._makeLong(path));
binding.stat(pathModule.toNamespacedPath(path));
return statsFromValues();
};

Expand All @@ -970,14 +971,14 @@ fs.readlink = function(path, options, callback) {
if (!nullCheck(path, callback)) return;
var req = new FSReqWrap();
req.oncomplete = callback;
binding.readlink(pathModule._makeLong(path), options.encoding, req);
binding.readlink(pathModule.toNamespacedPath(path), options.encoding, req);
};

fs.readlinkSync = function(path, options) {
options = getOptions(options, {});
handleError((path = getPathFromURL(path)));
nullCheck(path);
return binding.readlink(pathModule._makeLong(path), options.encoding);
return binding.readlink(pathModule.toNamespacedPath(path), options.encoding);
};

function preprocessSymlinkDestination(path, type, linkPath) {
Expand All @@ -988,7 +989,7 @@ function preprocessSymlinkDestination(path, type, linkPath) {
// Junctions paths need to be absolute and \\?\-prefixed.
// A relative target is relative to the link's parent directory.
path = pathModule.resolve(linkPath, '..', path);
return pathModule._makeLong(path);
return pathModule.toNamespacedPath(path);
} else {
// Windows symlinks don't tolerate forward slashes.
return ('' + path).replace(/\//g, '\\');
Expand All @@ -1012,7 +1013,7 @@ fs.symlink = function(target, path, type_, callback_) {
req.oncomplete = callback;

binding.symlink(preprocessSymlinkDestination(target, type, path),
pathModule._makeLong(path),
pathModule.toNamespacedPath(path),
type,
req);
};
Expand All @@ -1025,7 +1026,7 @@ fs.symlinkSync = function(target, path, type) {
nullCheck(path);

return binding.symlink(preprocessSymlinkDestination(target, type, path),
pathModule._makeLong(path),
pathModule.toNamespacedPath(path),
type);
};

Expand All @@ -1044,8 +1045,8 @@ fs.link = function(existingPath, newPath, callback) {
var req = new FSReqWrap();
req.oncomplete = callback;

binding.link(pathModule._makeLong(existingPath),
pathModule._makeLong(newPath),
binding.link(pathModule.toNamespacedPath(existingPath),
pathModule.toNamespacedPath(newPath),
req);
};

Expand All @@ -1054,8 +1055,8 @@ fs.linkSync = function(existingPath, newPath) {
handleError((newPath = getPathFromURL(newPath)));
nullCheck(existingPath);
nullCheck(newPath);
return binding.link(pathModule._makeLong(existingPath),
pathModule._makeLong(newPath));
return binding.link(pathModule.toNamespacedPath(existingPath),
pathModule.toNamespacedPath(newPath));
};

fs.unlink = function(path, callback) {
Expand All @@ -1065,13 +1066,13 @@ fs.unlink = function(path, callback) {
if (!nullCheck(path, callback)) return;
var req = new FSReqWrap();
req.oncomplete = callback;
binding.unlink(pathModule._makeLong(path), req);
binding.unlink(pathModule.toNamespacedPath(path), req);
};

fs.unlinkSync = function(path) {
handleError((path = getPathFromURL(path)));
nullCheck(path);
return binding.unlink(pathModule._makeLong(path));
return binding.unlink(pathModule.toNamespacedPath(path));
};

fs.fchmod = function(fd, mode, callback) {
Expand Down Expand Up @@ -1129,15 +1130,15 @@ fs.chmod = function(path, mode, callback) {
if (!nullCheck(path, callback)) return;
var req = new FSReqWrap();
req.oncomplete = callback;
binding.chmod(pathModule._makeLong(path),
binding.chmod(pathModule.toNamespacedPath(path),
modeNum(mode),
req);
};

fs.chmodSync = function(path, mode) {
handleError((path = getPathFromURL(path)));
nullCheck(path);
return binding.chmod(pathModule._makeLong(path), modeNum(mode));
return binding.chmod(pathModule.toNamespacedPath(path), modeNum(mode));
};

if (constants.O_SYMLINK !== undefined) {
Expand Down Expand Up @@ -1175,13 +1176,13 @@ fs.chown = function(path, uid, gid, callback) {
if (!nullCheck(path, callback)) return;
var req = new FSReqWrap();
req.oncomplete = callback;
binding.chown(pathModule._makeLong(path), uid, gid, req);
binding.chown(pathModule.toNamespacedPath(path), uid, gid, req);
};

fs.chownSync = function(path, uid, gid) {
handleError((path = getPathFromURL(path)));
nullCheck(path);
return binding.chown(pathModule._makeLong(path), uid, gid);
return binding.chown(pathModule.toNamespacedPath(path), uid, gid);
};

// converts Date or number to a fractional UNIX timestamp
Expand Down Expand Up @@ -1216,7 +1217,7 @@ fs.utimes = function(path, atime, mtime, callback) {
if (!nullCheck(path, callback)) return;
var req = new FSReqWrap();
req.oncomplete = callback;
binding.utimes(pathModule._makeLong(path),
binding.utimes(pathModule.toNamespacedPath(path),
toUnixTimestamp(atime),
toUnixTimestamp(mtime),
req);
Expand All @@ -1227,7 +1228,7 @@ fs.utimesSync = function(path, atime, mtime) {
nullCheck(path);
atime = toUnixTimestamp(atime);
mtime = toUnixTimestamp(mtime);
binding.utimes(pathModule._makeLong(path), atime, mtime);
binding.utimes(pathModule.toNamespacedPath(path), atime, mtime);
};

fs.futimes = function(fd, atime, mtime, callback) {
Expand Down Expand Up @@ -1383,7 +1384,7 @@ FSWatcher.prototype.start = function(filename,
encoding) {
handleError((filename = getPathFromURL(filename)));
nullCheck(filename);
var err = this._handle.start(pathModule._makeLong(filename),
var err = this._handle.start(pathModule.toNamespacedPath(filename),
persistent,
recursive,
encoding);
Expand Down Expand Up @@ -1472,7 +1473,8 @@ util.inherits(StatWatcher, EventEmitter);
StatWatcher.prototype.start = function(filename, persistent, interval) {
handleError((filename = getPathFromURL(filename)));
nullCheck(filename);
this._handle.start(pathModule._makeLong(filename), persistent, interval);
this._handle.start(pathModule.toNamespacedPath(filename),
persistent, interval);
};


Expand Down Expand Up @@ -1627,7 +1629,7 @@ fs.realpathSync = function realpathSync(p, options) {

// On windows, check that the root exists. On unix there is no need.
if (isWindows && !knownHard[base]) {
binding.lstat(pathModule._makeLong(base));
binding.lstat(pathModule.toNamespacedPath(base));
knownHard[base] = true;
}

Expand Down Expand Up @@ -1666,7 +1668,7 @@ fs.realpathSync = function realpathSync(p, options) {
// Use stats array directly to avoid creating an fs.Stats instance just
// for our internal use.

var baseLong = pathModule._makeLong(base);
var baseLong = pathModule.toNamespacedPath(base);
binding.lstat(baseLong);

if ((statValues[1/*mode*/] & S_IFMT) !== S_IFLNK) {
Expand Down Expand Up @@ -1706,7 +1708,7 @@ fs.realpathSync = function realpathSync(p, options) {

// On windows, check that the root exists. On unix there is no need.
if (isWindows && !knownHard[base]) {
binding.lstat(pathModule._makeLong(base));
binding.lstat(pathModule.toNamespacedPath(base));
knownHard[base] = true;
}
}
Expand Down
Loading

0 comments on commit 1f8d527

Please sign in to comment.