| # 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!" |