Skip to content

Commit

Permalink
Use dart.dev everywhere (flutter#74)
Browse files Browse the repository at this point in the history
Drop section on installing from library level doc comment - it isn't
useful enough there, and it had some outdated links.

Replace `http://dartlang.org` with `https://dart.dev` everywhere.

Add a browser example to the doc comment for `context.split` for
consistency with the comment on `p.split`.

Switch some doc comments to use single quotes and avoid `new`.
  • Loading branch information
natebosch authored Apr 7, 2020
1 parent 2d245ec commit d14d10e
Show file tree
Hide file tree
Showing 7 changed files with 198 additions and 235 deletions.
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -36,7 +36,7 @@ underlying platform that the program is running on, you can create a
[Context] and give it an explicit [Style]:

```dart
var context = new p.Context(style: Style.windows);
var context = p.Context(style: Style.windows);
context.join('directory', 'file.txt');
```

Expand Down
53 changes: 18 additions & 35 deletions lib/path.dart
Original file line number Diff line number Diff line change
Expand Up @@ -4,23 +4,6 @@

/// 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][pkg].
///
/// [pub]: http://pub.dartlang.org
/// [pkg]: http://pub.dartlang.org/packages/path
///
/// ## Usage ##
///
/// The path library was designed to be imported with a prefix, though you don't
/// have to if you don't want to:
///
Expand All @@ -30,7 +13,7 @@
/// 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");
/// 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.
Expand All @@ -39,8 +22,8 @@
/// 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");
/// var context = 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.
Expand Down Expand Up @@ -221,8 +204,8 @@ String extension(String path, [int level = 1]) =>
///
/// // URL
/// p.rootPrefix('path/to/foo'); // -> ''
/// p.rootPrefix('http://dartlang.org/path/to/foo');
/// // -> 'http://dartlang.org'
/// p.rootPrefix('https://dart.dev/path/to/foo');
/// // -> 'https://dart.dev'
String rootPrefix(String path) => context.rootPrefix(path);

/// Returns `true` if [path] is an absolute path and `false` if it is a
Expand All @@ -231,7 +214,7 @@ String rootPrefix(String path) => context.rootPrefix(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 `/`.
/// optional hostname (e.g. `https://dart.dev`, `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
Expand Down Expand Up @@ -315,8 +298,8 @@ String joinAll(Iterable<String> parts) => context.joinAll(parts);
/// // -> [r'\\server\share', 'foo', 'bar', 'baz']
///
/// // Browser
/// p.split('http://dartlang.org/path/to/foo');
/// // -> ['http://dartlang.org', 'path', 'to', 'foo']
/// p.split('https://dart.dev/path/to/foo');
/// // -> ['https://dart.dev', 'path', 'to', 'foo']
List<String> split(String path) => context.split(path);

/// Canonicalizes [path].
Expand Down Expand Up @@ -367,8 +350,8 @@ String normalize(String path) => context.normalize(path);
/// p.relative(r'D:\other', from: r'C:\home'); // -> 'D:\other'
///
/// // URL
/// p.relative('http://dartlang.org', from: 'http://pub.dartlang.org');
/// // -> 'http://dartlang.org'
/// p.relative('https://dart.dev', from: 'https://pub.dev');
/// // -> 'https://dart.dev'
String relative(String path, {String from}) =>
context.relative(path, from: from);

Expand Down Expand Up @@ -422,8 +405,8 @@ String setExtension(String path, String extension) =>
/// p.fromUri('file:///C:/path/to/foo') // -> r'C:\path\to\foo'
///
/// // URL
/// p.fromUri('http://dartlang.org/path/to/foo')
/// // -> 'http://dartlang.org/path/to/foo'
/// p.fromUri('https://dart.dev/path/to/foo')
/// // -> 'https://dart.dev/path/to/foo'
///
/// If [uri] is relative, a relative path will be returned.
///
Expand All @@ -444,8 +427,8 @@ String fromUri(uri) => context.fromUri(uri);
/// // -> Uri.parse('file:///C:/path/to/foo')
///
/// // URL
/// p.toUri('http://dartlang.org/path/to/foo')
/// // -> Uri.parse('http://dartlang.org/path/to/foo')
/// p.toUri('https://dart.dev/path/to/foo')
/// // -> Uri.parse('https://dart.dev/path/to/foo')
///
/// If [path] is relative, a relative URI will be returned.
///
Expand All @@ -463,13 +446,13 @@ Uri toUri(String path) => context.toUri(path);
///
/// // POSIX at "/root/path"
/// p.prettyUri('file:///root/path/a/b.dart'); // -> 'a/b.dart'
/// p.prettyUri('http://dartlang.org/'); // -> 'http://dartlang.org'
/// p.prettyUri('https://dart.dev/'); // -> 'https://dart.dev'
///
/// // Windows at "C:\root\path"
/// p.prettyUri('file:///C:/root/path/a/b.dart'); // -> r'a\b.dart'
/// p.prettyUri('http://dartlang.org/'); // -> 'http://dartlang.org'
/// p.prettyUri('https://dart.dev/'); // -> 'https://dart.dev'
///
/// // URL at "http://dartlang.org/root/path"
/// p.prettyUri('http://dartlang.org/root/path/a/b.dart'); // -> r'a/b.dart'
/// // URL at "https://dart.dev/root/path"
/// p.prettyUri('https://dart.dev/root/path/a/b.dart'); // -> r'a/b.dart'
/// p.prettyUri('file:///root/path'); // -> 'file:///root/path'
String prettyUri(uri) => context.prettyUri(uri);
36 changes: 20 additions & 16 deletions lib/src/context.dart
Original file line number Diff line number Diff line change
Expand Up @@ -68,7 +68,7 @@ class Context {
/// Creates a new path by appending the given path parts to [current].
/// Equivalent to [join()] with [current] as the first argument. Example:
///
/// var context = new Context(current: '/root');
/// var context = Context(current: '/root');
/// context.absolute('path', 'to', 'foo'); // -> '/root/path/to/foo'
///
/// If [current] isn't absolute, this won't return an absolute path.
Expand Down Expand Up @@ -172,8 +172,8 @@ class Context {
///
/// // URL
/// context.rootPrefix('path/to/foo'); // -> ''
/// context.rootPrefix('http://dartlang.org/path/to/foo');
/// // -> 'http://dartlang.org'
/// context.rootPrefix('https://dart.dev/path/to/foo');
/// // -> 'https://dart.dev'
String rootPrefix(String path) => path.substring(0, style.rootLength(path));

/// Returns `true` if [path] is an absolute path and `false` if it is a
Expand All @@ -182,7 +182,7 @@ class Context {
/// 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 `/`.
/// optional hostname (e.g. `https://dart.dev`, `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
Expand Down Expand Up @@ -315,6 +315,10 @@ class Context {
/// context.split(r'C:\path\to\foo'); // -> [r'C:\', 'path', 'to', 'foo']
/// context.split(r'\\server\share\path\to\foo');
/// // -> [r'\\server\share', 'foo', 'bar', 'baz']
///
/// // Browser
/// context.split('https://dart.dev/path/to/foo');
/// // -> ['https://dart.dev', 'path', 'to', 'foo']
List<String> split(String path) {
final parsed = _parse(path);
// Filter out empty parts that exist due to multiple separators in a row.
Expand Down Expand Up @@ -429,7 +433,7 @@ class Context {
/// Attempts to convert [path] to an equivalent relative path relative to
/// [current].
///
/// var context = new Context(current: '/root/path');
/// var context = Context(current: '/root/path');
/// context.relative('/root/path/a/b.dart'); // -> 'a/b.dart'
/// context.relative('/root/other.dart'); // -> '../other.dart'
///
Expand All @@ -451,7 +455,7 @@ class Context {
/// This will also return an absolute path if an absolute [path] is passed to
/// a context with a relative path for [current].
///
/// var context = new Context(r'some/relative/path');
/// var context = Context(r'some/relative/path');
/// context.relative(r'/absolute/path'); // -> '/absolute/path'
///
/// If [current] is relative, it may be impossible to determine a path from
Expand Down Expand Up @@ -986,8 +990,8 @@ class Context {
/// // -> r'C:\path\to\foo'
///
/// // URL
/// context.fromUri('http://dartlang.org/path/to/foo')
/// // -> 'http://dartlang.org/path/to/foo'
/// context.fromUri('https://dart.dev/path/to/foo')
/// // -> 'https://dart.dev/path/to/foo'
///
/// If [uri] is relative, a relative path will be returned.
///
Expand All @@ -1008,8 +1012,8 @@ class Context {
/// // -> Uri.parse('file:///C:/path/to/foo')
///
/// // URL
/// context.toUri('http://dartlang.org/path/to/foo')
/// // -> Uri.parse('http://dartlang.org/path/to/foo')
/// context.toUri('https://dart.dev/path/to/foo')
/// // -> Uri.parse('https://dart.dev/path/to/foo')
Uri toUri(String path) {
if (isRelative(path)) {
return style.relativePathToUri(path);
Expand All @@ -1029,18 +1033,18 @@ class Context {
/// or path-formatted.
///
/// // POSIX
/// var context = new Context(current: '/root/path');
/// var context = Context(current: '/root/path');
/// context.prettyUri('file:///root/path/a/b.dart'); // -> 'a/b.dart'
/// context.prettyUri('http://dartlang.org/'); // -> 'http://dartlang.org'
/// context.prettyUri('https://dart.dev/'); // -> 'https://dart.dev'
///
/// // Windows
/// var context = new Context(current: r'C:\root\path');
/// var context = Context(current: r'C:\root\path');
/// context.prettyUri('file:///C:/root/path/a/b.dart'); // -> r'a\b.dart'
/// context.prettyUri('http://dartlang.org/'); // -> 'http://dartlang.org'
/// context.prettyUri('https://dart.dev/'); // -> 'https://dart.dev'
///
/// // URL
/// var context = new Context(current: 'http://dartlang.org/root/path');
/// context.prettyUri('http://dartlang.org/root/path/a/b.dart');
/// var context = Context(current: 'https://dart.dev/root/path');
/// context.prettyUri('https://dart.dev/root/path/a/b.dart');
/// // -> r'a/b.dart'
/// context.prettyUri('file:///root/path'); // -> 'file:///root/path'
String prettyUri(uri) {
Expand Down
2 changes: 1 addition & 1 deletion lib/src/style.dart
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@ abstract class Style {
/// manipulate URL paths in the browser.
///
/// URLs use "/" (forward slash) as separators. Absolute paths either start
/// with a protocol and optional hostname (e.g. `http://dartlang.org`,
/// with a protocol and optional hostname (e.g. `https://dart.dev`,
/// `file://`) or with "/".
static final Style url = UrlStyle();

Expand Down
9 changes: 4 additions & 5 deletions test/posix_test.dart
Original file line number Diff line number Diff line change
Expand Up @@ -297,8 +297,8 @@ void main() {
test('does not walk before root on absolute paths', () {
expect(context.normalize('..'), '..');
expect(context.normalize('../'), '..');
expect(context.normalize('http://dartlang.org/..'), 'http:');
expect(context.normalize('http://dartlang.org/../../a'), 'a');
expect(context.normalize('https://dart.dev/..'), 'https:');
expect(context.normalize('https://dart.dev/../../a'), 'a');
expect(context.normalize('file:///..'), '.');
expect(context.normalize('file:///../../a'), '../a');
expect(context.normalize('/..'), '/');
Expand Down Expand Up @@ -572,7 +572,7 @@ void main() {
'/path/to/foo#bar');
expect(context.fromUri(Uri.parse('_%7B_%7D_%60_%5E_%20_%22_%25_')),
r'_{_}_`_^_ _"_%_');
expect(() => context.fromUri(Uri.parse('http://dartlang.org')),
expect(() => context.fromUri(Uri.parse('https://dart.dev')),
throwsArgumentError);
});

Expand Down Expand Up @@ -604,8 +604,7 @@ void main() {
});

test('with an http: URI', () {
expect(context.prettyUri('http://dartlang.org/a/b'),
'http://dartlang.org/a/b');
expect(context.prettyUri('https://dart.dev/a/b'), 'https://dart.dev/a/b');
});

test('with a relative URI', () {
Expand Down
Loading

0 comments on commit d14d10e

Please sign in to comment.