util: make `inspect()` accept an "options" argument

Consolidates all the formatting options into an "options" object argument.
This is so that we don't have to be constantly remembering the order of
the arguments and so that we can add more formatting options easily.

Closes #4085.

doc/api/util.markdown

@@ -66,28 +66,28 @@ Output with timestamp on `stdout`.
     require('util').log('Timestamped message.');
 
 
-## util.inspect(object, [showHidden], [depth], [colors])
+## util.inspect(object, [options])
 
 Return a string representation of `object`, which is useful for debugging.
 
-If `showHidden` is `true`, then the object's non-enumerable properties will be
+An optional *options* object may be passed that alters certain aspects of the
-shown too. Defaults to `false`.
+formatted string:
 
-If `depth` is provided, it tells `inspect` how many times to recurse while
+ - `showHidden` - if `true` then the object's non-enumerable properties will be
-formatting the object. This is useful for inspecting large complicated objects.
+   shown too. Defaults to `false`.
 
-The default is to only recurse twice.  To make it recurse indefinitely, pass
+ - `depth` - tells `inspect` how many times to recurse while formatting the
-in `null` for `depth`.
+   object. This is useful for inspecting large complicated objects. Defaults to
+   `2`. To make it recurse indefinitely pass `null`.
 
-If `colors` is `true`, the output will be styled with ANSI color codes.
+ - `colors` - if `true`, then the output will be styled with ANSI color codes.
-Defaults to `false`.
+   Defaults to `false`. Colors are customizable, see below.
-Colors are customizable, see below.
 
 Example of inspecting all properties of the `util` object:
 
     var util = require('util');
 
-    console.log(util.inspect(util, true, null));
+    console.log(util.inspect(util, { showHidden: true, depth: null }));
 
 ### Customizing `util.inspect` colors
 

lib/util.js

@@ -110,19 +110,30 @@ var error = exports.error = function(x) {
  * in the best way possible given the different types.
  *
  * @param {Object} obj The object to print out.
- * @param {Boolean} showHidden Flag that shows hidden (not enumerable)
+ * @param {Object} opts Optional options object that alters the output.
- *    properties of objects.
- * @param {Number} depth Depth in which to descend in object. Default is 2.
- * @param {Boolean} colors Flag to turn on ANSI escape codes to color the
- *    output. Default is false (no coloring).
  */
-function inspect(obj, showHidden, depth, colors) {
+function inspect(obj, opts/* legacy: showHidden, depth, colors*/) {
+  // default options
   var ctx = {
-    showHidden: showHidden,
     seen: [],
-    stylize: colors ? stylizeWithColor : stylizeNoColor
+    stylize: stylizeNoColor
   };
-  return formatValue(ctx, obj, (typeof depth === 'undefined' ? 2 : depth));
+  // legacy...
+  if (arguments.length >= 3) ctx.depth = arguments[2];
+  if (arguments.length >= 4) ctx.colors = arguments[3];
+  if (typeof opts === 'boolean') {
+    // legacy...
+    ctx.showHidden = opts;
+  } else if (opts) {
+    // got an "options" object
+    exports._extend(ctx, opts);
+  }
+  // set default options
+  if (typeof ctx.showHidden === 'undefined') ctx.showHidden = false;
+  if (typeof ctx.depth === 'undefined') ctx.depth = 2;
+  if (typeof ctx.colors === 'undefined') ctx.colors = false;
+  if (ctx.colors) ctx.stylize = stylizeWithColor;
+  return formatValue(ctx, obj, ctx.depth);
 }
 exports.inspect = inspect;
 

test/simple/test-util-inspect.js

@@ -137,3 +137,15 @@ assert.doesNotThrow(function() {
     hasOwnProperty: null
   });
 });
+
+// new API, accepts an "options" object
+var subject = { foo: 'bar', hello: 31, a: { b: { c: { d: 0 } } } };
+Object.defineProperty(subject, 'hidden', { enumerable: false, value: null });
+
+assert(util.inspect(subject, { showHidden: false }).indexOf('hidden') === -1);
+assert(util.inspect(subject, { showHidden: true }).indexOf('hidden') !== -1);
+assert(util.inspect(subject, { colors: false }).indexOf('\u001b[32m') === -1);
+assert(util.inspect(subject, { colors: true }).indexOf('\u001b[32m') !== -1);
+assert(util.inspect(subject, { depth: 2 }).indexOf('c: [Object]') !== -1);
+assert(util.inspect(subject, { depth: 0 }).indexOf('a: [Object]') !== -1);
+assert(util.inspect(subject, { depth: null }).indexOf('{ d: 0 }') !== -1);