Add a filesystem descriptor library to scheduled_test.

pkg/scheduled_test/lib/src/descriptor/entry.dart

+// Copyright (c) 2013, 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 descriptor.entry;
+
+import 'dart:async';
+
+import 'utils.dart';
+
+/// The base class for various declarative descriptions of filesystem entries.
+/// All asynchronous operations on descriptors are [schedule]d unless otherwise
+/// noted.
+abstract class Entry {
+  /// The name of this entry. For most operations, this must be a [String;

[Bob Nystrom, 2013/02/22 17:58:21]

].

[nweiz, 2013/02/22 20:57:20]

Done.

+  /// however, if the entry will only be used for validation, it may be a
+  /// non-[String] [Pattern]. In this case, there must be only one entry
+  /// matching it in the physical filesystem for validation to succeed.
+  final Pattern name;
+
+  Entry(this.name);
+
+  /// Schedules the creation of the described entry within [parent]. Returns a

[Bob Nystrom, 2013/02/22 17:58:21]

[parent] -> the [parent] directory

[nweiz, 2013/02/22 20:57:20]

Done.

+  /// [Future] that is completed after the creation is done.

[Bob Nystrom, 2013/02/22 17:58:21]

is completed -> completes

[nweiz, 2013/02/22 20:57:20]

Done.

+  ///
+  /// [parent] defaults to [defaultRoot].
+  Future create([String parent]);
+
+  /// Schedules the validation of the described entry. This validates that the
+  /// physical file system under [parent] contains an entry that matches the one
+  /// described by [this]. Returns a [Future] that completes to `null` if the
+  /// entry is valid, or throws an error if it failed.
+  ///
+  /// [parent] defaults to [defaultRoot].
+  Future validate([String parent]);
+
+  /// Treats the [Descriptor] as an in-memory filesystem and returns a stream of
+  /// the contents of the entry at [path]. This operation is not [schedule]d.
+  ///
+  /// If [this] represents a directory, [path] should be a path within that
+  /// directory. If this represents a file, [path] should be `null`, and the
+  /// contents of the file will be loaded.

[Bob Nystrom, 2013/02/22 17:58:21]

This feels like two conceptually different methods combined into one. How about:

Stream<List<int>> load(String path)
A method only on Directory that finds the right child entry and returns its
contents. It does so by building a path and then calling:

Stream<List<int>> read()
A method on Entry that returns the contents of the given entry. File entry types
implement this. Directory throws.

Thoughts?

[nweiz, 2013/02/22 20:57:20]

I think it's important that there not be methods specific to a certain type of
Entry, meaning that load() should be on Entry as well. Otherwise, it makes it
harder for new entry types to be added transparently. But I do like this
factoring.

+  ///
+  /// All errors in loading the file will be passed through the returned
+  /// [Stream].
+  Stream<List<int>> load([String path]);
+
+  /// Asserts that the name of the descriptor is a [String] and returns it.
+  String get stringName {
+    if (name is String) return name;
+    throw 'Pattern $nameDescription must be a string.';
+  }
+
+  /// Returns a human-readable description of [name], for error reporting. For
+  /// string names, this will just be the name in quotes; for regular
+  /// expressions, it will use JavaScript-style `/.../` notation.
+  String get nameDescription => describePattern(name);
+
+  /// Returns a detailed tree-style description of [this].
+  String describe();
+}