Windows и POSIX

По умолчанию, поведение модуля path зависит от операционной системы, на которой работает приложение Node.js. В частности, при работе на Windows, модуль path будет предполагать использование путей в стиле Windows.

Поэтому использование path.basename() может давать разные результаты в POSIX и Windows:

В POSIX:

path.basename('C:\\temp\\myfile.html');
// Returns: 'C:\\temp\\myfile.html'

В Windows:

path.basename('C:\\temp\\myfile.html');
// Returns: 'myfile.html'

Для достижения согласованных результатов при работе с путями к файлам Windows на любой операционной системе, используйте path.win32:

В POSIX и Windows:

path.win32.basename('C:\\temp\\myfile.html');
// Returns: 'myfile.html'

Для достижения согласованных результатов при работе с путями к файлам POSIX на любой операционной системе, используйте path.posix:

В POSIX и Windows:

path.posix.basename('/tmp/myfile.html');
// Returns: 'myfile.html'

В Windows Node.js следует концепции рабочей директории на каждом диске. Это поведение можно наблюдать при использовании пути к диску без обратной косой черты. Например, path.resolve('C:\\') потенциально может возвращать другой результат, чем path.resolve('C:'). Для получения более подробной информации, ознакомьтесь со страницей MSDN здесь.

path.basename(path[, ext])

• path <строка>
• ext <строка> Необязательное расширение файла
• Возвращает: <строка>

Метод path.basename() возвращает последнюю часть path, аналогично команде Unix basename. Конечные разделители каталогов игнорируются, см. path.sep.

path.basename('/foo/bar/baz/asdf/quux.html');
// Returns: 'quux.html'

path.basename('/foo/bar/baz/asdf/quux.html', '.html');
// Returns: 'quux'

Хотя Windows обычно обрабатывает имена файлов, включая расширения, без учета регистра, эта функция не делает этого. Например, C:\\foo.html и C:\\foo.HTML ссылаются на один и тот же файл, но basename обрабатывает расширение как строку, учитывающую регистр:

path.win32.basename('C:\\foo.html', '.html');
// Returns: 'foo'

path.win32.basename('C:\\foo.HTML', '.html');
// Returns: 'foo.HTML'

Ошибка TypeError возникает, если path не является строкой или если ext задано и не является строкой.

path.delimiter

• <строка>

Предоставляет платформенно-зависимый разделитель путей:

• ; для Windows
• : для POSIX

Например, в POSIX:

console.log(process.env.PATH);
// Prints: '/usr/bin:/bin:/usr/sbin:/sbin:/usr/local/bin'

process.env.PATH.split(path.delimiter);
// Returns: ['/usr/bin', '/bin', '/usr/sbin', '/sbin', '/usr/local/bin']

В Windows:

console.log(process.env.PATH);
// Prints: 'C:\Windows\system32;C:\Windows;C:\Program Files\node\'

process.env.PATH.split(path.delimiter);
// Returns ['C:\\Windows\\system32', 'C:\\Windows', 'C:\\Program Files\\node\\']

path.dirname(path)

• path <строка>
• Возвращает: <строка>

Метод path.dirname() возвращает имя каталога path, аналогично команде Unix dirname. Конечные разделители каталогов игнорируются, см. path.sep.

path.dirname('/foo/bar/baz/asdf/quux');
// Returns: '/foo/bar/baz/asdf'

Ошибка TypeError возникает, если path не является строкой.

path.extname(path)

• path <строка>
• Возвращает: <строка>

Метод path.extname() возвращает расширение path, от последнего вхождения символа . (точка) до конца строки в последней части path. Если в последней части path нет символа ., или если нет символов . помимо первого символа имени базовой части path (см. path.basename()), возвращается пустая строка.

path.extname('index.html');
// Returns: '.html'

path.extname('index.coffee.md');
// Returns: '.md'

path.extname('index.');
// Returns: '.'

path.extname('index');
// Returns: ''

path.extname('.index');
// Returns: ''

path.extname('.index.md');
// Returns: '.md'

Ошибка TypeError возникает, если path не является строкой.

path.format(pathObject)

• pathObject <Объект>
  • dir <строка>
  • root <строка>
  • base <строка>
  • name <строка>
  • ext <строка>
• Возвращает: <строка>

