# hprotocol

> Streaming human readable command protocol

Latest version **0.5.0** (published 2014-02-19) · 0 weekly downloads

## Install

```sh
npm install hprotocol
pnpm add hprotocol
yarn add hprotocol
bun add hprotocol
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.5.0 |
| Published | 2014-02-19 |
| First published | 2013-09-28 |
| Weekly downloads | 0 |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 2 |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 3 |
| Maintainers | mafintosh |
| Keywords | simple, easy, parser, generator, protocol, stream, streaming, human, readable, nc |

## Links

- npm: https://www.npmjs.com/package/hprotocol
- Repository: https://github.com/mafintosh/hprotocol
- Issues: https://github.com/mafintosh/hprotocol/issues
- npm.io page: https://npm.io/package/hprotocol

## Dependencies (2)

- [fifo](https://npm.io/package/fifo.md) ~0.2.0
- [pump](https://npm.io/package/pump.md) ~0.1.5

## Alternatives

- [@mapbox/jsonlint-lines-primitives](https://npm.io/package/@mapbox/jsonlint-lines-primitives.md) — 5.3M weekly downloads
- [reftools](https://npm.io/package/reftools.md) — 3.5M weekly downloads
- [@hey-api/openapi-ts](https://npm.io/package/@hey-api/openapi-ts.md) — 3.5M weekly downloads
- [@mapbox/geojson-rewind](https://npm.io/package/@mapbox/geojson-rewind.md) — 2.4M weekly downloads
- [turbo-stream](https://npm.io/package/turbo-stream.md) — 1.7M weekly downloads

## Recent versions

- 0.5.0 (latest) — 2014-02-19
- 0.4.5 — 2014-02-19
- 0.4.4 — 2013-11-14
- 0.4.3 — 2013-11-13
- 0.4.1 — 2013-10-19
- 0.4.0 — 2013-10-19
- 0.3.2 — 2013-10-01
- 0.3.1 — 2013-09-30
- 0.3.0 — 2013-09-30
- 0.2.3 — 2013-09-29
- 0.2.2 — 2013-09-29
- 0.2.1 — 2013-09-29
- 0.2.0 — 2013-09-29
- 0.1.5 — 2013-09-28
- 0.1.4 — 2013-09-28
- … 3 more at https://npm.io/package/hprotocol/versions

## README

# hprotocol

Streaming human readable command protocol

	npm install hprotocol

[![build status](https://secure.travis-ci.org/mafintosh/hprotocol.png)](http://travis-ci.org/mafintosh/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

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

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

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

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

---
_Source: https://npm.io/package/hprotocol · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._