Create a glob package.

pkg/glob/README.md

Index: pkg/glob/README.md
diff --git a/pkg/glob/README.md b/pkg/glob/README.md
new file mode 100644
index 0000000000000000000000000000000000000000..ff5445ecb7bf07217e585641fa9fb7c7b915db40
--- /dev/null
+++ b/pkg/glob/README.md
@@ -0,0 +1,122 @@
+`glob` is a file and directory globbing library that supports both checking
+whether a path matches a glob and listing all entities that match a glob.
+
+A "glob" is a pattern designed specifically to match files and directories. Most
+shells support globs natively.
+
+## Usage
+
+To construct a glob, just use `new Glob()`. As with `RegExp`s, it's a good idea
+to keep around a glob if you'll be using it more than once so that it doesn't
+have to be compiled over and over. You can check whether a path matches the glob
+using `Glob.matches()`:
+
+```dart
+import 'package:glob/glob.dart';
+
+final dartFile = new Glob("**.dart");
+
+// Print all command-line arguments that are Dart files.
+void main(List<String> arguments) {
+  for (var argument in arguments) {
+    if (dartFile.matches(argument)) print(argument);
+  }
+}
+```
+
+You can also list all files that match a glob using `Glob.list()` or
+`Glob.listSync()`:
+
+```dart
+import 'package:glob/glob.dart';
+
+final dartFile = new Glob("**.dart");
+
+// Recursively list all Dart files in the current directory.
+void main(List<String> arguments) {
+  for (var entity in dartFile.listSync()) {
+    print(entity.path);
+  }
+}
+```
+
+## Syntax
+
+The glob syntax hews closely to the widely-known Bash glob syntax, with a few
+exceptions that will be outlined below.

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

"will be" -> "are".

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

Done.

+
+In order to be as cross-platform and as close to the Bash syntax as possible,
+all globs use POSIX path syntax, including using `/` as a directory separator
+regardless of which platform they're on. This is true even for Windows roots;
+for example, a glob matching all files in the C drive would be `C:/*`.

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

This means r"C:\foo.txt" will not match the file C:\foo.txt? That's going to
make users really sad.

Maybe this should do platform detection like path does?

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

That's correct. r"C:\foo.txt" is already a well-formed, meaningful glob
(equivalent to "C:foo.txt"). There's no good way to make backslashes work how
Windows users expect, and I think this is the simplest and most-understandable
alternative.
It's important that globs be as cross-platform as possible. If we fundamentally
change their syntax across platforms, they lose their utility as a
general-purpose representation of "this group of files".

+
+### Match any characters in a filename: `*`
+
+The `*` character matches any character other than `/`. This means that it can

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

"any" -> "zero or more of any"

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

Done.

+be used to match all files in a given directory that match a pattern without
+also matching files in a subdirectory. For example, `lib/*.dart` will match
+`lib/glob.dart` but not `lib/src/utils.dart`.
+
+### Match any characters across directories: `**`
+
+`**` is like `*`, but matches `/` as well. It's useful for matching files or

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

Does this mean "a**b" will match "azzzb", "a/zzb", etc.? I know of course that
idiomatic usage of ** is surrounded by path separators, but it seems confusing
if you omit them.

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

Yes. It's useful to use ** without surrounding separators when doing things like
"**.dart", which will match all dart files recursively beneath the current
directory.

+listing directories recursively. For example, `lib/**.dart` will match both
+`lib/glob.dart` and `lib/src/utils.dart`.
+
+If `**` appears at the beginning of a glob, it will not match absolute paths.
+For example, `**.dart` won't match `/foo.dart`, although `/**.dart` will. This
+is to ensure that listing a bunch of paths and checking whether they matches a
+glob produces the same results as listing that glob.

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

I don't understand this. Can you explain why this exception is needed?

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

I explain in the text: it ensures that the list behavior is the same as the
matches behavior. In other words, there shouldn't be any paths that match a glob
that the glob wouldn't list.

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

Right, but you don't say *why* the behavior between listing and matching would
be different without this exception.

Thinking about it more, I get it now. If you list the files that match
"**.dart", you only get stuff within the cwd that match that. When listing,
there's a sort of implied "./" prefix.

Will "**.dart" match "../foo.dart"? Should it?

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

Added some more clarification.

+
+This is an extension to Bash glob syntax that's widely supported by other glob
+implementations.
+
+### Match any single character: `?`
+
+The `?` character matches a single character other than `/`. Unlike `*`, it
+won't match any more or fewer than one character. For example, `test?.dart` will
+match `test1.dart` but not `test10.dart` or `test.dart`.
+
+### Match a range of characters: `[...]`
+
+The `[...]` construction matches one of several characters. It can contain
+individual characters, such as `[abc]`, in which case it will match any of those
+characters; it can contain ranges, such as `[a-zA-Z]`, in which case it will
+match any characters that fall within the range; or it can contain a mix of
+both. It will only ever match a single character. For example,
+`test[a-zA-Z_].dart` will match `testx.dart`, `testA.dart`, and `test_.dart`,
+but not `test-.dart`.
+
+If it starts with `^` or `!`, the construction will instead match all characters
+*not* mentioned. For example, `test[^a-z].dart` will match `test1.dart` but not
+`testa.dart`.
+
+This construction never matches `/`.
+
+### Match one of several possibilities: `{...,...}`
+
+The `{...,...}` construction matches one of several options, each of which is a
+glob itself. For example, `lib/{*.dart,src/*}` matches `lib/glob.dart` and
+`lib/src/data.txt`. It can contain any number of options greater than one, and
+can even contain nested options.
+
+This is an extension to Bash glob syntax, although it is supported by other
+layers of Bash and is often used in conjunction with globs.
+
+### Escaping a character: `\`
+
+The `\` character can be used in any context to escape a character that would
+otherwise be semantically meaningful. For example, `\*.dart` matches `*.dart`
+but not `test.dart`.
+
+### Syntax errors
+
+Because they're used as part of the shell, almost all strings are valid Bash
+globs. This implementation is more picky, and performs some validation to ensure
+that globs are meaningful. For instance, unclosed `{` and `[` are disallowed.
+
+### Reserved syntax: `(...)`
+
+Parentheses are reserved in case this package adds support for Bash extended
+globbing in the future. For the time being, using them will throw an error
+unless they're escaped.