Qualog is a Java library for inserting logging statements into code. It is a quasi logging module, meaning that it does not support many features from other logging modules, such as Log4J. It differs from Log4J in that it is nearly exclusively focused on output format, including color highlighting, stack traces, and collection unrolling. It requires a minimal amount of configuration, such that the following is sufficient:

public static void main(String[] args)
{
    tr.Ace.setVerbose(true);
    tr.Ace.log("args", args);
}

This produces the following:

[Example.java     89] {Example     #main                } args[0]: this
[                 89] {            #                    } args[1]: is
[                 89] {            #                    } args[2]: a
[                 89] {            #                    } args[3]: test

The Basics

Names

The Qualog code is in the package org.incava.qualog, but for brevity, the class tr.Ace can be used instead, for all but the most advanced functionality, since tr.Ace subclasses (aliases) org.incava.qualog.Qualog.

Initialization

To enable logging, simply call:

tr.Ace.setVerbose(true);

Logging

To generate a simple logging statement:

tr.Ace.log("I'm here");

This, by default, generates a line of output that includes the following, based on where the log method was invoked: the file name (the base name, not the full path), the line number, and the class and method names, then the message passed to the log method.

To log a collection, including both C-style arrays, and objects of type java.util.Collection, the invocation is identical:

Collection comps = new HashSet();

comps.add("VIC-20");
comps.add("C64");
comps.add(new String[] { "][", "//e", "///" });
comps.add("XT");

tr.Ace.log("my computers", comps);

For C-style arrays:

String[] langs = new String[] { 
    "C",
    "C++",
    "Java",
    "Ruby"
};

tr.Ace.log("my languages", langs);

Collections are unrolled recursively.

Stacks

Instead of one line of output, Qualog can write the stack from which the method was invoked:

tr.Ace.stack("hello");

Output is:

[Example.java     89] {Example     #methodTwo           } hello
[                114] {            #methodOne           } ""
[                 34] {            #<init>              } ""
[Main.java        10] {Main        #main                } ""

Stacks can be generated for collections as well, with the full stack written only for the last object in the collection.

Color Highlighting

Normally, log output is written in plain text. On platforms that support it, colors (and other text decorations) can be written instead, either by adding the arguments to the log method, or by replacing the log method name with the color. For the stack method, the color arguments must be passed. For example:

tr.Ace.log(tr.Ace.BLUE, "skies ahead");
// equivalently:
tr.Ace.blue("iris");

tr.Ace.stack(tr.Ace.BOLD, "statement");
tr.Ace.stack(tr.Ace.REVERSE, "direction");

Levels

Qualog supports logging levels, where the "coarsest" is simply verbose, or the equivalent being level 5, the default logging level where an explicit level is not used. However, logging can be done with more specific levels:

tr.Ace.setOutput(tr.Ace.VERBOSE, tr.Ace.LEVEL8);
tr.Ace.log(tr.Ace.LEVEL7, "this is logged");
tr.Ace.stack(tr.Ace.LEVEL9, "this is not logged");

Modes

Qualog supports two logging modes, verbose and quiet. The previous examples, with the "file:line ... class#method ... message" output format, show the result of verbose mode. In quiet mode, only the output message is displayed, not the file, line, class, or method. This supports output expected from using command-line options of "--verbose" versus "--quiet". Of course, levels (see the previous section) are applied to both modes, so the previous example would be:

tr.Ace.setOutput(tr.Ace.QUIET, tr.Ace.LEVEL8);
tr.Ace.log(tr.Ace.LEVEL7, "this message is displayed");
tr.Ace.stack(tr.Ace.LEVEL9, "but not this message");

Filtering

Qualog offers limited filtering, selectively applying colors to a given package, class, or method. In the following example, the class name of Range would be in red, and the class name of Pair would be displayed as bold:

tr.Ace.setClassColor(Range.class.getName(), Qualog.RED);
tr.Ace.setClassColor(Pair.class.getName(), Qualog.BOLD);

Output

By default, Qualog writes to standard error. This can be changed via the setOut method, by passing a stream of type PrintWriter:

tr.Ace.setOut(new PrintWriter(...));

Chaining

The log and stack methods always return true, so they can be used in conditionals, for example:

if (x > 4 && tr.Ace.log("x: " + x) && 
    y < 10 && tr.Ace.log("y: " + y) &&
    z.contains("foo") && tr.Ace.log("foo is in z")) { ... }

This functionality makes it easy to insert debugging statements into the middle of conditionals, without interrupting the existing code.

Example

See the API for more.