gulp-spawn-shim

gulp-spawn-shim

Thin wrapper (shim) of Node.js's child_process.spawn() with respect to gulp (vinyl file streams) by binding to stdin, stdout, and stderr.

Supports both streaming and buffer modes (for vinyl) specified in the gulp plugin guidelines.

Note: Gulp stream objects known as vinyl objects.

An alternative to this plugin is gulp-spawn.

Install

1. Install Node.js

2. Run: npm install gulp-spawn-shim

API

gspawn(options [, callback])

gspawn(callback)

Arguments

• options -- an object containing options for gulp-spawn-shim

• callback -- callback function with signature function(file, opts, cb)

  The callback function is invoked before child_process.spawn(...) is executed.

  The callback function is passed the file (vinyl object), and opts (a filtered object of the one passed to spawn()).

  If options is excluded, the callback function is passed an empty options objects from which you must populate. This is useful for when you want to dynamically execute different child_process.spawn() profiles on various files.

Options

child_process.spawn parameters:

• options.cmd - (String) cmd parameter of child_process.spawn. Required

• options.args - (Array) args parameter of child_process.spawn. Default: Empty array

• options.options - (Object) options parameter of child_process.spawn. Default: undefined

args templates -- these are options to replace placeholder with file information in args (e.g. cmd -o filename.pdf):

• opts.template -- object containing args template info. Default: Object.

Note: Template placeholders are done via gulp-util.template(), which itself uses lodash templates.

• opts.basename -- placeholder for file's basename. Default: "<%= basename %>".

• opts.extname -- placeholder for file's extension name. Default: "<%= extname %>".

• opts.filename -- placeholder for file's name. Default: "<%= filename %>".

Events

gulp-spawn-shim emit several events, some from the plugin itself, and other from child_process.spawn().

• failure -- Default error handler for internal plugin errors.

  Since this plugin uses async-queue-stream internally, the default error is failure instead of the standard stream error event. Therefore, this plugin does not stop processing files when a file coerce a plugin error.

  Handler signature: .on('failure', function(err) {})

• stderr -- stderr output from child_process.spawn(). stderr output is textual.

  Handler signature: .on('stderr', function(stderr) {})

• exit -- exit code from child_process.spawn(). exit code passed is a number.

  Handler signature: .on('exit', function(exit) {})

Usage

var
spawn = require('gulp-spawn-shim'),
opts = {};

opts.cmd = 'pandoc';
opts.args = ['-t', 'html'];

gulp.src('./notes/**/*.md')
    .pipe(spawn(opts))
    .pipe(gulp.desct(...));

Under the hood

1. As vinyl objects are passed to gulp-spawn-shim, contents of the file (e.g. file.contents) are piped to stdin of the child_process.spawn() instance.

2. Any stdout are piped back to file.contents.

   Note: If there is no stdout, gulp-spawn-shim will not push the file to the next stream -- and thus the file will be dropped silently.

3. Any misc. events such as stderr and exit codes are emitted appropriately.

License

MIT. See LICENSE.