hprotocol

Streaming human readable command protocol

npm install hprotocol

What does it do?

hprotocol allows you to easily generate a command protocol that its easy to parse both for programs and human beings.

As an example lets generate a protocol that echoes a value

var hprotocol = require('hprotocol');
var net = require('net');

var protocol = hprotocol()
	.use('echo value > value');

net.createServer(function(socket) {
	var client = protocol();

	// listen for the echo command
	client.on('echo', function(value, callback) {
		callback(null, 'echo: '+value);
	});

	// setup the pipe chain
	socket.pipe(client.stream).pipe(socket);

	// print the protocol specification for easier usage
	socket.write(client.specification);
}).listen(9999);

The echo value > value syntax denotes an echo command that accepts a value and returns a value. Open a new termainal and try interfacing with the server.

$ nc localhost 9999 # create a socket to the server
$ echo test         # send a echo command
$ > test            # this is the reply from the server

Similary you can interface with the server using node:

var client = protocol(); // using the same protocol as above
var socket = net.connect(9999, 'localhost');

socket.pipe(client.stream).pipe(socket);

client.echo('test', function(err, value) {
	console.log(value); // prints echo: test
});

Optionally you can use pass the stream to protocol to setup the pipe chain for you

var socket = net.connect(9999, 'localhost');
var client = protocol(socket);

client.echo(...);

Command syntax

Similary to the above example the command syntax is always

command argument1 argument2 ... > response

If the command does not have a response just do

command argument1 arguments2

If a series of arguments should the passed as an array add ... to the syntax

command test args... > response

Similary if your response is an array

command test args... > response...

Some examples of this could be

var protocol = hprotocol()
	.use('hello')
	.use('add numbers... > number')
	.use('reverse values... > values...')

var client = protocol();

client.on('hello', function() {
	// no response for this since no > in the spec
	console.log('hello world');
});

client.on('add', function(numbers, callback) {
	numbers = numbers.map(Number); // convert to numbers
	var sum = numbers.reduce(function(a, b) {
		return a+b;
	}, 0);
	callback(null, sum); // return a single value
});

client.on('reverse', function(values, callback) {
	callback(null, values.reverse());
});

// setup a pipe chain
socket.pipe(client.stream).pipe(socket);

If the above socket was listening on port 9999 we could do

echo 'add 1 2 3 4' | nc localhost 9999
# prints > 10

License

MIT