5 API Reference

The Inspector functor is available for import at the URI 'x-oz://system/Inspector'. It exports the following application programmer's interface:

inspect: {Inspector.inspect X}; opens a new Inspector window if none exists, then displays X in the active widget.
inspectN: {Inspector.inspectN +I X}; opens a new Inspector window if none exists, then displays X in the widget with number I, counting from zero. Note that the chosen widget must have been created already. This is always the case for number zero.
configure: {Inspector.configure +Key +Value}; sets the configuration option with key Key to value Value. The following sections starting with Section 5.2 explain in detail which keys and values are valid parameters.
configureN: {Inspector.configureN +I +Key X}; behaves like configure but directly addresses the widget number I which must be existing already.
close: {Inspector.close}; closes the Inspector window, if any.
'class': Inspector.new +OptionRecord; creates are new Inspector instance. This function replaces the old class field for safety reasons. Extensions are still possible by using adapter construction. This object is concurrency safe and can be used in any space. +OptionRecord denotes a record containing user options, with unit the empty case. Of course, all features must denote a valid option.
object: Inspector.object; is the default instance of the Inspector and is implicitly used by Inspect, Inspector.inspectN, Inspector.configure, Inspector.configureN and Inspector.close. This object is creating using the above Inspector.new function.
reflect: Inspector.reflect; exports the reflection function used by the inspector to reflect deep space values. Use at your own risk.
reflect: Inspector.unreflect; exports the unreflection function used by the inspector. Use at your own risk.

5.1 Inspector object methods

The inspector object provides the methods shown below.

inspect(X): inspects the value X.
inspectN(+N X): inspects the value denoted by X using widget number N. Keep in mind then the corresponding widget must have been created already.
configureEntry(+Key +Value): tells the inspector to update the option denoted by Key with value Value.
close: closes and unmaps the inspector object.

5.2 Inspector Options

This section covers global Inspector options.

inspectorWidth: {Inspector.configure inspectorWidth +I}; adjusts the Inspector's horizontal window dimension to I pixels. Defaults to 600.
inspectorDepth: {Inspector.configure inspectorDepth +I}; adjusts the Inspector's vertical window dimension to I pixels. Defaults to 400.
inspectorOptionsRange: {Inspector.configure inspectorOptionsRange +A}; determines which widgets will be affected by reconfiguration. A can be either 'active' or 'all', with the obvious meaning.

5.3 Value Represenation

This section explains how to configure the value representation using the API.

widgetTreeWidth: {Inspector.configure widgetTreeWidth +I}; adjusts the global width traversal limit to I. Defaults to 50.
widgetTreeDepth: {Inspector.configure widgetTreeDepth +I}; adjusts the global depth traversal limit to I. Defaults to 15.
widgetTreeDisplayMode: {Inspector.configure widgetTreeDisplayMode +B}; switches between tree and graph representation, depending on whether B denotes true or false, respectively.
widgetUseNodeSet: {Inspector.configure widgetUseNodeSet +I}; determines the subtree alignment. If I is 1, the standard aligment is used. A value of 2 selects fixed width indentation.
widgetShowStrings: {Inspector.configure widgetShowStrings +B}; switches between normal and readable representation of strings. It defaults to false.

This sections explains how to create context menus. The current implementation only allows to attach entire context menus to a node. A context menu simply is a tuple menu(WidthList DepthList MappingList ActionList) as follows:

WidthList and DepthList denote integer lists describing the possible limit changes. The integer zero serves as separator indicator. Both lists default to [1 5 10 0 ~1 ~5 ~10].
MappingList denotes a list of tuples following the pattern 'Shown Label'(MapFun). See Section 5.5.2 for details about writing mappings.
If the function should be used for auto-mapping, use auto('Shown Label'(MapFun)) instead. Each list must not contain more than one auto mapping entry.
ActionList denotes a list of tuples following the pattern 'Shown Label'(ActionProc). See Section 5.5.3 for details about writing actions.

5.5.1 Registering context menus

Context menus are registered using the statement

{Inspector.configure +Type +Menu}

where Type denotes an atom composed of a valid type prefix as shown in Figure 5.2 and a Menu suffix. Menu denotes the menu as described in Section 5.5.

`hashtuple`	Tuples with label `#`
`pipetuple`	Possible open lists such as streams
`list`	Closed lists
labeltuple	Tuple with any other label
record	Oz Records (without kinded reocrds)
kindedrecord	Feature constraints
future	Futures
free	Variables
fdint	Finite domain variables
fset	Finite set menus
array	Oz arrays
dictionary	Oz dictionaries
class	Oz classes
object	Oz objects
chunk	Oz chunks
cell	Oz cell

Figure 5.2: Menu types

For example, executing

{Inspector.configure recordMenu Menu}

assigns a new record context menu denoted by Menu.

5.5.2 Mapping Functions

Writing mapping functions is easy: Every function follows the pattern below.

fun {MyMapFunction Value MaxWidth MaxDepth} if {WantToMap Value} then ... /* computations */ ... else Value end end

MaxWidth and MaxDepth are integers denoting the node's width and depth limits. This allows to handle cycles independently of whether they would have been recognized or not. Keep in mind that mapping functions should not have side-effects.

5.5.3 Action Procedures

Action procedures follow the pattern below.

proc {MyAction Value} ... /* computations */ ... end

5.6 Equivalence Relations

Equivalence relations are registered using the statement

{Inspector.configure widgetRelationList ['RelationName'(RelFun) /* ... more relations */]}

Every RelFun is expected to compute the characteristic function of its relation and therefore follows the pattern

fun {RelFun X Y} /* computations resulting true or false */ end

These functions should not have side effects. Again, the implementation currently only supports the replacement of the all relations.

5.7 Inspecting user-defined types

Oz allows to add new types to the system. The Inspector is able to display such values without beeing rebuilt provided that they can be distinguished using Value.status and transformed to a built-in type. In this case, it is sufficient to add a new mapping function attached to that type. In the default case, the inspector will use Value.toVirtualString to obtain a useful representation of the unknown value. Depending on its type, the value will be monitored und updated, too.

For example, to introduce weak dictionaries to the inspector use the code shown below.

local fun {ItemFun V W D} {WeakDictionary.items V} end Key = case {Value.status {WeakDictionary.new _}} of det(T) then T [] _ then generic end TypeKey = {VirtualString.toAtom Key#'Menu'} in {Inspector.configure TypeKey menu(nil nil [auto('Show Contents'(ItemFun))] nil)} end

See Section 5.5.2 for details about how ItemFun is built.

`int`	`float`	`atom`
`bool`	`unit`	`name`
`bytestring`	`procedure`	`future`
`free`	Oz variables
`fdint`	Oz finite domain variables
`label`	record/tuple labels
`feature`	record features
`background`	widget backround
`variableref`	using occurence of graph reference
`ref`	defining occurence of graph reference
`generic`	the generic value
`braces`	parentheses around mixfix tuples
`colon`	separator between feature and subtree
`widthbitmap`	left arrow
`depthbitmap`	down arrow
`separator`	separators such as `#` and `\|`
`proxy`	background color used for mappings
`selection`	background color used for selections