Path

[Stabile: 2 - Stabile]

Stabile: 2 Stabilità: 2 - Stabile

Codice Sorgente: lib/path.js

Il modulo node:path fornisce utilità per lavorare con percorsi di file e directory. È possibile accedervi utilizzando:

CJS

const path = require('node:path')

ESM

import path from 'node:path'

Windows vs. POSIX

Il funzionamento predefinito del modulo node:path varia in base al sistema operativo su cui è in esecuzione un'applicazione Node.js. In particolare, quando è in esecuzione su un sistema operativo Windows, il modulo node:path presupporrà che vengano utilizzati percorsi in stile Windows.

Quindi, l'utilizzo di path.basename() potrebbe produrre risultati diversi su POSIX e Windows:

Su POSIX:

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

Su Windows:

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

Per ottenere risultati coerenti quando si lavora con percorsi di file Windows su qualsiasi sistema operativo, utilizzare path.win32:

Su POSIX e Windows:

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

Per ottenere risultati coerenti quando si lavora con percorsi di file POSIX su qualsiasi sistema operativo, utilizzare path.posix:

Su POSIX e Windows:

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

Su Windows, Node.js segue il concetto di directory di lavoro per unità. Questo comportamento può essere osservato quando si utilizza un percorso di unità senza una barra rovesciata. Ad esempio, path.resolve('C:\\') può potenzialmente restituire un risultato diverso da path.resolve('C:'). Per ulteriori informazioni, consultare questa pagina MSDN.

path.basename(path[, suffix])

[Cronologia]

Versione	Modifiche
v6.0.0	Il passaggio di un valore non stringa come argomento path ora genera un'eccezione.
v0.1.25	Aggiunto in: v0.1.25

• path <stringa>
• suffix <stringa> Un suffisso opzionale da rimuovere
• Restituisce: <stringa>

Il metodo path.basename() restituisce l'ultima parte di un path, in modo simile al comando basename di Unix. I separatori di directory finali vengono ignorati.

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

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

Sebbene Windows in genere tratti i nomi di file, comprese le estensioni di file, in modo non sensibile alla distinzione tra maiuscole e minuscole, questa funzione non lo fa. Ad esempio, C:\\foo.html e C:\\foo.HTML fanno riferimento allo stesso file, ma basename tratta l'estensione come una stringa sensibile alla distinzione tra maiuscole e minuscole:

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

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

Viene generato un TypeError se path non è una stringa o se suffix viene fornito e non è una stringa.

path.delimiter

Aggiunto in: v0.9.3

• <stringa>

Fornisce il delimitatore di percorso specifico della piattaforma:

• ; per Windows
• : per POSIX

Ad esempio, su POSIX:

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

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

Su Windows:

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

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

path.dirname(path)

[Cronologia]

Versione	Modifiche
v6.0.0	L'invio di un valore non stringa come argomento path ora genererà un'eccezione.
v0.1.16	Aggiunto in: v0.1.16

• path <stringa>
• Restituisce: <stringa>

Il metodo path.dirname() restituisce il nome della directory di un path, in modo simile al comando Unix dirname. I separatori di directory finali vengono ignorati, vedere path.sep.

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

Viene generato un TypeError se path non è una stringa.

path.extname(path)

[Cronologia]

Versione	Modifiche
v6.0.0	L'invio di un valore non stringa come argomento path ora genererà un'eccezione.
v0.1.25	Aggiunto in: v0.1.25

• path <stringa>
• Restituisce: <stringa>

Il metodo path.extname() restituisce l'estensione del path, dall'ultima occorrenza del carattere . (punto) fino alla fine della stringa nell'ultima parte del path. Se non c'è . nell'ultima parte del path, o se non ci sono caratteri . diversi dal primo carattere del nome base di path (vedere path.basename()), viene restituita una stringa vuota.

path.extname('index.html')
// Restituisce: '.html'

path.extname('index.coffee.md')
// Restituisce: '.md'

path.extname('index.')
// Restituisce: '.'

path.extname('index')
// Restituisce: ''

path.extname('.index')
// Restituisce: ''

path.extname('.index.md')
// Restituisce: '.md'

Viene generato un TypeError se path non è una stringa.

path.format(pathObject)

[Cronologia]

Versione	Cambiamenti
v19.0.0	Il punto verrà aggiunto se non è specificato in ext.
v0.11.15	Aggiunto in: v0.11.15

• pathObject <Object> Qualsiasi oggetto JavaScript con le seguenti proprietà:

  • dir <string>
  • root <string>
  • base <string>
  • name <string>
  • ext <string>

• Restituisce: <string>

Il metodo path.format() restituisce una stringa di percorso da un oggetto. Questo è l'opposto di path.parse().

