Merge changes resulting in v0.13.0

Author: pabigot

CHANGELOG.md

@@ -1,11 +1,17 @@
 # Change Log
 
-## [0.12.1] - 2016-0308
+## [0.13.0] - 2016-03-27
+
+* **API** Add [fieldFor][doc:BitStructure.fieldFor].
+* Fix incorrect encoding of [boolean-valued bit fields][doc:Boolean].
+* **API** Add [offsetOf][doc:Structure.offsetOf] and [layoutFor][doc:Structure.layoutFor].
+
+## [0.12.1] - 2016-03-08
 
 * Disable coverage testing for [patchIssue3992][doc:patchIssue3992] to
   avoid taking a penalty on node versions that have been updated.
 
-## [0.12.0] - 2016-0308
+## [0.12.0] - 2016-03-08
 
 * **API** Replace `setClassLayout` with [bindConstructorLayout][doc:bindConstructorLayout].
 * **API** Replace `objectPrototype` with [makeDestinationObject][doc:makeDestinationObject].
@@ -98,6 +104,7 @@
 
 * Initial release.
 
+[0.13.0]: https://github.com/pabigot/buffer-layout/compare/v0.12.1...v0.13.0
 [0.12.0]: https://github.com/pabigot/buffer-layout/compare/v0.11.0...v0.12.0
 [0.11.0]: https://github.com/pabigot/buffer-layout/compare/v0.10.0...v0.11.0
 [0.10.0]: https://github.com/pabigot/buffer-layout/compare/v0.9.0...v0.10.0
@@ -131,6 +138,8 @@
 [doc:Sequence]: http://pabigot.github.io/buffer-layout/module-Layout-Sequence.html
 [doc:Sequence.count]: http://pabigot.github.io/buffer-layout/module-Layout-Sequence.html#count
 [doc:Structure]: http://pabigot.github.io/buffer-layout/module-Layout-Structure.html
