Adds early implementation of bundle reading with test.

Author: colinbdclark

.jshintrc

@@ -0,0 +1,27 @@
+{
+    "white": false,
+    "newcap": true,
+    "regexp": true,
+    "browser": true,
+    "forin": false,
+    "nomen": true,
+    "bitwise": false,
+    "maxerr": 100,
+    "indent": 4,
+    "plusplus": false,
+    "curly": true,
+    "eqeqeq": true,
+    "freeze": true,
+    "latedef": true,
+    "noarg": true,
+    "nonew": true,
+    "quotmark": "double",
+    "undef": true,
+    "unused": true,
+    "strict": true,
+    "asi": false,
+    "boss": false,
+    "evil": false,
+    "expr": false,
+    "funcscope": false
+}

README.md

@@ -6,7 +6,7 @@ osc.js is a library for reading and writing [Open Sound Control](http://opensoun
 Why osc.js?
 -----------
 
-There are several other OSC libraries written in JavaScript. All of them depend on Node.js-specific APIs, which means they can't be run in a browser. osc.js uses only cross-platform APIs (specifically, `TypedArrays` and `DataView`) to ensure that it can run in any modern JavaScript environment.
+There are several other OSC libraries available for JavaScript. However, they all depend on Node.js-specific APIs. This means that they can't be run in a browser. osc.js uses only cross-platform APIs (specifically, `TypedArrays` and `DataView`), ensuring that it can run in any modern JavaScript environment.
 
 What Does it Do?
 ----------------
@@ -15,11 +15,17 @@ osc.js reads and writes OSC-formatted binary data into plain JavaScript objects.
 
 You can receive OSC data in whatever manner works best for your application: serial port APIs such as node-serialport or chrome.serial, socket APIs such as Node.js dgram or WebRTC data channels, WebSockets or binary XHR messages should all work. Connect osc.js up to your source of incoming/outgoing data, and you're all set.
 
+This approach is consistent with the design of Open Sound Control as a _content format_ that is independent from its means of transport.
+
 Status
 ------
 
-osc.js is new and still in development. It does not yet (but will) support:
+osc.js is still under development. It supports all OSC 1.0 and 1.1 required types, and most optional types. The semantics for time tags conform to the OSC 1.0 specification.
+
+osc.js does not yet (but will) support:
 
-* Bundles
+* Writing bundles
 * color types
 * MIDI types
+* array types ("[" and "]")
+* documentation

osc.js

@@ -443,8 +443,7 @@ var osc = osc || {};
 
         for (var i = 0; i < argTypes.length; i++) {
             var argType = argTypes[i],
-                typeSpec = osc.argumentTypes[argType],
-                argReader;
+                typeSpec = osc.argumentTypes[argType];
 
             if (!typeSpec) {
                 throw new Error("'" + argType + "' is not a valid OSC type tag. Type tag string was: " +
@@ -542,6 +541,11 @@ var osc = osc || {};
         };
 
         var address = osc.readString(dv, offsetState);
+        return osc.readMessageContents(address, dv, offsetState, withMetadata);
+    };
+
+    // Unsupported, non-API function.
+    osc.readMessageContents = function (address, dv, offsetState, withMetadata) {
         if (address.indexOf("/") !== 0) {
             throw new Error("A malformed OSC address was found while reading " +
                 "an OSC message. String was: " + address);
@@ -573,6 +577,50 @@ var osc = osc || {};
         });
     };
 
+    osc.readBundle = function (dv, offsetState, withMetadata) {
+        return osc.readPacket(dv, offsetState, withMetadata);
+    };
+
+    // Unsupported, non-API function.
+    osc.readBundleContents = function (dv, offsetState, withMetadata) {
+        var timeTag = osc.readTimeTag(dv, offsetState),
+            packets = [];
+
+        while (offsetState.idx < dv.byteLength) {
+            var packetSize = osc.readInt32(dv, offsetState),
+                // TODO: Improve performance  by not splitting the underlying ArrayBuffer when we recurse.
+                packetArr = dv.buffer.slice(offsetState.idx, offsetState.idx + packetSize),
+                packet = osc.readPacket(packetArr, undefined, withMetadata);
+
+            packets.push(packet);
+            offsetState.idx += packetSize;
+        }
+
+        return {
+            timeTag: timeTag,
+            packets: packets
+        };
+    };
+
+    osc.readPacket = function (dv, offsetState, withMetadata) {
+        dv = osc.wrapAsDataView(dv);
+        offsetState = offsetState || {
+            idx: 0
+        };
+
+        var header = osc.readString(dv, offsetState),
+            firstChar = header[0];
+
+        if (firstChar === "#") {
+            return osc.readBundleContents(dv, offsetState, withMetadata);
+        } else if (firstChar === "/") {
+            return osc.readMessageContents(header, dv, offsetState, withMetadata);
+        }
+
+        throw new Error("The header of an OSC packet didn't contain an OSC address or a #bundle string." +
+            "Header was: " + header);
+    };
+
     // Unsupported, non-API.
     osc.argumentTypes = {
         i: {
@@ -651,9 +699,10 @@ var osc = osc || {};
                     (typeof Buffer !== "undefined" && arg instanceof Buffer)) {
                     return "b";
                 }
-            default:
-                throw new Error("Can't infer OSC argument type for value: " + arg);
+                break;
         }
+
+        throw new Error("Can't infer OSC argument type for value: " + arg);
     };
 
     // Unsupported, non-API function.

