broccoli-multi-filter

Helper base class for Broccoli plugins that map input files into output files one-to-many. This class is a drop-in replacement for broccoli-filter.

API

class MultiFilter {
  /**
   * Abstract base-class for filtering purposes.
   *
   * Enforces that it is invoked on an instance of a class which prototypically
   * inherits from Filter, and which is not itself Filter.
   */
  constructor(inputNode: BroccoliNode, options: FilterOptions): MultiFilter;

  /**
   * Abstract method `processString`: must be implemented on subclasses of
   * MultiFilter.
   * 
   * The `addOutputFile` callback accepts two arguments `(contents: string, outputRelativeFilename: string)`
   * this file must be called to generate any side-effect files and make sure they are handled properly with
   * the caching layer.
   *
   * The return value is written as the contents of the output file
   */
  abstract processString(contents: string, relativePath: string, addOutputFile: Function): string;

  /**
   * Virtual method `getDestFilePath`: determine whether the source file should
   * be processed, and optionally rename the output file when processing occurs.
   *
   * Return `null` to pass the file through without processing. Return
   * `relativePath` to process the file with `processString`. Return a
   * different path to process the file with `processString` and rename it.
   *
   * By default, if the options passed into the `MultiFilter` constructor contain a
   * property `extensions`, and `targetExtension` is supplied, the first matching
   * extension in the list is replaced with the `targetExtension` option's value.
   */
  virtual getDestFilePath(relativePath: string): string;
}

Options

• extensions: An array of file extensions to process, e.g. ['md', 'markdown'].
• targetExtension: The file extension of the corresponding output files, e.g. 'html'.
• inputEncoding: The character encoding used for reading input files to be processed (default: 'utf8'). For binary files, pass null to receive a Buffer object in processString.
• outputEncoding: The character encoding used for writing output files after processing (default: 'utf8'). For binary files, pass null and return a Buffer object from processString.
• name, annotation: Same as broccoli-plugin; see there.

All options except name and annotation can also be set on the prototype instead of being passed into the constructor.

Example Usage

var MultiFilter = require('broccoli-multi-filter');

Awk.prototype = Object.create(MultiFilter.prototype);
Awk.prototype.constructor = Awk;
function Awk(inputNode, search, replace, options) {
  options = options || {};
  MultiFilter.call(this, inputNode, {
    annotation: options.annotation
  });
  this.keepOriginal = options.keepOriginal;
  this.search = search;
  this.replace = replace;
}

Awk.prototype.extensions = ['txt'];
Awk.prototype.targetExtension = 'txt';

Awk.prototype.processString = function(content, relativePath, addOutputFile) {
  // Record the original content, but this could be a sourcemap file or any other side-effect.
  // This can also be called multiple times -- once for each non-primary file.
  if (this.keepOriginal) {
    addOutputFile(content, relativePath + ".original");
  }
  return content.replace(this.search, this.replace);
};

In Brocfile.js, use your new Awk plugin like so:

var node = new Awk('docs', 'ES6', 'ECMAScript 2015');

module.exports = node;

Converting from broccoli-filter

1. Change your require to broccoli-multi-filter.
2. Make sure tests still pass.
3. Add the addOutputFile argument to your implementation of processString.
4. Call addOutputFile to generate any additional files you need to generate.

master

1.2.3-multi.2

• Fix bug for rebuilding from cache with multiple output files.

1.2.3-multi.1

• Add support for multiple output files.

1.2.3

• Update walk-sync dependency.

1.2.2

• (Based on 1.2.0:) Fix file naming issue in caching code

1.2.1

• Temporarily revert to 1.1.0

1.2.0

• Replace with @caitp's cauliflower-filter implementation and @stefanpenner's tests

1.1.0

• Add name and annotation options

1.0.0

• Bump without change

0.2.0

• Derive from new broccoli-plugin base class. Notably, this means that subclasses always must call Filter.call(this, inputTree) in their constructors, instead of settings this.inputTree = inputTree.

0.1.14

• Improve performance by symlinking when possible

0.1.13

• Improve error message when processString isn't overridden in subclass

0.1.12

• Throw on undefined inputTree

0.1.11

• Update dependencies

0.1.10

• Do not override this.inputEncoding/this.outputEncoding if not provided

0.1.9

• Fix inputEncoding/outputEncoding defaults

0.1.8

• Add inputEncoding and outputEncoding options

0.1.7

• Update dependency to deal with symlinks correctly

0.1.6

• Copy instead of hardlinking

0.1.5

• Use new broccoli-writer base class

0.1.4

• Use broccoli-kitchen-sink-helpers instead of larger broccoli dependency

0.1.3

• Remove stray console.log O_O

0.1.2

• Augment error objects for better error reporting

0.1.1

• Update broccoli dependency

0.1.0

• Pass relativePath argument to processFile

0.0.1

• Initial release