Метод path.format() возвращает строку пути из объекта. Это обратное действие path.parse().

При предоставлении свойств для pathObject следует помнить, что существуют комбинации, где одно свойство имеет приоритет над другим:

• pathObject.root игнорируется, если предоставлено pathObject.dir
• pathObject.ext и pathObject.name игнорируются, если существует pathObject.base

Например, в POSIX:

// If `dir`, `root` and `base` are provided,
// `${dir}${path.sep}${base}`
// 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. `ext` will be ignored.
path.format({
  root: '/',
  base: 'file.txt',
  ext: 'ignored'
});
// Returns: '/file.txt'

// `name` + `ext` will be used if `base` is not specified.
path.format({
  root: '/',
  name: 'file',
  ext: '.txt'
});
// Returns: '/file.txt'

В Windows:

path.format({
  dir: 'C:\\path\\dir',
  base: 'file.txt'
});
// Returns: 'C:\\path\\dir\\file.txt'

path.isAbsolute(path)

• path <строка>
• Возвращает: <булево>

Метод path.isAbsolute() определяет, является ли path абсолютным путем.

Если заданная path является строкой нулевой длины, будет возвращено false.

Например, в POSIX:

path.isAbsolute('/foo/bar'); // true
path.isAbsolute('/baz/..');  // true
path.isAbsolute('qux/');     // false
path.isAbsolute('.');        // false

В Windows:

path.isAbsolute('//server');    // true
path.isAbsolute('\\\\server');  // true
path.isAbsolute('C:/foo/..');   // true
path.isAbsolute('C:\\foo\\..'); // true
path.isAbsolute('bar\\baz');    // false
path.isAbsolute('bar/baz');     // false
path.isAbsolute('.');           // false

Ошибка TypeError возникает, если path не является строкой.

path.join([...paths])

• ...paths <строка> Последовательность сегментов пути
• Возвращает: <строка>

Метод path.join() объединяет все заданные path сегменты вместе, используя платформенно-зависимый разделитель в качестве разделителя, а затем нормализует полученный путь.

Сегменты путей нулевой длины игнорируются. Если объединенная строка пути имеет нулевую длину, возвращается '.', представляющая текущую рабочую директорию.

path.join('/foo', 'bar', 'baz/asdf', 'quux', '..');
// Returns: '/foo/bar/baz/asdf'

path.join('foo', {}, 'bar');
// Throws 'TypeError: Path must be a string. Received {}'

Ошибка TypeError возникает, если какой-либо из сегментов пути не является строкой.

path.normalize(path)

• path <строка>
• Возвращает: <строка>

Метод path.normalize() нормализует заданный path, разрешая '..' и '.' сегменты.

Когда встречаются несколько последовательных символов разделения сегментов пути (например, / в POSIX и либо \ или / в Windows), они заменяются одним экземпляром символа разделения сегментов пути, специфичного для платформы (/ в POSIX и \ в Windows). Конечные разделители сохраняются.

Если path — строка нулевой длины, возвращается '.', представляющая текущий рабочий каталог.

Например, в POSIX:

path.normalize('/foo/bar//baz/asdf/quux/..');
// Returns: '/foo/bar/baz/asdf'

В Windows:

path.normalize('C:\\temp\\\\foo\\bar\\..\\');
// Returns: 'C:\\temp\\foo\\'

Поскольку Windows распознаёт несколько разделителей пути, оба разделителя будут заменены на экземпляры предпочтительного разделителя Windows (\):

path.win32.normalize('C:////temp\\\\/\\/\\/foo/bar');
// Returns: 'C:\\temp\\foo\\bar'

Если path не является строкой, выбрасывается TypeError.

path.parse(path)

• path <строка>
• Возвращает: <Объект>

Метод path.parse() возвращает объект, свойства которого представляют значимые элементы path. Конечные разделители каталога игнорируются, см. path.sep.

Возвращаемый объект будет иметь следующие свойства:

• dir <строка>
• root <строка>
• base <строка>
• name <строка>
• ext <строка>

Например, в POSIX:

path.parse('/home/user/dir/file.txt');
// Returns:
// { root: '/',
//   dir: '/home/user/dir',
//   base: 'file.txt',
//   ext: '.txt',
//   name: 'file' }

