Skip to content

Commit

Permalink
doc: minor improvements to util.md
Browse files Browse the repository at this point in the history 
PR-URL: #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>
  • Loading branch information
@thefourtheye
thefourtheye committed May 29, 2016
1 parent ead6c2d commit 435e673
Showing 1 changed file with 79 additions and 77 deletions.
156 changes: 79 additions & 77 deletions doc/api/util.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -19,12 +19,13 @@ const util = require('util');
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`
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.

For example:

```js
const util = require('util');
const debuglog = util.debuglog('foo');

debuglog('hello from foo [%d]', 123);
Expand All @@ -46,7 +47,7 @@ environment variable. For example: `NODE_DEBUG=fs,net,tls`.
## util.deprecate(function, string)

The `util.deprecate()` method wraps the given `function` in such a way that
marks it as being deprecated.
it is marked as deprecated.

```js
const util = require('util');
Expand All @@ -58,10 +59,10 @@ exports.puts = util.deprecate(() => {
}, '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,
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`
this warning will be emitted and printed to `stderr` exactly once, the first
time it is called. After the warning is emitted, the wrapped `function`
is called.

If either the `--no-deprecation` or `--no-warnings` command line flags are
Expand Down Expand Up @@ -106,10 +107,10 @@ util.format('%s:%s', 'foo');
// Returns 'foo:%s'
```

If there are more arguments passed to the `util.format()` method than there are
placeholders, the extra arguments are coerced into strings (for objects and
symbols, `util.inspect()` is used) then concatenated to the returned string,
delimited by a space.
If there are more arguments passed to the `util.format()` method than the
number of placeholders, the extra arguments are coerced into strings (for
objects and symbols, `util.inspect()` is used) then concatenated to the
returned string, each delimited by a space.

```js
util.format('%s:%s', 'foo', 'bar', 'baz'); // 'foo:bar baz'
Expand All @@ -125,7 +126,7 @@ util.format(1, 2, 3); // '1 2 3'

## 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
the two styles are [semantically incompatible][]._

Expand Down Expand Up @@ -153,7 +154,7 @@ MyStream.prototype.write = function(data) {
this.emit('data', data);
}

var stream = new MyStream();
const stream = new MyStream();

console.log(stream instanceof EventEmitter); // true
console.log(MyStream.super_ === EventEmitter); // true
Expand All @@ -168,20 +169,19 @@ stream.write('It works!'); // Received data: "It works!"

* `object` {any} Any JavaScript primitive or Object.
* `options` {Object}
* `showHidden` {boolean} If `true`, the `object`'s non-enumerable and
symbol properties will be included in the formatted result. Defaults to
`false`.
* `depth` (number) Specifies how many times to recurse while formatting the
`object`. This is useful for inspecting large complicated objects. Defaults
to `2`. To make it recurse indefinitely pass `null`.
* `showHidden` {boolean} If `true`, the `object`'s non-enumerable symbols and
properties will be included in the formatted result. Defaults to `false`.
* `depth` {number} Specifies the number of times to recurse while formatting
the `object`. This is useful for inspecting large complicated objects.
Defaults to `2`. To make it recurse indefinitely pass `null`.
* `colors` {boolean} If `true`, the output will be styled with ANSI color
codes. Defaults to `false`. Colors are customizable, see
[Customizing `util.inspect` colors][].
* `customInspect` {boolean} If `false`, then custom `inspect(depth, opts)`
functions exported on the `object` being inspected will not be called.
Defaults to `true`.
* `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`.
* `maxArrayLength` {number} Specifies the maximum number of array and
`TypedArray` elements to include when formatting. Defaults to `100`. Set to
Expand Down Expand Up @@ -243,7 +243,7 @@ Objects may also define their own `inspect(depth, opts)` function that
```js
const util = require('util');

var obj = { name: 'nate' };
const obj = { name: 'nate' };
obj.inspect = function(depth) {
return `{${this.name}}`;
};
Expand All @@ -257,7 +257,9 @@ return a value of any type that will be formatted accordingly by
`util.inspect()`.

```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) {
return { bar: 'baz' };
};
Expand Down Expand Up @@ -300,11 +302,11 @@ Returns `true` if the given `object` is an `Array`. Otherwise, returns `false`.
```js
const util = require('util');

util.isArray([])
util.isArray([]);
// true
util.isArray(new Array)
util.isArray(new Array);
// true
util.isArray({})
util.isArray({});
// false
```

Expand All @@ -319,11 +321,11 @@ Returns `true` if the given `object` is a `Boolean`. Otherwise, returns `false`.
```js
const util = require('util');

util.isBoolean(1)
util.isBoolean(1);
// false
util.isBoolean(0)
util.isBoolean(0);
// false
util.isBoolean(false)
util.isBoolean(false);
// true
```

Expand All @@ -338,11 +340,11 @@ Returns `true` if the given `object` is a `Buffer`. Otherwise, returns `false`.
```js
const util = require('util');

util.isBuffer({ length: 0 })
util.isBuffer({ length: 0 });
// false
util.isBuffer([])
util.isBuffer([]);
// false
util.isBuffer(Buffer.from('hello world'))
util.isBuffer(Buffer.from('hello world'));
// true
```

