Oberon/ETH Oberon/Tutorial/Watson

这些教程页面由André Fischer (afi) 编写，并由Hannes Marais 提供编辑协助，托管在ETHZ，并保留在ETH 许可下。相关内容可在系统中通过 Book.Tool 找到。扩展内容也可在纸质版上获得。一些教程页面位于WayBack 存档中。

浏览器和 Watson 用户指南

[ 文本 | 目录 | 索引 | 主索引 ]

教程目标

学习如何使用浏览器或更智能的浏览器 Watson 及其伴侣面板 Watson.Panel 获取模块信息。此外，还将学习创建定义模块以记录您自己的系统扩展。

预计时间：20分钟。

定义模块

一个定义模块描述了一个模块接口，它是完整模块的摘要。它包含对导出名称的声明，这些名称可被其他模块使用。它也称为模块的公用视图，其优势在于文本的简洁性。通过这个清晰定义的模块接口，可以在不知道实现方式的情况下使用模块。此外，在构造时，可以定义一个模块，而无需了解它在将来如何使用。

在 Oberon 中，无需写下模块的定义：浏览器和 Watson 是两种软件开发工具，负责从模块中提取必要的信息。在下文中，将解释信息从哪里收集。

介绍浏览器

检索模块定义的主要工具是浏览器。例如，看一下编译器的定义模块：Browser.ShowDef Compiler。

使用浏览器

浏览器只导出两个命令，它们在 Browser.Tool 中有文档记录，并在下面描述。OMEGA^[1] 版本的浏览器只导出 "Browser.ShowDef" 命令。

显示模块定义 - Browser.ShowDef

Browser.ShowDef (modName | ^) [\[d][e]] 打开一个名为 "modName.Def" 的文档查看器，显示命名模块的定义。只使用modName中的第一个名称部分。定义是使用编译后的对象文件modName.Obj 或符号文件modName.Sym 中包含的符号信息构建的。选项是

d：显示详细信息，即：记录大小和记录中字段的偏移量、导出变量和过程的条目号。
e：扩展基本类型（浏览器递归应用）

示例

Browser.ShowDef Outlines.Tool - (* 只使用第一个名称部分。 *)

Browser.ShowDef Outlines.Obj\d

Browser.ShowDef Outlines\e

Browser.ShowDef Outlines\de

显示对象定义 - Browser.ShowObj (OMEGA中没有)

Browser.ShowObj (modName.objName | ^) [\[d][e]] 打开一个名为 "modName.objName" 的文档查看器，显示模块modName中特定对象objName的定义（只使用第一个名称部分）。选项相同，定义方式与Browser.ShowDef相同。

示例：Browser.ShowObj Display.Frame\d

介绍Watson

Watson 使用一种特殊的策略从各种信息源中提取模块定义：定义文件、模块文件或标记的模块文本、符号信息、对象文件，尽管没有直接关系，但还有教程文档。搜索策略由搜索顺序定义，但也可以根据需要修改。Watson 本质上是一个具有扩展功能的 "智能" 浏览器，使其在复杂的软件开发项目中必不可少。

它的一些额外功能是

模块定义可以从（源）模块文本中构建。在这种情况下，Watson 从文本中提取三个额外的信息元素，并将它们包含在定义文本中
1. 形式为 (** 任何注释 *) 的导出注释
2. 形式为嵌入式注释的教程引用，例如：(*L Tutorial.Label *)
3. ASSERT 语句中找到的前置条件或后置条件及其陷阱编号。ASSERT 语句文本必须遵守以下约定
  100 <= trap < 110 : 前置条件
  120 <= trap < 130 : 后置条件
  请注意，Watson 删除导出标记 (*)，但不删除只读标记 (-)。
定义文本是一个超文本，具有不同含义的超链接，用不同的颜色表示
1. 导入的模块以红色显示。这样的超链接将显示一个模块定义。
2. 类型和常量以蓝色显示。这样的超链接将显示一个对象定义，或移动到其在当前定义文本中的定义位置。
3. 教程或文档名称以绿色显示。这样的超链接将在定义点打开教程，其中提供解释文本。
定义模块可以是一个HTML文本，可以使用任何市售的Web浏览器或Oberon Web浏览器查看。但是，在这种情况下，所有超文本链接将显示为相同的颜色。

示例模块

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.

选择模块文本并将其复制到一个新的空查看器中，例如，您可以将其命名为“Items.Mod”。使用以下命令编译模块：

Builder.Compile /s Items.Mod 并显示 Items 的定义：

Watson.ShowDef Items

以下是Oberon用户将获得的定义文本。为了那些在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.

