diff options
Diffstat (limited to 'doc/api/util.markdown')
-rw-r--r-- | doc/api/util.markdown | 111 |
1 files changed, 75 insertions, 36 deletions
diff --git a/doc/api/util.markdown b/doc/api/util.markdown index 8b34ba6658..a1bfdb0f69 100644 --- a/doc/api/util.markdown +++ b/doc/api/util.markdown @@ -2,9 +2,46 @@ Stability: 5 - Locked -These functions are in the module `'util'`. Use `require('util')` to access -them. +These functions are in the module `'util'`. Use `require('util')` to +access them. +The `util` module is primarily designed to support the needs of Node's +internal APIs. Many of these utilities are useful for your own +programs. If you find that these functions are lacking for your +purposes, however, you are encouraged to write your own utilities. We +are not interested in any future additions to the `util` module that +are unnecessary for Node's internal functionality. + +## util.debuglog(section) + +* `section` {String} The section of the program to be debugged +* Returns: {Function} The logging function + +This is used to create a function which conditionally writes to stderr +based on the existence of a `NODE_DEBUG` environment variable. If the +`section` name appears in that environment variable, then the returned +function will be similar to `console.error()`. If not, then the +returned function is a no-op. + +For example: + +```javascript +var debuglog = util.debuglog('foo'); + +var bar = 123; +debuglog('hello from foo [%d]', bar); +``` + +If this program is run with `NODE_DEBUG=foo` in the environment, then +it will output something like: + + FOO 3245: hello from foo [123] + +where `3245` is the process id. If it is not run with that +environment variable set, then it will not print anything. + +You may separate multiple `NODE_DEBUG` environment variables with a +comma. For example, `NODE_DEBUG=fs,net,tls`. ## util.format(format, [...]) @@ -37,35 +74,12 @@ 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. @@ -94,6 +108,8 @@ Example of inspecting all properties of the `util` object: ### Customizing `util.inspect` colors +<!-- type=misc --> + Color output (if enabled) of `util.inspect` is customizable globally via `util.inspect.styles` and `util.inspect.colors` objects. @@ -116,6 +132,8 @@ There are also `bold`, `italic`, `underline` and `inverse` codes. ### Custom `inspect()` function on Objects +<!-- type=misc --> + Objects also may define their own `inspect(depth)` function which `util.inspect()` will invoke and use the result of when inspecting the object: @@ -198,17 +216,6 @@ Returns `true` if the given "object" is an `Error`. `false` otherwise. // 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 @@ -241,3 +248,35 @@ through the `constructor.super_` property. console.log('Received data: "' + data + '"'); }) stream.write("It works!"); // Received data: "It works!" + + +## util.debug(string) + + Stability: 0 - Deprecated: use console.error() instead. + +Deprecated predecessor of `console.error`. + +## util.error([...]) + + Stability: 0 - Deprecated: Use console.error() instead. + +Deprecated predecessor of `console.error`. + +## util.puts([...]) + + Stability: 0 - Deprecated: Use console.log() instead. + +Deprecated predecessor of `console.log`. + +## util.print([...]) + + Stability: 0 - Deprecated: Use `console.log` instead. + +Deprecated predecessor of `console.log`. + + +## util.pump(readableStream, writableStream, [callback]) + + Stability: 0 - Deprecated: Use readableStream.pipe(writableStream) + +Deprecated predecessor of `stream.pipe()`. |