Quando si forniscono proprietà a pathObject, ricorda che ci sono combinazioni in cui una proprietà ha la priorità su un'altra:

• pathObject.root viene ignorato se viene fornito pathObject.dir
• pathObject.ext e pathObject.name vengono ignorati se esiste pathObject.base

Ad esempio, su POSIX:

// Se vengono forniti `dir`, `root` e `base`,
// verrà restituito `${dir}${path.sep}${base}`. `root` viene ignorato.
path.format({
  root: '/ignorato',
  dir: '/home/utente/dir',
  base: 'file.txt',
})
// Restituisce: '/home/utente/dir/file.txt'

// `root` verrà utilizzato se `dir` non è specificato.
// Se viene fornito solo `root` o `dir` è uguale a `root`, allora il
// separatore della piattaforma non verrà incluso. `ext` verrà ignorato.
path.format({
  root: '/',
  base: 'file.txt',
  ext: 'ignorato',
})
// Restituisce: '/file.txt'

// `name` + `ext` verranno utilizzati se `base` non è specificato.
path.format({
  root: '/',
  name: 'file',
  ext: '.txt',
})
// Restituisce: '/file.txt'

// Il punto verrà aggiunto se non è specificato in `ext`.
path.format({
  root: '/',
  name: 'file',
  ext: 'txt',
})
// Restituisce: '/file.txt'

Su Windows:

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

path.matchesGlob(path, pattern)

Aggiunto in: v22.5.0, v20.17.0

[Stabile: 1 - Sperimentale]

Stabile: 1 Stabilità: 1 - Sperimentale

• path <stringa> Il percorso rispetto al quale confrontare il glob.
• pattern <stringa> Il glob rispetto al quale verificare il percorso.
• Restituisce: <booleano> Indica se il path corrisponde al pattern.

Il metodo path.matchesGlob() determina se path corrisponde a pattern.

Per esempio:

path.matchesGlob('/foo/bar', '/foo/*') // true
path.matchesGlob('/foo/bar*', 'foo/bird') // false

Viene generato un TypeError se path o pattern non sono stringhe.

path.isAbsolute(path)

Aggiunto in: v0.11.2

• path <stringa>
• Restituisce: <booleano>

Il metodo path.isAbsolute() determina se path è un percorso assoluto.

Se il path fornito è una stringa di lunghezza zero, verrà restituito false.

Ad esempio, su POSIX:

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

Su 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

Viene generato un TypeError se path non è una stringa.

path.join([...paths])

Aggiunto in: v0.1.16

• ...paths <stringa> Una sequenza di segmenti di percorso
• Restituisce: <stringa>

Il metodo path.join() unisce tutti i segmenti di path forniti utilizzando il separatore specifico della piattaforma come delimitatore, quindi normalizza il percorso risultante.

I segmenti di path di lunghezza zero vengono ignorati. Se la stringa del percorso unito è una stringa di lunghezza zero, verrà restituito '.', che rappresenta la directory di lavoro corrente.

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

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

Viene generato un TypeError se uno qualsiasi dei segmenti di percorso non è una stringa.

path.normalize(path)

Aggiunto in: v0.1.23

• path <stringa>
• Restituisce: <stringa>

Il metodo path.normalize() normalizza il path dato, risolvendo i segmenti '..' e '.'.

Quando vengono trovati più caratteri di separazione del segmento di percorso sequenziali (ad es. / su POSIX e \ o / su Windows), essi vengono sostituiti da una singola istanza del separatore di segmento di percorso specifico della piattaforma (/ su POSIX e \ su Windows). I separatori finali vengono conservati.

Se il path è una stringa di lunghezza zero, viene restituito '.', che rappresenta la directory di lavoro corrente.

Su POSIX, i tipi di normalizzazione applicati da questa funzione non aderiscono strettamente alle specifiche POSIX. Ad esempio, questa funzione sostituirà due barre iniziali con una singola barra come se fosse un normale percorso assoluto, mentre alcuni sistemi POSIX assegnano un significato speciale ai percorsi che iniziano esattamente con due barre. Allo stesso modo, altre sostituzioni eseguite da questa funzione, come la rimozione dei segmenti .., possono modificare il modo in cui il sistema sottostante risolve il percorso.

Ad esempio, su POSIX:

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

Su Windows:

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

Poiché Windows riconosce più separatori di percorso, entrambi i separatori verranno sostituiti da istanze del separatore preferito di Windows (\):

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

Viene generato un TypeError se path non è una stringa.

path.parse(path)

Aggiunto in: v0.11.15

• path <stringa>
• Restituisce: <Oggetto>

Il metodo path.parse() restituisce un oggetto le cui proprietà rappresentano elementi significativi del path. I separatori di directory finali vengono ignorati, vedere path.sep.

L'oggetto restituito avrà le seguenti proprietà:

