1berry/nodejs
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

doc: improvements to console.markdown copy

Browse Source 
Several improvements including a few new examples

PR-URL: https://github.com/nodejs/node/pull/4428
Reviewed-By: Stephen Belanger <admin@stephenbelanger.com>
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
Reviewed-By: Evan Lucas <evanlucas@me.com>
This commit is contained in:
James M Snell 2015-12-26 09:13:23 -08:00
parent 7d5c1b5b1a
commit e4c835e1cb
1 changed files with 117 additions and 53 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

170
doc/api/console.markdown
View File

@ -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
<!--type=class-->
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}
<!--type=global-->
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,36 +124,53 @@ 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)
Starts a timer that can be used to compute the duration of an operation. Timers
are identified by a unique name. Use the same name when you call
are identified by a unique `label`. Use the same `label` when you call
[`console.timeEnd()`][] to stop the timer and output the elapsed time in
milliseconds. Timer durations are accurate to the sub-millisecond.
milliseconds to stdout. Timer durations are accurate to the sub-millisecond.
### 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++) {
@ -129,18 +181,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.<anonymous> (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