packages/barback/lib/src/transformer/transformer.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 barback.transformer.transformer;

import 'dart:async';

import '../asset/asset_id.dart';
import '../utils.dart';
import 'transform.dart';

/// A [Transformer] represents a processor that takes in one or more input
/// assets and uses them to generate one or more output assets.
///
/// Dart2js, a SASS->CSS processor, a CSS spriter, and a tool to concatenate
/// files are all examples of transformers. To define your own transformation
/// step, extend (or implement) this class.
///
/// If possible, transformers should implement [DeclaringTransformer] as well to
/// help barback optimize the package graph.
abstract class Transformer {
  /// Override this to return a space-separated list of file extensions that are
  /// allowed for the primary inputs to this transformer.
  ///
  /// Each extension must begin with a leading `.`.
  ///
  /// If you don't override [isPrimary] yourself, it defaults to allowing any
  /// asset whose extension matches one of the ones returned by this. If you
  /// don't override [isPrimary] *or* this, it allows all files.
  String get allowedExtensions => null;

  Transformer() {
    if (allowedExtensions == null) return;

    var invalidExtensions = allowedExtensions
        .split(" ")
        .where((extension) => !extension.startsWith("."))
        .map((extension) => '"$extension"');
    if (invalidExtensions.isEmpty) return;

    throw new FormatException('Each extension in $this.allowedExtensions '
        'must begin with a ".", but ${toSentence(invalidExtensions)} '
        '${pluralize("doesn't", invalidExtensions.length, plural: "don't")}.');
  }

  /// Returns `true` if [id] can be a primary input for this transformer.
  ///
  /// While a transformer can read from multiple input files, one must be the
  /// "primary" input. This asset determines whether the transformation should
  /// be run at all. If the primary input is removed, the transformer will no
  /// longer be run.
  ///
  /// A concrete example is dart2js. When you run dart2js, it will traverse
  /// all of the imports in your Dart source files and use the contents of all
  /// of those to generate the final JS. However you still run dart2js "on" a
  /// single file: the entrypoint Dart file that has your `main()` method.
  /// This entrypoint file would be the primary input.
  ///
  /// If this is not overridden, defaults to allow any asset whose extension
  /// matches one of the ones returned by [allowedExtensions]. If *that* is
  /// not overridden, allows all assets.
  ///
  /// This may return a `Future<bool>` or, if it's entirely synchronous, a
  /// `bool`.
  isPrimary(AssetId id) {
    // Allow all files if [primaryExtensions] is not overridden.
    if (allowedExtensions == null) return true;

    for (var extension in allowedExtensions.split(" ")) {
      if (id.path.endsWith(extension)) return true;
    }

    return false;
  }

  /// Run this transformer on the primary input specified by [transform].
  ///
  /// The [transform] is used by the [Transformer] for two purposes (in
  /// addition to accessing the primary input). It can call `getInput()` to
  /// request additional input assets. It also calls `addOutput()` to provide
  /// generated assets back to the system. Either can be called multiple times,
  /// in any order.
  ///
  /// In other words, a Transformer's job is to find all inputs for a
  /// transform, starting at the primary input, then generate all output assets
  /// and yield them back to the transform.
  ///
  /// If this does asynchronous work, it should return a [Future] that completes
  /// once it's finished.
  apply(Transform transform);

  String toString() => runtimeType.toString().replaceAll("Transformer", "");
}