1berry/nodejs
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

doc: edit and simplify util.inspect() docs

Browse Source 
PR-URL: https://github.com/nodejs/node/pull/25195
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de>
This commit is contained in:
cjihrig 2018-12-23 13:37:35 -05:00
parent ee12607c1c
commit 3c5e2372db
No known key found for this signature in database
GPG Key ID: 7434390BDBE9B9C5
1 changed files with 36 additions and 42 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

78
doc/api/util.md
View File

@ -432,22 +432,21 @@ changes:
* `object` {any} Any JavaScript primitive or `Object`. * `object` {any} Any JavaScript primitive or `Object`.
* `options` {Object} * `options` {Object}
* `showHidden` {boolean} If `true`, the `object`'s non-enumerable symbols and * `showHidden` {boolean} If `true`, `object`'s non-enumerable symbols and
properties will be included in the formatted result as well as [`WeakMap`][] properties are included in the formatted result. [`WeakMap`][] and
and [`WeakSet`][] entries. **Default:** `false`. [`WeakSet`][] entries are also included. **Default:** `false`.
* `depth` {number} Specifies the number of times to recurse while formatting * `depth` {number} Specifies the number of times to recurse while formatting
the `object`. This is useful for inspecting large complicated objects. To `object`. This is useful for inspecting large objects. To recurse up to
make it recurse up to the maximum call stack size pass `Infinity` or `null`. the maximum call stack size pass `Infinity` or `null`.
**Default:** `2`. **Default:** `2`.
* `colors` {boolean} If `true`, the output will be styled with ANSI color * `colors` {boolean} If `true`, the output is styled with ANSI color
codes. Colors are customizable, see [Customizing `util.inspect` colors][]. codes. Colors are customizable. See [Customizing `util.inspect` colors][].
**Default:** `false`. **Default:** `false`.
* `customInspect` {boolean} If `false`, then * `customInspect` {boolean} If `false`,
`[util.inspect.custom](depth, opts)` functions will not be called. `[util.inspect.custom](depth, opts)` functions are not invoked.
**Default:** `true`. **Default:** `true`.
* `showProxy` {boolean} If `true`, then objects and functions that are * `showProxy` {boolean} If `true`, `Proxy` inspection includes
`Proxy` objects will be introspected to show their `target` and `handler` the [`target` and `handler`][] objects. **Default:** `false`.
objects. **Default:** `false`.
* `maxArrayLength` {integer} Specifies the maximum number of `Array`, * `maxArrayLength` {integer} Specifies the maximum number of `Array`,
[`TypedArray`][], [`WeakMap`][] and [`WeakSet`][] elements to include when [`TypedArray`][], [`WeakMap`][] and [`WeakSet`][] elements to include when
formatting. Set to `null` or `Infinity` to show all elements. Set to `0` or formatting. Set to `null` or `Infinity` to show all elements. Set to `0` or
@ -455,28 +454,26 @@ changes:
* `breakLength` {integer} The length at which an object's keys are split * `breakLength` {integer} The length at which an object's keys are split
across multiple lines. Set to `Infinity` to format an object as a single across multiple lines. Set to `Infinity` to format an object as a single
line. **Default:** `60` for legacy compatibility. line. **Default:** `60` for legacy compatibility.
* `compact` {boolean} Setting this to `false` changes the default indentation * `compact` {boolean} Setting this to `false` causes each object key to
to use a line break for each object key instead of lining up multiple be displayed on a new line. It will also add new lines to text that is
properties in one line. It will also break text that is above the longer than `breakLength`. Note that no text will be reduced below 16
`breakLength` size into smaller and better readable chunks and indents
objects the same as arrays. Note that no text will be reduced below 16
characters, no matter the `breakLength` size. For more information, see the characters, no matter the `breakLength` size. For more information, see the
example below. **Default:** `true`. example below. **Default:** `true`.
* `sorted` {boolean|Function} If set to `true` or a function, all properties * `sorted` {boolean|Function} If set to `true` or a function, all properties
of an object and Set and Map entries will be sorted in the returned string. of an object, and `Set` and `Map` entries are sorted in the resulting
If set to `true` the [default sort][] is going to be used. If set to a string. If set to `true` the [default sort][] is used. If set to a function,
function, it is used as a [compare function][]. it is used as a [compare function][].
* `getters` {boolean|string} If set to `true`, getters are going to be * `getters` {boolean|string} If set to `true`, getters are inspected. If set
inspected as well. If set to `'get'` only getters without setter are going to `'get'`, only getters without a corresponding setter are inspected. If
to be inspected. If set to `'set'` only getters having a corresponding set to `'set'`, only getters with a corresponding setter are inspected.
setter are going to be inspected. This might cause side effects depending on This might cause side effects depending on the getter function.
the getter function. **Default:** `false`. **Default:** `false`.
* Returns: {string} The representation of passed object * Returns: {string} The representation of `object`.
The `util.inspect()` method returns a string representation of `object` that is The `util.inspect()` method returns a string representation of `object` that is
intended for debugging. The output of `util.inspect` may change at any time intended for debugging. The output of `util.inspect` may change at any time
and should not be depended upon programmatically. Additional `options` may be and should not be depended upon programmatically. Additional `options` may be
passed that alter certain aspects of the formatted string. passed that alter the result.
`util.inspect()` will use the constructor's name and/or `@@toStringTag` to make `util.inspect()` will use the constructor's name and/or `@@toStringTag` to make
an identifiable tag for an inspected value. an identifiable tag for an inspected value.
@ -504,7 +501,7 @@ const util = require('util');
console.log(util.inspect(util, { showHidden: true, depth: null })); console.log(util.inspect(util, { showHidden: true, depth: null }));
``` ```
The following example highlights the difference with the `compact` option: The following example highlights the effect of the `compact` option:
```js ```js
const util = require('util'); const util = require('util');
@ -561,13 +558,11 @@ console.log(util.inspect(o, { compact: false, depth: 5, breakLength: 80 }));
// chunks. // chunks.
``` ```
Using the `showHidden` option allows to inspect [`WeakMap`][] and [`WeakSet`][] The `showHidden` option allows [`WeakMap`][] and [`WeakSet`][] entries to be
entries. If there are more entries than `maxArrayLength`, there is no guarantee inspected. If there are more entries than `maxArrayLength`, there is no
which entries are displayed. That means retrieving the same [`WeakSet`][] guarantee which entries are displayed. That means retrieving the same
entries twice might actually result in a different output. Besides this any item [`WeakSet`][] entries twice may result in different output. Furthermore, entries
might be collected at any point of time by the garbage collector if there is no with no remaining strong references may be garbage collected at any time.
strong reference left to that object. Therefore there is no guarantee to get a
reliable output.
```js ```js
const { inspect } = require('util'); const { inspect } = require('util');
@ -580,8 +575,8 @@ console.log(inspect(weakSet, { showHidden: true }));
// WeakSet { { a: 1 }, { b: 2 } } // WeakSet { { a: 1 }, { b: 2 } }
``` ```
The `sorted` option makes sure the output is identical, no matter of the The `sorted` option ensures that an object's property insertion order does not
properties insertion order: impact the result of `util.inspect()`.
```js ```js
const { inspect } = require('util'); const { inspect } = require('util');
@ -608,11 +603,9 @@ assert.strict.equal(
); );
``` ```
Please note that `util.inspect()` is a synchronous method that is mainly `util.inspect()` is a synchronous method intended for debugging. Its maximum
intended as a debugging tool. Its maximum output length is limited to output length is approximately 128 MB. Inputs that result in longer output will
approximately 128 MB and input values that result in output bigger than that be truncated.
will not be inspected fully. Such values can have a significant performance
overhead that can block the event loop for a significant amount of time.
### Customizing `util.inspect` colors ### Customizing `util.inspect` colors
@ -2222,6 +2215,7 @@ Deprecated predecessor of `console.log`.
[`assert.deepStrictEqual()`]: assert.html#assert_assert_deepstrictequal_actual_expected_message [`assert.deepStrictEqual()`]: assert.html#assert_assert_deepstrictequal_actual_expected_message
[`console.error()`]: console.html#console_console_error_data_args [`console.error()`]: console.html#console_console_error_data_args
[`console.log()`]: console.html#console_console_log_data_args [`console.log()`]: console.html#console_console_log_data_args
[`target` and `handler`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Proxy#Terminology
[`util.format()`]: #util_util_format_format_args [`util.format()`]: #util_util_format_format_args
[`util.inspect()`]: #util_util_inspect_object_options [`util.inspect()`]: #util_util_inspect_object_options
[`util.promisify()`]: #util_util_promisify_original [`util.promisify()`]: #util_util_promisify_original