点击上面的绿色斑点，将打开此文档这里：
“Item”的含义
Item 是一个简单的对象，具有名称和颜色属性。它没有真正的功能或目的，但仍然是一个真实的示例。

使用Watson面板

使用以下命令打开Watson面板： Desktops.OpenDoc Watson.Panel

此图形用户界面包含一些命令按钮，由Setup图标化器中的设置以及下方出现的复选框控制。

使用Setup设置选项

要将设置调整到您的偏好，请点击图标化器左上角的小方块将其翻转。在各个字段中输入适当的值，如下所述。当设置合适时，点击[保存设置]按钮，并点击图标化器的小方块将其恢复到原始位置。这些设置将保存在Watson库 Watson.Lib 中。

搜索顺序：此文本字段包含一个最多五个大写字母的字符串，它确定从左到右，使用各种信息源创建定义文本的顺序。每个源都用一个大写字母表示，含义如下

D：使用现有的 definition 文本。在定义模块 (.Def) 或文本字段“Def Archive”中指定的存档中搜索定义文本。定义模块的名称必须以“.Def”结尾 - 请参阅创建定义。
M：使用 module 的文本创建定义模块。文本可以包含在模块文件中或标记的查看器中。
S：使用 symbol 文件 (.Sym) 中或对象文件中的符号信息创建定义文本。
C：使用对象文件中的信息创建定义文本。在这种情况下，只会显示 commands 的定义。它等同于使用 System.ShowCommands 命令获得的结果。
T：打开与模块关联的 tutorial。模块和教程之间的关联在“教程链接”中定义。

文件仅在当前目录中搜索。如果字段为空，Watson 将使用默认顺序“DMSCT”，即上面描述的信息源的顺序。请注意，此顺序提供了最佳的搜索策略，并且在每次缺失步骤中，Watson 提供的信息量都会减少。但是，可以更改顺序，并且未明确指定的信息源将被忽略。也可以使用“选择源”单选按钮覆盖设置顺序。

Def Archive：此文本字段包含存档（文件）的名称，该存档包含定义文本。Oberon 系统的模块定义在存档“Definitions.Arc”中提供。此文件可以使用自定义开发模块的定义扩展。或者，可以构建新的独立存档，但只能搜索一个这样的存档。存档必须在当前搜索路径中找到（请参阅 OBERON.INI）

Mod 文件名：此文本字段可以包含模块名称过滤器，格式为 [prefix] [* [postfix]]，其中 Watson 将用 Watson 命令中指定的名称替换星号。如果只指定前缀，Watson 将假设一个模块名称，该名称由三部分组成：prefix name .Mod。在这两种情况下，如果系统无法打开具有该名称的文件，它将进一步尝试打开一个名为 name .Mod 的文件。

应用程序：一些 Oberon 模块是平台相关的：例如，Win.Display.Mod 就是这种情况。如果文本字段包含“Win.”或“Win.*.Mod”，Watson 可以在 Windows 平台上生成几乎任何模块的定义模块。

示例：假设 Watson 命令中出现的名称是“Sample”

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

教程链接：此文本工具定义了模块和教程之间的关联。每行文本包含一对名称，左侧是模块名称，右侧是教程名称或形式为 tutorial.label 的双部分限定名称。标签必须由教程导出，它标识在哪里打开教程。教程的文件名必须以“.html”结尾。

示例:

   Watson    Watson
   Items     Watson.HELPITEM

选择源

当选择“自动”单选按钮（这是默认设置）时，将应用信息源搜索顺序，但您可以使用其他单选按钮暂时覆盖此顺序。在这种情况下，对应于所选单选按钮的信息源将首先被搜索，而搜索顺序中指定的其他源将按顺序被搜索。

示例：给定默认顺序“DMSCT”，选择“Sym”将导致新的顺序“SDMCT”。

格式化选项

当使用标记的查看器或 .Mod 文件中的模块文本创建定义文本时，创建的文本可以以三种不同的形式格式化

不对源模块文本进行修改。
所有文本以 Syntax10 字体显示：选中“仅 Syntax10 字体”（命令选项 p）。此选项将覆盖“注释以斜体显示”选项。
注释以斜体显示：选中“注释以斜体显示”（命令选项 i）。

请注意，如果首先利用 .Def 文件，例如，当搜索顺序为 DMSCT 时，这些选项将被忽略。

符号文件选项

当使用从符号文件或对象文件提取的符号信息创建定义文本时，创建的文本可以提供三种不同的信息内容

不添加任何信息。
显示所有详细信息：选中“显示所有详细信息”（命令选项 d）。
扩展基本类型信息：选中“扩展基本类型”（命令选项 x）。

