# 2 Using the Browser

In this section the functionality of the Browser is presented. Simultaneously, notions required for reading of the following sections are explained.

## 2.1 Invoking the Browser

The Browser can be invoked by the predefined unary procedure `Browse`. For example,

> `{Browse X}`

creates a browser window and shows the current constraint on the variable `X`.

A browser window can be closed via the Close entry of the Browser menu, or by the `C-x` keyboard accelerator.

Normally the `Browse` procedure is used in the top-level computation space. Browsing from local computation spaces is not concurrent 1, and there is a number of restrictions of the Browser functionality, which are considered in the Section 2.9.

## 2.2 The User Interface

A Browser window (Figure 1.1) consists of a text widget in which browsed information is shown, a menubar and scrollbars. The red button on the right side of the menubar, called the break button, is used to stop browsing as soon as possible.

Menu entries can be active or passive, depending on the Browser state. On the right side of menu entries their keyboard accelerators are specified, if any. Using an accelerator of a (currently) passive entry has no effect.

The view of the text widget can be adjusted by the scrollbars. The number of lines in the text widget depends on information that is browsed, and is limited only by the Tk implementation. Lines in text widget are never wrapped, and its width is determined automatically by the Tk library.

The Browser automatically changes the layout of information shown in its text widget whenever the window size is changed by the user, or user changes the currently used font.

The usual 'cut-and-paste' mechanism can be used with the Browser if you want to paste a part of a term's representation somewhere else. A text fragment is selected like in Emacs or the X11 terminal emulator (xterm), except that the `Shift` key must be kept pressed during the selection, and that there are no word- or line- selection modes. On Windows, a selected text is copied by means of `C-q`

## 2.3 Browser Module

The `Browser` module exports the following values:

`Browser.'class'`

  is an Oz class that implements the Browser.

`Browser.object`

  is an instance of `Browser.'class'`2:

  > `BrowserObject = {New Browser.'class' init}`

`Browser.browse`

  is an unary procedure used to tell `Browser.object` to browse its argument. It is also available as procedure `Browse` in the OPI:

  > `Browse = proc {$ X} {Browser.object browse(X)} end`

Methods of the `Browser.'class'` are summarized in the Chapter 4.

## 2.5 The Basic Output Format

This section describes the simplest Oz value's representation the Browser supports. In this case the Browser thinks of a value as of a tree that leaf nodes are primitive values and non-leaf nodes are records. Note that equal subtrees are represented as many times as they occur; this is a simplification with respect to the value graph described in Section 2.4. More concise representations are discussed in Section 2.7.

The description is divided into the following issues:

- Browsing of arbitrarily deep and wide terms.

- Using parenthesis to override the term constructor precedences.

- Printing layout for compound terms.

Each (sub)term is shown in a certain viewing form, namely, it can be drawn completely, partially or it can be shrunken:

Completely

  means that the term is shown if it represents a primitive value, finite domain or a variable; or all its subterm(s) are shown in some form if the term is compound.

Partially

  means that only the first subterms of the compound term are shown, the rest of them is replaced with '`,,,`';

Shrunken

  means that the term is shown in the form '`,,,`'.

The form of each (sub)term is determined by values of the width and depth browse limits:

Width

  specifies for each compound (sub)term the number of its subterms that are shown, i. e. the number from above.

Depth

  specifies the depth in a term's representation where subterms are shrunken.

These parameters can be set via the `Display Parameters` submenu of the `Options` menu. Note that increasing of values `Depth` and `Width` affects all currently shown terms.

Terms shown by the Browser are built with respect to the Oz term constructor precedences as defined in Oz Notation , and uses round parentheses to override them.

The Browser tries to produce the most compact printing layout for compound terms. Namely, it packs in one row as many subterms as possible, while usual minimal subterm indentation is provided. The only exception of this rule is that record subterms are shown in one column if they don't fit in one row. However, this can be switched off via turning off the option `Record Fields Aligned` of the `Layout` submenu of the `Options` menu.

