This specification provides a language-neutral Console interface compatible with the JavaScript window.console object that first appeared as part of the Firebug plugin for Mozilla Firefox and that has subsequently been implemented in other major browsers, as well as in non-browser JavaScript environments such as Node and PhantomJS.

Additional editorial contributions to this document are welcome. For details on how to contribute, see the instructions in the accompanying README file.

[more TK later…]

Introduction

This specification defines a language-neutral Console interface that represents a means for programatically writing output to a console such as a standalone shell environment for a scripting language, an operating-system shell, or the console component of a Web-developer toolsuite in a Web browser. The interface is compatible with the JavaScript window.console object that first appeared as part of the Firebug plugin for Mozilla Firefox and that has subsequently been implemented in other major browsers, as well as in non-browser JavaScript environments such as Node.

The scope of this specification is thus limited to:

This specification defines a single conformance class: a conforming console handler.

A console handler is any implementation capable of processing Console payloads according to the definitions and requirements provided in this specification.

A conforming console handler is any console handler that conforms to the definitions and requirements provided in this specification.

Conforming console handlers MUST:

The Console interface

This section defines the Console interface. The Console interface represents a means for programatically writing output payloads to a console.

void log (in any... args)
Outputs a payload to the console, with the value of its PayloadContents property set to args. permits format string, writes to stdout
void debug (in any... args)
Outputs a payload to the console, with the value of its PayloadContents property set to args, and the value of its LineNumber property set to the source-code line number from which the method was called. permits format string, writes to stderr
void info (in any... args)
Outputs a payload to the console, with the value of its PayloadContents property set to args, and the value of its Severity property set to Info, and the value of its LineNumber property set to the source-code line number from which the method was called. permits format string, writes to stderr
void warn (in any... args)
Outputs a payload to the console, with the value of its PayloadContents property set to args, and the value of its Severity property set to Warning, and the value of its LineNumber property set to the source-code line number from which the method was called. permits format string, writes to stderr
void error (in any... args)
Outputs a payload to the console, with the value of its PayloadContents property set to args, and the value of its Severity property set to Error, and the value of its LineNumber property set to the source-code line number from which the method was called. permits format string, writes to stderr
void assert (boolean expression, in any... args)
Tests whether the boolean expression argument evaluates to true; and, if expression does not evaluate to true, throws an assertion failed exception and, if args is specified, outputs a payload to the console, with the value of its PayloadContents property set to args. writes to stderr
Authoring guidelines:

Payloads

Conceptually, a payload consists of one or more payload items, each of which can be a particular data type; for example, a literal such as a string or number, or identifier such as a variable name or an object name.

There are two broad types of payloads:

Both classes of payload have certain properties, and invoking a method that causes a payload to be output to the console causes the payload, conceptually, to be sent to a console handler along with its properties. The console handler then renders the payload, displaying each payload item in a way appropriate for its data type and, in the case of format-string payloads, in accordance with the format specifiers in its format string. For example, in the case of a payload item that is an identifier for an object, the console handler can provide a collapsible/hyperlinked tree view of the object. Additionally, the console can use the payload property information to further supplement the display of the payload itself; for example, for a payload associated with an error condition, the console can prepend to its rendering of the payload a string such “Error”, and/or an error icon.

The properties of a payload

A payload consists of three abstract payload properties: PayloadContents, LineNumber, and Severity.

PayloadContents
The actual content of the payload, which consists of one or more payload items.
LineNumber
A source-code line number with which to associate a payload. …
Severity
An indicator of the severity level of a payload. There are three possible severity levels: Error, Warning, and Info.

The PayloadContents, LineNumber, and Severity properties are all abstractions used here for specification purposes only, and need not correspond to any specific entities within an implementation of this specification.

Non-format-string payloads

Non-format-string payloads are payloads whose first payload item is not a format string.

Format-string payloads

Some Console methods support can output format-string payloads, which are payloads that use printf-like format strings.

A format string is a string that contains ordinary literal text in combination with format specifiers.

The following is an example that uses a format string.

console.log()

In Console method calls that allow format strings, the format string is always the first argument, and is followed by one or more arguments that serve as its argument list.

The format specifiers in format strings use a simple form of markup consisting of a "%" character followed by a single character.

Format specifiers are not rendered literally in output but instead cause arguments from the argument list to be fetched and rendered according to the specified format. The arguments are fetched from the argument list in the same order as the format specifiers; the first format specifier causes the first argument in the argument list to be fetched, the second format specifier causes the second argument in the argument list to be fetched, and so on.

Output

To output a payload, a conforming console handler MUST follow these steps: …

Handling exceptions

To throw an assertion failed exception, a conforming console handler MUST….

Acknowledgements

This document incorporates modified and verbatim content from the Console API page of the Firebug Wiki.