Console
STATUS: PROPOSED, DISCUSSED, SOME IMPLEMENTATIONS
- Implementations
- [[Implementations/Wakanda|]] (partial), [[Implementations/AvocadoDB|]]
Contents
- 1 console
- 1.1 Prior Art
- 1.2 Proposals
- 1.2.1 log(object[, object, ...])
- 1.2.2 debug(object[, object, ...])
- 1.2.3 info(object[, object, ...])
- 1.2.4 warn(object[, object, ...])
- 1.2.5 error(object[, object, ...])
- 1.2.6 assert(expression[, object, ...])
- 1.2.7 dir(object)
- 1.2.8 dirxml(node)
- 1.2.9 trace()
- 1.2.10 group(object[, object, ...])
- 1.2.11 groupEnd()
- 1.2.12 time(name)
- 1.2.13 timeEnd(name)
- 1.2.14 profile([title])
- 1.2.15 profileEnd()
- 1.2.16 count([title])
- 1.3 Related Discussions
console
console is a well known logging facility to all the JS devs. By utilizing this standard interface which is almost identical across all major browsers, we will gain from familiarity from the developers. console is not a replacement for a `print` or any other full featured logging API, it may be an easily available default instance of a logger or a wrapper on `print`. Message representation and implementation is up to the platform provider.
Prior Art
Proposals
- console/A by Irakli Gozalishvili
All platforms must support a module, `console`, that MUST export following:
log(object[, object, ...])
logs a message to with visual "log" representation allowing user to distinguish form other message types. You may pass as many arguments as you'd like, and they will be joined together in a space-delimited line.
The first argument to log may be a string containing printf-like string substitution patterns. For example:
require("console").log("The %s jumped over %d tall buildings", animal, count);
The example above can be re-written without string substitution to achieve the same result:
require("console").log("The", animal, "jumped over", count, "tall buildings");
These two techniques can be combined. If you use string substitution but provide more arguments than there are substitution patterns, the remaining arguments will be appended in a space-delimited line, like so:
require("console").log("I am %s and I have:", myName, thing1, thing2, thing3);
If objects are logged, platform provider may write the as static text, or a representation of an object, some platforms might dump interactive hyperlinks that can be inspected.
Here is the complete set of patterns that you may use for string substitution:
| String Substitution Patterns | |
| %s | String |
| %d, %i | Integer (numeric formatting is not yet supported) |
| %f | Floating point number (numeric formatting is not yet supported) |
| %o | Object hyperlink |
debug(object[, object, ...])
Logs a message, with a visual "debug" representation. Optionally includes an info of a caller (file, line where it was called from).
info(object[, object, ...])
Logs a message with the visual "info" representation. Optionally includes an info of a caller (file, line where it was called from).
warn(object[, object, ...])
Logs a message with the visual "warning" representation. Optionally includes an info of a caller (file, line where it was called from).
error(object[, object, ...])
Logs a message with the visual "error" representation. Optionally includes an info of a caller (file, line where it was called from).
assert(expression[, object, ...])
Tests that an expression is true. If not, logs a message and throws an exception.
dir(object)
Logs a static / interactive listing of all properties of the object.
dirxml(node)
Logs the XML source tree of an HTML or XML element. Even though there is no CommonJS standards for XML, HTML yet most likely there will be one at some point. In order to keep compatibility with well known console from browsers, platform should implement this and may decide to default for a log or dir described above.
trace()
Logs a static / interactive stack trace of JavaScript execution at the point where it is called. Details that platform is able to provide is most likely will be different there for it's up to platform, some may provide full stack trace like the functions on the stack, as well as the values that were passed as arguments to each function. While others may log just a module require graph.
group(object[, object, ...])
Logs a message to and opens a nested block to indent all future messages sent. Call require("console").groupEnd() to close the block. Representation of block is up to the platform, it can be an interactive block or just a set of indented sub messages.
groupEnd()
Closes the most recently opened block created by a call to require("console").group() or require("console").groupCollapsed()
time(name)
Creates a new timer under the given name. Call require("console").timeEnd(name) with the same name to stop the timer and log the time elapsed..
timeEnd(name)
Stops a timer created by a call to require("console").time(name) and logs the time elapsed.
profile([title])
Turns on profiler. The optional argument title would contain the text to be logged in the header of the profile report. Data included in a report generated by a profiler is up to platform.
profileEnd()
Turns off profiler and logs its report.
count([title])
Writes the number of times that the line of code where count was called was executed. The optional argument title will print a message in addition to the number of the count.
