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:
parent
ead6c2d5bb
commit
435e673efd
156
doc/api/util.md
156
doc/api/util.md
@ -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.');
|
||||||
```
|
```
|
||||||
|
Loading…
x
Reference in New Issue
Block a user