Oberon/ETH Oberon/Tutorial/Watson

These tutorial pages were written by André Fischer (afi) with editorial assistance of Hannes Marais, were hosted at the ETHZ and remain under the ETH license. Related content is found in the system via Book.Tool. Extended content is also available on paper. Some tutorial pages are in the WayBack archive.

Browser and Watson User's Guide

[ Text | Contents | Index | Master index ]

Tutorial objective

Learn how to obtain module information using the browser or the even smarter browser Watson and its companion panel Watson.Panel. Also learn to create definition modules documenting your own system extensions.

Estimated time: 20 minutes.

Definition module

A definition module describes a module interface and is a summary of the complete module. It contains the declaration of the exported names which may be used by other modules. It also known as the public view of the module and its advantage is its textual compactness. With this clearly defined module interface, a module can be used without knowledge of how it is implemented. Also, at construction time a module can be defined without knowledge of how it will be used in the future.

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

The primary tool for retrieving a module definition is the browser. Look for example at the definition module of the compiler: Browser.ShowDef Compiler .

Using the browser

The browser exports only two commands which are documented in the Browser.Tool and are described below. The browser for the OMEGA^[1] version exports only the command "Browser.ShowDef".

Show module definition - Browser.ShowDef

Browser.ShowDef (modName | ^) [\[d][e]] opens a document viewer named "modName.Def" displaying the definition of the named module. Only the first name part in modName is used. The definition is constructed using the symbol information contained in the compiled object file modName.Obj or respectively in the symbol file modName.Sym. The options are:

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)

Examples:

Browser.ShowDef Outlines.Tool - (* only the first name part is used. *)

Browser.ShowDef Outlines.Obj\d

Browser.ShowDef Outlines\e

Browser.ShowDef Outlines\de

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

Browser.ShowObj (modName.objName | ^) [\[d][e]] opens a document viewer named "modName.objName" displaying the definition of a specific object objName in the module modName (only the first name part is used). The options are the same and the definition is constructed in the same manner as for Browser.ShowDef.

Example: Browser.ShowObj Display.Frame\d

Introducing Watson

Watson uses a special strategy for extracting a module definition from various information sources: definition file, module file or marked module text, symbol information, object file, and although not in direct relation, tutorial document. The search strategy is defined by the Search order but it can also be modified on demand. Watson is in essence a "smart" browser with extended capabilities making it indispensable in complex software development projects.

Some of its extra capabilities are:

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-condition
  Note that Watson removes the export marks (*) but not the read-only marks (-).
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.
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 however, all hypertext links will appear in the same color.

Sample module

MODULE Items; (** PS 1.12.96 21:47:21 *)
  IMPORT Obj := Objects, Texts;

  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 1.12.96 21:47:21 *)

  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 above 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

Open the Watson panel with: Desktops.OpenDoc 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

To adjust the settings to your preferences, click on the little square at the left top of the iconizer to flip it. Enter the appropriate values in the various fields as described hereafter. When the settings are adequate, click the [Save settings] button, and click on the little square of the iconizer to return it to its original position. These settings are saved in the Watson library Watson.Lib.

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

Tutorial Links: This text gadget defines the association between modules and tutorials. Each text line contains a name pair with at the left a module name and at the right a tutorial name or a two-part qualified name of the form: tutorial.label . The label, which must be exported by the tutorial, identifies where to open the tutorial. The file name of a tutorial must have the suffix ".html".

Example:

   Watson    Watson
   Items     Watson.HELPITEM

Select Source

When the radio-button "Auto" is selected (this is the default setting), the information sources search order applies, but you can temporarily overwrite this order with one of the remaining radio-buttons. If that is the case, the information source corresponding to the selected radio-button is then searched first, while the remaining sources specified in the search order follow in order.

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

Formatting Options

When a module text in a marked viewer or in a .Mod file is used to create a definition text, the created text may be formatted in three different forms:

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

Note that these options are ignored, if a .Def file is exploited first, e.g. when the searching sequence is DMSCT.

Symbol file Options

When symbol information extracted from a symbol file or an object file is used to create a definition text, the created text may offer three different information contents:

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

Note that these options are ignored, if a .Def or a .Mod file is exploited first, that is, the default search order must start with S or the check box Sym must be checked.

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

Command buttons for showing information

Note that feedback information appears in the Oberon log, indicating from which source Watson obtained the information for constructing the module definition.

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

Note that feedback information appears in the Oberon log, indicating from which source Watson obtained the information for constructing the module definition.

Show module definition - Watson.ShowDef

Watson.ShowDef [\options] (module | * | ^) opens a viewer named "module.Def" displaying the definition of the named module. The name must be an Oberon name, of which only the first part of a qualified multipart name is used. Watson attempts to open the information sources in a specified search order and reports on the outcome of the search: if the requested information is found, the name of the source is listed in the Oberon log, otherwise an error message "no information about ... available" appears.

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:

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
the formatting options: d and x.
the symbol file options: i and p

Exercise: Create a definition module for the sample program "Items.Mod" first. Then make sure that the text gadget of the "Tutorial Links" contains a line

Items Watson.HELPITEM

and try this: Watson.ShowDef \T Items

Show object definition - Watson.ShowObj

Watson.ShowObj [\options] (module.object | ^) opens a viewer named "module.Def" displaying the definition of the selected object in the selected module. The parameter must contain a two-part qualified name of the form module.object, where object is the name of an object exported by module. If that object is not found, the entire module definition is displayed.

The options are the same as for Watson.ShowDef.

Make definitions - Watson.MakeDefs

Watson.MakeDefs [\c] ({modName} (~ | ^) | *) creates a definition module (.Def) for each module file (.Mod) in the list. The module files must be found in the current directory. If the option \c is used, HTML document files (*.Def.html) are created instead. Caution: If a matching definition or HTML file already exists, it is overwritten.

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

Watson.ConvertDefs {defName}~ | ^ converts each definition module (.Def) named in the list into a HTML document file (*.Def.html). The definition modules to convert must be found in the current directory or in the archive file specified in the Watson panel settings.
Caution: If a matching HTML file already exists, it is overwritten.

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

Show imports (OMEGA only) - Watson.ShowImports

Watson.ShowImports [\options] (module | ^) opens a viewer named "module.Imp" displaying a map of all the modules imported by the named module, and of all the exported objects in those modules which are effectively imported. This "uses what?" request may take some time to complete. Only the first part of a qualified multipart module name is used.

Show exports (OMEGA only) - Watson.ShowExports

Watson.ShowExports [\options] (module | ^) opens a viewer named "module.Def" displaying the definition of the named module, in the same fashion as [Show Def ^], but the objects exported by the selected module which are effectively used in other modules are shown in green. When such a green spot is clicked with the middle mouse key, it shows a list of modules using the object. Selecting one of the module with the mouse cursor and releasing the mouse key, opens the module. This "where used?" request is only valuable when a module is effectively used by other modules. This request may take some time to complete. Only the first part of a qualified multipart module name is used.

Check module consistency (OMEGA only) - Watson.Check

Watson.Check {module[*]} | ^ | all opens a viewer named "Check.Out" telling if the named modules can be loaded or not. If not, a message is displayed in the log. The objective is to check the consistency of the named modules or of all modules. Only the first part of qualified multipart names is used.