A comprehensive, cross-platform path manipulation library for Dart.

The path package provides common operations for manipulating paths: joining, splitting, normalizing, etc.

We've tried very hard to make this library do the "right" thing on whatever platform you run it on, including in the browser. When you use the top-level functions, it will assume the current platform's path style and work with that. If you want to explicitly work with paths of a specific style, you can construct a p.Context for that style.

Using #

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 p;

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:

p.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 Context and give it an explicit [Style]:

var context = new p.Context(style: Style.windows);
context.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.

Stability #

The path package is used by many Dart packages, and as such it strives for a very high degree of stability. For the same reason, though, releasing a new major version would probably cause a lot of versioning pain, so some flexibility is necessary.

We try to guarantee that operations with valid inputs and correct output will not change. Operations where one or more inputs are invalid according to the semantics of the corresponding platform may produce different output over time. Operations for which path produces incorrect output will also change so that we can fix bugs.

Also, the path package's URL handling is based on the WHATWG URL spec. This is a living standard, and some parts of it haven't yet been entirely solidified by vendor support. The path package reserves the right to change its URL behavior if the underlying specification changes, although if the change is big enough to break many valid uses we may elect to treat it as a breaking change anyway.

FAQ #

Where can I use this? #

The path package runs on the Dart VM and in the browser under both dart2js and Dartium. On the browser, window.location.href is used as the current path.

Why doesn't this make paths first-class objects? #

When you have path objects, then every API that takes a path has to decide if it accepts strings, path objects, or both.

Accepting strings is the most convenient, but then it seems weird to have these path objects that aren't actually accepted by anything that needs a path. Once you've created a path, you have to always call .toString() on it before you can do anything useful with it.
Requiring objects forces users to wrap path strings in these objects, which is tedious. It also means coupling that API to whatever library defines this path class. If there are multiple "path" libraries that each define their own path types, then any library that works with paths has to pick which one it uses.
Taking both means you can't type your API. That defeats the purpose of having a path type: why have a type if your APIs can't annotate that they expect it?

Given that, we've decided this library should simply treat paths as strings.

How cross-platform is this? #

We believe this library handles most of the corner cases of Windows paths (POSIX paths are generally pretty straightforward):

It understands that both "/" and "\" are valid path separators, not just "\".
It can accurately tell if a path is absolute based on drive-letters or UNC prefix.
It understands that "/foo" is not an absolute path on Windows.
It knows that "C:\foo\one.txt" and "c:/foo\two.txt" are two files in the same directory.

What is a "path" in the browser? #

If you use this package in a browser, then it considers the "platform" to be the browser itself and uses URL strings to represent "browser paths".

1.6.2 #

Set max SDK version to <3.0.0, and adjust other dependencies.

1.6.1 #

Drop the retype implementation for compatibility with the latest SDK.

1.6.0 #

Add a PathMap class that uses path equality for its keys.
Add a PathSet class that uses path equality for its contents.

1.5.1 #

Fix a number of bugs that occurred when the current working directory was / on Linux or Mac OS.

1.5.0 #

Add a setExtension() top-level function and Context method.

1.4.2 #

Treat package: URLs as absolute.
Normalize c:\foo\. to c:\foo.

1.4.1 #

Root-relative URLs like /foo are now resolved relative to the drive letter for file URLs that begin with a Windows-style drive letter. This matches the WHATWG URL specification.

When a root-relative URLs like /foo is converted to a Windows path using fromUrl(), it is now resolved relative to the drive letter. This matches IE's behavior.

1.4.0 #

Add equals(), hash() and canonicalize() top-level functions and Context methods. These make it easier to treat paths as map keys.
Properly compare Windows paths case-insensitively.
Further improve the performance of isWithin().

1.3.9 #

Further improve the performance of isWithin() when paths contain /. sequences that aren't /../.

1.3.8 #

Improve the performance of isWithin() when the paths don't contain asymmetrical . or .. components.
Improve the performance of relative() when from is null and the path is already relative.
Improve the performance of current when the current directory hasn't changed.

1.3.7 #

Improve the performance of absolute() and normalize().

1.3.6 #

Ensure that path.toUri preserves trailing slashes for relative paths.

1.3.5 #

Added type annotations to top-level and static fields.

