Merge changes resulting in v0.10.0

CHANGELOG.md

@@ -1,5 +1,17 @@
 # Change Log
 
+## [Unreleased]
+
+## [0.10.0] - 2016-01-23
+
+* **API** Change some exceptions (especially integer value spans) to
+  throw `RangeError` instead of `TypeError`, resolving
+  [issue #12][issue#12].
+* **API** [Add][issue#14] [boolean-valued bit fields][doc:Boolean].
+* Increase coverage of primary module to 100%.
+* Update dev dependency modules.
+* Fix always-false pre-convert type check.
+
 ## [0.9.0] - 2015-12-22
 
 * **API** Support inferring [Sequence][doc:Sequence.count] and
@@ -73,6 +85,8 @@
 
 * Initial release.
 
+[Unreleased]: https://github.com/pabigot/buffer-layout/compare/v0.10.0...next
+[0.10.0]: https://github.com/pabigot/buffer-layout/compare/v0.9.0...v0.10.0
 [0.9.0]: https://github.com/pabigot/buffer-layout/compare/v0.8.0...v0.9.0
 [0.8.0]: https://github.com/pabigot/buffer-layout/compare/v0.7.0...v0.8.0
 [0.7.1]: https://github.com/pabigot/buffer-layout/compare/v0.7.0...v0.7.1
@@ -86,6 +100,7 @@
 [doc:BitStructure]: http://pabigot.github.io/buffer-layout/module-Layout-BitStructure.html
 [doc:Blob]: http://pabigot.github.io/buffer-layout/module-Layout-Blob.html
 [doc:Blob.length]: http://pabigot.github.io/buffer-layout/module-Layout-Blob.html#length
+[doc:Boolean]: http://pabigot.github.io/buffer-layout/module-Layout-Boolean.html
 [doc:Constant]: http://pabigot.github.io/buffer-layout/module-Layout-Constant.html
 [doc:CString]: http://pabigot.github.io/buffer-layout/module-Layout-CString.html
 [doc:Layout.encode]: http://pabigot.github.io/buffer-layout/module-Layout-Layout.html#encode
@@ -113,6 +128,7 @@
 [issue#11]: https://github.com/pabigot/buffer-layout/issues/11
 [issue#12]: https://github.com/pabigot/buffer-layout/issues/12
 [issue#13]: https://github.com/pabigot/buffer-layout/issues/13
+[issue#14]: https://github.com/pabigot/buffer-layout/issues/14
 [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

README.md

@@ -144,13 +144,13 @@ The buffer-layout way:
 
 See [Union](http://pabigot.github.io/buffer-layout/module-Layout-Union.html).
 
-#### Packed bit fields on a little-endian machine
+### Packed bit fields on a little-endian machine
 
 The C definition:
 
     struct ds {
       unsigned int b00l03: 3;
-      unsigned int b03l01: 1;
+      unsigned int flg03: 1;
       unsigned int b04l18: 24;
       unsigned int b1Cl04: 4;
     } st;
@@ -160,14 +160,14 @@ The buffer-layout way:
     var ds = lo.bits(lo.u32());
     var b = new Buffer(4);
     ds.addField(3, 'b00l03');
-    ds.addField(1, 'b03l01');
+    ds.addBoolean('flg03');
     ds.addField(24, 'b04l18');
     ds.addField(4, 'b1Cl04');
     b.fill(0xff);
     assert.equal(ds.encode({b00l03: 3, b04l18: 24, b1Cl04: 4}, b), 4);
     assert.equal(Buffer('8b010040', 'hex').compare(b), 0);
     assert.deepEqual(ds.decode(b),
-                     {b00l03: 3, b03l01: 1, b04l18: 24, b1Cl04: 4});
+                     {b00l03: 3, flg03: true, b04l18: 24, b1Cl04: 4});
 
 See [BitStructure](http://pabigot.github.io/buffer-layout/module-Layout-BitStructure.html).
 

lib/Layout.js

@@ -118,6 +118,7 @@
  * @local VariantLayout
  * @local BitStructure
  * @local BitField
+ * @local Boolean
  * @local Blob
  * @local CString
  * @local Constant
@@ -381,7 +382,7 @@ function GreedyCount(elementSpan, property) {
     elementSpan = 1;
   }
   if ((!Number.isInteger(elementSpan)) || (0 >= elementSpan)) {
-    throw new TypeError('elementSpan must be a positive integer');
+    throw new TypeError('elementSpan must be a (positive) integer');
   }
   ExternalLayout.call(this, -1, property);
 
@@ -409,7 +410,7 @@ GreedyCount.prototype.decode = function(b, offset) {
 };
 /** Implement {@link Layout#encode|encode} for {@link GreedyCount|GreedyCount}. */
 GreedyCount.prototype.encode = function(src, b, offset) {
-  return;
+  return 0;
 };
 
 /** An {@link ExternalLayout|ExternalLayout} that supports accessing a
@@ -499,7 +500,7 @@ OffsetLayout.prototype.encode = function(src, b, offset) {
 function UInt(span, property) {
   Layout.call(this, span, property);
   if (6 < this.span) {
-    throw new TypeError('span must not exceed 6 bytes');
+    throw new RangeError('span must not exceed 6 bytes');
   }
   Object.freeze(this);
 }
@@ -539,7 +540,7 @@ UInt.prototype.encode = function(src, b, offset) {
 function UIntBE(span, property) {
   Layout.call(this, span, property);
   if (6 < this.span) {
-    throw new TypeError('span must not exceed 6 bytes');
+    throw new RangeError('span must not exceed 6 bytes');
   }
   Object.freeze(this);
 }
@@ -579,7 +580,7 @@ UIntBE.prototype.encode = function(src, b, offset) {
 function Int(span, property) {
   Layout.call(this, span, property);
   if (6 < this.span) {
-    throw new TypeError('span must not exceed 6 bytes');
+    throw new RangeError('span must not exceed 6 bytes');
   }
   Object.freeze(this);
 }
@@ -619,7 +620,7 @@ Int.prototype.encode = function(src, b, offset) {
 function IntBE(span, property) {
   Layout.call(this, span, property);
   if (6 < this.span) {
-    throw new TypeError('span must not exceed 6 bytes');
+    throw new RangeError('span must not exceed 6 bytes');
   }
   Object.freeze(this);
 }
@@ -1616,7 +1617,7 @@ function VariantLayout(union,
     throw new TypeError('union must be a Union');
   }
   if ((!Number.isInteger(variant)) || (0 > variant)) {
-    throw new TypeError('variant must be a non-negative integer');
+    throw new TypeError('variant must be a (non-negative) integer');
   }
   if (!(layout instanceof Layout)) {
     throw new TypeError('layout must be a Layout');
@@ -1738,10 +1739,11 @@ function fixBitwiseResult(v) {
  * BitField|BitField} instances that provide the extracted properties.
  * The container simply defines the aggregate representation and its
  * bit ordering.  The representation is an object containing
- * properties with numeric values.
+ * properties with numeric or {@link Boolean|boolean} values.
  *
  * {@link BitField|BitField}s are added with the {@link
- * BitStructure#addField|addField} method.
+ * BitStructure#addField|addField} and {@link
+ * BitStructure#addBoolean|addBoolean} methods.
 
  * @param {Layout} word - initializer for {@link
  * BitStructure#word|word}.  The parameter must be an instance of
@@ -1763,7 +1765,7 @@ function BitStructure(word, msb, property) {
     throw new TypeError('word must be a UInt or UIntBE layout');
   }
   if (4 < word.span) {
-    throw new Error('word cannot exceed 32 bits');
+    throw new RangeError('word cannot exceed 32 bits');
   }
   Layout.call(this, word.span, property);
 
@@ -1855,6 +1857,18 @@ BitStructure.prototype.addField = function(bits, property) {
   this.fields.push(bf);
   return bf;
 };
+/** As with {@link BitStructure#addField|addField} for single-bit
+ * fields with `boolean` value representation.
+ *
+ * @param {string} property - initializer for {@link
+ * Layout#property|property}.
+ *
+ * @return {Boolean} */
+BitStructure.prototype.addBoolean = function(property) {
+  var bf = new Boolean(this, property);
+  this.fields.push(bf);
+  return bf;
+};
 
 /** Represent a sequence of bits within a {@link
  * BitStructure|BitStructure}.
@@ -1940,7 +1954,10 @@ BitField.prototype.decode = function() {
   return value;
 };
 /** Store a value into the corresponding subsequence of the containing
- * bit field. */
+ * bit field.
+ *
+ * **NOTE** This is not a specialization of {@link
+ * Layout#encode|Layout.encode} and there is no return value. */
 BitField.prototype.encode = function(value) {
   if ((!Number.isInteger(value))
       || (value != fixBitwiseResult(value & this.valueMask))) {
@@ -1952,6 +1969,36 @@ BitField.prototype.encode = function(value) {
                                  | wordValue);
 };
 
+/** Represent a single bit within a {@link
+ * BitStructure|BitStructure} as a JavaScript boolean.
+ *
+ * **NOTE** User code should not invoke this construtor directly.  Use
+ * the container {@link BitStructure#addBoolean|addBoolean} helper
+ * method.
+ *
+ * @param {BitStructure} container - initializer for {@link
+ * BitField#container|container}.
+ *
+ * @param {string} [property] - initializer for {@link
+ * Layout#property|property}.
+ *
+ * @constructor
+ * @augments {BitField}
+ */
+function Boolean(container, property) {
+  BitField.call(this, container, 1, property);
+};
+Boolean.prototype = Object.create(BitField.prototype);
+Boolean.prototype.constructor = Boolean;
+/** 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. */
+
 /** Contain a fixed-length block of arbitrary data, represented as a
  * Buffer.
  *
@@ -2019,7 +2066,7 @@ 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 Error('Blob.encode requires (length ' + span + ') Buffer as src');
   }
   if ((offset + span) > b.length) {
     throw new RangeError('encoding overruns Buffer');
@@ -2080,7 +2127,7 @@ CString.prototype.encode = function(src, b, offset) {
   /* Must force this to a string, lest it be a number and the
    * "utf8-encoding" below actually allocate a buffer of length
    * src */
-  if (!(src instanceof String)) {
+  if ('string' !== typeof src) {
     src = src.toString();
   }
   var srcb = new Buffer(src, 'utf8');
@@ -2157,6 +2204,7 @@ exports.Union = Union;
 exports.VariantLayout = VariantLayout;
 exports.BitStructure = BitStructure;
 exports.BitField = BitField;
+exports.Boolean = Boolean;
 exports.Blob = Blob;
 exports.CString = CString;
 exports.Constant = Constant;

package.json

@@ -1,6 +1,6 @@
 {
   "name": "buffer-layout",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "Translation between JavaScript values and Buffers",
   "keywords": [
     "Buffer",
@@ -18,14 +18,14 @@
   "author": "Peter A. Bigot <pab@pabigot.com>",
   "main": "./lib/Layout.js",
   "devDependencies": {
-    "coveralls": "~2.11.4",
-    "istanbul": "~0.4.0",
-    "jscs": "~2.7.0",
-    "jsdoc": "~3.3.3",
-    "jshint": "^2.8.0",
-    "jslint": "~0.9.3",
-    "lodash": "~3.9.3",
-    "mocha": "~2.2.5"
+    "coveralls": "~2.11.6",
+    "istanbul": "~0.4.2",
+    "jscs": "~2.8.0",
+    "jsdoc": "~3.4.0",
+    "jshint": "^2.9.1",
+    "jslint": "~0.9.6",
+    "lodash": "~4.0.0",
+    "mocha": "~2.3.4"
   },
   "engines": {
     "node": ">=0.12"
@@ -34,10 +34,10 @@
     "coverage": "istanbul cover _mocha -- -u tdd",
     "coveralls": "istanbul cover _mocha --report lcovonly -- -u tdd && cat ./coverage/lcov.info | coveralls",
     "jscs": "jscs lib/ test/",
+    "jsdoc": "jsdoc -c jsdoc/conf.json",
     "jslint": "jslint lib/Layout.js || true",
     "lint": "jshint lib/*.js test/*.js || true",
     "lint.strict": "jshint lib/Layout.js",
-    "mkdoc": "jsdoc -c jsdoc/conf.json",
     "test": "mocha -u tdd"
   },
   "jshintConfig": {