merge for 1.1.0 release

CHANGELOG.md

@@ -1,5 +1,12 @@
 # Change Log
 
+## [1.1.0] - 2018-01-06
+
+* **API** Add a third parameter to Structure specifying it should decode
+  short buffers as prefixes, resolving [issue #19][issue#19].
+* **API** Interpret string argument to BitStructure `msb` parameter as
+  a `property` parameter, resolving [issue #17][issue#17].
+
 ## [1.0.0] - 2017-12-17
 
 * Minimum Node version increased to 4.5 to support dependency
@@ -115,6 +122,7 @@
 
 * Initial release.
 
+[1.1.0]: https://github.com/pabigot/buffer-layout/compare/v1.0.0...v1.1.0
 [1.0.0]: https://github.com/pabigot/buffer-layout/compare/v0.13.0...v1.0.0
 [0.13.0]: https://github.com/pabigot/buffer-layout/compare/v0.12.0...v0.13.0
 [0.12.1]: https://github.com/pabigot/buffer-layout/compare/v0.12.0...v0.12.1
@@ -169,6 +177,8 @@
 [issue#13]: https://github.com/pabigot/buffer-layout/issues/13
 [issue#14]: https://github.com/pabigot/buffer-layout/issues/14
 [issue#15]: https://github.com/pabigot/buffer-layout/issues/15
+[issue#17]: https://github.com/pabigot/buffer-layout/issues/17
+[issue#19]: https://github.com/pabigot/buffer-layout/issues/19
 [ci:travis]: https://travis-ci.org/pabigot/buffer-layout
 [ci:coveralls]: https://coveralls.io/github/pabigot/buffer-layout
 [node:issue#3992]: https://github.com/nodejs/node/issues/3992

LICENSE

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2015 Peter A. Bigot
+Copyright (c) 2015-2018 Peter A. Bigot
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

lib/Layout.js

@@ -1,6 +1,6 @@
 /* The MIT License (MIT)
  *
- * Copyright 2015-2017 Peter A. Bigot
+ * Copyright 2015-2018 Peter A. Bigot
  *
  * Permission is hereby granted, free of charge, to any person obtaining a copy
  * of this software and associated documentation files (the "Software"), to deal
@@ -1166,18 +1166,26 @@ class Sequence extends Layout {
  * @param {string} [property] - initializer for {@link
  * Layout#property|property}.
  *
+ * @param {Boolean} [decodePrefixes] - initializer for {@link
+ * Structure#decodePrefixes|property}.
+ *
  * @throws {Error} - if `fields` contains an unnamed variable-length
  * layout.
  *
  * @constructor
  * @augments {Layout}
  */
 class Structure extends Layout {
-  constructor(fields, property) {
+  constructor(fields, property, decodePrefixes) {
     if (!(Array.isArray(fields)
           && fields.reduce((acc, v) => acc && (v instanceof Layout), true))) {
       throw new TypeError('fields must be array of Layout instances');
     }
+    if (('boolean' === typeof property)
+        && (undefined === decodePrefixes)) {
+      decodePrefixes = property;
+      property = undefined;
+    }
 
     /* Verify absence of unnamed variable-length fields. */
     for (const fd of fields) {
@@ -1205,6 +1213,17 @@ class Structure extends Layout {
      *
      * @type {Layout[]} */
     this.fields = fields;
+
+    /** Control behavior of {@link Layout#decode|decode()} given short
+     * buffers.
+     *
+     * In some situations a structure many be extended with additional
+     * fields over time, with older installations providing only a
+     * prefix of the full structure.  If this property is `true`
+     * decoding will accept those buffers and leave subsequent fields
+     * undefined, as long as the buffer ends at a field boundary.
+     * Defaults to `false`. */
+    this.decodePrefixes = !!decodePrefixes;
   }
 
   /** @override */
@@ -1239,6 +1258,10 @@ class Structure extends Layout {
         dest[fd.property] = fd.decode(b, offset);
       }
       offset += fd.getSpan(b, offset);
+      if (this.decodePrefixes
+          && (b.length === offset)) {
+        break;
+      }
     }
     return dest;
   }
@@ -1920,9 +1943,12 @@ function fixBitwiseResult(v) {
  * {@link UInt|UInt} (or {@link UIntBE|UIntBE}) that is no more than 4
  * bytes wide.
  *
- * @param {bool} msb - `true` if the bit numbering starts at the most
- * significant bit of the containing word; `false` (default) if it
- * starts at the least significant bit of the containing word.
+ * @param {bool} [msb] - `true` if the bit numbering starts at the
+ * most significant bit of the containing word; `false` (default) if
+ * it starts at the least significant bit of the containing word.  If
+ * the parameter at this position is a string and `property` is
+ * `undefined` the value of this argument will instead be used as the
+ * value of `property`.
  *
  * @param {string} [property] - initializer for {@link
  * Layout#property|property}.
@@ -1936,6 +1962,11 @@ class BitStructure extends Layout {
           || (word instanceof UIntBE))) {
       throw new TypeError('word must be a UInt or UIntBE layout');
     }
+    if (('string' === typeof msb)
+        && (undefined === property)) {
+      property = msb;
+      msb = undefined;
+    }
     if (4 < word.span) {
       throw new RangeError('word cannot exceed 32 bits');
     }
@@ -2557,7 +2588,7 @@ exports.f64 = (property => new Double(property));
 exports.f64be = (property => new DoubleBE(property));
 
 /** Factory for {@link Structure|Structure} values. */
-exports.struct = ((fields, property) => new Structure(fields, property));
+exports.struct = ((fields, property, decodePrefixes) => new Structure(fields, property, decodePrefixes));
 
 /** Factory for {@link BitStructure|BitStructure} values. */
 exports.bits = ((word, msb, property) => new BitStructure(word, msb, property));

package.json

@@ -1,6 +1,6 @@
 {
   "name": "buffer-layout",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Translation between JavaScript values and Buffers",
   "keywords": [
     "Buffer",
@@ -18,7 +18,7 @@
   "author": "Peter A. Bigot <[email protected]>",
   "main": "./lib/Layout.js",
   "devDependencies": {
-    "coveralls": "~3.0.0",
+    "coveralls": "^3.0.0",
     "eslint": "~4.13.1",
     "eslint-config-google": "~0.9.1",
     "eslint-plugin-pabigot": "~1.1.0",