Permalink
Browse files

doc: more realistic custom inspect example

Changes the custom inspect example to a more complex object that
actually uses the parameters of the custom inspect function. I
specifically chose a wrapper of a value called a "Box" that inspects
to "Box < inner_inspect_value >".

I also want there to be documentation explaining what the code is
actually doing. E.g., the padding replacement part is to make the
inspected value line up properly when multi-line inputs are given.

I also went with having a space between the Box's brackets and the inner
value because it matches how objects work, and that should definitely be
listed as a convention somewhere in here.

Also, the convention to shorten only when depth is less than 0, not e.g.
at 0.

But I don't know how to write the documentation for that, so I'm leaving
that to somebody who reads this message.

Ref: #8442
PR-URL: #8875
Reviewed-By: Evan Lucas <evanlucas@me.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Anna Henningsen <anna@addaleax.net>
  • Loading branch information...
Havvy authored and addaleax committed Oct 1, 2016
1 parent 366fc7a commit 97dfcede2bcdf777895f911bb1366aeba942405c
Showing with 24 additions and 6 deletions.
  1. +24 −6 doc/api/util.md
@@ -286,13 +286,31 @@ invoke and use the result of when inspecting the object:
```js
const util = require('util');
const obj = { name: 'nate' };
obj[util.inspect.custom] = function(depth) {
return `{${this.name}}`;
};
class Box {
constructor(value) {
this.value = value;
}
util.inspect(obj);
// "{nate}"
inspect(depth, options) {
if (depth < 0) {
return options.stylize('[Box]', 'special');
}
const newOptions = Object.assign({}, options, {
depth: options.depth === null ? null : options.depth - 1
});
// Five space padding because that's the size of "Box< ".
const padding = ' '.repeat(5);
const inner = util.inspect(this.value, newOptions).replace(/\n/g, '\n' + padding);
return options.stylize('Box', 'special') + '< ' + inner + ' >';
}
}
const box = new Box(true);
util.inspect(box);
// "Box< true >"
```
Custom `[util.inspect.custom](depth, opts)` functions typically return a string

0 comments on commit 97dfced

Please sign in to comment.