Expand All @@ -357,11 +359,11 @@ Returns `true` if the given `object` is a `Date`. Otherwise, returns `false`.
```js
const util = require('util');

util.isDate(new Date())
util.isDate(new Date());
// true
util.isDate(Date())
util.isDate(Date());
// false (without 'new' returns a String)
util.isDate({})
util.isDate({});
// false
```

Expand All @@ -377,11 +379,11 @@ Returns `true` if the given `object` is an [`Error`][]. Otherwise, returns
```js
const util = require('util');

util.isError(new Error())
util.isError(new Error());
// true
util.isError(new TypeError())
util.isError(new TypeError());
// true
util.isError({ name: 'Error', message: 'an error occurred' })
util.isError({ name: 'Error', message: 'an error occurred' });
// false
```

Expand Down Expand Up @@ -413,13 +415,13 @@ Returns `true` if the given `object` is a `Function`. Otherwise, returns
const util = require('util');

function Foo() {}
var Bar = function() {};
const Bar = function() {};

util.isFunction({})
util.isFunction({});
// false
util.isFunction(Foo)
util.isFunction(Foo);
// true
util.isFunction(Bar)
util.isFunction(Bar);
// true
```

Expand All @@ -435,11 +437,11 @@ Returns `true` if the given `object` is strictly `null`. Otherwise, returns
```js
const util = require('util');

util.isNull(0)
util.isNull(0);
// false
util.isNull(undefined)
util.isNull(undefined);
// false
util.isNull(null)
util.isNull(null);
// true
```

Expand All @@ -455,11 +457,11 @@ returns `false`.
```js
const util = require('util');

util.isNullOrUndefined(0)
util.isNullOrUndefined(0);
// false
util.isNullOrUndefined(undefined)
util.isNullOrUndefined(undefined);
// true
util.isNullOrUndefined(null)
util.isNullOrUndefined(null);
// true
```

Expand All @@ -474,13 +476,13 @@ Returns `true` if the given `object` is a `Number`. Otherwise, returns `false`.
```js
const util = require('util');

util.isNumber(false)
util.isNumber(false);
// false
util.isNumber(Infinity)
util.isNumber(Infinity);
// true
util.isNumber(0)
util.isNumber(0);
// true
util.isNumber(NaN)
util.isNumber(NaN);
// true
```

Expand All @@ -496,13 +498,13 @@ Returns `true` if the given `object` is strictly an `Object` __and__ not a
```js
const util = require('util');

util.isObject(5)
util.isObject(5);
// false
util.isObject(null)
util.isObject(null);
// false
util.isObject({})
util.isObject({});
// true
util.isObject(function(){})
util.isObject(function(){});
// false
```

Expand All @@ -518,23 +520,23 @@ Returns `true` if the given `object` is a primitive type. Otherwise, returns
```js
const util = require('util');

util.isPrimitive(5)
util.isPrimitive(5);
// true
util.isPrimitive('foo')
util.isPrimitive('foo');
// true
util.isPrimitive(false)
util.isPrimitive(false);
// true
util.isPrimitive(null)
util.isPrimitive(null);
// true
util.isPrimitive(undefined)
util.isPrimitive(undefined);
// true
util.isPrimitive({})
util.isPrimitive({});
// false
util.isPrimitive(function() {})
util.isPrimitive(function() {});
// false
util.isPrimitive(/^$/)
util.isPrimitive(/^$/);
// false
util.isPrimitive(new Date())
util.isPrimitive(new Date());
// false
```

Expand All @@ -549,11 +551,11 @@ Returns `true` if the given `object` is a `RegExp`. Otherwise, returns `false`.
```js
const util = require('util');

util.isRegExp(/some regexp/)
util.isRegExp(/some regexp/);
// true
util.isRegExp(new RegExp('another regexp'))
util.isRegExp(new RegExp('another regexp'));
// true
util.isRegExp({})
util.isRegExp({});
// false
```

Expand All @@ -568,13 +570,13 @@ Returns `true` if the given `object` is a `string`. Otherwise, returns `false`.
```js
const util = require('util');

util.isString('')
util.isString('');
// true
util.isString('foo')
util.isString('foo');
// true
util.isString(String('foo'))
util.isString(String('foo'));
// true
util.isString(5)
util.isString(5);
// false
```

Expand All @@ -589,11 +591,11 @@ Returns `true` if the given `object` is a `Symbol`. Otherwise, returns `false`.
```js
const util = require('util');

util.isSymbol(5)
util.isSymbol(5);
// false
util.isSymbol('foo')
util.isSymbol('foo');
// false
util.isSymbol(Symbol('foo'))
util.isSymbol(Symbol('foo'));
// true
```

Expand All @@ -608,12 +610,12 @@ Returns `true` if the given `object` is `undefined`. Otherwise, returns `false`.
```js
const util = require('util');

var foo;
util.isUndefined(5)
const foo = undefined;
util.isUndefined(5);
// false
util.isUndefined(foo)
util.isUndefined(foo);
// true
util.isUndefined(null)
util.isUndefined(null);
// false
```

Expand All @@ -627,7 +629,7 @@ The `util.log()` method prints the given `string` to `stdout` with an included
timestamp.

```js
const util = require('util')
const util = require('util');

util.log('Timestamped message.');
```
Expand Down

0 comments on commit 435e673

Please sign in to comment.