A non-shrunken (sub)term can be shrunken explicitly by means of the `Shrink` commands of the `Selection` menu. The command is applied to a selection, which is described in Section 2.8. A partially shown or shrunken (sub)term can be expanded:

- If a (sub)term was shrunken, it is replaced by a subterm which is `Depth` deep, where `Depth` is the Browser's current expansion limit. The expansion limits can be set by means of the `Display Parameters` submenu of the `Options` menu.

- If a (sub)term was partially shown, its further `Width` subterms are viewed, where `Width` is the Browser's expansion limit.

## 2.6 Controlling Browsing

Browser draws terms sequentially, in the depth-first, left-to-right fashion, one term after each other. Drawing process can be stopped nearly all the time by pressing the break button (or by using the `Break` entry of the `Browser` menu). When browsing is being stopped, (sub)term(s) yet to be drawn appear in shrunken form, and started but not yet completed (sub)term(s) appear partially.

More than term can be shown simultaneously in a Browser window. The Browser contains a first-in-first-out buffer where information about browsed terms is kept. The buffer size limits the number of simultaneously shown terms; it can be set via the `Buffer` submenu of the `Options` menu. All terms in the buffer can be removed via the `Clear` entry of the `Browser` menu. All terms except the last one can be removed via the `Clear All But Last` entry.

## 2.7 Represntation of Rational Trees

The Browser can represent a cyclic tree, i.e. a tree-like graph that contains ``backward'' edges (edges starting in a node below its target). A cyclic tree representation is built as follows:

- A subterm representing a target node obtains a unique prefix of the form `C``=`, where is a number.

- For all backward to that node edges pseudo-nodes are created, which are represented as `C`.

For example, the value of determined by the expression

> `declare
> N = {NewName}
> X = a(f1:X f2:N f3:N)
> in {Browse X}`

is browsed as `C1=a(f1:C1 f2:<N: `N`> f3:<N: `N`>)` .

A textual representation of a value graph described in Section 2.4 is generated using the ``minimal graph'' representation option. Informally speaking, in this mode equal subgraphs are represented only once; all subsequent subgraphs that are equal to an already created one 1 are represented as a reference to it. For instance, the Browser output for the example above would be `R1=a(f1:R1 f2:R2=<N: `N`> f3:R2)` .

The representation options are set by means of the `Representation` submenu of the `Options` menu, by choosing one of the `Tree`, `Graph` and `Minimal Graph`.

Note that additional parenthesis are inserted around textual representation of (sub)terms with the prefixes `R``=` or `C``=`, if necessary. For instance, the Browser output of the example:

> `declare
> X = a(1|2|3|b(c) b(c))
> in {Browse X}`

is `a(1|2|3|(R1=b(c)) R1)`.

The only operation defined on reference names is dereferencing. Its effect is scrolling to a term tagged with the reference name, and selecting it. The `Deref` command can be invoked from the `Selection` menu or by the keyboard accelerator, similarly to `Expand` and `Shrink` commands.

## 2.8 Actions

An arbitrary shown (sub)term can be selected. This is achieved by clicking the left mouse button. Deselection proceeds by clicking the right one. Selected (sub)terms are shown in the text widget on a wheat colored background. Selected (sub)terms are targets for both pre-defined browser operations (like `Shrink` and `Expand` described in SectionSection 2.5) and user-defined actions.

The Actions mechanism provide for application of unary procedures with the current selection as an argument. There are two predefined actions: `Show` and `Browse`. There can be user-defined actions, which are added by means of the `add`, `set` and `delete` methods of `BrowserClass`:

> `%%
> declare
> P = proc {$ S} {Browse {Value.status S}} end
> in
> {Browser add(P label:'Show Status')}
> {Browser set(P)}
> %% use the action now!
> {Browser delete(P)} % delete(all)
> {Browser set(Show)}`

In this example a new action `P` is created (which effect is printing the status of a selection), then it is added (`add`) and set (`set`) as the current one. At this point user can either click the middle mouse button or use the `Apply Action` entry of the `Selection` menu in order to invoke it. After that the action is removed, and the predefined `Show` is set as the current.

