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 ^] 相同的方式顯示命名模組的定義，但所選模組匯出的實際在其他模組中使用的物件將以綠色顯示。當使用滑鼠中鍵單擊此綠色點時，它將顯示使用該物件的模組列表。使用滑鼠游標選擇其中一個模組並釋放滑鼠鍵，將開啟該模組。此“在何處使用？”請求僅在模組實際被其他模組使用時才有價值。此請求可能需要一些時間才能完成。僅使用限定的多部分模組名稱的第一部分。