doc: minor improvements to util.md

PR-URL: https://github.com/nodejs/node/pull/6932
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Robert Jefe Lindstaedt <robert.lindstaedt@gmail.com>
Reviewed-By: Brian White <mscdex@mscdex.net>
This commit is contained in:
Sakthipriyan Vairamani 2016-05-24 00:44:14 +05:30
parent ead6c2d5bb
commit 435e673efd

View File

@ -19,12 +19,13 @@ const util = require('util');
The `util.debuglog()` method is used to create a function that conditionally The `util.debuglog()` method is used to create a function that conditionally
writes debug messages to `stderr` based on the existence of the `NODE_DEBUG` writes debug messages to `stderr` based on the existence of the `NODE_DEBUG`
environment variable. If the `section` name appears within the value of that environment variable. If the `section` name appears within the value of that
environment variable, then the returned function operate similar to environment variable, then the returned function operates similar to
`console.error()`. If not, then the returned function is a no-op. `console.error()`. If not, then the returned function is a no-op.
For example: For example:
```js ```js
const util = require('util');
const debuglog = util.debuglog('foo'); const debuglog = util.debuglog('foo');
debuglog('hello from foo [%d]', 123); debuglog('hello from foo [%d]', 123);
@ -46,7 +47,7 @@ environment variable. For example: `NODE_DEBUG=fs,net,tls`.
## util.deprecate(function, string) ## util.deprecate(function, string)
The `util.deprecate()` method wraps the given `function` in such a way that The `util.deprecate()` method wraps the given `function` in such a way that
marks it as being deprecated. it is marked as deprecated.
```js ```js
const util = require('util'); const util = require('util');
@ -58,10 +59,10 @@ exports.puts = util.deprecate(() => {
}, 'util.puts: Use console.log instead'); }, 'util.puts: Use console.log instead');
``` ```
When called, `util.deprecated()` will return a function that will emit a When called, `util.deprecate()` will return a function that will emit a
`DeprecationWarning` using the `process.on('warning')` event. By default, `DeprecationWarning` using the `process.on('warning')` event. By default,
this warning will be emitted and printed to `stderr` exactly once the first this warning will be emitted and printed to `stderr` exactly once, the first
time that it is called. After the warning is emitted, the wrapped `function` time it is called. After the warning is emitted, the wrapped `function`
is called. is called.
If either the `--no-deprecation` or `--no-warnings` command line flags are If either the `--no-deprecation` or `--no-warnings` command line flags are
@ -106,10 +107,10 @@ util.format('%s:%s', 'foo');
// Returns 'foo:%s' // Returns 'foo:%s'
``` ```
If there are more arguments passed to the `util.format()` method than there are If there are more arguments passed to the `util.format()` method than the
placeholders, the extra arguments are coerced into strings (for objects and number of placeholders, the extra arguments are coerced into strings (for
symbols, `util.inspect()` is used) then concatenated to the returned string, objects and symbols, `util.inspect()` is used) then concatenated to the
delimited by a space. returned string, each delimited by a space.
```js ```js
util.format('%s:%s', 'foo', 'bar', 'baz'); // 'foo:bar baz' util.format('%s:%s', 'foo', 'bar', 'baz'); // 'foo:bar baz'
@ -125,7 +126,7 @@ util.format(1, 2, 3); // '1 2 3'
## util.inherits(constructor, superConstructor) ## util.inherits(constructor, superConstructor)
_Note: usage of util.inherits() is discouraged. Please use the ES6 `class` and _Note: usage of `util.inherits()` is discouraged. Please use the ES6 `class` and
`extends` keywords to get language level inheritance support. Also note that `extends` keywords to get language level inheritance support. Also note that
the two styles are [semantically incompatible][]._ the two styles are [semantically incompatible][]._
@ -153,7 +154,7 @@ MyStream.prototype.write = function(data) {
this.emit('data', data); this.emit('data', data);
} }
var stream = new MyStream(); const stream = new MyStream();
console.log(stream instanceof EventEmitter); // true console.log(stream instanceof EventEmitter); // true
console.log(MyStream.super_ === EventEmitter); // true console.log(MyStream.super_ === EventEmitter); // true
@ -168,12 +169,11 @@ stream.write('It works!'); // Received data: "It works!"
* `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 and * `showHidden` {boolean} If `true`, the `object`'s non-enumerable symbols and
symbol properties will be included in the formatted result. Defaults to properties will be included in the formatted result. Defaults to `false`.
`false`. * `depth` {number} Specifies the number of times to recurse while formatting
* `depth` (number) Specifies how many times to recurse while formatting the the `object`. This is useful for inspecting large complicated objects.
`object`. This is useful for inspecting large complicated objects. Defaults Defaults to `2`. To make it recurse indefinitely pass `null`.
to `2`. To make it recurse indefinitely pass `null`.
* `colors` {boolean} If `true`, the output will be styled with ANSI color * `colors` {boolean} If `true`, the output will be styled with ANSI color
codes. Defaults to `false`. Colors are customizable, see codes. Defaults to `false`. Colors are customizable, see
[Customizing `util.inspect` colors][]. [Customizing `util.inspect` colors][].
@ -181,7 +181,7 @@ stream.write('It works!'); // Received data: "It works!"
functions exported on the `object` being inspected will not be called. functions exported on the `object` being inspected will not be called.
Defaults to `true`. Defaults to `true`.
* `showProxy` {boolean} If `true`, then objects and functions that are * `showProxy` {boolean} If `true`, then objects and functions that are
`Proxy` objects will be introspected to show their `target` and `hander` `Proxy` objects will be introspected to show their `target` and `handler`
objects. Defaults to `false`. objects. Defaults to `false`.
* `maxArrayLength` {number} Specifies the maximum number of array and * `maxArrayLength` {number} Specifies the maximum number of array and
`TypedArray` elements to include when formatting. Defaults to `100`. Set to `TypedArray` elements to include when formatting. Defaults to `100`. Set to
@ -243,7 +243,7 @@ Objects may also define their own `inspect(depth, opts)` function that
```js ```js
const util = require('util'); const util = require('util');
var obj = { name: 'nate' }; const obj = { name: 'nate' };
obj.inspect = function(depth) { obj.inspect = function(depth) {
return `{${this.name}}`; return `{${this.name}}`;
}; };
@ -257,7 +257,9 @@ return a value of any type that will be formatted accordingly by
`util.inspect()`. `util.inspect()`.
```js ```js
var obj = { foo: 'this will not show up in the inspect() output' }; const util = require('util');
const obj = { foo: 'this will not show up in the inspect() output' };
obj.inspect = function(depth) { obj.inspect = function(depth) {
return { bar: 'baz' }; return { bar: 'baz' };
}; };
@ -300,11 +302,11 @@ Returns `true` if the given `object` is an `Array`. Otherwise, returns `false`.
```js ```js
const util = require('util'); const util = require('util');
util.isArray([]) util.isArray([]);
// true // true
util.isArray(new Array) util.isArray(new Array);
// true // true
util.isArray({}) util.isArray({});
// false // false
``` ```
@ -319,11 +321,11 @@ Returns `true` if the given `object` is a `Boolean`. Otherwise, returns `false`.
```js ```js
const util = require('util'); const util = require('util');
util.isBoolean(1) util.isBoolean(1);
// false // false
util.isBoolean(0) util.isBoolean(0);
// false // false
util.isBoolean(false) util.isBoolean(false);
// true // true
``` ```
@ -338,11 +340,11 @@ Returns `true` if the given `object` is a `Buffer`. Otherwise, returns `false`.
```js ```js
const util = require('util'); const util = require('util');
util.isBuffer({ length: 0 }) util.isBuffer({ length: 0 });
// false // false
util.isBuffer([]) util.isBuffer([]);
// false // false
util.isBuffer(Buffer.from('hello world')) util.isBuffer(Buffer.from('hello world'));
// true // true
``` ```
@ -357,11 +359,11 @@ Returns `true` if the given `object` is a `Date`. Otherwise, returns `false`.
```js ```js
const util = require('util'); const util = require('util');
util.isDate(new Date()) util.isDate(new Date());
// true // true
util.isDate(Date()) util.isDate(Date());
// false (without 'new' returns a String) // false (without 'new' returns a String)
util.isDate({}) util.isDate({});
// false // false
``` ```
@ -377,11 +379,11 @@ Returns `true` if the given `object` is an [`Error`][]. Otherwise, returns
```js ```js
const util = require('util'); const util = require('util');
util.isError(new Error()) util.isError(new Error());
// true // true
util.isError(new TypeError()) util.isError(new TypeError());
// true // true
util.isError({ name: 'Error', message: 'an error occurred' }) util.isError({ name: 'Error', message: 'an error occurred' });
// false // false
``` ```
@ -413,13 +415,13 @@ Returns `true` if the given `object` is a `Function`. Otherwise, returns
const util = require('util'); const util = require('util');
function Foo() {} function Foo() {}
var Bar = function() {}; const Bar = function() {};
util.isFunction({}) util.isFunction({});
// false // false
util.isFunction(Foo) util.isFunction(Foo);
// true // true
util.isFunction(Bar) util.isFunction(Bar);
// true // true
``` ```
@ -435,11 +437,11 @@ Returns `true` if the given `object` is strictly `null`. Otherwise, returns
```js ```js
const util = require('util'); const util = require('util');
util.isNull(0) util.isNull(0);
// false // false
util.isNull(undefined) util.isNull(undefined);
// false // false
util.isNull(null) util.isNull(null);
// true // true
``` ```
@ -455,11 +457,11 @@ returns `false`.
```js ```js
const util = require('util'); const util = require('util');
util.isNullOrUndefined(0) util.isNullOrUndefined(0);
// false // false
util.isNullOrUndefined(undefined) util.isNullOrUndefined(undefined);
// true // true
util.isNullOrUndefined(null) util.isNullOrUndefined(null);
// true // true
``` ```
@ -474,13 +476,13 @@ Returns `true` if the given `object` is a `Number`. Otherwise, returns `false`.
```js ```js
const util = require('util'); const util = require('util');
util.isNumber(false) util.isNumber(false);
// false // false
util.isNumber(Infinity) util.isNumber(Infinity);
// true // true
util.isNumber(0) util.isNumber(0);
// true // true
util.isNumber(NaN) util.isNumber(NaN);
// true // true
``` ```
@ -496,13 +498,13 @@ Returns `true` if the given `object` is strictly an `Object` __and__ not a
```js ```js
const util = require('util'); const util = require('util');
util.isObject(5) util.isObject(5);
// false // false
util.isObject(null) util.isObject(null);
// false // false
util.isObject({}) util.isObject({});
// true // true
util.isObject(function(){}) util.isObject(function(){});
// false // false
``` ```
@ -518,23 +520,23 @@ Returns `true` if the given `object` is a primitive type. Otherwise, returns
```js ```js
const util = require('util'); const util = require('util');
util.isPrimitive(5) util.isPrimitive(5);
// true // true
util.isPrimitive('foo') util.isPrimitive('foo');
// true // true
util.isPrimitive(false) util.isPrimitive(false);
// true // true
util.isPrimitive(null) util.isPrimitive(null);
// true // true
util.isPrimitive(undefined) util.isPrimitive(undefined);
// true // true
util.isPrimitive({}) util.isPrimitive({});
// false // false
util.isPrimitive(function() {}) util.isPrimitive(function() {});
// false // false
util.isPrimitive(/^$/) util.isPrimitive(/^$/);
// false // false
util.isPrimitive(new Date()) util.isPrimitive(new Date());
// false // false
``` ```
@ -549,11 +551,11 @@ Returns `true` if the given `object` is a `RegExp`. Otherwise, returns `false`.
```js ```js
const util = require('util'); const util = require('util');
util.isRegExp(/some regexp/) util.isRegExp(/some regexp/);
// true // true
util.isRegExp(new RegExp('another regexp')) util.isRegExp(new RegExp('another regexp'));
// true // true
util.isRegExp({}) util.isRegExp({});
// false // false
``` ```
@ -568,13 +570,13 @@ Returns `true` if the given `object` is a `string`. Otherwise, returns `false`.
```js ```js
const util = require('util'); const util = require('util');
util.isString('') util.isString('');
// true // true
util.isString('foo') util.isString('foo');
// true // true
util.isString(String('foo')) util.isString(String('foo'));
// true // true
util.isString(5) util.isString(5);
// false // false
``` ```
@ -589,11 +591,11 @@ Returns `true` if the given `object` is a `Symbol`. Otherwise, returns `false`.
```js ```js
const util = require('util'); const util = require('util');
util.isSymbol(5) util.isSymbol(5);
// false // false
util.isSymbol('foo') util.isSymbol('foo');
// false // false
util.isSymbol(Symbol('foo')) util.isSymbol(Symbol('foo'));
// true // true
``` ```
@ -608,12 +610,12 @@ Returns `true` if the given `object` is `undefined`. Otherwise, returns `false`.
```js ```js
const util = require('util'); const util = require('util');
var foo; const foo = undefined;
util.isUndefined(5) util.isUndefined(5);
// false // false
util.isUndefined(foo) util.isUndefined(foo);
// true // true
util.isUndefined(null) util.isUndefined(null);
// false // false
``` ```
@ -627,7 +629,7 @@ The `util.log()` method prints the given `string` to `stdout` with an included
timestamp. timestamp.
```js ```js
const util = require('util') const util = require('util');
util.log('Timestamped message.'); util.log('Timestamped message.');
``` ```