• dir <stringa>
• root <stringa>
• base <stringa>
• name <stringa>
• ext <stringa>

Ad esempio, su POSIX:

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

┌─────────────────────┬────────────┐
│          dir        │    base    │
├──────┬              ├──────┬─────┤
│ root │              │ name │ ext │
"  /    home/user/dir / file  .txt "
└──────┴──────────────┴──────┴─────┘
(Tutti gli spazi nella riga "" devono essere ignorati. Sono puramente per la formattazione.)

Su Windows:

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

┌─────────────────────┬────────────┐
│          dir        │    base    │
├──────┬              ├──────┬─────┤
│ root │              │ name │ ext │
" C:\      path\dir   \ file  .txt "
└──────┴──────────────┴──────┴─────┘
(Tutti gli spazi nella riga "" devono essere ignorati. Sono puramente per la formattazione.)

Viene generato un TypeError se path non è una stringa.

path.posix

[Cronologia]

Versione	Modifiche
v15.3.0	Esposto come require('path/posix').
v0.11.15	Aggiunto in: v0.11.15

• <Object>

La proprietà path.posix fornisce l'accesso alle implementazioni specifiche POSIX dei metodi path.

L'API è accessibile tramite require('node:path').posix o require('node:path/posix').

path.relative(from, to)

[Cronologia]

Versione	Modifiche
v6.8.0	Su Windows, gli slash iniziali per i percorsi UNC sono ora inclusi nel valore di ritorno.
v0.5.0	Aggiunto in: v0.5.0

• from <stringa>
• to <stringa>
• Restituisce: <stringa>

Il metodo path.relative() restituisce il percorso relativo da from a to in base alla directory di lavoro corrente. Se from e to si risolvono nello stesso percorso (dopo aver chiamato path.resolve() su ciascuno), viene restituita una stringa di lunghezza zero.

Se viene passata una stringa di lunghezza zero come from o to, verrà utilizzata la directory di lavoro corrente invece delle stringhe di lunghezza zero.

Ad esempio, su POSIX:

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

Su Windows:

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

Viene generato un TypeError se from o to non sono una stringa.

path.resolve([...paths])

Aggiunto in: v0.3.4

• ...paths <stringa> Una sequenza di percorsi o segmenti di percorso
• Restituisce: <stringa>

Il metodo path.resolve() risolve una sequenza di percorsi o segmenti di percorso in un percorso assoluto.

La sequenza di percorsi fornita viene elaborata da destra a sinistra, con ogni path successivo anteposto finché non viene costruito un percorso assoluto. Ad esempio, data la sequenza di segmenti di percorso: /foo, /bar, baz, chiamare path.resolve('/foo', '/bar', 'baz') restituirebbe /bar/baz perché 'baz' non è un percorso assoluto ma '/bar' + '/' + 'baz' lo è.

Se, dopo aver elaborato tutti i segmenti path forniti, non è stato ancora generato un percorso assoluto, viene utilizzata la directory di lavoro corrente.

Il percorso risultante viene normalizzato e le barre finali vengono rimosse a meno che il percorso non venga risolto nella directory principale.

I segmenti path di lunghezza zero vengono ignorati.

Se non vengono passati segmenti path, path.resolve() restituirà il percorso assoluto della directory di lavoro corrente.

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

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

path.resolve('wwwroot', 'static_files/png/', '../gif/image.gif')
// Se la directory di lavoro corrente è /home/myself/node,
// questo restituisce '/home/myself/node/wwwroot/static_files/gif/image.gif'

Viene generato un TypeError se uno qualsiasi degli argomenti non è una stringa.

path.sep

Aggiunto in: v0.7.9

• <string>

Fornisce il separatore di segmento di percorso specifico della piattaforma:

• \ su Windows
• / su POSIX

Ad esempio, su POSIX:

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

Su Windows:

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

Su Windows, sia la barra (/) che la barra rovesciata () sono accettate come separatori di segmento di percorso; tuttavia, i metodi path aggiungono solo barre rovesciate ().

path.toNamespacedPath(path)

Aggiunto in: v9.0.0

• path <string>
• Restituisce: <string>

Solo sui sistemi Windows, restituisce un percorso con prefisso namespace equivalente per il path dato. Se path non è una stringa, path verrà restituito senza modifiche.

Questo metodo è significativo solo sui sistemi Windows. Sui sistemi POSIX, il metodo non è operativo e restituisce sempre path senza modifiche.

path.win32

[Cronologia]

Versione	Modifiche
v15.3.0	Esposto come require('path/win32').
v0.11.15	Aggiunto in: v0.11.15

• <Object>

La proprietà path.win32 fornisce l'accesso alle implementazioni specifiche di Windows dei metodi path.

L'API è accessibile tramite require('node:path').win32 o require('node:path/win32').