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.

1 files changed, 20 insertions, 9 deletions

diff --git a/lib/util.js b/lib/util.js
index ebb18810cc..86acd8ba0d 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;