Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

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.
  • Loading branch information...
commit 881f9c41dd49e17318ea8164e1579d354d8f9569 1 parent 7611c7c
@TooTallNate authored
View
22 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
View
29 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;
View
12 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);
Please sign in to comment.
Something went wrong with that request. Please try again.