Add aggregate transformer types to barback.

pkg/barback/lib/src/transformer/aggregate_transformer.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 barback.transformer.aggregate_transformer;
+
+/// An alternate interface for transformers that want to perform aggregate
+/// transformations on multiple inputs without any individual one of them being
+/// considered "primary".
+///
+/// This is useful for transformers like image spriting, where all the images in
+/// a directory need to be combined into a single image. A normal [Transformer]
+/// can't do this gracefully since when it's running on a single image, it has
+/// no way of knowing what other images exist to request as secondary inputs.
+///
+/// Aggregate transformers work by classifying assets into different groups
+/// based on their ids in [classifyPrimary]. Then [apply] is run once for each
+/// group. For example, a spriting transformer might put each image asset into a
+/// group identified by its directory name. All images in a given directory will
+/// end up in the same group, and they'll all be passed to one [apply] call.
+///
+/// If possible, aggregate transformers should implement
+/// [DeclaringAggregateTransformer] as well to help barback optimize the package
+/// graph.
+abstract class AggregateTransformer {
+  /// Classifies an asset id by returning a key identifying which group the
+  /// asset should be placed in.
+  ///
+  /// All assets for which [classifyPrimary] returns the same key are passed
+  /// together to the same [apply] call.
+  ///
+  /// Any value that can be passed across isolate boundaries can be returned. If

[Bob Nystrom, 2014/05/05 23:41:56]

Really? I thought we were just going to use an AssetId for this.

[nweiz, 2014/05/06 22:46:40]

That wasn't my plan. It also seems like a lot of users will be writing something
like "new AssetId(id.package, theThingIActuallyWantToReturn)".

There's no utility in allowing users to specify a different package in the ID,
since all assets will be coming from the same package, so it just seems like it
would make more work for them and encode a bunch of our assumptions about what
types of classification are likely to exist.

[Bob Nystrom, 2014/05/06 23:55:09]

Per our discussion, let's make this a string and document it should be
path-like.

[nweiz, 2014/05/07 01:28:50]

Done.

+  /// [classifyPrimary] needs to do asynchronous work, it can also return a
+  /// [Future] that completes to the key.
+  ///
+  /// A return value of `null` indicates that the transformer is not interested
+  /// in an asset. Assets with a key of `null` will not be passed to any [apply]
+  /// call.

[Bob Nystrom, 2014/05/05 23:41:56]

It might help clarify to say this is equivalent to isPrimary returning false in
a non-aggregate transformer.

[nweiz, 2014/05/06 22:46:40]

Done.

+  classifyPrimary(AssetId id);
+
+  /// Runs this transformer on a group of primary inputs specified by
+  /// [transform].
+  ///
+  /// If this does asynchronous work, it should return a [Future] that completes
+  /// once it's finished.
+  apply(AggregateTransform transform);
+
+  String toString() => runtimeType.toString().replaceAll("Transformer", "");
+}