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);