Path#

The Path API provides utility functions for handling and transforming file and directory paths. It is inspired by the Node.js path module, offering familiar methods for developers to work with paths effectively.

Overview#

The Path API provides methods for:

• Normalizing paths.
• Determining if a path is absolute.
• Joining path segments.
• Extracting path components like directory name, base name, and extension.
• Parsing paths into structured objects.

It simplifies cross-platform path handling by using the appropriate path delimiters and separators for the current operating system.

Static Methods#

Path.normalize(path: string): string#

Normalizes the given path by resolving .. and . segments.

• Parameters:
  • path: The input path to normalize.
• Returns:
  • A normalized path string.

Example:#

1const normalizedPath = Path.normalize('/foo/bar//baz/asdf/quux/..')
2console.log(normalizedPath) // '/foo/bar/baz/asdf'

Path.isAbsolute(path: string): boolean#

Determines whether a given path is absolute.

• Parameters:
  • path: The input path.
• Returns:
  • true if the path is absolute, otherwise false.

Example:#

1console.log(Path.isAbsolute('/foo/bar')) // true
2console.log(Path.isAbsolute('foo/bar'))  // false

Path.join(...args: string[]): string#

Joins multiple path segments into a single path and normalizes it.

• Parameters:
  • ...args: The path segments to join.
• Returns:
  • A single normalized path string.

Example:#

1const joinedPath = Path.join('/foo', 'bar', 'baz/asdf', 'quux', '..')
2console.log(joinedPath) // '/foo/bar/baz/asdf'

Path.dirname(path: string): string#

Returns the directory name of a path.

• Parameters:
  • path: The input path.
• Returns:
  • The directory name.

Example:#

1console.log(Path.dirname('/foo/bar/baz/asdf/quux')) // '/foo/bar/baz/asdf'

Path.basename(path: string, ext?: string): string#

Returns the last portion of a path, similar to the Unix basename command. Optionally, removes a file extension.

• Parameters:
  • path: The input path.
  • ext (optional): The file extension to remove.
• Returns:
  • The base name of the path.

Example:#

1console.log(Path.basename('/foo/bar/baz/asdf/quux.html')) // 'quux.html'
2console.log(Path.basename('/foo/bar/baz/asdf/quux.html', '.html')) // 'quux'

Path.extname(path: string): string#

Returns the extension of the path.

• Parameters:
  • path: The input path.
• Returns:
  • The file extension, or an empty string if none exists.

Example:#

1console.log(Path.extname('/foo/bar/baz/asdf/quux.html')) // '.html'
2console.log(Path.extname('/foo/bar/baz/asdf/quux'))     // ''

Path.parse(path: string): { root: string; dir: string; base: string; ext: string; name: string; }#

Parses a path into an object with the following properties:

• root: The root of the path.

• dir: The directory name.

• base: The file name including the extension.

• ext: The file extension.

• name: The file name without the extension.

• Parameters:

  • path: The input path.

• Returns:

  • An object with the parsed path properties.

Example:#

1const parsed = Path.parse('/foo/bar/baz/asdf/quux.html')
2console.log(parsed)
3// {
4//   root: '/',
5//   dir: '/foo/bar/baz/asdf',
6//   base: 'quux.html',
7//   ext: '.html',
8//   name: 'quux'
9// }

Common Use Cases#

Normalize a Path#

1const normalizedPath = Path.normalize('./foo/bar/../baz')
2console.log(normalizedPath) // './foo/baz'

Check If a Path is Absolute#

1console.log(Path.isAbsolute('/absolute/path')) // true
2console.log(Path.isAbsolute('relative/path'))  // false

Join Multiple Path Segments#

1const fullPath = Path.join('/home', 'user', 'documents', 'file.txt')
2console.log(fullPath) // '/home/user/documents/file.txt'

Extract File Name and Extension#

1const fileName = Path.basename('/path/to/file.txt')
2const fileExt = Path.extname('/path/to/file.txt')
3console.log(fileName) // 'file.txt'
4console.log(fileExt)  // '.txt'

Parse a Path#

1const pathDetails = Path.parse('/path/to/file.txt')
2console.log(pathDetails)
3// {
4//   root: '/',
5//   dir: '/path/to',
6//   base: 'file.txt',
7//   ext: '.txt',
8//   name: 'file'
9// }

Best Practices#

1. Use Normalization: Always normalize paths to ensure consistent formatting across platforms.
2. Avoid Hardcoding Delimiters: Use methods like join instead of concatenating strings with / or \\.

Full Example#

1import { Path } from 'scripting'
2
3function main() {
4  const filePath = '/foo/bar/baz/asdf/quux.html'
5
6  console.log("Normalized Path:", Path.normalize(filePath))
7  console.log("Is Absolute:", Path.isAbsolute(filePath))
8  console.log("Directory Name:", Path.dirname(filePath))
9  console.log("Base Name:", Path.basename(filePath))
10  console.log("Extension:", Path.extname(filePath))
11
12  const parsedPath = Path.parse(filePath)
13  console.log("Parsed Path:", parsedPath)
14
15  const joinedPath = Path.join('/foo', 'bar', 'baz')
16  console.log("Joined Path:", joinedPath)
17}
18
19main()