merge for 1.2.0 release

Author: pabigot

CHANGELOG.md

@@ -1,5 +1,14 @@
 # Change Log
 
+## [1.2.0] - 2018-03-14
+
+* **API** Add [UTF8][doc:UTF8] to encode UTF strings in a possibly
+  bounded buffer, resolving [issue #21][issue#21].
+* **API** Allow the layout parameter of
+  a [VariantLayout][doc:VariantLayout] to be omitted in cases where no
+  data beyond the discriminator is required,
+  resolving [issue #20][issue#20].
+
 ## [1.1.0] - 2018-01-06
 
 * **API** Add a third parameter to Structure specifying it should decode
@@ -122,6 +131,7 @@
 
 * Initial release.
 
+[1.2.0]: https://github.com/pabigot/buffer-layout/compare/v1.1.0...v1.2.0
 [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
@@ -154,14 +164,16 @@
 [doc:NearInt64]: http://pabigot.github.io/buffer-layout/module-Layout-NearInt64.html
 [doc:OffsetLayout]: http://pabigot.github.io/buffer-layout/module-Layout-OffsetLayout.html
 [doc:patchIssue3992]: http://pabigot.github.io/buffer-layout/module-patchIssue3992.html
-[doc:Union]: http://pabigot.github.io/buffer-layout/module-Layout-Union.html
-[doc:Union.getSourceVariant]: http://pabigot.github.io/buffer-layout/module-Layout-Union.html#getSourceVariant
-[doc:UnionDiscriminator]: http://pabigot.github.io/buffer-layout/module-Layout-UnionDiscriminator.html
 [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
+[doc:Union]: http://pabigot.github.io/buffer-layout/module-Layout-Union.html
+[doc:Union.getSourceVariant]: http://pabigot.github.io/buffer-layout/module-Layout-Union.html#getSourceVariant
+[doc:UnionDiscriminator]: http://pabigot.github.io/buffer-layout/module-Layout-UnionDiscriminator.html
+[doc:UTF8]: http://pabigot.github.io/buffer-layout/module-Layout-UTF8.html
+[doc:VariantLayout]: http://pabigot.github.io/buffer-layout/module-Layout-VariantLayout.html
 [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
@@ -179,6 +191,8 @@
 [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
+[issue#20]: https://github.com/pabigot/buffer-layout/issues/20
+[issue#21]: https://github.com/pabigot/buffer-layout/issues/21
 [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

@@ -132,10 +132,14 @@ The buffer-layout way:
 
     const t = lo.u8('t');
     const un = lo.union(t, lo.seq(lo.u8(), 4, 'u8'));
+    const nul = un.addVariant('n'.charCodeAt(0), 'nul');
     const u32 = un.addVariant('w'.charCodeAt(0), lo.u32(), 'u32');
     const s16 = un.addVariant('h'.charCodeAt(0), lo.seq(lo.s16(), 2), 's16');
     const f32 = un.addVariant('f'.charCodeAt(0), lo.f32(), 'f32');
     const b = Buffer.alloc(un.span);
+    assert.deepEqual(un.decode(b), {t: 0, u8: [0, 0, 0, 0]});
+    assert.deepEqual(un.decode(Buffer.from('6e01020304', 'hex')),
+                     {nul: true});
     assert.deepEqual(un.decode(Buffer.from('7778563412', 'hex')),
                      {u32: 0x12345678});
     assert.deepEqual(un.decode(Buffer.from('660000bd41', 'hex')),
@@ -156,6 +160,11 @@ representing the union and the variants:
     lo.bindConstructorLayout(Union,
                              lo.union(lo.u8('t'), lo.seq(lo.u8(), 4, 'u8')));
 
+    function Vn() {}
+    util.inherits(Vn, Union);
+    lo.bindConstructorLayout(Vn,
+                             Union.layout_.addVariant('n'.charCodeAt(0), 'nul'));
+
     function Vu32(v) { this.u32 = v; }
     util.inherits(Vu32, Union);
     lo.bindConstructorLayout(Vu32,
@@ -186,6 +195,14 @@ representing the union and the variants:
     v.encode(b);
     assert.equal(Buffer.from('660000bd41', 'hex').compare(b), 0);
 
+    b.fill(0xFF);
+    v = new Vn();
+    v.encode(b);
+    assert.equal(Buffer.from('6effffffff', 'hex').compare(b), 0);
+
+Note that one variant (`'n'`) carries no data, leaving the remainder of
+the buffer unchanged when stored.
+
 See
 [Layout.makeDestinationObject()](http://pabigot.github.io/buffer-layout/module-Layout-Layout.html#makeDestinationObject)
 and

jsdoc/custom/local.js

@@ -30,9 +30,20 @@ function buildRE(prefix, tag) {
 exports.handlers = {
     jsdocCommentFound: function(e) {
         if (thisModule) for (var local in registry) {
-            var sv = '$1'+thisModule+'~'+'$2';
-            e.comment = e.comment.replace(buildRE('{', local), sv);
-            e.comment = e.comment.replace(buildRE('{@link\\s*\\*?\\s*', local), sv);
+            /* Handle {@link local} => {@link module~local|local} (across EOL) */
+            var re = new RegExp('({@link\\s*\\*?\\s*)\\b(' + local + '\\b[^|}]*)}', 'g');
+            e.comment = e.comment.replace(re,
+                                         '$1' + thisModule + '~$2\|$2}');
+
+            /* Handle {local} => {thisModule~local}.  Brace reference
+             * doesn't support providing alternative text. */
+            e.comment = e.comment.replace(buildRE('{', local),
+                                          '$1' + thisModule + '~$2');
+
+            /* Handle `@cmd local` => `@cmd thisModule~local` for
+             * certain commands (across EOL) */
+            e.comment = e.comment.replace(buildRE('@(event|link|memberof|name)\\s*\\*?\\s*', local),
+                                         '$1' + thisModule + '~$3');
         }
     },