Skip to content

plug-ins.md

Latest commit

 

History

History
146 lines (98 loc) · 3.62 KB

plug-ins.md

File metadata and controls

146 lines (98 loc) · 3.62 KB

Plug-ins

Normally, unified plug-ins receive upon attaching two arguments: processor (the Processor it’s attached to) and options (an Object users can provide to configure the plug-in).

If a plug-in is attached by unified-engine, a third argument is given: fileSet.

Example

The following example processes readme.md and uses a plug-in that adds a “completer” and another file (history.md).

var engine = require('unified-engine')
var remark = require('remark')

/* Ensure the completer runs once per file-set. */
completer.pluginId = 'some-plugin-id'

engine(
  {
    processor: remark(),
    injectedPlugins: [plugin],
    files: ['readme.md']
  },
  done
)

function done(err) {
  if (err) throw err
}

function plugin(processor, options, set) {
  set.use(completer)
  set.add('history.md')
}

function completer(set) {
  console.log('done:', set.valueOf().map(path))
}

function path(file) {
  return file.path
}

Yields:

done: [ 'readme.md', 'history.md' ]
readme.md: no issues found

Note that history.md is not reported: only files given by the user are reported (or written).

Table of Contents

FileSet

Internally, a fileSet is created to process multiple files through unified processors. This set, containing all files, is exposed to plug-ins as an argument to the attacher.

fileSet.valueOf()

Access the files in a set. Returns a list of VFiles being processed.

fileSet.add(file|filePath)

Add a file to be processed. The given file is processed like other files with a few differences. The added files are:

  • Ignored when their file-path is already added
  • Never written to the file-system or streamOut
  • Not reported for

Returns self.

Parameters
  • filePath (string) — Path to virtual file
  • file (VFile) — Virtual file

fileSet.use(completer)

Attach a completer to a middleware pipeline which runs when all files are transformed (before compilation). Returns self.

function completer(fileSet[, next])

Function invoked when all files are processed.

If an error occurs (either because it’s thrown, returned, rejected, or passed to next), no further completers run and all files fail.

Parameters
Returns
  • Error
  • Promise — If a promise is returned, the function is asynchronous, and must be resolved (with nothing) or rejected (with an Error)
Properties
  • pluginId (string) — Plug-ins specified through various mechanisms are attached to a new processor for each file. If a completer is used multiple times, it is invoked multiple times as well. To ensure completers don’t get re-attached, specify a pluginId. This will ensure only one completer per pluginId is added.
function next([err])

If the signature of a completer includes next (second argument), the function may finish asynchronous, and must invoke next().

Parameters
  • err (Error, optional) — Fatal error