Skip to content

Commit 07774e6

Browse files
committed
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 parent 5823290 commit 07774e6

File tree

3 files changed

+43
-20
lines changed

3 files changed

+43
-20
lines changed

doc/api/util.markdown

Lines changed: 11 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -66,28 +66,28 @@ Output with timestamp on `stdout`.
6666
require('util').log('Timestamped message.');
6767

6868

69-
## util.inspect(object, [showHidden], [depth], [colors])
69+
## util.inspect(object, [options])
7070

7171
Return a string representation of `object`, which is useful for debugging.
7272

73-
If `showHidden` is `true`, then the object's non-enumerable properties will be
74-
shown too. Defaults to `false`.
73+
An optional *options* object may be passed that alters certain aspects of the
74+
formatted string:
7575

76-
If `depth` is provided, it tells `inspect` how many times to recurse while
77-
formatting the object. This is useful for inspecting large complicated objects.
76+
- `showHidden` - if `true` then the object's non-enumerable properties will be
77+
shown too. Defaults to `false`.
7878

79-
The default is to only recurse twice. To make it recurse indefinitely, pass
80-
in `null` for `depth`.
79+
- `depth` - tells `inspect` how many times to recurse while formatting the
80+
object. This is useful for inspecting large complicated objects. Defaults to
81+
`2`. To make it recurse indefinitely pass `null`.
8182

82-
If `colors` is `true`, the output will be styled with ANSI color codes.
83-
Defaults to `false`.
84-
Colors are customizable, see below.
83+
- `colors` - if `true`, then the output will be styled with ANSI color codes.
84+
Defaults to `false`. Colors are customizable, see below.
8585

8686
Example of inspecting all properties of the `util` object:
8787

8888
var util = require('util');
8989

90-
console.log(util.inspect(util, true, null));
90+
console.log(util.inspect(util, { showHidden: true, depth: null }));
9191

9292
### Customizing `util.inspect` colors
9393

lib/util.js

Lines changed: 20 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -110,19 +110,30 @@ var error = exports.error = function(x) {
110110
* in the best way possible given the different types.
111111
*
112112
* @param {Object} obj The object to print out.
113-
* @param {Boolean} showHidden Flag that shows hidden (not enumerable)
114-
* properties of objects.
115-
* @param {Number} depth Depth in which to descend in object. Default is 2.
116-
* @param {Boolean} colors Flag to turn on ANSI escape codes to color the
117-
* output. Default is false (no coloring).
113+
* @param {Object} opts Optional options object that alters the output.
118114
*/
119-
function inspect(obj, showHidden, depth, colors) {
115+
function inspect(obj, opts/* legacy: showHidden, depth, colors*/) {
116+
// default options
120117
var ctx = {
121-
showHidden: showHidden,
122118
seen: [],
123-
stylize: colors ? stylizeWithColor : stylizeNoColor
119+
stylize: stylizeNoColor
124120
};
125-
return formatValue(ctx, obj, (typeof depth === 'undefined' ? 2 : depth));
121+
// legacy...
122+
if (arguments.length >= 3) ctx.depth = arguments[2];
123+
if (arguments.length >= 4) ctx.colors = arguments[3];
124+
if (typeof opts === 'boolean') {
125+
// legacy...
126+
ctx.showHidden = opts;
127+
} else if (opts) {
128+
// got an "options" object
129+
exports._extend(ctx, opts);
130+
}
131+
// set default options
132+
if (typeof ctx.showHidden === 'undefined') ctx.showHidden = false;
133+
if (typeof ctx.depth === 'undefined') ctx.depth = 2;
134+
if (typeof ctx.colors === 'undefined') ctx.colors = false;
135+
if (ctx.colors) ctx.stylize = stylizeWithColor;
136+
return formatValue(ctx, obj, ctx.depth);
126137
}
127138
exports.inspect = inspect;
128139

test/simple/test-util-inspect.js

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -137,3 +137,15 @@ assert.doesNotThrow(function() {
137137
hasOwnProperty: null
138138
});
139139
});
140+
141+
// new API, accepts an "options" object
142+
var subject = { foo: 'bar', hello: 31, a: { b: { c: { d: 0 } } } };
143+
Object.defineProperty(subject, 'hidden', { enumerable: false, value: null });
144+
145+
assert(util.inspect(subject, { showHidden: false }).indexOf('hidden') === -1);
146+
assert(util.inspect(subject, { showHidden: true }).indexOf('hidden') !== -1);
147+
assert(util.inspect(subject, { colors: false }).indexOf('\u001b[32m') === -1);
148+
assert(util.inspect(subject, { colors: true }).indexOf('\u001b[32m') !== -1);
149+
assert(util.inspect(subject, { depth: 2 }).indexOf('c: [Object]') !== -1);
150+
assert(util.inspect(subject, { depth: 0 }).indexOf('a: [Object]') !== -1);
151+
assert(util.inspect(subject, { depth: null }).indexOf('{ d: 0 }') !== -1);

0 commit comments

Comments
 (0)