From 07774e6b9570f90166a54fa87af74b8a7cf9926a Mon Sep 17 00:00:00 2001
From: Nathan Rajlich <nathan@tootallnate.net>
Date: Tue, 9 Oct 2012 18:47:08 -0700
Subject: [PATCH] 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            | 22 +++++++++++-----------
 lib/util.js                      | 29 ++++++++++++++++++++---------
 test/simple/test-util-inspect.js | 12 ++++++++++++
 3 files changed, 43 insertions(+), 20 deletions(-)

diff --git a/doc/api/util.markdown b/doc/api/util.markdown
index 66ce52ddcc0a2f..1a914e51f17bac 100644
--- a/doc/api/util.markdown
+++ b/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
-shown too. Defaults to `false`.
+An optional *options* object may be passed that alters certain aspects of the
+formatted string:
 
-If `depth` is provided, it tells `inspect` how many times to recurse while
-formatting the object. This is useful for inspecting large complicated objects.
+ - `showHidden` - if `true` then the object's non-enumerable properties will be
+   shown too. Defaults to `false`.
 
-The default is to only recurse twice.  To make it recurse indefinitely, pass
-in `null` for `depth`.
+ - `depth` - tells `inspect` how many times to recurse while formatting the
+   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.
-Defaults to `false`.
-Colors are customizable, see below.
+ - `colors` - if `true`, then the output will be styled with ANSI color codes.
+   Defaults to `false`. 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
 
diff --git a/lib/util.js b/lib/util.js
index ebb18810ccbbdc..86acd8ba0d6e20 100644
--- a/lib/util.js
+++ b/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)
- *    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).
+ * @param {Object} opts Optional options object that alters the output.
  */
-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;
 
diff --git a/test/simple/test-util-inspect.js b/test/simple/test-util-inspect.js
index 0877c76d6ff682..65f8548f12138b 100644
--- a/test/simple/test-util-inspect.js
+++ b/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);