#27 want streaming way to iterate array elements

#100 jsprint shows more "hole" values than it should
#101 test suite could use common mechanism for standalone tests
#104 test suite should take more care to avoid GC during gcore
Reviewed by: Julien Gilli <[email protected]>
Approved by: Julien Gilli <[email protected]>

Author: David Pacheco

.gitignore

@@ -1,2 +1,4 @@
 build
+node_modules
+make_stamps
 tools/mdbv8diff/node_modules

CHANGES.md

@@ -5,7 +5,7 @@
 -->
 
 <!--
-    Copyright (c) 2017, Joyent, Inc.
+    Copyright (c) 2018, Joyent, Inc.
 -->
 
 # mdb_v8 changelog
@@ -14,6 +14,12 @@
 
 None.
 
+## v1.3.0 (2018-01)
+
+* #27 want streaming way to iterate array elements
+* #100 jsprint shows more "hole" values than it should
+* #101 test suite could use common mechanism for standalone tests
+
 ## v1.2.1 (2017-09-20)
 
 * #96 jsclosure crash on invalid context index

GNUmakefile

@@ -5,7 +5,7 @@
 #
 
 #
-# Copyright (c) 2015, Joyent, Inc.
+# Copyright (c) 2018, Joyent, Inc.
 #
 
 #
@@ -48,6 +48,7 @@ MDBV8_VERS_TAG	 = "dev"
 #
 MDBV8_SOURCES		 = \
     mdb_v8.c \
+    mdb_v8_array.c \
     mdb_v8_cfg.c \
     mdb_v8_function.c \
     mdb_v8_strbuf.c \
@@ -122,6 +123,18 @@ MAKESO	 	 = $(CC) -o $@ -shared $(SOFLAGS) $(LDFLAGS) $^
 GITDESCRIBE	 = $(shell git describe --all --long --dirty | \
     awk -F'-g' '{print $$NF}')
 
+#
+# Include eng.git Makefile for managing "node_modules" directory.  A number of
+# items that are normally provided by Makefile.defs are specified here directly.
+#
+TOP		  = $(shell pwd)
+NPM		  = npm
+MAKE_STAMPS_DIR	  = make_stamps
+CLEAN_FILES	 += $(MAKE_STAMPS_DIR)
+MAKE_STAMP_REMOVE = mkdir -p $(@D); rm -f $(@)
+MAKE_STAMP_CREATE = mkdir -p $(@D); touch $(@)
+include ./tools/mk/Makefile.node_modules.defs
+
 #
 # TARGETS
 #
@@ -137,7 +150,7 @@ check-cstyle:
 CLEAN_FILES += $(MDBV8_BUILD)
 
 .PHONY: test
-test: $(MDBV8_ALLTARGETS)
+test: $(MDBV8_ALLTARGETS) $(STAMP_NODE_MODULES)
 	$(CATEST) -a
 
 .PHONY: prepush
@@ -172,6 +185,8 @@ $(MDBV8_BUILD):
 	$(MKDIRP)
 
 #
-# Include common Joyent Makefile for JavaScript "check" targets.
+# Include common Joyent Makefile for JavaScript "check" targets and
+# "node_modules" management targets.
 #
-include Makefile.targ
+include ./Makefile.targ
+include ./tools/mk/Makefile.node_modules.targ

docs/usage.md

@@ -617,6 +617,84 @@ Of course, you can use other commands to inspect these values further.
 
 See also: `jsfunction`
 
+### jsarray
+
+    addr::jsarray [-i]
+
+Given an address `addr` of an instance of the JavaScript "Array" class, print
+the contents of the array.  Each element of the array is printed on its own
+line.  With no options, the result can be piped to `::jsprint` to print each
+element.
+
+For example, take this snippet:
+
+    var x = [ 'one', 'two', 'three' ];
+
+With `::jsarray`, this prints three pointers, one for each string:
+
+    > 9d780985::jsarray
+    8bc27629
+    8bc27639
+    8bc27649
+
+We can pipe this to `::jsprint` to see the strings:
+
+    > 9d780985::jsarray | ::jsprint
+    "one"
+    "two"
+    "three"
+
+With "-i", each value is prefixed with its integer index in the array:
+
+    > 9d780985::jsarray -i
+    0 8bc27629
+    1 8bc27639
+    2 8bc27649
+
+Note that JavaScript arrays can contain holes, where there is no element for a
+particular index (not even "undefined").  These appear when an element was
+removed using the `delete` keyword or when an array was initialized with a
+specific length, but not all of the elements were filled in.
+
+When `::jsarray` encounters a hole, the hole is printed out using a special
+value that `::jsprint` shows indicates a hole.  For example, take this snippet:
+
+    var x = new Array(4);
+    x[0] = 'one';
+    x[1] = 'two';
+    x[2] = 'three';
+    delete (x[1]);
+
+This produces an array with two holes: one at index 1 (because it was deleted)
+and one at index 3 (because it was never initialized, but the length was
+initialized to include this index).  If you print this out with `console.log`,
+you'd see:
+
+    [ 'one', , 'three',  ]
+
+(Note the extra commas where there are holes.)
+
+`::jsarray` prints the holes, which may look like ordinary values:
+
+    > 81780a0d::jsarray
+    aba27661
+    b4d080c1
+    aba27681
+    b4d080c1
+
+but are recognized by `::jsprint` as special:
+
+    > 81780a0d::jsarray | ::jsprint
+    "one"
+    hole
+    "three"
+    hole
+
+The default behavior around the printing of hole values may change in the
+future.
+
+See also: `walk jselement`
+
 ### jsconstructor
 
     addr::jsconstructor [-v]
@@ -875,6 +953,34 @@ With "-f", show only frames for function `function`.  With "-p", show only
 With "-a", show all information about hidden frames, the frame pointer for each
 frame, and other native objects for each frame (e.g., JSFunction addresses).
 
+### walk jselement
+
+    addr::walk jselement
+
+Given a JavaScript array identified by `addr`, enumerates the elements of the
+array.  This behaves very similarly to `::jsarray`.  See the notes about holes
+under `::jsarray`.
+
+For example, the array created by this code:
+
+    var x = [ 'one', 'two', 'three' ]
+
+is enumerated in the debugger like this:
+
+    > 9d780985::walk jselement
+    0x8bc27629
+    0x8bc27639
+    0x8bc27649
+
+The results can be piped to `::jsprint` to print the actual values:
+
+    > 9d780985::walk jselement | ::jsprint
+    "one"
+    "two"
+    "three"
+
+See also: `jsarray`.
+
 ### walk jsframe
 
     ::walk jsframe

package.json

@@ -0,0 +1,10 @@
+{
+	"name": "mdb_v8_deps",
+	"version": "1.0.0",
+	"description": "package used only to install devDependencies for mdb_v8",
+	"private": true,
+	"devDependencies": {
+		"vasync": "^2.2.0",
+		"verror": "^1.10.0"
+	}
+}