┌─────────────────────┬────────────┐
│          dir        │    base    │
├──────┬              ├──────┬─────┤
│ root │              │ name │ ext │
"  /    home/user/dir / file  .txt "
└──────┴──────────────┴──────┴─────┘
(All spaces in the "" line should be ignored. They are purely for formatting.)

В Windows:

path.parse('C:\\path\\dir\\file.txt');
// Returns:
// { root: 'C:\\',
//   dir: 'C:\\path\\dir',
//   base: 'file.txt',
//   ext: '.txt',
//   name: 'file' }

┌─────────────────────┬────────────┐
│          dir        │    base    │
├──────┬              ├──────┬─────┤
│ root │              │ name │ ext │
" C:\      path\dir   \ file  .txt "
└──────┴──────────────┴──────┴─────┘
(All spaces in the "" line should be ignored. They are purely for formatting.)

Если path не является строкой, выбрасывается TypeError.

path.posix

• <Объект>

Свойство path.posix предоставляет доступ к POSIX-специфическим реализациям методов path.

path.relative(from, to)

• from <строка>
• to <строка>
• Возвращает: <строка>

Метод path.relative() возвращает относительный путь от from к to на основе текущего рабочего каталога. Если from и to разрешаются до одного и того же пути (после вызова path.resolve() для каждого), возвращается строка нулевой длины.

Если в качестве from или to передаётся строка нулевой длины, вместо неё используется текущий рабочий каталог.

Например, в POSIX:

path.relative('/data/orandea/test/aaa', '/data/orandea/impl/bbb');
// Returns: '../../impl/bbb'

В Windows:

path.relative('C:\\orandea\\test\\aaa', 'C:\\orandea\\impl\\bbb');
// Returns: '..\\..\\impl\\bbb'

Если from или to не является строкой, выбрасывается TypeError.

path.resolve([...paths])

• ...paths <строка> Последовательность путей или сегментов пути
• Возвращает: <строка>

Метод path.resolve() разрешает последовательность путей или сегментов пути в абсолютный путь.

Указанная последовательность путей обрабатывается справа налево, и каждый последующий path добавляется в начало, пока не будет построен абсолютный путь. Например, при последовательности сегментов пути: /foo, /bar, baz, вызов path.resolve('/foo', '/bar', 'baz') вернёт /bar/baz, потому что 'baz' не является абсолютным путем, а '/bar' + '/' + 'baz' — является.

Если после обработки всех переданных path сегментов абсолютный путь ещё не сгенерирован, используется текущий рабочий каталог.

Полученный путь нормализован и конечные слэши удаляются, если только путь не разрешен до корневого каталога.

Сегменты пути нулевой длины игнорируются.

Если не передано ни одного сегмента path, path.resolve() вернёт абсолютный путь текущего рабочего каталога.

path.resolve('/foo/bar', './baz');
// Returns: '/foo/bar/baz'

path.resolve('/foo/bar', '/tmp/file/');
// Returns: '/tmp/file'

path.resolve('wwwroot', 'static_files/png/', '../gif/image.gif');
// If the current working directory is /home/myself/node,
// this returns '/home/myself/node/wwwroot/static_files/gif/image.gif'

Если какой-либо из аргументов не является строкой, выбрасывается TypeError.

path.sep

• <строка>

Предоставляет разделитель сегментов пути, специфичный для платформы:

• \ в Windows
• / в POSIX

Например, в POSIX:

'foo/bar/baz'.split(path.sep);
// Returns: ['foo', 'bar', 'baz']

В Windows:

'foo\\bar\\baz'.split(path.sep);
// Returns: ['foo', 'bar', 'baz']

В Windows как прямой слэш (/) так и обратный слэш (\) принимаются как разделители сегментов пути; однако методы path добавляют только обратные слэши (\).

path.toNamespacedPath(path)

• path <строка>
• Возвращает: <строка>

Только на системах Windows, возвращает эквивалентный путь с префиксом пространства имён namespace-prefixed path для данного path. Если path не является строкой, path возвращается без изменений.

Этот метод имеет смысл только на системах Windows. На системах POSIX метод не работает и всегда возвращает path без изменений.

path.win32

• <Объект>

Свойство path.win32 предоставляет доступ к Windows-специфическим реализациям методов path.