doc/api/console.markdown

   1 # Console
   2
   3     Stability: 2 - Stable
   4
   5 The module defines a `Console` class and exports a `console` object.
   6
   7 The `console` object is a special instance of `Console` whose output is
   8 sent to stdout or stderr.
   9
  10 For ease of use, `console` is defined as a global object and can be used
  11 directly without `require`.
  12
  13 ## Class: Console
  14
  15 <!--type=class-->
  16
  17 Use `require('console').Console` or `console.Console` to access this class.
  18
  19     const Console = require('console').Console;
  20     const Console = console.Console;
  21
  22 You can use the `Console` class to create a simple logger like `console` but
  23 with different output streams.
  24
  25 ### new Console(stdout[, stderr])
  26
  27 Create a new `Console` by passing one or two writable stream instances.
  28 `stdout` is a writable stream to print log or info output. `stderr`
  29 is used for warning or error output. If `stderr` isn't passed, the warning
  30 and error output will be sent to the `stdout`.
  31
  32     const output = fs.createWriteStream('./stdout.log');
  33     const errorOutput = fs.createWriteStream('./stderr.log');
  34     // custom simple logger
  35     const logger = new Console(output, errorOutput);
  36     // use it like console
  37     var count = 5;
  38     logger.log('count: %d', count);
  39     // in stdout.log: count 5
  40
  41 The global `console` is a special `Console` whose output is sent to
  42 `process.stdout` and `process.stderr`:
  43
  44     new Console(process.stdout, process.stderr);
  45
  46 ## console
  47
  48 * {Object}
  49
  50 <!--type=global-->
  51
  52 For printing to stdout and stderr. Similar to the console object functions
  53 provided by most web browsers, here the output is sent to stdout or stderr.
  54
  55 The console functions are synchronous when the destination is a terminal or
  56 a file (to avoid lost messages in case of premature exit) and asynchronous
  57 when it's a pipe (to avoid blocking for long periods of time).
  58
  59 That is, in the following example, stdout is non-blocking while stderr
  60 is blocking:
  61
  62     $ node script.js 2> error.log | tee info.log
  63
  64 Typically, the blocking/non-blocking dichotomy is not something you should
  65 worry about unless you log huge amounts of data.
  66
  67 ### console.assert(value[, message][, ...])
  68
  69 Similar to [`assert.ok()`][], but the error message is formatted as
  70 `util.format(message...)`.
  71
  72 ### console.dir(obj[, options])
  73
  74 Uses [`util.inspect()`][] on `obj` and prints the resulting string to stdout.
  75 This function bypasses any custom `inspect()` function on `obj`. An optional
  76 `options` object may be passed that alters certain aspects of the formatted
  77 string:
  78
  79 - `showHidden` - if `true` then the object's non-enumerable and symbol
  80 properties will be shown too. Defaults to `false`.
  81
  82 - `depth` - tells `inspect` how many times to recurse while formatting the
  83 object. This is useful for inspecting large complicated objects. Defaults to
  84 `2`. To make it recurse indefinitely, pass `null`.
  85
  86 - `colors` - if `true`, then the output will be styled with ANSI color codes.
  87 Defaults to `false`. Colors are customizable; see
  88 [customizing `util.inspect()` colors][].
  89
  90 ### console.error([data][, ...])
  91
  92 Same as [`console.log()`][] but prints to stderr.
  93
  94 ### console.info([data][, ...])
  95
  96 Same as [`console.log()`][].
  97
  98 ### console.log([data][, ...])
  99
 100 Prints to stdout with newline. This function can take multiple arguments in a
 101 `printf()`-like way:
 102
 103     var count = 5;
 104     console.log('count: %d', count);
 105     // prints 'count: 5'
 106
 107 If formatting elements are not found in the first string then
 108 [`util.inspect()`][] is used on each argument.  See [`util.format()`][] for more
 109 information.
 110
 111 ### console.time(label)
 112
 113 Used to calculate the duration of a specific operation. To start a timer, call
 114 the `console.time()` method, giving it a name as only parameter. To stop the
 115 timer, and to get the elapsed time in milliseconds, just call the
 116 [`console.timeEnd()`][] method, again passing the
 117 timer's name as the parameter.
 118
 119 ### console.timeEnd(label)
 120
 121 Stops a timer that was previously started by calling [`console.time()`][] and
 122 prints the result to the console:
 123
 124     console.time('100-elements');
 125     for (var i = 0; i < 100; i++) {
 126       ;
 127     }
 128     console.timeEnd('100-elements');
 129     // prints 100-elements: 262ms
 130
 131 ### console.trace(message[, ...])
 132
 133 Print to stderr `'Trace :'`, followed by the formatted message and stack trace
 134 to the current position.
 135
 136 ### console.warn([data][, ...])
 137
 138 Same as [`console.error()`][].
 139
 140 [`assert.ok()`]: assert.html#assert_assert_value_message_assert_ok_value_message
 141 [`console.error()`]: #console_console_error_data
 142 [`console.log()`]: #console_console_log_data
 143 [`console.time()`]: #console_console_time_label
 144 [`console.timeEnd()`]: #console_console_timeend_label
 145 [`util.format()`]: util.html#util_util_format_format
 146 [`util.inspect()`]: util.html#util_util_inspect_object_options
 147 [customizing `util.inspect()` colors]: util.html#util_customizing_util_inspect_colors