Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

More realistic custom inspect example #8875

Closed
wants to merge 2 commits into from
Closed

More realistic custom inspect example #8875

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
bc57bc8
docs: more realistic custom inspect example
Havvy Oct 1, 2016
ad9ef92
use " ".repeat in custom util.inspect example
Havvy Oct 2, 2016
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
30 changes: 24 additions & 6 deletions doc/api/util.md
View file
Open in desktop
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;
}
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I’m not sure, so this is just a suggestion, but maybe leaving the “simpler” example first would be helpful? The Box example is good but maybe a bit overwhelming on the first look?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If we keep it, then I'd argue that we'd want to also add text saying it's a minimal example.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@Havvy Agreed. Maybe subheadings that say something like:

A simple example

A more realistic example


util.inspect(obj);
// "{nate}"
inspect(depth, options) {
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@addaleax ... what do you think.. should this be modified to use the new symbol you introduced as an alternative to using inspect directly?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@jasnell We could do that, but the motivation for introducing the symbol-based alternative were objects that have a regular inspect property which would conflict with what Node expects, and that doesn’t really apply to this use case. And as long as v4.x is supported, just using inspect is probably what I would do here, too. (But yeah, it’s hard to explain that situation concisely in an example).

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@Havvy .. as a suggestion per @fhinkel's request, a code comment in here that describes the basic flow would be helpful.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Will do when I have time and energy.

if (depth < 0) {
return options.stylize('[Box]', 'special');
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@Havvy ... likewise here, a comment that describes briefly what options.stylize does.

}

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);
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

And a comment here about what this call to util.inspect is for.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Will do when I have time and energy.

return options.stylize('Box', 'special') + '< ' + inner + ' >';
Copy link
Member

@jasnell jasnell Oct 6, 2016 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I know I already signed off on this but, just as a very minor nit, this could be slightly simplified to:

return `${options.stylize('Box', 'special')}<${inner}>`;

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I am not sure I’d find that more readable… long expressions inside ${} are a bit weird imho.

So, maybe options.stylize('Box', 'special') + < ${inner} >;?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do we really want to mix quasiquoting and string concatenation together?

Seems like any option we go with (other than just string concatenation IMO) looks weird.

}
}

const box = new Box(true);

util.inspect(box);
// "Box< true >"
```

Custom `[util.inspect.custom](depth, opts)` functions typically return a string
Expand Down