Console provides a consistent cross platform logging and debugging API. The API is consistent with that of the WebKit console. Developers can:
- redirect calls to "trace" to the console
- log messages at different levels
- print stack traces
- inspect structured objects in the WebKit console
- log multiple values in a single trace
- make assertions that trigger errors when they fail
- count invocations at positions within their code
- visually group log messages
- use timers to measure program performance
- start and stop profiling where available
- log Haxe objects in way that is easily inspectable in the WebKit console
- insert breakpoints (on supported platforms)
Console currently supports a number compile time modes:
- On system platforms (neko/php/cpp/nodejs) console prints to stdout, colorising output
- In JS/Flash running in WebKit browser console prints to WebKit console
- In JS running in non-webkit browser console prints to an element in the DOM
- In Flash running standalone or in a non-WebKit browser console prints to an on screen logging panel.
- When the compiler flag
no_console
is set, the console inlines null expressions, removing any runtime overhead from logging.
Example Usage:
You can download an example of mconsole usage here.
To enable the console, call:
Consolestart;
To log a message at a named level:
;;;;;
Messages default to LogLevel.log:
;
Log multiple values using trace. In WebKit console each value is inspectable (rather than concatenating as a string)
;
You can also call the logging API directly:
Console
Errors will print a message, then a stack trace:
Console;
Outputs:
Error: Epic fail
@ SomeClass.someMethod:20
@ SomeOtherClass.someOtherMethod:48
You can also use Console.trace
to print a stack trace without triggering
an error:
Console;
Outputs:
Stack trace:
@ SomeClass.someMethod:20
@ SomeOtherClass.someOtherMethod:48
Assertion will print a message and stack trace, then throw and exception when the condition is false:
Console;
Outputs:
Assertion failed: foo is not false
@ SomeClass.someMethod:20
@ SomeOtherClass.someOtherMethod:48
To count the number of times a line of code is invoked:
{ Console;} ;;
Outputs:
apples: 1
apples: 2
Note that counters are identified by their position, not their label:
Console;Console;
Outputs
apples: 1
apples: 1
To insert a breakpoint in JavaScript or Flash:
Console;
Group log messages together visually:
Console;Console;Console;Console;Console;Console;
Output:
Group
grouped log
Nested Group
nested warn
Timers can be used to quickly monitor runtime performance:
Console;for i in 04200000000 ;Console;
Output:
munging: 2410ms
JavaScript/Webkit only
The WebKit profiler can be started and stopped:
Consoleprofile"performance";var { return x * x; }var x = ;Console;
And markers added to the WebKit timeline view:
Console;
Type conversion
As the WebKit console has user friendly structure inspection, console will try to convert native Haxe values into something inspectable where possible:
// inspectable XML domConsole; // enums and enums with parametersConsole;Console;Console; // mapesvar map = <String>;map;Console; var intMap = <String>;intMap;Console; // and iterable objects in generalvar list = <String>;list;list;Console;
Printer
Printing is implemented by a mconsole.Printer
. Custom printers can be used:
Console;
A default printer is always created. This is a ConsoleView
for JavaScript and
Flash, or a FilePrinter for system targets.
To implement a custom printer:
/**A ConsolePrinter that raises an alert for each log message.*/ implements mconsolePrinter public :Void { jsLib; }
Caveats
When logging to the WebKit console (JavaScript in a WebKit browser) redirected traces will not display the correct source position in the console panel. The position of the Console.haxeTrace will be shown instead. This is a limitation of the Haxe logging API.
Flash targets can talk to the WebKit console over external interface, but messages will not show the correct position. Use a ConsoleView if you require log positions.