xargs v1.1.3

xargs

Build and execute command lines from a input stream. This is the streaming version of the "xargs" unix command.

Installation

npm install --save xargs

Usage

The function exported by this module returns a duplex stream that collects all string chunks written to it into an array, which is used as the argument vector for the specified command:

var streamify = require('stream-array');
var xargs = require('xargs');

streamify(['arg1', 'arg2', 'arg3'])
  .pipe(xargs(['echo']))
  .pipe(process.stdout);  // outputs: arg1 arg2 arg3

This can be useful for running shell commands in a gulp pipeline, for example:

var gulp = require('gulp');
var map = require('map-stream');

gulp.src('test/*.js')
  .pipe(map(function(file, cb) { cb(null, file.path); }))
  .pipe(xargs('mocha'))  // if xargs receives a string, it will use shell-quote to parse it into an argument vector for child_process.spawn.
  .pipe(process.stdout);

Note that xargs() will use each received chunk as an individual argument, so it expects an object stream as input(each item will have it's toString method called). If a raw stream is required, simply pipe it through a module like split.

For example, here's a simplified version of the xargs command:

var xargs = require('xargs');
var split = require('split');

process.stdin
  .pipe(split())
  .pipe(xargs([process.argv[2]].concat(process.argv.slice(3))))
  .pipe(process.stdout);

Like the unix command, xargs will redirect the spawned process stdin to /dev/null, but if the input option is passed and set to a stream, xargs will use it as the source of arguments, and whatever is written to the stream will be piped into the process:

var fs = require('fs');
var str = require('string-to-stream');

str([1, 2, 3, 4, 5].join('\n'))
  .pipe(fs.createWriteStream('args.txt'))
  .on('unpipe', function() {
    xargs('echo', {input: fs.createReadStream('args.txt')})
      .pipe(process.stdout);  // will print "1 2 3 4 5"
  });

In this case, the xargs input should be a raw stream.

As a bonus, xargs may be used as a nicer/streaming API for child_process.spawn. If the input option is passed and set to null, xargs won't redirect stdin to /dev/null and won't try to read arguments from anywhere else. Instead, it will just forward any data piped to it into the spawned process:

// print all words(unique) found in a list of files passed as argument

xargs(['cat'].concat(process.argv.slice(2)), {input: null}).end()
  .pipe(xargs('tr -s "[[:punct:][:space:]]" "\n"', {input: null}))
  .pipe(xargs('tr "[:upper:]" "[:lower:]"', {input: null}))
  .pipe(xargs('sort', {input: null}))
  .pipe(xargs('uniq', {input: null}))
  .pipe(process.stdout)

Note that the end() method returns the stream, so it can be chained with more pipe() calls.

The xargs.spawn a wrapper that passes {input: null}, so the above may be rewritten as:

var s = xargs.spawn

s(['cat'].concat(process.argv.slice(2))).end()
  .pipe(s('tr -s "[[:punct:][:space:]]" "\n"'))
  .pipe(s('tr "[:upper:]" "[:lower:]"'))
  .pipe(s('sort'))
   // inheriting stdout is more efficient than piping to it
  .pipe(s('uniq', {stdio: ['pipe', process.stdout, process.stderr]}))

API

xargs(argv, opts)

Return a XargsStream that will spawn a process using argv and opts. The returned instance can be used as if it was the the spawned process stdout.

argv is the argument vector and can be an array or a string. If it's a string, it will be parsed with shell-quote. All chunks chunks written to the XargsStream are appended to the end of argv before the command is spawned.

opts accepts the same options as require('child_process').spawn with a extra input option, which can be used to specify an alternate stream to read arguments from. If input is null, xargs wont try to read arguments from any stream.

If no input option is passed the default value for stdio is ['ignore', 'pipe', process.stderr]. In all other cases it is ['pipe', 'pipe', process.stderr](stderr is always inherited by default). The stdio value can be overriden and the properties stdin, stdout and stderr are set on the XargsStream after the process is spawned.

Both arguments are optional, but if argv is ommited "/bin/echo" program will be executed.

xargs.spawn(argv, options)

Wrapper around xargs(argv, options) that will force the {input: null} option.

XargsStream.kill(signal)

Wrapper around ChildProcess.kill() that will queue signals if the process wasn't started when this method is called.