Console

A Collection of Interesting Ideas, 14 October 2014

This version:
https://terinjokes.github.io/console-spec
Editor:
Version History:
https://github.com/terinjokes/console-spec/commits
Participate:
File an issue (open issues)
Send feedback to whatwg@whatwg.org (archives)
IRC: #whawg on Freenode

Abstract

This specification standardizes APIs for console debugging facilities.

Table of Contents

Status

This specification is in the process of establishing itself in the WHATWG. As such, the term "Living Standard" indicates a goal, rather than reality.

Please join us in the issue tracker for more discussion.

1. Logger Function

@TODO: Write this.

2. Interface Console

[NoInterfaceObject]
interface Console {
  // Logging
  void assert(boolean condition, optional anymessage);
  void clear();
  void count(optional DOMString label = "");
  void debug(any... data);
  void error(any... data);
  void info(any... data);
  void log(any... data);
  void table(anytabularData, optional sequence<DOMString> properties);
  void trace(any... data);
  void warn(any... data);

  // Grouping
  void group(any... data);
  void groupCollapse(any... data);
  void groupEnd();

  // Timing
  void time(DOMString label);
  void timeEnd(DOMString label);
};

partial interface Window {
  attribute Console console;
};

partial interface WorkerGlobalScope {
  attribute Console console;
};

2.1. Logging Methods

2.1.1. assert()

If expression is false, print the message as an error level message.

2.1.2. clear()

If possible for the environment, clear the console. Otherwise, do nothing.

2.1.3. count()

Counts the number of times count has been called with the provided label.

2.1.4. debug()

The side effect of running the logger function with data and logLevel set to log.

2.1.5. error()

The side effect of running the logger function with data and logLevel set to error.

2.1.6. info()

The side effect of running the logger function with data and logLevel set to info.

2.1.7. log()

The side effect of running the logger function with data and logLevel set to log.

2.1.8. table()

Try to construct a table with the columns of the properties of tabularData 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. This will need a good algorithm.

2.1.9. trace()

The side effect of running the logger function with data and logLevel set to error.

2.1.10. warn()

The side effect of running the logger function with data and logLevel set to warn.

2.2. Grouping Methods

2.2.1. group()

2.2.2. groupCollapse()

2.2.3. groupEnd()

2.3. Timing Methods

2.3.1. time()

Start an internal timer stored in the timer table as label.

2.3.2. timeEnd()

Store the current value of the internal timer stored as label as duration. Remove the timer from tha timer table. Then, the side effect of running the logger function with arguments label and duration.

3. Formatting Specifiers

Note: Consider keeping these format specifiers general enough to be re-used by other specifications.

4. JavaScript Object inspection

TODO: Define an interface that allows JavaScript objects to format themselves for inspection.

Acknowledgments

Conformance

All diagrams, examples, and notes in this specification are non-normative, as are all sections explicitly marked non-normative. Everything else in this specification is normative.

The key words "MUST", "MUST NOT", "REQUIRED", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in the normative parts of this specification are to be interpreted as described in RFC2119. For readability, these words do not appear in all uppercase letters in this specification. [RFC2119]

Conformance requirements phrased as algorithms or specific steps may be implemented in any manner, so long as the end result is equivalent.

References

Normative References

[rfc2119]
S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Best Current Practice. URL: http://www.ietf.org/rfc/rfc2119.txt

Index

IDL Index

[NoInterfaceObject]
interface Console {
  // Logging
  void assert(boolean condition, optional anymessage);
  void clear();
  void count(optional DOMString label = "");
  void debug(any... data);
  void error(any... data);
  void info(any... data);
  void log(any... data);
  void table(anytabularData, optional sequence<DOMString> properties);
  void trace(any... data);
  void warn(any... data);

  // Grouping
  void group(any... data);
  void groupCollapse(any... data);
  void groupEnd();

  // Timing
  void time(DOMString label);
  void timeEnd(DOMString label);
};

partial interface Window {
  attribute Console console;
};

partial interface WorkerGlobalScope {
  attribute Console console;
};