Add a filesystem descriptor library to scheduled_test.

pkg/scheduled_test/lib/descriptor.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.
+
+/// A library for declaratively describing a filesystem structure, usually for
+/// the purpose of creating or validating it as part of a scheduled test.
+///
+/// You can use [dir] and [file] to define a filesystem structure. Then, you can
+/// call [Entry.create] to schedule a task that will create that structure on
+/// the physical filesystem, or [Entry.validate] to schedule an assertion that
+/// that structure exists. For example:
+///
+///     import 'package:scheduled_test/descriptor.dart' as d;
+///     import 'package:scheduled_test/scheduled_test.dart';
+///
+///     void main() {
+///       test('Directory.rename', () {
+///         d.dir('parent', [
+///           d.file('sibling', 'sibling-contents'),
+///           d.dir('old-name', [
+///             d.file('child', 'child-contents')
+///           ])
+///         ]).create();
+///
+///         schedule(() =>
+///             new Directory('parent/old-name').rename('parent/new-name'));
+///
+///         d.dir('parent', [
+///           d.file('sibling', 'sibling-contents'),
+///           d.dir('new-name', [
+///             d.file('child', 'child-contents')
+///           ])
+///         ]).validate();
+///       })
+///     }
+///
+/// Usually you don't want your tests cluttering up your working directory with
+/// fake filesystem entities. You can set [defaultRoot] to configure where
+/// filesystem descriptors are rooted on the physical filesystem. For example,
+/// to create a temporary directory for each test:
+///
+///     import 'package:scheduled_test/descriptor.dart' as d;
+///     import 'package:scheduled_test/scheduled_test.dart';
+///
+///     void main() {
+///       setUp(() {
+///         var tempDir;
+///         schedule(() {
+///           return new Directory('').createTemp().then((dir) {

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

Seems like this is almost always the behavior you want. Can it default to this
if you don't set it?

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

I don't think it's possible to have this code run consistently enough to provide
a good user experience. There's no way for a library to register a setUp
function, so it would have to lazily run when the user first creates a
descriptor. This could be after the schedule has started running, which means
that from the user's perspective it's going to be confusing when the sandbox
path is available and when it's not. To say nothing of the confusion if the user
doesn't realize that their directories are being created in some temp directory
somewhere.

I think on the whole it's easier for the user to grok if they have control of
the sandbox creation and management. I could add a library function in a future
CL to make this easier, though.

[Bob Nystrom, 2013/02/22 22:08:57]

Could schedule() do that eagerly?

[nweiz, 2013/02/22 23:05:21]

It's a Dart constraint, not a unittest constraint. There's no way for a library
being imported to cause any code to be run, including code that would register
this sort of callback.

+///             tempDir = dir;
+///             d.defaultRoot = tempDir.path;
+///           });
+///         });
+///
+///         currentSchedule.onComplete.schedule(() {
+///           d.defaultRoot = null;
+///           return tempDir.delete(recursive: true);
+///         });
+///       });
+///
+///       // ...
+///     }
+library descriptor;
+
+import 'dart:async';
+
+import 'package:path/path.dart' as path;
+
+import 'scheduled_test.dart';
+import 'src/descriptor/directory.dart';
+import 'src/descriptor/entry.dart';
+import 'src/descriptor/file.dart';
+
+export 'src/descriptor/directory.dart';
+export 'src/descriptor/entry.dart';
+export 'src/descriptor/file.dart';
+
+/// The root path for descriptors. Top-level descriptors will be created and
+/// validated at this path. Defaults to the current working directory.

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

How about defaulting to a temp directory for each schedule?

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

See above.

+///
+/// If this is set to `null`, it will reset itself to the current working
+/// directory.
+String get defaultRoot => _defaultRoot == null ? path.current : _defaultRoot;
+set defaultRoot(String value) {
+  _defaultRoot = value;
+}
+String _defaultRoot;
+
+/// Creates a new [File] descriptor with [name] and [contents].

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

new -> new text

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

Done.

+File file(Pattern name, String contents) => new File(name, contents);

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

Maybe make contents optional and default to just the file name if omitted?
Sometimes you want to create a file but you don't really care what it contains.

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

Done, although I think it's more intuitive if it defaults to an empty file.

[Bob Nystrom, 2013/02/22 22:08:57]

That works too.

+
+/// Creates a new [File] descriptor with [name] and [contents].
+File binaryFile(Pattern name, List<int> contents) =>
+    new File.bytes(name, contents);
+
+/// Creates a new [Directory] descriptor with [name] and [contents].
+Directory dir(Pattern name, [List<Entry> contents]) =>

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

List -> Iterable

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

Done.

+    new Directory(name, contents == null ? <Entry>[] : contents);