Dart Documentation › path

path library

A comprehensive, cross-platform path manipulation library.

Installing

Use pub to install this package. Add the following to your pubspec.yaml file.

dependencies:
  path: any

Then run pub install.

For more information, see the path package on pub.dartlang.org.

Usage

The path library was designed to be imported with a prefix, though you don't have to if you don't want to:

import 'package:path/path.dart' as path;

The most common way to use the library is through the top-level functions. These manipulate path strings based on your current working directory and the path style (POSIX, Windows, or URLs) of the host platform. For example:

path.join("directory", "file.txt");

This calls the top-level join function to join "directory" and "file.txt" using the current platform's directory separator.

If you want to work with paths for a specific platform regardless of the underlying platform that the program is running on, you can create a Builder and give it an explicit Style:

var builder = new path.Builder(style: Style.windows);
builder.join("directory", "file.txt");

This will join "directory" and "file.txt" using the Windows path separator, even when the program is run on a POSIX machine.

Properties

final String current #

Gets the path to the current working directory.

In the browser, this means the current URL. When using dart2js, this currently returns . due to technical constraints. In the future, it will return the current URL.

String get current {
 if (_io != null) {
   return (_io.declarations[#Directory] as ClassMirror)
       .getField(#current).reflectee.path;
 } else if (_html != null) {
   return _html.getField(#window).reflectee.location.href;
 } else {
   return '.';
 }
}

final posix #

A default builder for manipulating POSIX paths.

final posix = new Builder(style: Style.posix)

final String separator #

Gets the path separator for the current platform. This is \ on Windows and / on other platforms (including the browser).

String get separator => _builder.separator;

final url #

A default builder for manipulating URLs.

final url = new Builder(style: Style.url)

final windows #

A default builder for manipulating Windows paths.

final windows = new Builder(style: Style.windows)

Functions

Uri toUri(String path) #

Returns the URI that represents path.

For POSIX and Windows styles, this will return a file: URI. For the URL style, this will just convert path to a Uri.

// POSIX
path.toUri('/path/to/foo')
  // -> Uri.parse('file:///path/to/foo')

// Windows
path.toUri(r'C:\path\to\foo')
  // -> Uri.parse('file:///C:/path/to/foo')

// URL
path.toUri('http://dartlang.org/path/to/foo')
  // -> Uri.parse('http://dartlang.org/path/to/foo')

If path is relative, a relative URI will be returned.

path.toUri('path/to/foo')
  // -> Uri.parse('path/to/foo')

Uri toUri(String path) => _builder.toUri(path);

String fromUri(Uri uri) #

Returns the path represented by uri.

For POSIX and Windows styles, uri must be a file: URI. For the URL style, this will just convert uri to a string.

// POSIX
path.fromUri(Uri.parse('file:///path/to/foo'))
  // -> '/path/to/foo'

// Windows
path.fromUri(Uri.parse('file:///C:/path/to/foo'))
  // -> r'C:\path\to\foo'

// URL
path.fromUri(Uri.parse('http://dartlang.org/path/to/foo'))
  // -> 'http://dartlang.org/path/to/foo'

String fromUri(Uri uri) => _builder.fromUri(uri);

String withoutExtension(String path) #

Removes a trailing extension from the last part of path.

withoutExtension('path/to/foo.dart'); // -> 'path/to/foo'

String withoutExtension(String path) => _builder.withoutExtension(path);

String relative(String path, {String from}) #

Attempts to convert path to an equivalent relative path from the current directory.

// Given current directory is /root/path:
path.relative('/root/path/a/b.dart'); // -> 'a/b.dart'
path.relative('/root/other.dart'); // -> '../other.dart'

If the from argument is passed, path is made relative to that instead.

path.relative('/root/path/a/b.dart',
    from: '/root/path'); // -> 'a/b.dart'
path.relative('/root/other.dart',
    from: '/root/path'); // -> '../other.dart'

If path and/or from are relative paths, they are assumed to be relative to the current directory.

Since there is no relative path from one drive letter to another on Windows, or from one hostname to another for URLs, this will return an absolute path in those cases.

// Windows
path.relative(r'D:\other', from: r'C:\home'); // -> 'D:\other'

// URL
path.relative('http://dartlang.org', from: 'http://pub.dartlang.org');
  // -> 'http://dartlang.org'

String relative(String path, {String from}) =>
   _builder.relative(path, from: from);

String normalize(String path) #

Normalizes path, simplifying it by handling .., and ., and removing redundant path separators whenever possible.

path.normalize('path/./to/..//file.text'); // -> 'path/file.txt'

String normalize(String path) => _builder.normalize(path);

List<String> split(String path) #

Splits path into its components using the current platform's separator.

path.split('path/to/foo'); // -> ['path', 'to', 'foo']

The path will not be normalized before splitting.

path.split('path/../foo'); // -> ['path', '..', 'foo']

If path is absolute, the root directory will be the first element in the array. Example:

// Unix
path.split('/path/to/foo'); // -> ['/', 'path', 'to', 'foo']

// Windows
path.split(r'C:\path\to\foo'); // -> [r'C:\', 'path', 'to', 'foo']

// Browser
path.split('http://dartlang.org/path/to/foo');
  // -> ['http://dartlang.org', 'path', 'to', 'foo']

List<String> split(String path) => _builder.split(path);

String joinAll(Iterable<String> parts) #

Joins the given path parts into a single path using the current platform's separator. Example:

path.joinAll(['path', 'to', 'foo']); // -> 'path/to/foo'

If any part ends in a path separator, then a redundant separator will not be added:

path.joinAll(['path/', 'to', 'foo']); // -> 'path/to/foo

If a part is an absolute path, then anything before that will be ignored:

path.joinAll(['path', '/to', 'foo']); // -> '/to/foo'

For a fixed number of parts, join is usually terser.

String joinAll(Iterable<String> parts) => _builder.joinAll(parts);

String join(String part1, [String part2, String part3, String part4, String part5, String part6, String part7, String part8]) #

Joins the given path parts into a single path using the current platform's separator. Example:

path.join('path', 'to', 'foo'); // -> 'path/to/foo'

If any part ends in a path separator, then a redundant separator will not be added:

path.join('path/', 'to', 'foo'); // -> 'path/to/foo

If a part is an absolute path, then anything before that will be ignored:

path.join('path', '/to', 'foo'); // -> '/to/foo'

String join(String part1, [String part2, String part3, String part4,
           String part5, String part6, String part7, String part8]) =>
 _builder.join(part1, part2, part3, part4, part5, part6, part7, part8);

bool isRootRelative(String path) #

Returns true if path is a root-relative path and false if it's not.

URLs that start with / are known as "root-relative", since they're relative to the root of the current URL. Since root-relative paths are still absolute in every other sense, isAbsolute will return true for them. They can be detected using isRootRelative.

No POSIX and Windows paths are root-relative.

bool isRootRelative(String path) => _builder.isRootRelative(path);

bool isRelative(String path) #

Returns true if path is a relative path and false if it is absolute. On POSIX systems, absolute paths start with a / (forward slash). On Windows, an absolute path starts with \\, or a drive letter followed by :/ or :\.

bool isRelative(String path) => _builder.isRelative(path);

bool isAbsolute(String path) #

Returns true if path is an absolute path and false if it is a relative path.

On POSIX systems, absolute paths start with a / (forward slash). On Windows, an absolute path starts with \\, or a drive letter followed by :/ or :\. For URLs, absolute paths either start with a protocol and optional hostname (e.g. http://dartlang.org, file://) or with a /.

URLs that start with / are known as "root-relative", since they're relative to the root of the current URL. Since root-relative paths are still absolute in every other sense, isAbsolute will return true for them. They can be detected using isRootRelative.

bool isAbsolute(String path) => _builder.isAbsolute(path);

String rootPrefix(String path) #

Returns the root of path, if it's absolute, or the empty string if it's relative.

// Unix
path.rootPrefix('path/to/foo'); // -> ''
path.rootPrefix('/path/to/foo'); // -> '/'

// Windows
path.rootPrefix(r'path\to\foo'); // -> ''
path.rootPrefix(r'C:\path\to\foo'); // -> r'C:\'

// URL
path.rootPrefix('path/to/foo'); // -> ''
path.rootPrefix('http://dartlang.org/path/to/foo');
  // -> 'http://dartlang.org'

String rootPrefix(String path) => _builder.rootPrefix(path);

String extension(String path) #

Gets the file extension of path: the portion of basename from the last . to the end (including the . itself).

path.extension('path/to/foo.dart');    // -> '.dart'
path.extension('path/to/foo');         // -> ''
path.extension('path.to/foo');         // -> ''
path.extension('path/to/foo.dart.js'); // -> '.js'

If the file name starts with a ., then that is not considered the extension:

path.extension('~/.bashrc');    // -> ''
path.extension('~/.notes.txt'); // -> '.txt'

String extension(String path) => _builder.extension(path);

String dirname(String path) #

Gets the part of path before the last separator.

path.dirname('path/to/foo.dart'); // -> 'path/to'
path.dirname('path/to');          // -> 'path'

Trailing separators are ignored.

builder.dirname('path/to/'); // -> 'path'

If an absolute path contains no directories, only a root, then the root is returned.

path.dirname('/');  // -> '/' (posix)
path.dirname('c:\');  // -> 'c:\' (windows)

If a relative path has no directories, then '.' is returned.

path.dirname('foo');  // -> '.'
path.dirname('');  // -> '.'

String dirname(String path) => _builder.dirname(path);

String basenameWithoutExtension(String path) #

Gets the part of path after the last separator, and without any trailing file extension.

path.basenameWithoutExtension('path/to/foo.dart'); // -> 'foo'

Trailing separators are ignored.

builder.basenameWithoutExtension('path/to/foo.dart/'); // -> 'foo'

String basenameWithoutExtension(String path) =>
   _builder.basenameWithoutExtension(path);

String basename(String path) #

Gets the part of path after the last separator.

path.basename('path/to/foo.dart'); // -> 'foo.dart'
path.basename('path/to');          // -> 'to'

Trailing separators are ignored.

builder.basename('path/to/'); // -> 'to'

String basename(String path) => _builder.basename(path);

String absolute(String path) #

Converts path to an absolute path by resolving it relative to the current working directory. If path is already an absolute path, just returns it.

path.absolute('foo/bar.txt'); // -> /your/current/dir/foo/bar.txt

String absolute(String path) => join(current, path);

Abstract Classes

Style

Classes

Builder