gulp-spawn-shim

gulp-spawn-shim

[![NPM version][npm-image]][npm-url]

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)

Arguments

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

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.