org.openquark.cal.runtime
Class DebugSupport

java.lang.Object
  org.openquark.cal.runtime.DebugSupport

public final class DebugSupport
extends Object

Contains various helper methods implementing machine-independent debugging support. In particular there are methods for displaying a textual debug string from a CalValue, as well as for calculating various useful statistics based on the CalValue. These methods all have in common that they don't modify the CalValue in any way, and thus are useful, when combined with tracing (such as with the Debug.trace function), for viewing the actual state of values in CAL as execution is occurring, without altering the execution's reduction sequence.

Author:

Bo Ilic

Nested Class Summary

static class

DebugSupport.InternalValueStats Immutable value class holding statistical information gathered from a CalValue The statistics/information gathered by this class are for debugging purposes only and should not be relied upon in production code.

Method Summary

static String	showInternal(CalValue calValue) Returns a representation of the argument CalValue useful for debugging purposes.
static String[]	showInternal(CalValue[] calValues) Returns representations of the argument CalValue elements useful for debugging purposes.
static String	showInternalForArgumentValues(CalValue[] argumentValues) A helper function for tracing support.
static String	showInternalGraph(CalValue calValue) Returns a representation of the CalValue argument useful for debugging purposes.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

showInternal

public static final String showInternal(CalValue calValue)

Returns a representation of the argument CalValue useful for debugging purposes. This representation is subject to change and should not be relied upon in production code. Does not do any evaluation or modify the CalValue in any way.

showInternal does not traverse the CalValue graph by using the Java call stack, and hence will not throw a java.lang.StackOverflowError. For example, it can handle displaying evaluated CAL lists that are thousands of elements long. Also, showInternal will successfully display cyclic value graphs.

showInternal will show some of the sharing of graph nodes in the graph structure of the CalValue. If a node having one or more children is shared, its first appearance will be marked e.g. <@nodeNumber = nodeText>, and subsequent appearances will just display as <@nodeNumber>. Nodes having zero children that are shared (such as function nodes or simple value nodes) are not shown as being shared. This makes the output easier to read while showing the most important sharing. To see more of the graph structure, use showInternalGraph.

Any exceptions (subclasses of Throwable) are caught and rethrown as a java.lang.RuntimeException with cause set to the caught exception, and a message displaying a partial showInternal result string if one is available. The main cause of exceptions will be an exception in Object.toString() on one of the foreign objects held onto by the CalValue graph.

Parameters:

calValue - CalValue whose textual representation is to be displayed. Cannot be null.

Returns:

a textual representation of the CalValue for debugging purposes.

showInternal

public static final String[] showInternal(CalValue[] calValues)

Returns representations of the argument CalValue elements useful for debugging purposes. This representation is subject to change and should not be relied upon in production code. Does not do any evaluation or modify the CalValue in any way.

showInternal does not traverse the CalValue graph by using the Java call stack, and hence will not throw a java.lang.StackOverflowError. For example, it can handle displaying evaluated CAL lists that are thousands of elements long. Also, showInternal will successfully display cyclic value graphs.

showInternal will show some of the sharing of graph nodes across the graph structures of the CalValue instances. If a node having one or more children is shared, its first appearance will be marked e.g. <@nodeNumber = nodeText>, and subsequent appearances will just display as <@nodeNumber>. Nodes having zero children that are shared (such as function nodes or simple value nodes) are not shown as being shared. This makes the output easier to read while showing the most important sharing. To see more of the graph structure, use showInternalGraph.

Any exceptions (subclasses of Throwable) are caught and rethrown as a java.lang.RuntimeException with cause set to the caught exception, and a message displaying a partial showInternal result string if one is available. The main cause of exceptions will be an exception in Object.toString() on one of the foreign objects held onto by the CalValue graph.

Parameters:

calValues - array of CalValue whose textual representations are to be displayed. Cannot be null.

Returns:

a textual representation of the each of the CalValue for debugging purposes.

showInternalGraph

public static final String showInternalGraph(CalValue calValue)

Returns a representation of the CalValue argument useful for debugging purposes. This representation is subject to change and should not be relied upon in production code. Does not do any evaluation or modify the CalValue in any way.

showInternalGraph does not traverse the CalValue graph by using the Java call stack, and hence will not throw a java.lang.StackOverflowError. For example, it can handle displaying evaluated CAL lists that are thousands of elements long. Also, showInternalGraph will successfully display cyclic value graphs.

showInternalGraph attempts to show more of the graph structure of the CalValue. If a node is shared, its first appearance will be marked e.g. <@nodeNumber = nodeText>, and subsequent appearances will just display as <@nodeNumber>. Indirections are shown using an asterisk *. To see less of the graph structure, and potentially a more readable output, use showInternal.

Any exceptions (subclasses of Throwable) are caught and rethrown as a java.lang.RuntimeException with cause set to the caught exception, and a message displaying a partial showInternalGraph result string if one is available. The main cause of exceptions will be an exception in Object.toString() on one of the foreign objects held onto by the CalValue graph.

Parameters:

calValue -

Returns:

a textual representation of the CalValue argument for debugging purposes.

showInternalForArgumentValues

public static String showInternalForArgumentValues(CalValue[] argumentValues)

A helper function for tracing support. This is equivalent to displaying the individual space-separated arguments by just calling showInternal, except that reference shared between separate arguments are displayed. For example, in the trace for: let x = [20, 30, 40 :: Int]; in deepSeq x x The 2 arguments of deepSeq will show sharing in the trace such as: Prelude.deepSeq <@1 = (Prelude.Cons 20 (Prelude.Cons 30 (Prelude.Cons 40 Prelude.Nil)))> <@1>

Parameters:

argumentValues -

Returns:

String