typespeed 2.0.13 → 2.0.16

package/test/node_modules/@acuminous/bitsyntax/README.md

@@ -0,0 +1,308 @@
+# Byte-wise matching for Node.JS
+
+[![Node.js CI](https://github.com/acuminous/bitsyntax-js/workflows/Node.js%20CI/badge.svg)](https://github.com/acuminous/bitsyntax-js/actions?query=workflow%3A%22Node.js+CI%22)
+[![NPM version](https://img.shields.io/npm/v/bitsyntax.svg?style=flat-square)](https://www.npmjs.com/package/@acuminous/bitsyntax)
+[![NPM downloads](https://img.shields.io/npm/dm/bitsyntax.svg?style=flat-square)](https://www.npmjs.com/package/@acuminous/bitsyntax)
+
+Gives a compact syntax for parsing and constructing byte buffers,
+derived from [Erlang's bit
+syntax](http://www.erlang.org/doc/programming_examples/bit_syntax.html#id64858).
+
+```js
+var bitsyntax = require('bitsyntax');
+var pattern = bitsyntax.matcher('len:8/integer, str:len/binary');
+var bound = pattern(new Buffer([4, 0x41, 0x42, 0x43, 0x44]));
+bound.str
+// => <Buffer 41 42 43 44>
+```
+
+A typical use of this is parsing byte streams from sockets. For
+example, size-prefixed frames:
+
+```js
+var framePattern = bitsyntax.matcher('len:32/integer, frame:len/binary, rest/binary');
+socket.on('data', function process(data) {
+  var m;
+  if (m = framePattern(data)) {
+    emit('frame', m.frame);
+    process(m.rest);
+  }
+  else {
+    stashForNextData(data);
+  }
+});
+```
+
+Patterns can also be used to construct byte buffers from supplied
+values:
+
+```js
+var spdyDataFrame = require('bitsyntax')
+  .builder('streamId:32, flags:8, length:24, data/binary');
+
+spdyDataFrame({streamId:5, flags:0, length:bin.length, data:bin});
+```
+
+One or more segments of a pattern may also be supplied in multiple
+arguments, if that is more convenient; this makes it easier to split a
+long pattern over lines:
+
+```js
+var p = bitsyntax.matcher('size:8, payload:size/binary',
+                          'rest/binary');
+```
+
+## API
+
+### `matcher`
+
+Compiles a pattern as a string (or strings), to a function that will
+return either a map of bindings, or `false`, given a buffer and
+optionally an environment. The environment contains values for bound
+variables in the pattern (if there are any).
+
+```js
+var p = bitsyntax.matcher('header:headerSize/binary, rest/binary');
+var b = p(new Buffer([1, 2, 3, 4, 5]), {headerSize: 3});
+b.header
+// => <Buffer 01 02 03>
+```
+
+A matcher will return `false` if the supplied buffer does not match
+the pattern; for example, if it has too few bytes, or a literal is not
+present.
+
+```js
+var p = bitsyntax.matcher('"foo=", str/binary');
+p(new Buffer("bar=humbug"));
+// => false
+```
+
+### `parse` and `match`
+
+When composed, equivalent to `matcher`; may be useful if you want to
+examine the internal structure of patterns.
+
+`parse` takes strings as for `matcher`, and returns the internal
+representation of the pattern. `match` takes this representation, a
+buffer, and optionally an environment, and returns the bindings or
+`false` (as with `matcher`).
+
+```js
+var p = bitsyntax.parse('header:headerSize/binary',
+                        'rest/binary');
+var b = bitsyntax.match(p, new Buffer([1, 2, 3, 4, 5]),
+                          {headerSize: 3});
+b.header
+// => <Buffer 01 02 03>
+```
+
+### `builder`
+
+Takes a pattern and returns a function that will construct a byte
+buffer, given values for the variables mentioned in the pattern.
+
+```js
+var cons = bitsyntax.builder('size:8, bin/binary');
+cons({size:6, bin:new Buffer('foobar')});
+// => <Buffer 06 66 6f 6f 62 61 72>
+```
+
+Patterns supplied to builders are slightly different to patterns
+supplied for matching, as noted below.
+
+### `build`
+
+Takes a parsed pattern and a map of variable values, and returns a
+buffer. As with `match`, may be useful to debug patterns.
+
+```js
+var pattern = bitsyntax.parse('size:8, bin:size/binary');
+bitsyntax.build(pattern, {size:6, bin: new Buffer('foobar')});
+// => <Buffer 06 66 6f 6f 62 61 72>
+```
+
+### `write`
+
+Writes variable values into a buffer, at an offset, according to the
+parsed pattern given. Returns the finishing offset, i.e., the supplied
+offset plus the number of bytes written.
+
+```js
+var pattern = bitsyntax.parse('size:8, bin/binary');
+var buf = new Buffer(7);
+bitsyntax.write(buf, 0, pattern,
+                {size:6, bin: new Buffer('foobar')});
+// => 7
+buf
+// => <Buffer 06 66 6f 6f 62 61 72>
+```
+
+## Patterns
+
+Patterns are sequences of segments, each matching a value. Segments
+have the general form
+
+     value:size/type_specifier_list
+
+The size and type specifier list may be omitted, giving three extra
+variations:
+
+    value
+    value:size
+    value/type_specifier_list
+
+The type specifier list is a list of keywords separated by
+hyphens. Type specifiers are described below.
+
+Patterns are generally supplied as strings, with a comma-separated
+series of segments.
+
+### Variable or value
+
+The first part of a segment gives a variable name or a literal
+value. If a variable name is given, the value matched by the segment
+will be bound to that variable name for the rest of the pattern. If a
+literal value is given, the matched value must equal that value. If a
+variable's value is given in the environment, the matched value must
+equal the provided value.
+
+When used in a builder, the literal value will be copied into the
+buffer according to the type it is given. A variable name indicates a
+slot into which a value supplied to the builder will be copied.
+
+The special variable name `_` discards the value matched; i.e., it
+simply skips over the appropriate number of bits in the input. '_' is
+not allowed in builder patterns.
+
+### Size and unit
+
+The size of a segment is given following the value or variable,
+separated with a colon:
+
+    foo:32
+
+The unit is given in the list of specifiers as `'unit' and
+an integer from 0..256, separated by a colon:
+
+    foo:4/integer-unit:8
+
+The size is the number of units in the value; the unit is given as a
+number of bits. Unit can be of use, for example, when you want to
+match integers of a number of bytes rather than a number of bits.
+
+For integers and floats, the default unit is 1 bit; to keep things
+aligned on byte boundaries, `unit * size` must currently be a multiple
+of 8. For binaries the default unit is 8, and the unit must be a
+multiple of 8.
+
+If the size is omitted and the type is integer, the size defaults to
+8. If the size is omitted and the type is binary, the segment will
+match all remaining bytes in the input; such a segment may only be
+used at the end of a pattern, when matching.
+
+The size may also be given as an integer variable matched earlier in
+the pattern, as in the example given at the top. When constructing, a
+size may be a variable referring to the supplied environment.
+
+In builders, numbers will be rounded, masked or padded to fit the size
+and units given; for example, `'256:8'` gives the binary `Buffer<00>`
+because the lowest eight bits are 0; `'255:16` gives the binary
+`Buffer<00 ff>`.
+
+### Type name specifier
+
+One of `integer`, `binary`, `string`, `float`. If not given, the
+default is `integer`.
+
+An integer is a big- or little-endian, signed or unsigned
+integer. Integers up to 32 bits are supported. Signed integers are
+two's complement format. In JavaScript, only integers between -(2^53)
+and 2^53 can be represented, and bitwise operators are only defined on
+32-bit signed integers.
+
+A binary is simply a byte buffer; usually this will result in a slice
+of the input buffer being returned, so beware mutation.
+
+A string is a UTF8 string consisting of the given number of bytes.
+
+A float is a 32- or 64-bit IEEE754 floating-point value (this is the
+standard JavaScript uses, as do Java and Erlang).
+
+### Endianness specifier
+
+Integers may be big- or little-endian; this refers to which 'end' of
+the bytes making up the integer are most significant. In network
+protocols integers are usually big-endian, meaning the first
+(left-most) byte is the most significant, but this is not always the
+case.
+
+A specifier of `big` means the integer will be parsed (or written into
+the result) as big-endian, and `little` means the integer will be
+parsed or written as little-endian. The default is big-endian.
+
+### Signedness specifier
+
+Integer segments may include a specifier of `signed` or `unsigned`. A
+signed integer is parsed as two's complement format. The default is
+unsigned.
+
+Signedness is ignored in builders.
+
+### Literal strings
+
+A quoted string appearing in a pattern is a shorthand for the bytes in
+its UTF8 encoding. For example,
+
+    "foobar", _/binary
+
+matches any buffer that starts with the bytes `0x66, 0x6f, 0x6f, 0x62,
+0x61, 0x72`.
+
+When used in a builder, a quoted string is copied into the result as
+the bytes of its UTF8 encoding.
+
+## Examples
+
+In the following the matched bytes are given in array notation for
+convenience. Bear in mind that `match()` actually takes a buffer for
+the bytes to match against. The phrase "returns X as Y" or "binds X as
+Y" means the return value is an object with value X mapped to the key
+Y.
+
+    54
+
+Matches the single byte `54`.
+
+    54:32
+
+Matches the bytes [0,0,0,54].
+
+    54:32/little
+
+Matches the bytes [54,0,0,0].
+
+    54:4/unit:8
+
+Matches the bytes [0,0,0,54].
+
+    int:32/signed
+
+Matches a binary of four bytes, and returns a signed 32-bit integer as
+`int`.
+
+    len:16, str:len/binary
+
+Matches a binary of `2 + len` bytes, and returns an unsigned 16-bit
+integer as `len` and a buffer of length `len` as `str`.
+
+    len:16, _:len/binary, rest/binary
+
+Matches a binary of at least `2 + len` bytes, binds an unsigned 16-bit
+integer as `len`, ignores the next `len` bytes, and binds the
+remaining (possibly zero-length) binary as `rest`.
+
+    s:8, key:s/binary, value/binary
+
+When given the environment `{s:6, key: "foobar"}`, will match a binary
+starting with [6, 0x66, 0x6f, 0x6f, 0x62, 0x61, 0x72, ...].

package/test/node_modules/@acuminous/bitsyntax/index.js

@@ -0,0 +1,10 @@
+'use strict';
+
+module.exports.parse = require('./lib/parse').parse;
+module.exports.match = require('./lib/interp').match;
+module.exports.build = require('./lib/constructor').build;
+module.exports.write = require('./lib/constructor').write;
+
+module.exports.matcher = module.exports.compile =
+  require('./lib/compile').compile;
+module.exports.builder = require('./lib/compile').compile_builder;

package/test/node_modules/@acuminous/bitsyntax/lib/compile.js

@@ -0,0 +1,303 @@
+// Compile patterns to recognisers and constructors
+
+'use strict';
+
+require('buffer-more-ints');
+var $ = require('util').format;
+
+var parse = require('./parse').parse;
+var interp = require('./interp'),
+  parse_int = interp.parse_int,
+  parse_float = interp.parse_float;
+var construct = require('./constructor'),
+  write_int = construct.write_int,
+  write_float = construct.write_float;
+
+var Buffer = require('safe-buffer').Buffer;
+
+var lines = [];
+function $start() {
+  lines = [];
+}
+function $line(/* format , args */) {
+  lines.push($.apply(null, arguments));
+}
+function $result() {
+  return lines.join('\n');
+}
+
+function bits_expr(segment) {
+  if (typeof segment.size === 'string') {
+    return $('%s * %d', var_name(segment.size), segment.unit);
+  }
+  else {
+    return (segment.size * segment.unit).toString();
+  }
+}
+
+function get_number(segment) {
+  $line('bits = %s;\n', bits_expr(segment));
+  var parser = (segment.type === 'integer') ?
+    'parse_int' : 'parse_float';
+  var be = segment.bigendian, sg = segment.signed;
+  $line("byteoffset = offset / 8; offset += bits");
+  $line("if (offset > binsize) { return false; }");
+  $line("else { result = %s(bin, byteoffset, bits / 8, %s, %s); }",
+        parser, be, sg);
+}
+
+function get_binary(segment) {
+  $line("byteoffset = offset / 8;");
+  if (segment.size === true) {
+    $line("offset = binsize;");
+    $line("result = bin.slice(byteoffset);");
+  }
+  else {
+    $line("bits = %s;", bits_expr(segment));
+    $line("offset += bits;");
+    $line("if (offset > binsize) { return false; }");
+    $line("else { result = bin.slice(byteoffset,",
+          "byteoffset + bits / 8); }");
+  }
+}
+
+function get_string(segment) {
+  $line("byteoffset = offset / 8;");
+  var strlen = segment.value.length;
+  var strlenbits = strlen * 8;
+  $line("offset += %d;", strlenbits);
+  $line("if (offset > binsize) { return false; }");
+  $line("else { result = bin.toString(byteoffset,",
+        $("byteoffset + %d); }", strlen));
+}
+
+function skip_bits(segment) {
+  if (typeof segment.size === 'string') {
+    // Damn. Have to look up the size.
+    $line("var skipbits = %s * %d;",
+          var_name(segment.size), segment.unit);
+    $line("if (offset + skipbits > binsize) { return false; }");
+    $line("else { offset += skipbits; }");
+  }
+  else if (segment.size === true) {
+    $line("if (offset % 8 === 0) { offset = binsize; }");
+    $line("else { return false; }");
+  }
+  else {
+    var bits = segment.unit * segment.size;
+    $line("if (offset + %d > binsize) { return false; }", bits);
+    $line("else { offset += %d; }", bits);
+  }
+}
+
+function match_seg(segment) {
+  if (segment.name === '_') {
+    skip_bits(segment);
+  }
+  else {
+    var assign_result;
+    switch (segment.type) {
+    case 'integer':
+    case 'float':
+      get_number(segment);
+      break;
+    case 'binary':
+      get_binary(segment);
+      break;
+    case 'string':
+      get_string(segment);
+      break;
+    }
+    $line("if (result === false) return false;");
+    if (segment.name) {
+      // variable is given a value in the environment
+      $line("else if (%s !== undefined) {", var_name(segment.name));
+      // .. and it is not the same as that matched
+      $line("if (%s != result) return false;",
+            var_name(segment.name));
+      $line("}");
+      // variable is free
+      $line('else %s = result;', var_name(segment.name));
+    }
+    else {
+      var repr = JSON.stringify(segment.value);
+      $line("else if (result != %s) return false;", repr);
+    }
+  }
+}
+
+function var_name(name) {
+  return  'var_' + name;
+}
+
+function variables(segments) {
+  var names = {};
+  for (var i = 0; i < segments.length; i++) {
+    var name = segments[i].name;
+    if (name && name !== '_') {
+      names[name] = true;
+    }
+    name = segments[i].size;
+    if (typeof name === 'string') {
+      names[name] = true;
+    }
+  }
+  return Object.keys(names);
+}
+
+function compile_pattern(segments) {
+  $start();
+  $line("return function(binary, env) {");
+  $line("'use strict';");
+  $line("var bin = binary, env = env || {};");
+  $line("var offset = 0, binsize = bin.length * 8;");
+  $line("var bits, result, byteoffset;");
+  var varnames = variables(segments);
+  for (var v = 0; v < varnames.length; v++) {
+    var name = varnames[v];
+    $line("var %s = env['%s'];", var_name(name), name);
+  }
+
+  var len = segments.length;
+  for (var i = 0; i < len; i++) {
+    var segment = segments[i];
+    $line("// " + JSON.stringify(segment));
+    match_seg(segment);
+  }
+
+  $line("if (offset == binsize) {");
+  $line("return {");
+  for (var v = 0; v < varnames.length; v++) {
+    var name = varnames[v];
+    $line("%s: %s,", name, var_name(name));
+  }
+  $line('};');
+  $line('}'); // if offset == binsize
+  $line("else return false;");
+  $line("}"); // end function
+
+  var fn = new Function('parse_int', 'parse_float', $result());
+  return fn(parse_int, parse_float);
+}
+
+
+function write_seg(segment) {
+  switch (segment.type) {
+  case 'string':
+    $line("offset += buf.write(%s, offset, 'utf8');",
+          JSON.stringify(segment.value));
+    break;
+  case 'binary':
+    $line("val = bindings['%s'];", segment.name);
+    if (segment.size === true) {
+      $line('size = val.length;');
+    }
+    else if (typeof segment.size === 'string') {
+      $line("size = (bindings['%s'] * %d) / 8;",
+            segment.size, segment.unit);
+    }
+    else {
+      $line("size = %d;", (segment.size * segment.unit) / 8);
+    }
+    $line('val.copy(buf, offset, 0, size);');
+    $line('offset += size;');
+    break;
+  case 'integer':
+  case 'float':
+    write_number(segment);
+    break;
+  }
+}
+
+function write_number(segment) {
+  if (segment.name) {
+    $line("val = bindings['%s'];", segment.name);
+  }
+  else {
+    $line("val = %d", segment.value);
+  }
+  var writer = (segment.type === 'integer') ?
+    'write_int' : 'write_float';
+  if (typeof segment.size === 'string') {
+    $line("size = (bindings['%s'] * %d) / 8;",
+          segment.size, segment.unit);
+  }
+  else {
+    $line('size = %d;', (segment.size * segment.unit) / 8);
+  }
+  $line('%s(buf, val, offset, size, %s);',
+        writer, segment.bigendian);
+  $line('offset += size;');
+}
+
+function size_of(segments) {
+  var variable = [];
+  var fixed = 0;
+
+  for (var i = 0; i < segments.length; i++) {
+    var segment = segments[i];
+    if (typeof segment.size === 'string' ||
+        segment.size === true) {
+      variable.push(segment);
+    }
+    else if (segment.type === 'string') {
+      fixed += Buffer.byteLength(segment.value);
+    }
+    else {
+      fixed += (segment.size * segment.unit) / 8;
+    }
+  }
+
+  $line('var buffersize = %d;', fixed);
+
+  if (variable.length > 0) {
+    for (var j = 0; j < variable.length; j++) {
+      var segment = variable[j];
+      if (segment.size === true) {
+        $line("buffersize += bindings['%s'].length;", segment.name);
+      }
+      else {
+        $line("buffersize += (bindings['%s'] * %d) / 8;",
+              segment.size, segment.unit);
+      }
+    }
+  }
+}
+
+function emit_write(segments) {
+  $line('var val, size;');
+
+  var len = segments.length;
+  for (var i = 0; i < len; i++) {
+    var segment = segments[i];
+    $line('// %s', JSON.stringify(segment));
+    write_seg(segment);
+  }
+}
+
+function compile_ctor(segments) {
+  $start();
+  $line('return function(bindings) {');
+  $line("'use strict';");
+  size_of(segments);
+  $line('var buf = Buffer.alloc(buffersize);');
+  $line('var offset = 0;');
+  emit_write(segments);
+  $line('return buf;');
+  $line('}'); // end function
+
+  return new Function('write_int', 'write_float', 'Buffer',
+                      $result())(write_int, write_float, Buffer);
+}
+
+module.exports.compile_pattern = compile_pattern;
+module.exports.compile = function() {
+  var str = [].join.call(arguments, ',');
+  var p = parse(str);
+  return compile_pattern(p);
+};
+module.exports.compile_builder = function() {
+  var str = [].join.call(arguments, ',');
+  var p = parse(str);
+  return compile_ctor(p);
+};