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.
This commit is contained in:
Nathan Rajlich 2012-10-09 18:47:08 -07:00
parent 5823290390
commit 07774e6b95
3 changed files with 43 additions and 20 deletions

View File

@ -66,28 +66,28 @@ Output with timestamp on `stdout`.
require('util').log('Timestamped message.'); 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. 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: Example of inspecting all properties of the `util` object:
var util = require('util'); var util = require('util');
console.log(util.inspect(util, true, null)); console.log(util.inspect(util, { showHidden: true, depth: null }));
### Customizing `util.inspect` colors ### Customizing `util.inspect` colors

View File

@ -110,19 +110,30 @@ var error = exports.error = function(x) {
* in the best way possible given the different types. * in the best way possible given the different types.
* *
* @param {Object} obj The object to print out. * @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 = { var ctx = {
showHidden: showHidden,
seen: [], 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; exports.inspect = inspect;

View File

@ -137,3 +137,15 @@ assert.doesNotThrow(function() {
hasOwnProperty: null 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);