Browser and Watson User's Guide

Tutorial objective

Estimated time: 20 minutes.

Definition module

In Oberon, it is not necessary to write down the definition of a module: the browser and Watson are two software development tools that take care of extracting the necessary information from the module. In the following, it will be explained wherefrom the information is collected.

Introducing the browser

Using the browser

Show module definition - Browser.ShowDef

• d: show detailed information, that is: record size and offset of fields in records, entry number of exported variables and procedures.
• e: expand base types (recursive application of the browser)

Show object definition - Browser.ShowObj (not in OMEGA)

Example: Browser.ShowObj Display.Frame\d

Introducing Watson

Some of its extra capabilities are:

1. The module definition can be constructed from the (source) module text. In that case, Watson extracts three additional information elements from the text and includes them in the definition text:
   1. exported comments of the form (** any comment *)
   2. references to tutorials in the form of interspersed comments like:    (*L Tutorial.Label *)
   3. the pre- or the post-conditions and their trap number found in ASSERT statements. The ASSERT statement text must adhere to the following convention:    100 <= trap < 110 : pre-condition    120 <= trap < 130 : post-conditionNote that Watson removes the export marks (*) but not the read-only marks (-).

2. The definition text is a hypertext with hyperlinks of different meanings indicated in different colors:
   1. Imported modules appear in red. Such a hyperlink displays a module definition.
   2. Types and constants appear in blue. Such a hyperlink displays an object definition or moves to the location of its definition in the current definition text.
   3. Tutorial or document names appear in green. Such a hyperlink opens a tutorial at a defined point, where an explanatory text is provided.

3. The definition module may be a HTML text which can be viewed with any commercially available Web browser or with the Oberon Web browser. In that case hovewer, all hypertext links will appear in the same color.

Sample module

