xargs

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


Installation

``sh
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:

`js
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:

`js
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:

`js
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:


`js
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:

`js
// 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:

`js
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.