console is a pre-defined PinballY object that lets you display text messages on the debugger's console window when you're using a debugger (see Debugging). This provides a simple way of seeing what's going on in your code when troubleshooting scripts. The PinballY console object is similar to the console object in a Web browser, with most of the same methods.
In the method descriptions below, "display" always means displaying on the debugger console. If you're not currently using a debugger, there is no console, so any messages are simply discarded. You can thus leave console logging messages in working code without bothering the user with extraneous messages. Even so, it's good practice to remove console messages when you're confident about a section of code and no longer need to instrument it: there's still some overhead in processing the method calls, and when you want to debug some other area of the code, you don't want to sift through the noise of leftover messages from unrelated areas.
console.assert(assertion, arguments...): If the assertion expression is false (or "falsey"), the function acts like console.log(), displaying the arguments the same way log() would. Otherwise nothing is displayed. This can be used to log messages when unexpected conditions occur.
console.count(label): Displays the number of times that this method has been called with the same label. If the label is omitted, a default label based on the calling code location is used instead; this can be used to count the number of times a particular line of code is executed.
console.countReset(label): Resets the counter associated with the given label, for the purposes of console.count().
console.error(arguments): Does the same thing as console.log(), but displays the message with special styling (that depends on the debugger) to indicate that it's an error messages.
console.exception(arguments): Identical to console.error().
console.format(formatString, arguments): Formats the printf-style "%" parameters in the format string, using the given arguments, and returns the resulting string. This uses the same formatting codes described for console.log(). This lets you access the special formatting features directly for messages displayed in other places besides the console.
console.info(arguments): Does the same thing as console.log(), but displays the message with special styling (that depends on the debugger) to indicate that it's an informational message.
console.log(object...): Displays a message on the console log by converting each object to its string representation (using toString()), and appending the strings together, separated by spaces. This is typically used to display simple string messages:
console.log(formatString, arguments...): If the first argument to console.log() is a string, and it contains one or more "printf"-style "%" format codes, console.log() interprets it as a format string with substitution variables. Each "%" code is replaced with a formatted version of the corresponding argument from the arguments list, in left-to-right order.
Here's how the printf-style format string is interpreted:
Format codes: Each format code starts with a "%" and ends with a letter indicating the data format to be used to format the corresponding argument. The main format codes are:
Flags, width, precision: You can include three optional elements before the format code characters: flags, width, and precision. These are specified like so:
Flags:
Width: This specifies the minimum width for the format. This works for all types except %o and %O, which ignore it. The width is given as an integer value, as in "%5d". If the formatted value is shorter than the minimum given by the width, padding is added, in the form of leading or trailing spaces. For the numeric formats, the padding is added as leading zeroes ("0" characters) if the "0" flag is specified; for strings, padding is always spaces. The width is a minimum only, not a maximum; values that exceed the width aren't truncated.
For example, "%5d" formats 100 as " 100" (with two leading spaces).
Precision: This is a number specified after a "." in the format string: it's the "3" in "%.3f" or "%7.3f".
For %f, the precision specifies the number of digits to show after the decimal point. Values are rounded if necessary. For example, "%.3f" displays 123.456789 as "123.457".
For integer formats, the precision simply has the effect of left-justifying the result instead of right-justifying it.
For strings, the precision gives the maximum width. If the string is longer, it's truncated.
console.time(label): Starts a timer under the given label. This establishes the starting time for elapsed time measurements using console.timeLog() and console.timeEnd().
console.timeEnd(label): Displays on the console the current elapsed time for the timer previously started under the given label with console.time(), and then removes the timer.
console.timeLog(label): Displays on the console the current elapsed time for the timer previously started under the given label with console.time().
console.trace(): Displays a call stack trace for the calling code.
console.warning(arguments): Does the same thing as console.log(), but displays the message with special styling (that depends on the debugger) to indicate that it's a warning message.