console.spec.whatwg.orgConsole Standard

Console Living Standard — Last Updated 24 January 2024 Participate: GitHub whatwg/console ( new issue , open issues ) Chat on Matrix Commits: GitHub whatwg/console/commits Snapshot as of this commit @consolelog Tests: web-platform-tests console/ ( ongoing work ) Translations (non-normative) : 日本語 Abstract This specification defines APIs for console debugging facilities. Table of Contents 1 Namespace console 1.1 Logging functions 1.1.1 assert( condition , ... data ) 1.1.2 clear() 1.1.3 debug(... data ) 1.1.4 error(... data ) 1.1.5 info(... data ) 1.1.6 log(... data ) 1.1.7 table( tabularData , properties ) 1.1.8 trace(... data ) 1.1.9 warn(... data ) 1.1.10 dir( item , options ) 1.1.11 dirxml(... data ) 1.2 Counting functions 1.2.1 count( label ) 1.2.2 countReset( label ) 1.3 Grouping functions 1.3.1 group(... data ) 1.3.2 groupCollapsed(... data ) 1.3.3 groupEnd() 1.4 Timing functions 1.4.1 time( label ) 1.4.2 timeLog( label , ... data ) 1.4.3 timeEnd( label ) 2 Supporting abstract operations 2.1 Logger( logLevel , args ) 2.2 Formatter( args ) 2.2.1 Summary of formatting specifiers 2.3 Printer( logLevel , args [, options ]) 2.3.1 Indicating logLevel severity 2.3.2 Printer user experience innovation 2.3.3 Common object formats 2.3.4 Example printer in Node.js 2.4 Reporting warnings to the console Acknowledgments Intellectual property rights Index Terms defined by this specification Terms defined by reference References Normative References IDL Index Status This specification is an early work in progress that welcomes feedback to refine toward more precise and compatible definitions. It is also the editors’ first specification, so please be kind and constructive. Please join us in the issue tracker for more discussion. 1. Namespace console [Exposed=*] namespace console { // but see namespace object requirements below // Logging undefined assert ( optional boolean condition = false , any ... data ); undefined clear (); undefined debug ( any ... data ); undefined error ( any ... data ); undefined info ( any ... data ); undefined log ( any ... data ); undefined table ( optional any tabularData , optional sequenceDOMStringproperties ); undefined trace ( any ... data ); undefined warn ( any ... data ); undefined dir ( optional any item , optional object ? options ); undefined dirxml ( any ... data ); // Counting undefined count ( optional DOMString label = "default"); undefined countReset ( optional DOMString label = "default"); // Grouping undefined group ( any ... data ); undefined groupCollapsed ( any ... data ); undefined groupEnd (); // Timing undefined time ( optional DOMString label = "default"); undefined timeLog ( optional DOMString label = "default", any ... data ); undefined timeEnd ( optional DOMString label = "default"); }; For historical reasons, console is lowercased. It is important that console is always visible and usable to scripts, even if the developer console has not been opened or does not exist. For historical web-compatibility reasons, the namespace object for console must have as its [[Prototype]] an empty object, created as if by ObjectCreate ( %ObjectPrototype% ), instead of %ObjectPrototype% . 1.1. Logging functions 1.1.1. assert( condition , ... data ) If condition is true, return. Let message be a string without any formatting specifiers indicating generically an assertion failure (such as "Assertion failed"). If data is empty , append message to data . Otherwise: Let first be data [0]. If Type ( first ) is not String, then prepend message to data . Otherwise: Let concat be the concatenation of message , U+003A (:), U+0020 SPACE, and first . Set data [0] to concat . Perform Logger ("assert", data ). 1.1.2. clear() Empty the appropriate group stack . If possible for the environment, clear the console. (Otherwise, do nothing.) 1.1.3. debug(... data ) Perform Logger ("debug", data ). 1.1.4. error(... data ) Perform Logger ("error", data ). 1.1.5. info(... data ) Perform Logger ("info", data ). 1.1.6. log(... data ) Perform Logger ("log", data ). 1.1.7. table( tabularData , properties ) Try to construct a table with the columns of the properties of tabularData (or use properties ) and rows of tabularData and log it with a logLevel of "log". Fall back to just logging the argument if it can’t be parsed as tabular. TODO: This will need a good algorithm. 1.1.8. trace(... data ) Let trace be some implementation-specific, potentially-interactive representation of the callstack from where this function was called. Optionally, let formattedData be the result of Formatter ( data ), and incorporate formattedData as a label for trace . Perform Printer ("trace", « trace »). The identifier of a function printed in a stack trace is implementation-dependant. It is also not guaranteed to be the same identifier that would be seen in new Error().stack . 1.1.9. warn(... data ) Perform Logger ("warn", data ). 1.1.10. dir( item , options ) Let object be item with generic JavaScript object formatting applied. Perform Printer ("dir", « object », options ). 1.1.11. dirxml(... data ) Let finalList be a new list , initially empty. For each item of data : Let converted be a DOM tree representation of item if possible; otherwise let converted be item with optimally useful formatting applied. Append converted to finalList . Perform Logger ("dirxml", finalList ). 1.2. Counting functions Each console namespace object has an associated count map , which is a map of strings to numbers, initially empty. 1.2.1. count( label ) Let map be the associated count map . If map [ label ] exists , set map [ label ] to map [ label ] + 1. Otherwise, set map [ label ] to 1. Let concat be the concatenation of label , U+003A (:), U+0020 SPACE, and ToString ( map [ label ]). Perform Logger ("count", « concat »). 1.2.2. countReset( label ) Let map be the associated count map . If map [ label ] exists , set map [ label ] to 0. Otherwise: Let message be a string without any formatting specifiers indicating generically that the given label does not have an associated count. Perform Logger ("countReset", « message »); 1.3. Grouping functions A group is an implementation-specific, potentially-interactive view for output produced by calls to Printer , with one further level of indentation than its parent. Each console namespace object has an associated group stack , which is a stack , initially empty. Only the last group in a group stack will host output produced by calls to Printer . 1.3.1. group(... data ) Let group be a new group . If data is not empty , let groupLabel be the result of Formatter ( data ). Otherwise, let groupLabel be an implementation-chosen label representing a group . Incorporate groupLabel as a label for group . Optionally, if the environment supports interactive groups, group should be expanded by default. Perform Printer ("group", « group »). Push group onto the appropriate group stack . 1.3.2. groupCollapsed(... data ) Let group be a new group . If data is not empty, let groupLabel be the result of Formatter ( data ). Otherwise, let groupLabel be an implementation-chosen label representing a group . Incorporate groupLabel as a label for group . Optionally, if the environment supports interactive groups, group should be collapsed by default. Perform Printer ("groupCollapsed", « group »). Push group onto the appropriate group stack . 1.3.3. groupEnd() Pop the last group from the group stack . 1.4. Timing functions Each console namespace object has an associated timer table , which is a map of strings to times, initially empty. 1.4.1. time( label ) If the associated timer table contains an entry with key label , return, optionally reporting a warning to the console indicating that a timer with label label has already been started. Otherwise, set the value of the entry with key label in the associated timer table to the current time. 1.4.2. timeLog( label , ... data ) Let timerTable be the associated timer table . Let startTime be timerTable [ label ]. Let...