tests/js/osc-tests.js

@@ -120,7 +120,7 @@
 
              equal(actual, expected, "The string should have been read correctly.");
              equal(offsetState.idx, testSpec.paddedString.length,
-                 "The offset state should correctly reflect the null padding of the OSC string.")
+                 "The offset state should correctly reflect the null padding of the OSC string.");
         });
 
     };
@@ -157,7 +157,7 @@
             testReadString(testSpec);
             testWriteString(testSpec);
         }
-    }
+    };
 
     stringTests(stringTestSpecs);
 
@@ -394,7 +394,7 @@
 
             arrayEqual(actual, expected, "The raw time tag should have have been written correctly.");
         });
-    }
+    };
 
     var timeTagTestSpecs = [
         {
@@ -428,7 +428,7 @@
         for (var i = 0; i < testSpecs.length; i++) {
             var testSpec = testSpecs[i];
             testReadTimeTag(testSpec);
-            testWriteTimeTag(testSpec)
+            testWriteTimeTag(testSpec);
         }
     };
 
@@ -657,4 +657,138 @@
 
     testMessages(messageTestSpecs);
 
+
+    /***********
+     * Bundles *
+     ***********/
+
+    var testReadBundle = function (testSpec) {
+        test("readBundle " + testSpec.name, function () {
+            var expected = testSpec.bundle,
+                dv = new DataView(testSpec.bytes.buffer),
+                offsetState = {
+                    idx: 0
+                };
+
+            var actual = osc.readBundle(dv, offsetState);
+            roundedDeepEqual(actual, expected,
+                "The bundle should have been read correctly.");
+            equal(offsetState.idx, dv.byteLength,
+                "The offset state should have been adjusted correctly.");
+        });
+    };
+
+    var bundleTestSpecs = [
+        {
+            name: "with nested bundles.",
+            bytes: new Uint8Array([
+                // "#bundle"
+                35, 98, 117, 110,
+                100, 108, 101, 0,
+                // timetag [3608492400, 0]
+                215, 21, 57, 112,
+                0, 0, 0, 0,
+
+                // first packet:
+                // size 24 bytes
+                0, 0, 0, 24,
+                // "/cat/meow/freq"
+                47, 99, 97, 116,
+                47, 109, 101, 111,
+                119, 47, 102, 114,
+                101, 113, 0, 0,
+                //,f
+                44, 102, 0, 0,
+                // 222.2
+                67, 94, 51, 51,
+
+                // second packet:
+                // size 44 bytes
+                0, 0, 0, 48,
+                // "#bundle"
+                35, 98, 117, 110,
+                100, 108, 101, 0,
+                // timetag [3608406000, 0]
+                215, 19, 231, 240,
+                0, 0, 0, 0,
+
+                // packet 2.a:
+                // size 28 bytes
+                0, 0, 0, 28,
+                // "/hamster/wheel/freq"
+                47, 104, 97, 109,
+                115, 116, 101, 114,
+                47, 119, 104, 101,
+                101, 108, 47, 102,
+                114, 101, 113, 0,
+                // type tag ,i
+                44, 105, 0, 0,
+                // 100
+                0, 0, 0, 100,
+
+                // third packet:
+                // size 32 bytes
+                0, 0, 0, 32,
+                // "/fish/burble/amp"
+                47, 102, 105, 115,
+                104, 47, 98, 117,
+                114, 98, 108, 101,
+                47, 97, 109, 112,
+                0, 0, 0, 0,
+                // type tag ,fs
+                44, 102, 115, 0,
+                // -6, "dB"
+                192, 192, 0, 0,
+                100, 66, 0, 0
+            ]),
+
+            bundle: {
+                timeTag: {
+                    // 215, 21, 57, 112 | 0, 0, 0, 0
+                    raw: [3608492400, 0],
+                    native: 1399503600000
+                },
+
+                packets: [
+                    {
+                        // 47 99 97 116 | 47 109 101 111 | 119 47 102 114 | 101 113 0 0
+                        address: "/cat/meow/freq",
+                        // type tag: ,f: 44 102 0 0 | values: 67 94 51 51
+                        args: 222.2
+                    },
+                    {
+                        timeTag: {
+                            // 215 19 231 240 | 0 0 0 0
+                            raw: [3608406000, 0],
+                            native: 1399417200000
+                        },
+                        packets: [
+                            {
+                                // 47 104 97 109 | 115 116 101 114 | 47 119 104 101 | 101 108 47 102 | 114 101 113 0
+                                address: "/hamster/wheel/freq",
+                                // type tag ,i: 44 105 0 0 | values: 66 200 0 0
+                                args: 100
+                            }
+                        ]
+                    },
+                    {
+                        // 47 102 105 115 | 104 47 98 117 | 114 98 108 101 | 47 97 109 112 | 0 0 0 0
+                        address: "/fish/burble/amp",
+                        // type tag ,fs: 44 102 115 0 | values: 255 255 255 250, 100 66 0 0
+                        args: [-6, "dB"]
+                    }
+                ]
+            }
+        }
+    ];
+
+    var testBundles = function (testSpecs) {
+        for (var i = 0; i < testSpecs.length; i++) {
+            var testSpec = testSpecs[i];
+            testReadBundle(testSpec);
+        }
+    };
+
+    testBundles(bundleTestSpecs);
+
 }());