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:


is an Oz class that implements the Browser.


is an instance of Browser.'class'2:

BrowserObject = {New Browser.'class' init}


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:

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


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.


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


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:


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


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:

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:

For example, the value of X determined by the expression

  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 RN= or CN=, if necessary. For instance, the Browser output of the example:

  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:

  P = proc {$ S} {Browse {Value.status S}} end 
  {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:

  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
           {Show 'Unify!'}
           S = @first
           state := start
  UnifyTwo = {New UnifyTwoClass noop}
  proc {UnifyAction S}
     {UnifyTwo click(S)}
  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:


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 optionvalue)

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.

Konstantin Popov
Version 1.4.0 (20080702)