请注意，如果首先利用 .Def 或 .Mod 文件，即，默认搜索顺序必须以 S 开头，或者选中“Sym”复选框，这些选项将被忽略。

这些选项与浏览器命令中的选项相同，即分别为 \d 和 \x。

用于显示信息的命令按钮

请注意，反馈信息将出现在 Oberon 日志中，指示 Watson 从哪个源获取了信息来构建模块定义。

每个按钮都隐藏着一个命令，将在下一章中描述。

[显示 Def ^] Watson.ShowDef ^.

[显示 Obj ^] Watson.ShowObj ^.

[显示 Def *] Watson.ShowDef *.

[显示 Imp ^] Watson.ShowImports ^.

[显示 Exp ^] Watson.ShowExports ^.

[检查 ^] Watson.Check ^.

Watson 命令

请注意，反馈信息将出现在 Oberon 日志中，指示 Watson 从哪个源获取了信息来构建模块定义。

显示模块定义 - Watson.ShowDef

Watson.ShowDef [\选项] (模块 | * | ^) 打开一个名为“module.Def”的查看器，显示命名模块的定义。该名称必须是 Oberon 名称，其中仅使用限定的多部分名称的第一部分。Watson 尝试按指定顺序打开信息源，并报告搜索结果：如果找到所需的信息，则 Oberon 日志中会列出源名称，否则会显示错误消息“关于...的信息不可用”。

如果信息源是标记的查看器 (*)，则此标记文本必须是有效的 Oberon 程序文本。如果不是，则日志中会列出错误的位置。

如果信息源是教程 (T)，则按“教程链接”中指定的打开方式打开。

选项属于三个不同的类别

由大写字母 D、M、S、C、T 表示的信息源，按所需顺序排列。此顺序优先于设置中定义的搜索顺序。并非所有源都必须明确命名 - 剩余位置将从设置中获取。
    设置中的搜索顺序：DMSCT
    命令参数：\MS
    结果搜索顺序：MSDCT
格式选项：d 和 x。
符号文件选项：i 和 p

练习：首先为示例程序“Items.Mod”创建定义模块。然后确保“教程链接”的文本工具包含一行

Items Watson.HELPITEM

然后试试这个：Watson.ShowDef \T Items

显示对象定义 - Watson.ShowObj

Watson.ShowObj [\选项] (module.object | ^) 打开一个名为“module.Def”的查看器，显示所选模块中所选对象的定义。参数必须包含形式为 module.object 的两部分限定名称，其中 object 是 module 导出的对象的名称。如果未找到该对象，则会显示整个模块定义。

选项与 Watson.ShowDef 相同。

创建定义 - Watson.MakeDefs

Watson.MakeDefs [\c] ({modName} (~ | ^) | *) 为列表中的每个模块文件 (.Mod) 创建一个定义模块 (.Def)。必须在当前目录中找到模块文件。如果使用选项 \c，则会创建 HTML 文档文件 (*.Def.html)。注意：如果匹配的定义或 HTML 文件已存在，则会覆盖它。

试试这个：Watson.MakeDefs Items.Mod ~

如果定义模块对您的安装很重要，则可以随时将其添加到定义存档中。

将定义转换为 HTML 文本 - Watson.ConvertDefs

Watson.ConvertDefs {defName}~ | ^ 将列表中命名的每个定义模块 (.Def) 转换为 HTML 文档文件 (*.Def.html)。要转换的定义模块必须位于当前目录中或 Watson 面板设置中指定的存档文件中。
注意：如果匹配的 HTML 文件已存在，则会覆盖它。

试试这个：Watson.ConvertDefs Items.Def Watson.Def ~

显示导入（仅限 OMEGA） - Watson.ShowImports

Watson.ShowImports [\选项] (模块 | ^) 打开一个名为“module.Imp”的查看器，显示命名模块导入的所有模块的映射，以及这些模块中实际导入的所有导出对象。此“使用什么？”请求可能需要一些时间才能完成。仅使用限定的多部分模块名称的第一部分。

显示导出（仅限 OMEGA） - Watson.ShowExports

Watson.ShowExports [\选项] (模块 | ^) 打开一个名为“module.Def”的查看器，以与 [Show Def ^] 相同的方式显示命名模块的定义，但所选模块导出的实际在其他模块中使用的对象将以绿色显示。当使用鼠标中键单击此绿色点时，它将显示使用该对象的模块列表。使用鼠标光标选择其中一个模块并释放鼠标键，将打开该模块。此“在何处使用？”请求仅在模块实际被其他模块使用时才有价值。此请求可能需要一些时间才能完成。仅使用限定的多部分模块名称的第一部分。