1.3.4 #

Fix dev_compiler warnings.

1.3.3 #

Performance improvement in Context.relative - don't call current if from is not relative.

1.3.2 #

Fix some analyzer hints.

1.3.1 #

Add a number of performance improvements.

1.3.0 #

Expose a top-level context field that provides access to a Context object for the current system.

1.2.3 #

Don't cache path Context based on cwd, as cwd involves a system-call to compute.

1.2.2 #

Remove the documentation link from the pubspec so this is linked to pub.flutter-io.cn by default.

1.2.1 #

Many members on Style that provided access to patterns and functions used internally for parsing paths have been deprecated.
Manually parse paths (rather than using RegExps to do so) for better performance.

1.2.0 #

Added path.prettyUri, which produces a human-readable representation of a URI.

1.1.0 #

path.fromUri now accepts strings as well as Uri objects.

Use this package as a library

1. Depend on it

Add this to your package's pubspec.yaml file:


dependencies:
  path: ^1.6.2

2. Install it

You can install packages from the command line:

with pub:


$ pub get

with Flutter:


$ flutter packages get

Alternatively, your editor might support pub get or flutter packages get. Check the docs for your editor to learn more.

3. Import it

Now in your Dart code, you can use:


import 'package:path/path.dart';

Version	Uploaded	Documentation	Archive
1.6.2	Jul 18, 2018
1.6.1	Jun 13, 2018
1.6.0	Jun 5, 2018
1.5.1	Nov 21, 2017
1.5.0	Nov 7, 2017
1.4.2	Jun 8, 2017
1.4.1	Dec 8, 2016
1.4.0	Oct 10, 2016
1.3.9	Dec 2, 2015
1.3.8	Dec 1, 2015

All 63 versions...

Popularity: Describes how popular the package is relative to other packages. [more]	99
Health: Code health derived from static analysis. [more]	90
Maintenance: Reflects how tidy and up-to-date the package is. [more]	85
Overall: Weighted score of the above. [more]	94

Learn more about scoring.

We analyzed this package on Feb 14, 2019, and provided a score, details, and suggestions below. Analysis was completed with status completed using:

Dart: 2.1.0
pana: 0.12.13

Platforms

Detected platforms: Flutter, web, other

No platform restriction found in primary library package:path/path.dart.

Health suggestions

Fix lib/src/context.dart. (-3.93 points)

Analysis of lib/src/context.dart reported 8 hints, including:

line 273 col 13: Use isNotEmpty instead of length

line 311 col 49: Use isNotEmpty for Iterables and Maps.

line 477 col 9: Use isNotEmpty instead of length

line 492 col 12: Use isNotEmpty instead of length

line 493 col 9: Use isNotEmpty instead of length

Fix lib/src/parsed_path.dart. (-3.45 points)

Analysis of lib/src/parsed_path.dart reported 7 hints, including:

line 90 col 7: Use isNotEmpty for Iterables and Maps.

line 93 col 12: Use isNotEmpty for Iterables and Maps.

line 97 col 9: Use isNotEmpty instead of length

line 100 col 36: Use = to separate a named parameter from its default value.

line 109 col 13: Use isNotEmpty instead of length

Fix lib/src/style/windows.dart. (-1 points)

Analysis of lib/src/style/windows.dart reported 2 hints:

line 39 col 46: Use = to separate a named parameter from its default value.

line 118 col 11: Use isEmpty instead of length

Fix additional 3 files with analysis or formatting issues. (-1.50 points)

Additional issues in the following files:

lib/src/internal_style.dart (1 hint)
lib/src/style/posix.dart (1 hint)
lib/src/style/url.dart (1 hint)

Maintenance suggestions

Maintain an example. (-10 points)

Create a short demo in the example/ directory to show how to use this package.

Common filename patterns include main.dart, example.dart, and path.dart. Packages with multiple examples should provide example/README.md.

For more information see the pub package layout conventions.

Homepage URL is insecure. (-5 points)

Update the homepage field and use a secure (https) URL.

Dependencies

Package	Constraint	Resolved	Available
Direct dependencies
Dart SDK	>=2.0.0-dev.62.0 <3.0.0
Dev dependencies
test	>=0.12.42 <2.0.0

Dart pub

path 1.6.2