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
Install Node.js
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 signaturefunction(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 differentchild_process.spawn()
profiles on various files.
Options
child_process.spawn parameters:
options.cmd
- (String) cmd parameter of child_process.spawn. Requiredoptions.args
- (Array) args parameter of child_process.spawn. Default: Empty arrayoptions.options
- (Object) options parameter of child_process.spawn. Default: undefined
Arg Templates
Available for args are placeholders made available for you to use. These placeholders...
<%= basename %>
- placeholder for file's basename (e.g.quux.html
)<%= extname %>
- placeholder for file's extension (e.g..html
)<%= filename %>
- placeholder for file's filename (e.g.quux
)
Note: Template placeholders are done via gulp-util.template(), which itself uses lodash templates.
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 streamerror
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.dest(...));
Under the hood
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.-
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.
Any misc. events such as stderr and exit codes are emitted appropriately.
License
MIT. See LICENSE.