From df7e1281a5255fcb94f01a680492a2fc1a58e2fd Mon Sep 17 00:00:00 2001 From: James M Snell Date: Sat, 26 Dec 2015 09:13:23 -0800 Subject: [PATCH] doc: improvements to console.markdown copy Several improvements including a few new examples PR-URL: https://github.com/nodejs/node/pull/4428 Reviewed-By: Stephen Belanger Reviewed-By: Colin Ihrig Reviewed-By: Evan Lucas --- doc/api/console.markdown | 170 ++++++++++++++++++++++++++++++++--------------- 1 file changed, 117 insertions(+), 53 deletions(-) diff --git a/doc/api/console.markdown b/doc/api/console.markdown index 85df0ab..c0cc060 100644 --- a/doc/api/console.markdown +++ b/doc/api/console.markdown @@ -2,29 +2,79 @@ Stability: 2 - Stable -The module defines a `Console` class and exports a `console` object. +The `console` module provides a simple debugging console that is similar to the +JavaScript console mechanism provided by web browsers. -The `console` object is a special instance of `Console` whose output is -sent to stdout or stderr. +The module exports two specific components: -For ease of use, `console` is defined as a global object and can be used -directly without `require`. +* A `Console` class with methods such as `console.log()`, `console.error()` and + `console.warn()` that can be used to write to any Node.js stream. +* A global `console` instance configured to write to `stdout` and `stderr`. + Because this object is global, it can be used without calling + `require('console')`. + +Example using the global `console`: + + console.log('hello world'); + // Prints: hello world, to stdout + console.log('hello %s', 'world'); + // Prints: hello world, to stdout + console.error(new Error('Whoops, something bad happened')); + // Prints: [Error: Whoops, something bad happened], to stderr + + const name = 'Will Robinson'; + console.warn(`Danger ${name}! Danger!`); + // Prints: Danger Will Robinson! Danger!, to stderr + +Example using the `Console` class: + + const out = getStreamSomehow(); + const err = getStreamSomehow(); + const myConsole = new console.Console(out, err); + + myConsole.log('hello world'); + // Prints: hello world, to out + myConsole.log('hello %s', 'world'); + // Prints: hello world, to out + myConsole.error(new Error('Whoops, something bad happened')); + // Prints: [Error: Whoops, something bad happened], to err + + const name = 'Will Robinson'; + myConsole.warn(`Danger ${name}! Danger!`); + // Prints: Danger Will Robinson! Danger!, to err + +While the API for the `Console` class is designed fundamentally around the +Web browser `console` object, the `Console` is Node.js is *not* intended to +duplicate the browsers functionality exactly. + +## Asynchronous vs Synchronous Consoles + +The console functions are synchronous when the destination is a terminal or +a file (to avoid lost messages in case of premature exit) and asynchronous +when the destination is a pipe (to avoid blocking for long periods of time). + +In the following example, stdout is non-blocking while stderr is blocking: + + $ node script.js 2> error.log | tee info.log + +Typically, the distinction between blocking/non-blocking is not important +unless an application is logging significant amounts of data. High volume +logging *should* use a `Console` instance that writes to a pipe. ## Class: Console -Use `require('console').Console` or `console.Console` to access this class. +The `Console` class can be used to create a simple logger with configurable +output streams and can be accessed using either `require('console').Console` +or `console.Console`: const Console = require('console').Console; const Console = console.Console; -You can use the `Console` class to create a simple logger like `console` but -with different output streams. - ### new Console(stdout[, stderr]) -Create a new `Console` by passing one or two writable stream instances. +Creates a new `Console` by passing one or two writable stream instances. `stdout` is a writable stream to print log or info output. `stderr` is used for warning or error output. If `stderr` isn't passed, the warning and error output will be sent to the `stdout`. @@ -39,42 +89,27 @@ and error output will be sent to the `stdout`. // in stdout.log: count 5 The global `console` is a special `Console` whose output is sent to -`process.stdout` and `process.stderr`: +`process.stdout` and `process.stderr`. It is equivalent to calling: new Console(process.stdout, process.stderr); -## console - -* {Object} - - - -For printing to stdout and stderr. Similar to the console object functions -provided by most web browsers, here the output is sent to stdout or stderr. - -The console functions are synchronous when the destination is a terminal or -a file (to avoid lost messages in case of premature exit) and asynchronous -when it's a pipe (to avoid blocking for long periods of time). - -That is, in the following example, stdout is non-blocking while stderr -is blocking: - - $ node script.js 2> error.log | tee info.log - -Typically, the blocking/non-blocking dichotomy is not something you should -worry about unless you log huge amounts of data. - ### console.assert(value[, message][, ...]) -Similar to [`assert.ok()`][], but the error message is formatted as -`util.format(message...)`. +A simple assertion test that verifies whether `value` is truthy. If it is not, +an `AssertionError` is throw. If provided, the error `message` is formatted +using [`util.format()`][] and used as the error message. + + console.assert(true, 'does nothing'); + // OK + console.assert(false, 'Whoops %s', 'didn\'t work'); + // AssertionError: Whoops didn't work ### console.dir(obj[, options]) Uses [`util.inspect()`][] on `obj` and prints the resulting string to stdout. -This function bypasses any custom `inspect()` function on `obj`. An optional -`options` object may be passed that alters certain aspects of the formatted -string: +This function bypasses any custom `inspect()` function defined on `obj`. An +optional `options` object may be passed that alters certain aspects of the +formatted string: - `showHidden` - if `true` then the object's non-enumerable and symbol properties will be shown too. Defaults to `false`. @@ -89,37 +124,54 @@ Defaults to `false`. Colors are customizable; see ### console.error([data][, ...]) -Same as [`console.log()`][] but prints to stderr. +Prints to stderr with newline. Multiple arguments can be passed, with the first +used as the primary message and all additional used as substitution +values similar to `printf()` (the arguments are all passed to +[`util.format()`][]). + + const code = 5; + console.error('error #%d', code); + // Prints: error #5, to stderr + console.error('error', code); + // Prints: error 5, to stderr + +If formatting elements (e.g. `%d`) are not found in the first string then +[`util.inspect()`][] is called on each argument and the resulting string +values are concatenated. See [`util.format()`][] for more information. ### console.info([data][, ...]) -Same as [`console.log()`][]. +The `console.info()` function is an alias for [`console.log()`][]. ### console.log([data][, ...]) -Prints to stdout with newline. This function can take multiple arguments in a -`printf()`-like way: +Prints to stdout with newline. Multiple arguments can be passed, with the first +used as the primary message and all additional used as substitution +values similar to `printf()` (the arguments are all passed to +[`util.format()`][]). var count = 5; console.log('count: %d', count); - // prints 'count: 5' + // Prints: count: 5, to stdout + console.log('count: ', count); + // Prints: count: 5, to stdout -If formatting elements are not found in the first string then -[`util.inspect()`][] is used on each argument. See [`util.format()`][] for more -information. +If formatting elements (e.g. `%d`) are not found in the first string then +[`util.inspect()`][] is called on each argument and the resulting string +values are concatenated. See [`util.format()`][] for more information. ### console.time(label) Used to calculate the duration of a specific operation. To start a timer, call -the `console.time()` method, giving it a name as only parameter. To stop the +the `console.time()` method, giving it a unique `label` as the only parameter. To stop the timer, and to get the elapsed time in milliseconds, just call the [`console.timeEnd()`][] method, again passing the -timer's name as the parameter. +timer's unique `label` as the parameter. ### console.timeEnd(label) Stops a timer that was previously started by calling [`console.time()`][] and -prints the result to the console: +prints the result to stdout: console.time('100-elements'); for (var i = 0; i < 100; i++) { @@ -130,18 +182,30 @@ prints the result to the console: ### console.trace(message[, ...]) -Print to stderr `'Trace :'`, followed by the formatted message and stack trace -to the current position. +Prints to stderr the string `'Trace :'`, followed by the [`util.format()`][] +formatted message and stack trace to the current position in the code. + + console.trace('Show me'); + // Prints: (stack trace will vary based on where trace is called) + // Trace: Show me + // at repl:2:9 + // at REPLServer.defaultEval (repl.js:248:27) + // at bound (domain.js:287:14) + // at REPLServer.runBound [as eval] (domain.js:300:12) + // at REPLServer. (repl.js:412:12) + // at emitOne (events.js:82:20) + // at REPLServer.emit (events.js:169:7) + // at REPLServer.Interface._onLine (readline.js:210:10) + // at REPLServer.Interface._line (readline.js:549:8) + // at REPLServer.Interface._ttyWrite (readline.js:826:14) ### console.warn([data][, ...]) -Same as [`console.error()`][]. +The `console.warn()` function is an alias for [`console.error()`][]. -[`assert.ok()`]: assert.html#assert_assert_value_message_assert_ok_value_message [`console.error()`]: #console_console_error_data [`console.log()`]: #console_console_log_data [`console.time()`]: #console_console_time_label [`console.timeEnd()`]: #console_console_timeend_label [`util.format()`]: util.html#util_util_format_format [`util.inspect()`]: util.html#util_util_inspect_object_options -[customizing `util.inspect()` colors]: util.html#util_customizing_util_inspect_colors -- 2.7.4