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