Add base Version class to start support versioning in pub.

utils/pub/version.dart

+// Copyright (c) 2012, 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.
+
+/**
+ * Handles version numbers, following the [Semantic Versioning][semver] spec.
+ *
+ * [semver]: http://semver.org/
+ */
+#library('pub_version');

[nweiz, 2012/05/15 23:12:19]

Why is this a separate library? Are you testing out the post-#source
one-library-per-file philosophy?

[Bob Nystrom, 2012/05/16 00:27:27]

Sort of. It doesn't depend on anything in pub, so it seemed nice to pull it out.

[nweiz, 2012/05/16 18:28:05]

Neither does source.dart. I think if we want to go this route, we should commit
to removing #source entirely in pub.

[Bob Nystrom, 2012/05/16 18:39:52]

I'm OK with that if you are, but I think we should incrementally move the
existing code over to that model.

[nweiz, 2012/05/16 21:02:07]

Sounds good.

+
+/** A parsed semantic version number. */
+class Version implements Comparable, VersionConstraint {
+  static final _PARSE_REGEX = const RegExp(
+      @'^'                                        // Start at beginning.
+      @'(\d+).(\d+).(\d+)'                        // Version number.
+      @'(-([0-9A-Za-z-.]+(\.[0-9A-Za-z-.]+)*))?'  // Pre-release.

[nweiz, 2012/05/15 23:12:19]

I believe the way this is currnetly written, the first "[0-9A-Za-z-.]+" will
greedily consume all the characters, leaving nothing for the second capture.
Maybe it shouldn't include "."?

Also, I think ".-" at the end of the [] is clearer than "-.", since it makes it
obvious that the hyphen isn't defining a range.

[Bob Nystrom, 2012/05/16 00:27:27]

Exactly right. Accidentally left that in from before I was separating out the
dotted sections.
Done.

+      @'(\+([0-9A-Za-z-.]+(\.[0-9A-Za-z-.]+)*))?' // Build.
+      @'$');                                      // Consume entire string.
+
+  /**
+   * Creates a new [Version] by parsing [text].
+   */
+  static Version parse(String text) {

[nweiz, 2012/05/15 23:12:19]

Factory constructor?

[Bob Nystrom, 2012/05/16 00:27:27]

Done.

+    ensure(bool predicate) {
+      if (!predicate) throw new FormatException('Could not parse "$text".');
+    }
+
+    final match = _PARSE_REGEX.firstMatch(text);
+    ensure(match != null);
+
+    try {
+      int major = Math.parseInt(match[1]);
+      int minor = Math.parseInt(match[2]);
+      int patch = Math.parseInt(match[3]);
+
+      String preRelease = match[5];
+      String build = match[8];
+
+      ensure(major >= 0);
+      ensure(minor >= 0);
+      ensure(patch >= 0);

[nweiz, 2012/05/15 23:12:19]

I don't think it's possible for these to be < 0.

[Bob Nystrom, 2012/05/16 00:27:27]

Done.

+
+      return new Version(major, minor, patch, pre: preRelease, build: build);

[nweiz, 2012/05/15 23:12:19]

I don't like using explicit keyword arguments when they're just repeating the
variable names.

[Bob Nystrom, 2012/05/16 00:27:27]

Done.

+    } catch (BadNumberFormatException ex) {
+      ensure(false);
+    }
+  }
+
+  /** The major version number: "1" in "1.2.3". */
+  final int major;
+
+  /** The minor version number: "2" in "1.2.3". */
+  final int minor;
+
+  /** The patch version number: "3" in "1.2.3". */
+  final int patch;
+
+  /** The pre-release identifier: "foo" in "1.2.3-foo". May be `null`. */
+  final String preRelease;
+
+  /** The build identifier: "foo" in "1.2.3+foo". May be `null`. */
+  final String build;
+
+  /** Creates a new [Version] object. */
+  Version(this.major, this.minor, this.patch, [String pre, this.build])
+    : preRelease = pre {

[nweiz, 2012/05/15 23:12:19]

Why not use "this." for pre/preRelease?

[Bob Nystrom, 2012/05/16 00:27:27]

I wanted the named argument to be "pre" for brevity, but not the field.

+    if (major < 0) throw new IllegalArgumentException(
+        'Major version must be non-negative.');
+    if (minor < 0) throw new IllegalArgumentException(
+        'Minor version must be non-negative.');
+    if (patch < 0) throw new IllegalArgumentException(
+        'Patch version must be non-negative.');
+  }
+
+  bool operator ==(Version other) {

[nweiz, 2012/05/15 23:12:19]

Shouldn't this take an untyped "other" parameter?

[Bob Nystrom, 2012/05/16 00:27:27]

It did at first, but then the first line was:

if (other is! Version) throw...

then I realized that's what checked mode is for. This way, it communicates at
the type signature level what this method expects.

[nweiz, 2012/05/16 18:28:05]

The first line should actually be:

  if (other is! Version) return false

For example, "1 == []" doesn't throw an error, it returns false.

[Bob Nystrom, 2012/05/16 18:39:52]

Done.

+    // TODO(rnystrom): Remove this once new equality semantics are implemented.
+    if (other == null) return false;
+    return compareTo(other) == 0;
+  }
+
+  bool operator <(Version other) => compareTo(other) < 0;
+  bool operator >(Version other) => compareTo(other) > 0;
+  bool operator <=(Version other) => compareTo(other) <= 0;
+  bool operator >=(Version other) => compareTo(other) >= 0;
+
+  /** Tests if [other] matches this version exactly. */
+  bool allows(Version other) => this == other;
+
+  int compareTo(Version other) {
+    if (major != other.major) return major.compareTo(other.major);
+    if (minor != other.minor) return minor.compareTo(other.minor);
+    if (patch != other.patch) return patch.compareTo(other.patch);
+
+    if (preRelease != other.preRelease) {
+      // Pre-releases always come before no pre-release string.
+      if (preRelease == null) return 1;
+      if (other.preRelease == null) return -1;
+
+      return _compareStrings(preRelease, other.preRelease);
+    }
+
+    if (build != other.build) {
+      // Builds always come after no build string.
+      if (build == null) return -1;
+      if (other.build == null) return 1;
+
+      return _compareStrings(build, other.build);
+    }
+
+    return 0;
+  }
+
+  String toString() {
+    var buffer = new StringBuffer();
+    buffer.add('$major.$minor.$patch');
+    if (preRelease != null) buffer.add('-$preRelease');
+    if (build != null) buffer.add('+$build');
+    return buffer.toString();
+  }
+
+  /**
+   * Compares the string part of two versions. This is used for the pre-release
+   * and build version parts. This follows Rule 12. of the Semantic Versioning
+   * spec.
+   */
+  int _compareStrings(String a, String b) {
+    var aParts = _splitParts(a);
+    var bParts = _splitParts(b);
+
+    for (int i = 0; i < Math.max(aParts.length, bParts.length); i++) {
+      var aPart = (i < aParts.length) ? aParts[i] : null;
+      var bPart = (i < bParts.length) ? bParts[i] : null;
+
+      if (aPart != bPart) {
+        // Missing parts come before present ones.
+        if (aPart == null) return -1;
+        if (bPart == null) return 1;
+
+        if (aPart is int) {
+          if (bPart is int) {
+            // Compare two numbers.
+            return aPart.compareTo(bPart);
+          } else {
+            // Numbers come before strings.
+            return -1;
+          }
+        } else {
+          if (bPart is int) {
+            // Strings come after numbers.
+            return 1;
+          } else {
+            // Compare two strings.
+            return aPart.compareTo(bPart);
+          }
+        }
+      }
+    }
+  }
+
+  /**
+   * Splits a string of dot-delimited identifiers into their component parts.
+   * Identifiers that are numeric are converted to numbers.
+   */
+  List _splitParts(String text) {
+    return text.split('.').map((part) {
+      try {
+        return Math.parseInt(part);
+      } catch (BadNumberFormatException ex) {
+        // Not a number.
+        return part;
+      }
+    });
+  }
+}
+
+/**
+ * A [VersionConstraint] is a predicate that can determine whether a given
+ * version is valid or not. For example, a ">= 2.0.0" constraint allows any
+ * version that is "2.0.0" or greater. Version objects themselves implement
+ * this to match a specific version.
+ */
+interface VersionConstraint {
+  bool allows(Version version);
+}
+
+/**
+ * Constrains versions to a fall within a given range. If there is a minimum,
+ * then this only allows versions that are at that minimum or greater. If there
+ * is a maximum, then only versions less than that are allowed. In other words,
+ * this allows `>= min, < max`.
+ */
+class VersionRange implements VersionConstraint {

[nweiz, 2012/05/15 23:12:19]

Won't users potentially want to specify "> min" or "<= max"? It seems like maybe
this should just keep flags for whether the min and max are inclusive or
exclusive.

[Bob Nystrom, 2012/05/16 00:27:27]

Yeah, I thought about that. I know we'll want these semantics, so I figured I'd
start with this at first and maybe expand later if we want that too.

+  final Version min;
+  final Version max;
+
+  VersionRange([this.min, this.max]) {
+    if (min != null && max != null && min > max) {
+      throw new IllegalArgumentException(
+          'Maximum version ("$max") must be less than minimum ("$min").');
+    }
+  }
+
+  /** Tests if [other] matches falls within this version range. */
+  bool allows(Version other) {
+    if (min != null && other < min) return false;
+    if (max != null && other >= max) return false;
+    return true;
+  }
+}
+
+/** Thrown by [Version.parse()] if the argument isn't a valid version string. */
+class FormatException implements Exception {
+  final String message;
+
+  FormatException(this.message);
+
+  String toString() => message;
+}