X-Git-Url: http://review.tizen.org/git/?a=blobdiff_plain;f=doc%2Fapi%2Fconsole.markdown;h=c0cc060ec14995b3bbbff676a8e82364bef1cfd8;hb=4cc6180fc56d432e9433ab15ab5ccc820826c341;hp=408f09374903dab5e8d0760e343c507a0b671943;hpb=99c9930ad626e2796af23def7cac19b65c608d18;p=platform%2Fupstream%2Fnodejs.git

diff --git a/doc/api/console.markdown b/doc/api/console.markdown
index 408f093..c0cc060 100644
--- a/doc/api/console.markdown
+++ b/doc/api/console.markdown
@@ -1,76 +1,211 @@
-# console
+# Console
 
-    Stability: 4 - API Frozen
+    Stability: 2 - Stable
 
-* {Object}
+The `console` module provides a simple debugging console that is similar to the
+JavaScript console mechanism provided by web browsers.
 
-<!--type=global-->
+The module exports two specific components:
 
-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.
+* 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 it's a pipe (to avoid blocking for long periods of time).
+when the destination is a pipe (to avoid blocking for long periods of time).
 
-That is, in the following example, stdout is non-blocking while stderr
-is blocking:
+In the following example, stdout is non-blocking while stderr is blocking:
 
     $ node script.js 2> error.log | tee info.log
 
-In daily use, the blocking/non-blocking dichotomy is not something you
-should worry about unless you log huge amounts of data.
+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
 
-## console.log([data], [...])
+<!--type=class-->
 
-Prints to stdout with newline. This function can take multiple arguments in a
-`printf()`-like way. Example:
+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`:
 
-    console.log('count: %d', count);
+    const Console = require('console').Console;
+    const Console = console.Console;
 
-If formatting elements are not found in the first string then `util.inspect`
-is used on each argument.  See [util.format()][] for more information.
+### new Console(stdout[, stderr])
 
-## console.info([data], [...])
+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`.
 
-Same as `console.log`.
+    const output = fs.createWriteStream('./stdout.log');
+    const errorOutput = fs.createWriteStream('./stderr.log');
+    // custom simple logger
+    const logger = new Console(output, errorOutput);
+    // use it like console
+    var count = 5;
+    logger.log('count: %d', count);
+    // in stdout.log: count 5
 
-## console.error([data], [...])
+The global `console` is a special `Console` whose output is sent to
+`process.stdout` and `process.stderr`. It is equivalent to calling:
 
-Same as `console.log` but prints to stderr.
+    new Console(process.stdout, process.stderr);
 
-## console.warn([data], [...])
+### console.assert(value[, message][, ...])
 
-Same as `console.error`.
+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.dir(obj)
+    console.assert(true, 'does nothing');
+      // OK
+    console.assert(false, 'Whoops %s', 'didn\'t work');
+      // AssertionError: Whoops didn't work
 
-Uses `util.inspect` on `obj` and prints resulting string to stdout. This function
-bypasses any custom `inspect()` function on `obj`.
+### console.dir(obj[, options])
 
-## console.time(label)
+Uses [`util.inspect()`][] on `obj` and prints the resulting string to stdout.
+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:
 
-Mark a time.
+- `showHidden` - if `true` then the object's non-enumerable and symbol
+properties will be shown too. Defaults to `false`.
 
-## console.timeEnd(label)
+- `depth` - tells `inspect` how many times to recurse while formatting the
+object. This is useful for inspecting large complicated objects. Defaults to
+`2`. To make it recurse indefinitely, pass `null`.
 
-Finish timer, record output. Example:
+- `colors` - if `true`, then the output will be styled with ANSI color codes.
+Defaults to `false`. Colors are customizable; see
+[customizing `util.inspect()` colors][].
 
-    console.time('100-elements');
-    for (var i = 0; i < 100; i++) {
-      ;
-    }
-    console.timeEnd('100-elements');
+### console.error([data][, ...])
 
-## console.trace(label)
+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()`][]).
 
-Print a stack trace to stderr of the current position.
+    const code = 5;
+    console.error('error #%d', code);
+      // Prints: error #5, to stderr
+    console.error('error', code);
+      // Prints: error 5, to stderr
 
-## console.assert(expression, [message])
+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.
 
-Same as [assert.ok()][] where if the `expression` evaluates as `false` throw an
-AssertionError with `message`.
+### console.info([data][, ...])
 
-[assert.ok()]: assert.html#assert_assert_value_message_assert_ok_value_message
-[util.format()]: util.html#util_util_format_format
+The `console.info()` function is an alias for [`console.log()`][].
+
+### console.log([data][, ...])
+
+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, to stdout
+    console.log('count: ', count);
+      // Prints: count: 5, to stdout
+
+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)
+
+Used to calculate the duration of a specific operation. To start a timer, call
+the `console.time()` method, giving it a unique `label` as the only parameter. To stop the
+timer, and to get the elapsed time in milliseconds, just call the
+[`console.timeEnd()`][] method, again passing the
+timer's unique `label` as the parameter.
+
+### console.timeEnd(label)
+
+Stops a timer that was previously started by calling [`console.time()`][] and
+prints the result to stdout:
+
+    console.time('100-elements');
+    for (var i = 0; i < 100; i++) {
+      ;
+    }
+    console.timeEnd('100-elements');
+    // prints 100-elements: 262ms
+
+### console.trace(message[, ...])
+
+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][, ...])
+
+The `console.warn()` function is an alias for [`console.error()`][].
+
+[`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