# 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`.

## 5.4 Visual Settings

This section explains how to configure the visual aspects of node drawing using the API.

`widgetTreeFont`

  > `{Inspector.configure widgetTreeFont font(family:``+F` `size:``+S` `weight:``+W``)}`

  selects the widget font as follows:

  - `+F` denotes either `'courier'` or `'helvetica'`.

  - `+S` denotes any integer out of `{10, 12, 14, 18, 24}`.

  - `+W` denotes either `'normal'` or `'bold'`.

  The default is `font(family:'courier' size:12 weight:'normal')`.

`widgetContextMenuFont`

  > `{Inspector.configure widgetContextMenuFont` `+V``)}`

  selects the font used to draw the context menus. `V` denotes any valid X font description. It defaults to `'-adobe-helvetica-bold-r-*-*-*-100-*'`.

### 5.4.1 Color Assignment

`{Inspector.configure` `+A``` `+Color``)}`

  assigns color `Color` to item type `A`. `Color` denotes an atom describing any valid hexadecimal RGB color code. `A` is composed of a type prefix and a 'Color' suffix. For example,

  > `{Inspector.configure intColor '#AAFF11'}`

  chooses to draw integer nodes with color `'#AAFF11'`. The complete list of known types is shown in table Figure 5.1.

  `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

  Figure 5.1: Known atomic types

## 5.5 Customizing Context Menus

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.