Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

doc: improvements to console.markdown copy #4428

Closed
wants to merge 1 commit into from
Closed

doc: improvements to console.markdown copy #4428

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
170 changes: 117 additions & 53 deletions doc/api/console.markdown
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It might be useful to say "similar, but not identical to" as we get a decent number of requests for console features that browsers have.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Heh, I see that you covered that topic a little further down.

JavaScript console mechanism provided by web browsers.

The module exports two specific components:

* 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` object is a special instance of `Console` whose 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 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

For ease of use, `console` is defined as a global object and can be used
directly without `require`.
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`.
Expand All @@ -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`.
Expand All @@ -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++) {
Expand All @@ -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