Deprecate publicly-visible properties on Style in path.
R=rnystrom@google.com
Review URL: https://codereview.chromium.org//304843002
git-svn-id: https://dart.googlecode.com/svn/branches/bleeding_edge/dart/pkg/path@36893 260f80e4-7a28-3924-810f-c04153c831b5
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 22fc34f..9a6eccf 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,3 +1,8 @@
+# 1.2.1
+
+* Many members on `Style` that provided access to patterns and functions used
+ internally for parsing paths have been deprecated.
+
# 1.2.0
* Added `path.prettyUri`, which produces a human-readable representation of a
diff --git a/lib/src/context.dart b/lib/src/context.dart
index 88ca61f..f3826d7 100644
--- a/lib/src/context.dart
+++ b/lib/src/context.dart
@@ -4,6 +4,7 @@
library path.context;
+import 'internal_style.dart';
import 'style.dart';
import 'parsed_path.dart';
import 'path_exception.dart';
@@ -30,7 +31,12 @@
}
}
- if (style == null) style = Style.platform;
+ if (style == null) {
+ style = Style.platform;
+ } else if (style is! InternalStyle) {
+ throw new ArgumentError("Only styles defined by the path package are "
+ "allowed.");
+ }
return new Context._(style, current);
}
@@ -38,7 +44,7 @@
Context._(this.style, this.current);
/// The style of path that this context works with.
- final Style style;
+ final InternalStyle style;
/// The current directory that relative paths will be relative to.
final String current;
diff --git a/lib/src/internal_style.dart b/lib/src/internal_style.dart
new file mode 100644
index 0000000..13fb57e
--- /dev/null
+++ b/lib/src/internal_style.dart
@@ -0,0 +1,75 @@
+// Copyright (c) 2014, the Dart project authors. Please see the AUTHORS file
+// for details. All rights reserved. Use of this source code is governed by a
+// BSD-style license that can be found in the LICENSE file.
+
+library path.internal_style;
+
+import 'context.dart';
+import 'style.dart';
+
+/// The internal interface for the [Style] type.
+///
+/// Users should be able to pass around instances of [Style] like an enum, but
+/// the members that [Context] uses should be hidden from them. Those members
+/// are defined on this class instead.
+abstract class InternalStyle extends Style {
+ /// The path separator for this style. On POSIX, this is `/`. On Windows,
+ /// it's `\`.
+ String get separator;
+
+ /// The [Pattern] that can be used to match a separator for a path in this
+ /// style. Windows allows both "/" and "\" as path separators even though "\"
+ /// is the canonical one.
+ Pattern get separatorPattern;
+
+ /// The [Pattern] that matches path components that need a separator after
+ /// them.
+ ///
+ /// Windows and POSIX styles just need separators when the previous component
+ /// doesn't already end in a separator, but the URL always needs to place a
+ /// separator between the root and the first component, even if the root
+ /// already ends in a separator character. For example, to join "file://" and
+ /// "usr", an additional "/" is needed (making "file:///usr").
+ Pattern get needsSeparatorPattern;
+
+ /// The [Pattern] that can be used to match the root prefix of an absolute
+ /// path in this style.
+ Pattern get rootPattern;
+
+ /// The [Pattern] that can be used to match the root prefix of a root-relative
+ /// path in this style.
+ ///
+ /// This can be null to indicate that this style doesn't support root-relative
+ /// paths.
+ final Pattern relativeRootPattern = null;
+
+ /// Gets the root prefix of [path] if path is absolute. If [path] is relative,
+ /// returns `null`.
+ String getRoot(String path) {
+ // TODO(rnystrom): Use firstMatch() when #7080 is fixed.
+ var matches = rootPattern.allMatches(path);
+ if (matches.isNotEmpty) return matches.first[0];
+ return getRelativeRoot(path);
+ }
+
+ /// Gets the root prefix of [path] if it's root-relative.
+ ///
+ /// If [path] is relative or absolute and not root-relative, returns `null`.
+ String getRelativeRoot(String path) {
+ if (relativeRootPattern == null) return null;
+ // TODO(rnystrom): Use firstMatch() when #7080 is fixed.
+ var matches = relativeRootPattern.allMatches(path);
+ if (matches.isEmpty) return null;
+ return matches.first[0];
+ }
+
+ /// Returns the path represented by [uri] in this style.
+ String pathFromUri(Uri uri);
+
+ /// Returns the URI that represents the relative path made of [parts].
+ Uri relativePathToUri(String path) =>
+ new Uri(pathSegments: context.split(path));
+
+ /// Returns the URI that represents [path], which is assumed to be absolute.
+ Uri absolutePathToUri(String path);
+}
diff --git a/lib/src/parsed_path.dart b/lib/src/parsed_path.dart
index 5356b44..3f3c3b9 100644
--- a/lib/src/parsed_path.dart
+++ b/lib/src/parsed_path.dart
@@ -4,12 +4,12 @@
library path.parsed_path;
+import 'internal_style.dart';
import 'style.dart';
-// TODO(rnystrom): Make this public?
class ParsedPath {
- /// The [Style] that was used to parse this path.
- Style style;
+ /// The [InternalStyle] that was used to parse this path.
+ InternalStyle style;
/// The absolute root portion of the path, or `null` if the path is relative.
/// On POSIX systems, this will be `null` or "/". On Windows, it can be
@@ -40,7 +40,7 @@
/// `true` if this is an absolute path.
bool get isAbsolute => root != null;
- factory ParsedPath.parse(String path, Style style) {
+ factory ParsedPath.parse(String path, InternalStyle style) {
var before = path;
// Remove the root prefix, if any.
diff --git a/lib/src/style.dart b/lib/src/style.dart
index 9da4b43..a94ec68 100644
--- a/lib/src/style.dart
+++ b/lib/src/style.dart
@@ -51,67 +51,37 @@
/// The name of this path style. Will be "posix" or "windows".
String get name;
- /// The path separator for this style. On POSIX, this is `/`. On Windows,
- /// it's `\`.
- String get separator;
-
- /// The [Pattern] that can be used to match a separator for a path in this
- /// style. Windows allows both "/" and "\" as path separators even though "\"
- /// is the canonical one.
- Pattern get separatorPattern;
-
- /// The [Pattern] that matches path components that need a separator after
- /// them.
- ///
- /// Windows and POSIX styles just need separators when the previous component
- /// doesn't already end in a separator, but the URL always needs to place a
- /// separator between the root and the first component, even if the root
- /// already ends in a separator character. For example, to join "file://" and
- /// "usr", an additional "/" is needed (making "file:///usr").
- Pattern get needsSeparatorPattern;
-
- /// The [Pattern] that can be used to match the root prefix of an absolute
- /// path in this style.
- Pattern get rootPattern;
-
- /// The [Pattern] that can be used to match the root prefix of a root-relative
- /// path in this style.
- ///
- /// This can be null to indicate that this style doesn't support root-relative
- /// paths.
- final Pattern relativeRootPattern = null;
-
/// A [Context] that uses this style.
Context get context => new Context(style: this);
- /// Gets the root prefix of [path] if path is absolute. If [path] is relative,
- /// returns `null`.
- String getRoot(String path) {
- // TODO(rnystrom): Use firstMatch() when #7080 is fixed.
- var matches = rootPattern.allMatches(path);
- if (matches.isNotEmpty) return matches.first[0];
- return getRelativeRoot(path);
- }
+ @Deprecated("Most Style members will be removed in path 2.0.")
+ String get separator;
- /// Gets the root prefix of [path] if it's root-relative.
- ///
- /// If [path] is relative or absolute and not root-relative, returns `null`.
- String getRelativeRoot(String path) {
- if (relativeRootPattern == null) return null;
- // TODO(rnystrom): Use firstMatch() when #7080 is fixed.
- var matches = relativeRootPattern.allMatches(path);
- if (matches.isEmpty) return null;
- return matches.first[0];
- }
+ @Deprecated("Most Style members will be removed in path 2.0.")
+ Pattern get separatorPattern;
- /// Returns the path represented by [uri] in this style.
+ @Deprecated("Most Style members will be removed in path 2.0.")
+ Pattern get needsSeparatorPattern;
+
+ @Deprecated("Most Style members will be removed in path 2.0.")
+ Pattern get rootPattern;
+
+ @Deprecated("Most Style members will be removed in path 2.0.")
+ Pattern get relativeRootPattern;
+
+ @Deprecated("Most style members will be removed in path 2.0.")
+ String getRoot(String path);
+
+ @Deprecated("Most style members will be removed in path 2.0.")
+ String getRelativeRoot(String path);
+
+ @Deprecated("Most style members will be removed in path 2.0.")
String pathFromUri(Uri uri);
- /// Returns the URI that represents the relative path made of [parts].
- Uri relativePathToUri(String path) =>
- new Uri(pathSegments: context.split(path));
+ @Deprecated("Most style members will be removed in path 2.0.")
+ Uri relativePathToUri(String path);
- /// Returns the URI that represents [path], which is assumed to be absolute.
+ @Deprecated("Most style members will be removed in path 2.0.")
Uri absolutePathToUri(String path);
String toString() => name;
diff --git a/lib/src/style/posix.dart b/lib/src/style/posix.dart
index 72e7044..e0b6017 100644
--- a/lib/src/style/posix.dart
+++ b/lib/src/style/posix.dart
@@ -5,10 +5,10 @@
library path.style.posix;
import '../parsed_path.dart';
-import '../style.dart';
+import '../internal_style.dart';
/// The style for POSIX paths.
-class PosixStyle extends Style {
+class PosixStyle extends InternalStyle {
PosixStyle();
final name = 'posix';
diff --git a/lib/src/style/url.dart b/lib/src/style/url.dart
index 4a7003d..1e84917 100644
--- a/lib/src/style/url.dart
+++ b/lib/src/style/url.dart
@@ -4,10 +4,10 @@
library path.style.url;
-import '../style.dart';
+import '../internal_style.dart';
/// The style for URL paths.
-class UrlStyle extends Style {
+class UrlStyle extends InternalStyle {
UrlStyle();
final name = 'url';
diff --git a/lib/src/style/windows.dart b/lib/src/style/windows.dart
index 1750578..be9f45f 100644
--- a/lib/src/style/windows.dart
+++ b/lib/src/style/windows.dart
@@ -5,10 +5,10 @@
library path.style.windows;
import '../parsed_path.dart';
-import '../style.dart';
+import '../internal_style.dart';
/// The style for Windows paths.
-class WindowsStyle extends Style {
+class WindowsStyle extends InternalStyle {
WindowsStyle();
final name = 'windows';
diff --git a/pubspec.yaml b/pubspec.yaml
index f21ac50..86e7d95 100644
--- a/pubspec.yaml
+++ b/pubspec.yaml
@@ -1,5 +1,5 @@
name: path
-version: 1.2.0
+version: 1.2.1-dev
author: Dart Team <misc@dartlang.org>
description: >
A string-based path manipulation library. All of the path operations you know
