mirror of
https://github.com/nodejs/node.git
synced 2024-12-01 16:10:02 +01:00
230 lines
6.4 KiB
Markdown
230 lines
6.4 KiB
Markdown
# util
|
|
|
|
Stability: 4 - API Frozen
|
|
|
|
These functions are in the module `'util'`. Use `require('util')` to access
|
|
them.
|
|
|
|
|
|
## util.format(format, [...])
|
|
|
|
Returns a formatted string using the first argument as a `printf`-like format.
|
|
|
|
The first argument is a string that contains zero or more *placeholders*.
|
|
Each placeholder is replaced with the converted value from its corresponding
|
|
argument. Supported placeholders are:
|
|
|
|
* `%s` - String.
|
|
* `%d` - Number (both integer and float).
|
|
* `%j` - JSON.
|
|
* `%%` - single percent sign (`'%'`). This does not consume an argument.
|
|
|
|
If the placeholder does not have a corresponding argument, the placeholder is
|
|
not replaced.
|
|
|
|
util.format('%s:%s', 'foo'); // 'foo:%s'
|
|
|
|
If there are more arguments than placeholders, the extra arguments are
|
|
converted to strings with `util.inspect()` and these strings are concatenated,
|
|
delimited by a space.
|
|
|
|
util.format('%s:%s', 'foo', 'bar', 'baz'); // 'foo:bar baz'
|
|
|
|
If the first argument is not a format string then `util.format()` returns
|
|
a string that is the concatenation of all its arguments separated by spaces.
|
|
Each argument is converted to a string with `util.inspect()`.
|
|
|
|
util.format(1, 2, 3); // '1 2 3'
|
|
|
|
|
|
## util.debug(string)
|
|
|
|
A synchronous output function. Will block the process and
|
|
output `string` immediately to `stderr`.
|
|
|
|
require('util').debug('message on stderr');
|
|
|
|
## util.error([...])
|
|
|
|
Same as `util.debug()` except this will output all arguments immediately to
|
|
`stderr`.
|
|
|
|
## util.puts([...])
|
|
|
|
A synchronous output function. Will block the process and output all arguments
|
|
to `stdout` with newlines after each argument.
|
|
|
|
## util.print([...])
|
|
|
|
A synchronous output function. Will block the process, cast each argument to a
|
|
string then output to `stdout`. Does not place newlines after each argument.
|
|
|
|
## util.log(string)
|
|
|
|
Output with timestamp on `stdout`.
|
|
|
|
require('util').log('Timestamped message.');
|
|
|
|
|
|
## util.inspect(object, [options])
|
|
|
|
Return a string representation of `object`, which is useful for debugging.
|
|
|
|
An optional *options* object may be passed that alters certain aspects of the
|
|
formatted string:
|
|
|
|
- `showHidden` - if `true` then the object's non-enumerable properties will be
|
|
shown too. Defaults to `false`.
|
|
|
|
- `depth` - tells `inspect` 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`.
|
|
|
|
- `colors` - if `true`, then the output will be styled with ANSI color codes.
|
|
Defaults to `false`. Colors are customizable, see below.
|
|
|
|
- `customInspect` - if `false`, then custom `inspect()` functions defined on the
|
|
objects being inspected won't be called. Defaults to `true`.
|
|
|
|
Example of inspecting all properties of the `util` object:
|
|
|
|
var util = require('util');
|
|
|
|
console.log(util.inspect(util, { showHidden: true, depth: null }));
|
|
|
|
### Customizing `util.inspect` colors
|
|
|
|
Color output (if enabled) of `util.inspect` is customizable globally
|
|
via `util.inspect.styles` and `util.inspect.colors` objects.
|
|
|
|
`util.inspect.styles` is a map assigning each style a color
|
|
from `util.inspect.colors`.
|
|
Highlighted styles and their default values are:
|
|
* `number` (yellow)
|
|
* `boolean` (yellow)
|
|
* `string` (green)
|
|
* `date` (magenta)
|
|
* `regexp` (red)
|
|
* `null` (bold)
|
|
* `undefined` (grey)
|
|
* `special` - only function at this time (cyan)
|
|
* `name` (intentionally no styling)
|
|
|
|
Predefined color codes are: `white`, `grey`, `black`, `blue`, `cyan`,
|
|
`green`, `magenta`, `red` and `yellow`.
|
|
There are also `bold`, `italic`, `underline` and `inverse` codes.
|
|
|
|
Objects also may define their own `inspect(depth)` function which `util.inspect()`
|
|
will invoke and use the result of when inspecting the object:
|
|
|
|
var util = require('util');
|
|
|
|
var obj = { name: 'nate' };
|
|
obj.inspect = function(depth) {
|
|
return '{' + this.name + '}';
|
|
};
|
|
|
|
util.inspect(obj);
|
|
// "{nate}"
|
|
|
|
|
|
## util.isArray(object)
|
|
|
|
Returns `true` if the given "object" is an `Array`. `false` otherwise.
|
|
|
|
var util = require('util');
|
|
|
|
util.isArray([])
|
|
// true
|
|
util.isArray(new Array)
|
|
// true
|
|
util.isArray({})
|
|
// false
|
|
|
|
|
|
## util.isRegExp(object)
|
|
|
|
Returns `true` if the given "object" is a `RegExp`. `false` otherwise.
|
|
|
|
var util = require('util');
|
|
|
|
util.isRegExp(/some regexp/)
|
|
// true
|
|
util.isRegExp(new RegExp('another regexp'))
|
|
// true
|
|
util.isRegExp({})
|
|
// false
|
|
|
|
|
|
## util.isDate(object)
|
|
|
|
Returns `true` if the given "object" is a `Date`. `false` otherwise.
|
|
|
|
var util = require('util');
|
|
|
|
util.isDate(new Date())
|
|
// true
|
|
util.isDate(Date())
|
|
// false (without 'new' returns a String)
|
|
util.isDate({})
|
|
// false
|
|
|
|
|
|
## util.isError(object)
|
|
|
|
Returns `true` if the given "object" is an `Error`. `false` otherwise.
|
|
|
|
var util = require('util');
|
|
|
|
util.isError(new Error())
|
|
// true
|
|
util.isError(new TypeError())
|
|
// true
|
|
util.isError({ name: 'Error', message: 'an error occurred' })
|
|
// false
|
|
|
|
|
|
## util.pump(readableStream, writableStream, [callback])
|
|
|
|
Stability: 0 - Deprecated: Use readableStream.pipe(writableStream)
|
|
|
|
Read the data from `readableStream` and send it to the `writableStream`.
|
|
When `writableStream.write(data)` returns `false` `readableStream` will be
|
|
paused until the `drain` event occurs on the `writableStream`. `callback` gets
|
|
an error as its only argument and is called when `writableStream` is closed or
|
|
when an error occurs.
|
|
|
|
|
|
## util.inherits(constructor, superConstructor)
|
|
|
|
Inherit the prototype methods from one
|
|
[constructor](https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Object/constructor)
|
|
into another. The prototype of `constructor` will be set to a new
|
|
object created from `superConstructor`.
|
|
|
|
As an additional convenience, `superConstructor` will be accessible
|
|
through the `constructor.super_` property.
|
|
|
|
var util = require("util");
|
|
var events = require("events");
|
|
|
|
function MyStream() {
|
|
events.EventEmitter.call(this);
|
|
}
|
|
|
|
util.inherits(MyStream, events.EventEmitter);
|
|
|
|
MyStream.prototype.write = function(data) {
|
|
this.emit("data", data);
|
|
}
|
|
|
|
var stream = new MyStream();
|
|
|
|
console.log(stream instanceof events.EventEmitter); // true
|
|
console.log(MyStream.super_ === events.EventEmitter); // true
|
|
|
|
stream.on("data", function(data) {
|
|
console.log('Received data: "' + data + '"');
|
|
})
|
|
stream.write("It works!"); // Received data: "It works!"
|