CONST
        (** Maximum number of items in array *)
        MaxItems* = 12;
        (** Name size *)
        NameLen = 32;
    TYPE
        Name* = ARRAY NameLen OF CHAR;

        (*L Watson.HELPITEM *)
        (** Item is an object with a name and a color *)
        Item* = POINTER TO ItemDesc;
        ItemDesc* = RECORD (Obj.ObjDesc)
            name-: Name; (** Name of the item *)
            col: INTEGER
        END;
    VAR
        items-: ARRAY MaxItems OF Item; (** Array of items - Read-only *)
        defaultCol*: INTEGER; (** Default color of an item *)
        W: Texts.Writer; (* A writer *)

    (** Get the color of a given item *)
    PROCEDURE GetColor*(item: Item; VAR col: INTEGER);
    BEGIN
        ASSERT(item # NIL, 100);
        col := item.col
    END GetColor;

    (** Create an item *)
    PROCEDURE MakeItem*(VAR item: Item; name: Name; col:INTEGER);
    BEGIN
        NEW(item); item.col := col;
        COPY(name, item.name);
        ASSERT(item # NIL, 120)
    END MakeItem;

    (** Insert an item in the array *)
    PROCEDURE InsertItem*(item: Item);
        VAR i: INTEGER;
    BEGIN
        ASSERT(item # NIL, 101);
        i := 0;
        LOOP
            IF i = MaxItems THEN EXIT END;
            IF items[i] = NIL THEN items[i] := item; EXIT END;
            INC(i)
        END
    END InsertItem;

    (** Delete an item in the array *)
    PROCEDURE DeleteItem*(itemNr: INTEGER);
    BEGIN
        ASSERT((0 <= itemNr) & (itemNr < MaxItems), 100);
        items[itemNr] := NIL
    END DeleteItem;

BEGIN
    Texts.OpenWriter(W); defaultCol := 15
END Items.

Select the module text and copy it into a new empty viewer which you may name "Items.Mod" for instance. Compile the module with:

    Builder.Compile /s Items.Mod and show the definition of Items with:

    Watson.ShowDef Items

Here is the definition text which an Oberon user will obtain. It is reproduced below to the attention of those who are browsing the tutorial on the Web.

    DEFINITION Items; (* PS *)

    IMPORT Objects;

    CONST
        (* Maximum number of items in array *)
        MaxItems = 12;
        (* Name size *)

    TYPE
        Name = ARRAY 32 OF CHAR;

        (* Item is an object with a name and a color *)
        Item = POINTER TO ItemDesc;
        ItemDesc = RECORD( Objects.ObjDesc    )
            name-: Name; (* Name of the item *)
        END;

    VAR
        items-: ARRAY MaxItems OF Item; (* Array of items - Read-only *)
        defaultCol: INTEGER; (* Default color of an item *)

    (* Get the color of a given item *)
    PROCEDURE GetColor (item: Item; VAR col: INTEGER);
        (* precondition (100): item # NIL *)

    (* Create an item *)
    PROCEDURE MakeItem (VAR item: Item; name: Name; col: INTEGER);
        (* postcondition (120): item # NIL *)

    (* Insert an item in the array *)
    PROCEDURE InsertItem (item: Item);
        (* precondition (101): item # NIL *)

    (* Delete an item in the array *)
    PROCEDURE DeleteItem (itemNr: INTEGER);
        (* precondition (100): (0 <= itemNr) & (itemNr < MaxItems) *)

END Items.

Clicking on the green spot causes this document to open here:
Meaning of "Item"

Item is a simple object with a name and a color attribute. It has no real function or purpose but is nevertheless a realistic example.

Using the Watson panel

This graphical user interface features a number of command buttons, controlled by the settings in the Setup iconizer, and by check boxes appearing in the lower part.

Setting the options with Setup

Search order: This text field contains a string of up to five capital letters which determines the order, from left to right, in which the various information sources are consulted for creating a definition text. Each source is represented by a capital letter with the following meaning:

D: an existing definition text is used. The definition text is searched in a definition module (.Def) or in the archive specified in the text field "Def Archive". The name of a definition module must have the suffix ".Def" - see Make definitions.
M: the text of a module is used to create the definition module. The text may be contained in a module file or in a marked viewer.
S: the symbol information in a symbol file (.Sym) or respectively in an object file is used to create the definition text.
C: the information in an object file is used to create the definition text. Only the definition of commands will appear in this case. It is equivalent to what is obtained with a System.ShowCommands command.
T: a tutorial associated with a module is opened. The association between module and tutorial is defined in "Tutorial Links".

Files are searched only in the current directory. If the field is empty, Watson uses the default order "DMSCT", the order in which the information sources were described above. Note that this order offers the best possible search strategy and that, at each missing step the amount of information Watson supplies is diminished. However, the order may be changed and information sources not explicitely specified are ignored. The set order can also be overwritten with the Select Source radio-buttons.

Def Archive: This text field contains the name of the archive (file) containing the definition texts. The module definitions of the Oberon system are delivered in the archive "Definitions.Arc". This file may be extended with the definitions of custom developed modules. Alternatively, new separate archives may be constructed, but only one such archive can be searched. The archive must be found in the current search path (see OBERON.INI)

Mod file name: This text field may contain a module name filter of the form [prefix] [* [postfix]] in which Watson will replace the asterisk by the name specified in the Watson command. If only a prefix is specified, Watson assumes a module name obtained by the concatenation of three parts: prefix name .Mod . In both cases, If the system cannot open a file with that name, it will further attempt to open a file named name .Mod .

Application: A number of Oberon modules are platform dependent: that is for instance the case for Win.Display.Mod. Watson can produce the definition module of almost any module on a Windows platform if the text field contains "Win." or "Win.*.Mod".

Examples: Assuming that the name appearing in the Watson command is "Sample":

    Win.*.Mod2   =>   Win.Sample.Mod2
    Win.*        =>   Win.Sample
    Win.         =>   Win.Sample.Mod
    *.Mod3       =>   Sample.Mod3
    *            =>   Sample
    empty string =>   Sample.Mod

Example:

    Watson    Watson
    Items     Watson.HELPITEM

Select Source

Example:
Given the default order "DMSCT", selecting "Sym" results in the new order "SDMCT".

Formatting Options

• without alteration to the source module text,
• with all text appearing in Syntax10 font: Syntax10 font only is checked (command option p). This option overwrites the Comments in italic one.
• with comments in italic: Comments in italic is checked (command option i),

Symbol file Options

• without addition,
• with all details: Show all details is checked (command option d),
• with extended base types information: Extend base type is checked (command option x).

These options are the same as those of the browser commands, that is \d and \x respectively.

Command buttons for showing information

Each of the buttons hides a command which is described in the subsequent chapter.

[Show Def ^] Watson.ShowDef ^.

[Show Obj ^] Watson.ShowObj ^.

[Show Def *] Watson.ShowDef *.

[Show Imp ^] Watson.ShowImports ^.

[Show Exp ^] Watson.ShowExports ^.

[Check ^] Watson.Check ^.

Watson commands

Show module definition - Watson.ShowDef

If the information source is the marked viewer (*), this marked text must be a valid Oberon program text. If it is not, the location of the error is listed in the log.

If the information source is a tutorial (T), it is opened as specified in "Tutorial Links".

The options belong to three different categories:

1. the information sources identified by the capital letters D, M, S, C, T in the desired order. This order takes precedence over the search order defined in the setup. Not all sources must be explicitely named - the remaining positions will be taken over from the setup.        Search order in Setup: DMSCT        Command parameter: \MS        Resulting search order: MSDCT
2. the formatting options: d and x.
3. the symbol file options: i and p

and try this: Watson.ShowDef \T Items

Show object definition - Watson.ShowObj

The options are the same as for Watson.ShowDef.

Make definitions - Watson.MakeDefs

Try this: Watson.MakeDefs Items.Mod ~

Such a definition module may be added to an archive of definitions at any time, if it is of some importance to your installation.

Convert definitions to HTML text- Watson.ConvertDefs

Try this: Watson.ConvertDefs Items.Def Watson.Def ~

Show imports (OMEGA only) - Watson.ShowImports

Show exports (OMEGA only) - Watson.ShowExports

Check module consistency (OMEGA only) - Watson.Check