Nodecat

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

Introductory Example

$ 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:

npm install nodecat

Recipes

Concatenate a filename starting with -

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

Concatenate to stdout via the API

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.');
    }
  }
);

Concatenate to a stream via the API

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):

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.