Skip to content

Commit

Permalink
doc: more realistic custom inspect example
Browse files Browse the repository at this point in the history
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 Myles Borins committed Nov 17, 2016
1 parent 6ed99a1 commit 6f113b0
Showing 1 changed file with 24 additions and 6 deletions.
30 changes: 24 additions & 6 deletions doc/api/util.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down

0 comments on commit 6f113b0

Please sign in to comment.