From 435e673efdfa24a0446ff1e93fa3baa19437f335 Mon Sep 17 00:00:00 2001 From: Sakthipriyan Vairamani Date: Tue, 24 May 2016 00:44:14 +0530 Subject: [PATCH] doc: minor improvements to util.md PR-URL: https://github.com/nodejs/node/pull/6932 Reviewed-By: James M Snell Reviewed-By: Robert Jefe Lindstaedt Reviewed-By: Brian White --- doc/api/util.md | 156 ++++++++++++++++++++++++------------------------ 1 file changed, 79 insertions(+), 77 deletions(-) diff --git a/doc/api/util.md b/doc/api/util.md index 893d0de4eb..f1245993f0 100644 --- a/doc/api/util.md +++ b/doc/api/util.md @@ -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); @@ -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'); @@ -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 @@ -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' @@ -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][]._ @@ -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 @@ -168,12 +169,11 @@ 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][]. @@ -181,7 +181,7 @@ stream.write('It works!'); // Received data: "It works!" 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 @@ -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}}`; }; @@ -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' }; }; @@ -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 ``` @@ -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 ``` @@ -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 ``` @@ -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 ``` @@ -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 ``` @@ -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 ``` @@ -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 ``` @@ -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 ``` @@ -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 ``` @@ -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 ``` @@ -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 ``` @@ -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 ``` @@ -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 ``` @@ -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 ``` @@ -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 ``` @@ -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.'); ```