Skip to content

Commit

Permalink
doc: improvements to console.markdown copy
Browse files Browse the repository at this point in the history
Several improvements including a few new examples
  • Loading branch information
jasnell committed Dec 30, 2015
1 parent 7d5c1b5 commit 36766ff
Showing 1 changed file with 117 additions and 53 deletions.
170 changes: 117 additions & 53 deletions doc/api/console.markdown
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
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

0 comments on commit 36766ff

Please sign in to comment.