+[doc:Structure.layoutFor]: http://pabigot.github.io/buffer-layout/module-Layout-Structure.html#layoutFor
+[doc:Structure.offsetOf]: http://pabigot.github.io/buffer-layout/module-Layout-Structure.html#offsetOf
 [issue#1]: https://github.com/pabigot/buffer-layout/issues/1
 [issue#2]: https://github.com/pabigot/buffer-layout/issues/2
 [issue#3]: https://github.com/pabigot/buffer-layout/issues/3

README.md

@@ -79,6 +79,7 @@ The buffer-layout way:
     var ds = lo.struct([lo.u8('v'),
                         lo.seq(lo.u8(), 3), // alignment padding
                         lo.u32('u32')]);
+    assert.equal(ds.offsetOf('u32'), 4);
     var b = new Buffer(8);
     b.fill(0xbd);
     assert.equal(ds.encode({v: 1, u32: 0x12345678}, b), 1 + 3 + 4);
@@ -105,6 +106,7 @@ The buffer-layout way:
 
     var ds = lo.struct([lo.u8('v'),
                         lo.u32('u32')]);
+    assert.equal(ds.offsetOf('u32'), 1);
     var b = new Buffer(5);
     b.fill(0xbd);
     assert.equal(ds.encode({v: 1, u32: 0x12345678}, b), 1 + 4);

lib/Layout.js

@@ -289,6 +289,19 @@ Layout.prototype.encode = function(src, b, offset) {
   throw new Error('Layout is abstract');
 };
 
+/* Provide text that carries a name (such as for a function that will
+ * be throwing an error) annotated with the property of a given layout
+ * (such as one for which the value was unacceptable).
+ *
+ * @ignore */
+function nameWithProperty(name, lo) {
+  if (lo.property) {
+    return name + '[' + lo.property + ']';
+  }
+  return name;
+}
+exports.nameWithProperty = nameWithProperty;
+
 /**
  * Calculate the span of a specific instance of a layout.
  *
@@ -1286,6 +1299,54 @@ Structure.prototype.fromArray = function(values) {
   });
   return dest;
 };
+/**
+ * Get access to the layout of a given property.
+ *
+ * @param {String} property - the structure member of interest.
+ *
+ * @return {Layout} - the layout associated with `property`, or
+ * undefined if there is no such property.
+ */
+Structure.prototype.layoutFor = function(property) {
+  var rv;
+  if (property) {
+    this.fields.forEach(function(fd) {
+      if (fd.property === property) {
+        rv = fd;
+      }
+    });
+  }
+  return rv;
+};
+
+/**
+ * Get the offset of a structure member.
+ *
+ * @param {String} property - the structure member of interest.
+ *
+ * @return {Number} - the offset in bytes to the start of `property`
+ * within the structure, or undefined if `property` is not a field
+ * within the structure.  If the property is a member but follows a
+ * variable-length structure member a negative number will be
+ * returned.
+ */
+Structure.prototype.offsetOf = function(property) {
+  var rv;
+  var offset = 0;
+  if (property) {
+    this.fields.forEach(function(fd) {
+      if (fd.property === property) {
+        rv = offset;
+      }
+      if (0 > fd.span) {
+        offset = -1;
+      } else if (0 <= offset) {
+        offset += fd.span;
+      }
+    });
+  }
+  return rv;
+};
 
 /**
  * An object that can provide a {@link
@@ -1963,6 +2024,25 @@ BitStructure.prototype.addBoolean = function(property) {
   this.fields.push(bf);
   return bf;
 };
+/**
+ * Get access to the bit field for a given property.
+ *
+ * @param {String} property - the bit field of interest.
+ *
+ * @return {BitField} - the field associated with `property`, or
+ * undefined if there is no such property.
+ */
+BitStructure.prototype.fieldFor = function(property) {
+  var rv;
+  if (property) {
+    this.fields.forEach(function(fd) {
+      if (fd.property === property) {
+        rv = fd;
+      }
+    });
+  }
+  return rv;
+};
 
 /**
  * Represent a sequence of bits within a {@link
@@ -2057,7 +2137,8 @@ BitField.prototype.decode = function() {
 BitField.prototype.encode = function(value) {
   if ((!Number.isInteger(value))
       || (value != fixBitwiseResult(value & this.valueMask))) {
-    throw new Error('value must be integer not exceeding ' + this.valueMask);
+    throw new TypeError(nameWithProperty('BitField.encode', this)
+                        + ' value must be integer not exceeding ' + this.valueMask);
   }
   var word = this.container._packedGetValue();
   var wordValue = fixBitwiseResult(value << this.start);
@@ -2084,16 +2165,22 @@ BitField.prototype.encode = function(value) {
  */
 function Boolean(container, property) {
   BitField.call(this, container, 1, property);
-};
+}
 util.inherits(Boolean, BitField);
 /** Override {@link BitField#decode|decode} for {@link Boolean|Boolean}.
  *
  * @returns {boolean} */
 Boolean.prototype.decode = function(b, offset) {
   return !!BitField.prototype.decode.call(this, b, offset);
 };
-/* There is no override for Boolean.encode since the `src` parameter
- * is interpreted as truthy. */
+/** @override */
+Boolean.prototype.encode = function(value) {
+  if ('boolean' === typeof value) {
+    // BitField requires integer values
+    value = +value;
+  }
+  return BitField.prototype.encode.call(this, value);
+};
 
 /**
  * Contain a fixed-length block of arbitrary data, represented as a
@@ -2162,7 +2249,8 @@ Blob.prototype.encode = function(src, b, offset) {
   }
   if (!((src instanceof Buffer)
          && (span === src.length))) {
-    throw new Error('Blob.encode requires (length ' + span + ') Buffer as src');
+    throw new TypeError(nameWithProperty('Blob.encode', this)
+                        + ' requires (length ' + span + ') Buffer as src');
   }
   if ((offset + span) > b.length) {
     throw new RangeError('encoding overruns Buffer');

package.json

@@ -1,6 +1,6 @@
 {
   "name": "buffer-layout",
-  "version": "0.12.1",
+  "version": "0.13.0",
   "description": "Translation between JavaScript values and Buffers",
   "keywords": [
     "Buffer",

test/LayoutTest.js

@@ -10,6 +10,20 @@ function reversedBuffer(b) {
   return new Buffer(ba.reverse());
 }
 
+/* Helper to check that a thrown exception is both the expected type
+ * and carries the expected message. */
+function checkError(exc, expect, regex) {
+  if (expect && !(exc instanceof expect)) {
+    console.log('checkError failed: exc ' + typeof exc + ' expect ' + expect);
+    return false;
+  }
+  if (regex && !exc.message.match(regex)) {
+    console.log('checkError failed: msg "' + exc.message + '" nomatch ' + regex);
+    return false;
+  }
+  return true;
+}
+
 suite('Layout', function() {
   test('#reversedBuffer', function() {
     var b = Buffer('0102030405', 'hex');
@@ -809,6 +823,37 @@ suite('Layout', function() {
       assert.equal(src.property, 'p');
       assert.strictEqual(dst.property, undefined);
     });
+    test('layoutFor', function() {
+      var u8 = lo.u8('u8');
+      var s32 = lo.s32('s32');
+      var cstr = lo.cstr('cstr');
+      var u16 = lo.u16('u16');
+      var d = lo.struct([u8, s32, cstr, u16], 's');
+      assert.strictEqual(d.layoutFor(), undefined);
+      assert.strictEqual(d.layoutFor('u8'), u8);
+      assert.strictEqual(d.layoutFor('cstr'), cstr);
+      assert.strictEqual(d.layoutFor('other'), undefined);
+    });
+    test('nameWithProperty', function() {
+      var s32 = lo.s32('s32');
+      var u16 = lo.u16('u16');
+      var d = lo.struct([s32, lo.u16(), u16], 's');
+      assert.equal(lo.nameWithProperty('struct', d), 'struct[s]');
+      assert.equal(lo.nameWithProperty('pfx', d.fields[1]), 'pfx');
+    });
+    test('offsetOf', function() {
+      var u8 = lo.u8('u8');
+      var s32 = lo.s32('s32');
+      var cstr = lo.cstr('cstr');
+      var u16 = lo.u16('u16');
+      var d = lo.struct([u8, s32, cstr, u16], 's');
+      assert.strictEqual(d.offsetOf(), undefined);
+      assert.strictEqual(d.offsetOf('u8'), 0);
+      assert.strictEqual(d.offsetOf('s32'), 1);
+      assert.strictEqual(d.offsetOf('cstr'), 5);
+      assert(0 > d.offsetOf('u16'));
+      assert.strictEqual(d.offsetOf('other'), undefined);
+    });
   });
   suite('VariantLayout', function() {
     test('invalid ctor', function() {
@@ -1485,6 +1530,17 @@ suite('Layout', function() {
       assert.deepEqual(bs.decode(b), {a1: 0, b4: 9, c11: 0x4F1, d16: 0x8a51});
       assert.equal(Buffer('518af14c', 'hex').compare(b), 0);
     });
+    test('fieldFor', function() {
+      var d = new lo.BitStructure(lo.u32(), true);
+      var b = d.addBoolean('b');
+      var b4 = d.addField(4, 'b4');
+      var c11 = d.addField(11, 'c11');
+      var d16 = d.addField(16, 'd16');
+      assert.strictEqual(d.fieldFor(), undefined);
+      assert.strictEqual(d.fieldFor('b'), b);
+      assert.strictEqual(d.fieldFor('c11'), c11);
+      assert.strictEqual(d.fieldFor('other'), undefined);
+    });
     test('gap coding', function() {
       var lsb = new lo.BitStructure(lo.u24());
       var msb = new lo.BitStructure(lo.u24(), true);
@@ -1520,8 +1576,20 @@ suite('Layout', function() {
       assert.notStrictEqual(true, obj.v);
       bs.encode({v: 1, b: 1}, b);
       assert.equal(b[0], 3);
+      bs.encode({v: 1, b: true}, b);
+      assert.equal(b[0], 3);
       bs.encode({v: 0, b: 0}, b);
       assert.equal(b[0], 0);
+      bs.encode({v: 0, b: false}, b);
+      assert.equal(b[0], 0);
+      bs.encode({}, b);
+      assert.equal(b[0], 0);
+      assert.throws(function() { bs.encode({v: false}, b); },
+                    function(err) { return checkError(err, TypeError, /BitField.encode\[v\] value must be integer/); });
+      assert.throws(function() { bs.encode({v: 1.2}, b); },
+                    function(err) { return checkError(err, TypeError, /BitField.encode\[v\] value must be integer/); });
+      assert.throws(function() { bs.encode({b: 1.2}, b); },
+                    function(err) { return checkError(err, TypeError, /BitField.encode\[b\] value must be integer/); });
     });
   });
   suite('Blob', function() {
@@ -1796,7 +1864,7 @@ suite('Layout', function() {
       assert.deepEqual(po, p);
     });
     test('bits', function() {
-      function Header() { };
+      function Header() { }
       Header.prototype.power = function() {
         return ['off', 'lo', 'med', 'hi'][this.pwr];
       };
@@ -1815,25 +1883,25 @@ suite('Layout', function() {
       assert.equal(b.compare(nb), 0);
     });
     test('union', function() {
-      function Union() { };
+      function Union() { }
       lo.bindConstructorLayout(Union, lo.union(lo.u8('var'), lo.blob(8, 'unk')));
       function VFloat(v) {
         this.f32 = v;
-      };
+      }
       util.inherits(VFloat, Union);
       lo.bindConstructorLayout(VFloat,
                                Union.layout_.addVariant(1, lo.f32(), 'f32'));
       function VCStr(v) {
         this.text = v;
-      };
+      }
       util.inherits(VCStr, Union);
       lo.bindConstructorLayout(VCStr,
                                Union.layout_.addVariant(2, lo.cstr(), 'text'));
       function Struct(u32, u16, s16) {
         this.u32 = u32;
         this.u16 = u16;
         this.s16 = s16;
-      };
+      }
       function VStruct(v) {
         this.struct = v;
       }

test/examples.js

@@ -23,6 +23,7 @@ struct ds {
     var ds = lo.struct([lo.u8('v'),
                         lo.seq(lo.u8(), 3), // alignment padding
                         lo.u32('u32')]);
+    assert.equal(ds.offsetOf('u32'), 4);
     var b = new Buffer(8);
     b.fill(0xbd);
     assert.equal(ds.encode({v: 1, u32: 0x12345678}, b), 1 + 3 + 4);
@@ -38,6 +39,7 @@ struct ds {
      */
     var ds = lo.struct([lo.u8('v'),
                         lo.u32('u32')]);
+    assert.equal(ds.offsetOf('u32'), 1);
     var b = new Buffer(5);
     b.fill(0xbd);
     assert.equal(ds.encode({v: 1, u32: 0x12345678}, b), 1 + 4);