A useful application of this mechanism is the action which equates two subsequent selections:

> `declare
> class UnifyTwoClass from Object.base
> prop final locking
> attr first: _ state: start
> meth click(S)
> case @state == start then
> {Show 'First...'}
> first := S
> state := continue
> else
> {Show 'Unify!'}
> S = @first
> state := start
> end
> end
> end
> UnifyTwo = {New UnifyTwoClass noop}
> proc {UnifyAction S}
> {UnifyTwo click(S)}
> end
> in skip`

Now we can set this action and browse, for instance, a list constructor with two variables:

> `{Browser createWindow}
> {Browser add(UnifyAction)}
> {Browser set(UnifyAction)}
> {Browser option(representation mode:graph)}
> %%
> {Browse _|_}`

If we will click the middle mouse button subsequently on the list constructor and the second variable, we will get a cyclic list: `C1=_|C1`.

## 2.9 Browsing in Local Computation Spaces

There are the following distinguishing features of using the Browser in a computation space:

- Browsing in a computation space is not concurrent.

- Print names of variables, (Oz) names, procedures, cells, chunks, spaces and threads are quoted. For instance, a variable `A` will be browsed as ``A``, and not as `A`.

- Print names of mentioned above objects are always generated in the extended format, without any respect to the current value of the options `Variable Status` and `Names And Procedures`.

- Feature constraints are converted to records, that is, their representation does not contain ellipses just before the closing parentheses.

- Generally, builiding `graph` and `minimal graph` representation yields wrong results. For instance, two equal variables are not detected as being equal; whereas two tuples `a(_)` and `a(_)` are detected as being equal.

- The Browser needs much more memory and runtime to perform browsing, in particular when large lists are browsed.

- Continuous browsing of big different terms leads to significant memory leakage in the Oz Emulator, which is limited by the total size of a textual representation of all browsed terms.

The differences mentioned above are straightforward once there is the understanding how the Browser works in that case.

The point here is that the Browser operates in the top-level computation space, whereas a constraint describing a value of a given variable can contain variables, names, procedures and so on that belong to the local computation space. These variables cannot occur in constraints in the top-level one; therefore, each constraint browsed in a local computation space is converted to a constraint which does not contain any variables, names and so on this transformation, called here reflection, takes place in the local computation space, where `Browse` call was issued. After that the reflected constraint is passed to the top-level computation space by a special builtin, and actually browsed.

The reflection step can take place only once for a browsed constraint; that is, browsing is not concurrent in this case.

Objects of mentioned above types are replaced by atoms during reflection. The number of new atoms created this way is limited by the size of a constraint graph to be browsed. Since atoms are not a subject for garbage collection in the Oz System, the memory consumed by the System grows up.

Since the reflection process must terminate, the Browser builds a minimal graph representation of a constraint, which is passed to the top-level computation space. This explains the computational complexity of browsing in local computation spaces.

## 2.10 Setting Options

Every Browser option that can be set by means of the `Options` menu can be set also by means of the `option` method of the `BrowserClass`. Its format is

> `option(`group`` option`:` value`)`

There is the complete list of possible options with example values:

> `option(buffer size:1)
> option(buffer separateBufferEntries:false)
> option(representation mode:minGraph)
> option(representation detailedChunks:true)
> option(representation detailedNamesAndProcedures:false)
> option(representation detailedVarStatus:false)
> option(representation strings:true)
> option(representation virtualStrings:false)
> option(display depth:100)
> option(display width:2000)
> option(display depthInc:2)
> option(display widthInc:5)
> option(layout size:14)
> option(layout bold:false)
> option(layout alignRecordFields:true)`

There is an additional group `special` which allows to control the geometry of the Browser window:

> `option(special xSize:800)
> option(special ySize:600)
> option(special xMinSize:300)
> option(special yMinSize:200)`

1. Two graphs are equal here iff they are unifiable.