The 'console' API

Relevant source files

The following files were used as context for generating this wiki page:

• Jurassic/Library/FirebugConsole/FirebugConsole.cs
• Jurassic/Library/FirebugConsole/IFirebugConsoleOutput.cs
• Jurassic/Library/FirebugConsole/StandardConsoleOutput.cs
• Jurassic/Library/FirebugConsole/FirebugConsole.g.cs
• Unit Tests/Core/DocumentationSamples.cs
• Unit Tests/Real-world/RealWorldTests.cs

The console API in Jurassic provides a non-standard set of commands for logging and debugging, based on the Firebug Console API. It is designed to be integrated into a .NET host application, allowing JavaScript code executed by the ScriptEngine to output messages, warnings, errors, and other debugging information. This functionality is not enabled by default but can be easily added by instantiating FirebugConsole and setting it as a global variable on the script engine.

The API supports formatted output, message grouping, and timers. The output destination is abstracted through the IFirebugConsoleOutput interface, with a default implementation that writes to the standard .NET console. This allows developers to redirect console output to custom targets like a UI element or a log file.

Sources: Jurassic/Library/FirebugConsole/FirebugConsole.cs:8-12, Unit Tests/Core/DocumentationSamples.cs:33-38

Architecture

The console API is built around three main components: FirebugConsole, IFirebugConsoleOutput, and StandardConsoleOutput.

• FirebugConsole: The central class that is exposed to the JavaScript environment. It inherits from ObjectInstance and contains the implementations of the console functions (log, warn, time, etc.).
• IFirebugConsoleOutput: An interface that defines the contract for an output target. This allows for decoupling the console logic from the actual output mechanism.
• StandardConsoleOutput: The default implementation of IFirebugConsoleOutput, which directs all output to the System.Console.

Sources: Jurassic/Library/FirebugConsole/FirebugConsole.cs, Jurassic/Library/FirebugConsole/IFirebugConsoleOutput.cs, Jurassic/Library/FirebugConsole/StandardConsoleOutput.cs

Component Relationship

The following diagram illustrates the relationship between the key classes of the console API.

Call Flow

A call to a function like console.log() from JavaScript triggers a sequence of method calls from the ScriptEngine to the FirebugConsole, which then delegates to the configured IFirebugConsoleOutput implementation.

Integration

To use the console API, you must create an instance of FirebugConsole and expose it as a global variable to the ScriptEngine.

// From Unit Tests/Core/DocumentationSamples.cs
var engine = new ScriptEngine();
engine.SetGlobalValue("console", new Jurassic.Library.FirebugConsole(engine));

Sources: Unit Tests/Core/DocumentationSamples.cs:36-38

This makes the console object available to any script executed by that engine instance.

// From Unit Tests/Real-world/RealWorldTests.cs
var engine = new ScriptEngine();
engine.SetGlobalValue("console", new Jurassic.Library.FirebugConsole(engine));
engine.ExecuteFile(@"../../../Real-world/Files/bignumber.js");
Assert.AreEqual("129963294281830400", engine.Evaluate(@"new BigNumber('129963294281830401').subtract(1).toString()"));

Sources: Unit Tests/Real-world/RealWorldTests.cs:172-175

API Methods

The FirebugConsole class exposes a variety of methods to the JavaScript environment. These methods are defined with the JSInternalFunction attribute.

Sources: Jurassic/Library/FirebugConsole/FirebugConsole.cs, Jurassic/Library/FirebugConsole/FirebugConsole.g.cs:10-21

Method	Parameters	Description
log	...items	Logs a general message.
debug	...items	Alias for log.
info	...items	Logs an informational message, often with a distinct style.
warn	...items	Logs a warning message.
error	...items	Logs an error message.
assert	expression, ...items	Logs an error if expression is false.
clear		Clears the console output.
group	...items	Starts an indented message group with a title.
groupCollapsed	...items	Starts a collapsed, indented message group.
groupEnd		Closes the most recent message group.
time	name = ""	Starts a timer with an optional name.
timeEnd	name = ""	Stops the specified timer and logs the elapsed time.

Logging and Formatting

The logging methods (log, debug, info, warn, error) share a common formatting mechanism. The first argument can be a string containing substitution patterns.

Sources: Jurassic/Library/FirebugConsole/FirebugConsole.cs:60-62, 219-227

Pattern	Description
%s	Substitutes with a string representation of the argument.
%d, %i	Substitutes with an integer representation of the argument.
%f	Substitutes with a floating-point representation of the argument.
%o	Substitutes with an object hyperlink (in environments that support it). In StandardConsoleOutput, this is treated as an object to be stringified.
%%	Substitutes with a literal % character.

The formatting logic is handled by the internal static method FormatObjects.

Output Styling

The StandardConsoleOutput implementation changes the Console.ForegroundColor based on the FirebugConsoleMessageStyle enum provided by the FirebugConsole methods.

• Information: ConsoleColor.White
• Warning: ConsoleColor.Yellow
• Error: ConsoleColor.Red
• Regular: Default console color.

After printing the message, the original color is restored.

Sources: Jurassic/Library/FirebugConsole/StandardConsoleOutput.cs:52-61

Timers

The time and timeEnd methods provide a simple way to measure the duration of operations. FirebugConsole maintains a private dictionary of Stopwatch instances, keyed by the timer name.

• time(name): Creates and starts a new Stopwatch for the given name. If a timer with that name already exists, the call is ignored.
• timeEnd(name): Stops the Stopwatch for the given name, logs the elapsed milliseconds, and removes it from the dictionary.

Sources: Jurassic/Library/FirebugConsole/FirebugConsole.cs:175-186, 192-205

Extensibility

The console's output can be customized by creating a class that implements the IFirebugConsoleOutput interface and assigning an instance of it to the FirebugConsole.Output property.

public interface IFirebugConsoleOutput
{
    void Log(FirebugConsoleMessageStyle style, object[] objects);
    void Clear();
    void StartGroup(string title, bool initiallyCollapsed);
    void EndGroup();
}

Sources: Jurassic/Library/FirebugConsole/IFirebugConsoleOutput.cs:8-28

This allows redirection of console messages to various targets, such as a file, a database, or a graphical user interface element in a host application. The default implementation, StandardConsoleOutput, demonstrates how to handle these calls for a standard console window.

Sources: Jurassic/Library/FirebugConsole/FirebugConsole.cs:35-44