nodecat

Nodecat
========


A Node.js implementation of cat, as specified by
POSIX/SUSv3.
No frills, no buffering, no charset conversion, just cat.

Introductory Example

``sh
$ marked README.md | nodecat header.html - footer.html > README.html
`

Features

* Supports copying stdin by default or explicitly using the name -.
* Copies all files byte-for-byte without requiring a valid encoding.
* Does not buffer any input or output (beyond any buffering done by the
libuv/Node internals and the stream.Readable.prototype.pipe
implementation).
* Handles both read and write errors gracefully.
* Recognizes the -u option specified by POSIX (which is ignored, since
nodecat is always unbuffered).
* Recognizes the -- option delimiter, allowing filenames which begin with
- after the delimiter.
* Asynchronous, non-blocking API to support concurrent use cases and
caller-provided streams.

Installation

This package can be
installed using npm, either globally or locally, by
running:

`sh
npm install nodecat
`

Recipes

$3

`sh
$ nodecat -- -unfortunate-name.html footer.html > combined.html
`

$3

`js
var nodecat = require('nodecat');
nodecat(
['header.html', '-', 'footer.html'],
{fileStreams: {'-': process.stdin}},
function(err) {
if (err) {
console.error('Error concatenating files: ', err);
} else {
console.error('Done concatenating files.');
}
}
);
`

$3

To concatenate files into a stream.Writable (which may be a
fs.WriteStream, net.Socket, tty.WriteStream, stream.PassThrough, or
any other stream.Writable subtype):

`js
var nodecat = require('nodecat');
var stream = require('stream');
var outStream = stream.PassThrough();
var errStream = stream.PassThrough();
nodecat(
['header.html', '-', 'footer.html'],
{
fileStreams: {'-': process.stdin},
outStream: outStream,
errStream: errStream
},
function(err) {
if (err) {
console.error('Error concatenating files: ', err);
} else {
console.error('Done concatenating files.');
console.error('Content:\n', String(outStream.read()));
}
}
);
`

Note: When nodecat is called on large files and stdout is redirected to a
file, it may be useful to use fs.createWriteStream('-', {fd: 1}) instead of
process.stdout, which does synchronous
writes. Be sure
to end the stream before exiting.

More examples can be found in the test
specifications.

API Docs

To use this module as a library, see the API
Documentation.

Contributing

Contributions are welcome and very much appreciated! Please add tests to
cover any changes and ensure npm test` passes.

If the desired change is large, complex, backwards-incompatible, can have
significantly differing implementations, or may not be in scope for this
project, opening an issue before writing the code can avoid frustration and
save a lot of time and effort.

Alternatives

If nodecat does not satisfy your needs, you may want to consider these
alternatives:

* cash-cat
* minicat
* posix-cat

License

This package is available under the terms of the
MIT License.