Create a glob package.

pkg/glob/lib/glob.dart

+// 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 glob;
+
+import 'package:path/path.dart' as p;
+
+import 'src/ast.dart';
+import 'src/parser.dart';
+import 'src/utils.dart';
+
+final _quoteRegExp = new RegExp(r'[*{[?\\}\],\-]');

[Bob Nystrom, 2014/08/27 00:42:04]

Doc comment. Also, escape "()".

[nweiz, 2014/08/27 01:36:32]

Done, although I'm ambivalent about rigorously document regular expressions that
would be inlined if not for Dart's const rules.

[Bob Nystrom, 2014/08/27 22:16:44]

Never in my life have I found myself thinking, "you know, I wish we had fewer
docs for our regular expressions." :)

[nweiz, 2014/09/02 19:48:15]

https://github.com/dart-lang/bleeding_edge/commit/098dc476b08b658bbdf71ab3fc8...

Just sayin'.

[Bob Nystrom, 2014/09/02 20:23:50]

The person reviewing that code didn't seem to mind! :)

I will note that that regex is a good bit easier to read than this one, but
fine.

+
+// TODO(nweiz): Add [list] and [listSync] methods.
+/// A glob for matching and listing files and directories.
+///
+/// A glob matches an entire string as a path. Although the glob pattern uses
+/// POSIX path syntax, it can match against POSIX, Windows, or URL paths. Which

[Bob Nystrom, 2014/08/27 00:42:04]

This is confusing. Maybe:

'Although the glob pattern syntax always uses "/" as a path separator, it can
match POSIX, Windows, or URL paths. The format it expects paths to use is based
on the `context`...'

[nweiz, 2014/08/27 01:36:32]

I think that's more confusing than my phrasing, especially since there are
differences beyond the separator for URL paths. 

[Bob Nystrom, 2014/08/27 22:16:44]

How about then: "Although the glob pattern uses POSIX syntax, it can match
POSIX, Windows, or URL paths. The format it expects paths to use is based...

The current text uses "path path path" and it isn't clear when you're talking
about a pattern, a path style, or a path argument.

[nweiz, 2014/09/02 19:48:15]

Done.

+/// path syntax it uses is based on the `context` parameter to [new Glob]; it
+/// defaults to the current system's syntax.
+///
+/// Paths are normalized before being matched against a glob, so for example the
+/// glob `foo/bar` matches the path `foo/./bar`. A relative glob can match an
+/// absolute path and vice versa; globs and paths are both interpreted as
+/// relative to `context.current`, which defaults to the current working
+/// directory.
+///
+/// When used as a [Pattern], a glob will return either one or zero matches for
+/// a string depending on whether the entire string matches the glob. These
+/// matches don't currently have capture groups, although this may change in the
+/// future.
+class Glob implements Pattern {
+  /// The pattern used to create this glob.
+  final String pattern;
+
+  /// The context in which paths matched against this glob are interpreted.
+  final p.Context context;
+
+  /// Whether this glob recursively matches and lists entities.

[Bob Nystrom, 2014/08/27 00:42:04]

It took me a while to figure out what this meant in the context of matches (for
listing it's a little more intuitive). Maybe something like, "If true, then a
path matches if it matches the glob itself or is contained in a directory that
does."

[nweiz, 2014/08/27 01:36:33]

Done.

+  final bool recursive;
+
+  /// The parsed AST of the glob.
+  final AstNode _ast;
+
+  /// Whether [context]'s current directory is absolute.
+  bool get _contextIsAbsolute {
+    if (_contextIsAbsoluteCache == null) {

[Bob Nystrom, 2014/08/27 00:42:04]

Why is this cached?

[nweiz, 2014/08/27 01:36:32]

I want to minimize the amount of work that has to be done on each [matches]
call, especially work that involves path stuff.

[Bob Nystrom, 2014/08/27 22:16:44]

That makes sense.

+      _contextIsAbsoluteCache = context.isAbsolute(context.current);
+    }
+    return _contextIsAbsoluteCache;
+  }
+  bool _contextIsAbsoluteCache;
+
+  /// Whether [pattern] could match absolute paths.
+  bool get _patternCouldBeAbsolute {

[Bob Nystrom, 2014/08/27 00:42:04]

"could be" reads confusingly to me. I don't think of globs as being relative or
absolute. How about _canMatchAbsolute?

[nweiz, 2014/08/27 01:36:33]

Done.

+    if (_patternCouldBeAbsoluteCache == null) {
+      _patternCouldBeAbsoluteCache = _ast.couldBeAbsolute;
+    }
+    return _patternCouldBeAbsoluteCache;
+  }
+  bool _patternCouldBeAbsoluteCache;
+
+  /// Whether [pattern] could match relative paths.
+  bool get _patternCouldBeRelative {
+    if (_patternCouldBeRelativeCache == null) {
+      _patternCouldBeRelativeCache = _ast.couldBeRelative;
+    }
+    return _patternCouldBeRelativeCache;
+  }
+  bool _patternCouldBeRelativeCache;
+
+  /// Returns [contents] with characters that are meaningful in globs
+  /// backslash-escaped.
+  static String quote(String contents) =>
+      contents.replaceAllMapped(_quoteRegExp, (match) => '\\${match[0]}');
+
+  /// Creates a new glob with [pattern].
+  ///
+  /// Paths matched against the glob are interpreted according to [context]. It
+  /// defaults to the system context.
+  ///
+  /// If [recursive] is true, this glob will match and list not only the files
+  /// and directories it explicitly lists, but anything beneath those as well.
+  Glob(String pattern, {p.Context context, bool recursive: false})
+      : this._(
+          pattern,
+          context == null ? p.context : context,
+          recursive);
+
+  // Internal constructor used to fake local variables for [context] and [ast].
+  Glob._(String pattern, p.Context context, bool recursive)

[Bob Nystrom, 2014/08/27 00:42:04]

It might be simpler to make this take the ast too and then make the above ctor a
factor ctor.

[nweiz, 2014/08/27 01:36:32]

I don't like making things factory constructors when I can avoid it since it
makes inheritance harder.

+      : pattern = pattern,
+        context = context,
+        recursive = recursive,
+        _ast = new Parser(pattern + (recursive ? "{,/**}" : ""), context)
+            .parse();
+
+  /// Returns whether this glob matches [path].
+  bool matches(String path) => matchAsPrefix(path) != null;
+
+  Match matchAsPrefix(String path, [int start = 0]) {
+    // Globs are like anchored RegExps in that they only match entire paths, so
+    // if the match starts anywhere after the first character it can't succeed.
+    if (start != 0) return null;
+
+    if (_patternCouldBeAbsolute &&
+        (_contextIsAbsolute || context.isAbsolute(path))) {
+      var absolutePath = context.normalize(context.absolute(path));
+      if (_ast.matches(_toPosixPath(absolutePath))) {
+        return new GlobMatch(path, this);
+      }
+    }
+
+    if (_patternCouldBeRelative) {
+      var relativePath = context.relative(path);
+      if (_ast.matches(_toPosixPath(relativePath))) {
+        return new GlobMatch(path, this);
+      }
+    }
+
+    return null;
+  }
+
+  /// Returns [path] converted to the POSIX format that globs match against.
+  String _toPosixPath(String path) {
+    if (context.style == p.Style.windows) return path.replaceAll('\\', '/');
+    if (context.style == p.Style.url) return Uri.decodeFull(path);
+    return path;
+  }
+
+  Iterable<Match> allMatches(String path, [int start = 0]) {
+    var match = matchAsPrefix(path, start);
+    return match == null ? [] : [match];
+  }
+
+  String toString() => pattern;
+}