Using the textual interface of Oberon

Tutorial objective

The tutorial is an application of the Gadgets system: you should organize your display space with, on the left your prefered desktop and on the right the Oberon system track. If your desktop covers the entire display screen, middle click on the [Close] button located in the top left corner and position this tutorial frame on the left, that is in the user track, of the screen for good visibility.

Estimated time: 60 minutes.

The viewer

The vertical stripe of a track is further subdivided horizontally into viewers. Viewers are stacked, one on top of another, and fill tracks from the bottom up without leaving gaps. Within this grid, viewers are opened and closed by issuing commands or under program control. There are two commands for opening text viewers - Edit.Open and System.Open. A log viewer, a specialized text viewer, is opened with System.OpenLog.

Viewer layout

• the title bar with the viewer name at the left followed by by what is called the menu text (a set of commands). The title bar appears on a grey background.
• the vertical scroll bar located on the left
• the main text area below the title bar

Placement of the viewer

Normally, when an open command is issued, Oberon makes a reasonable guess as to where to place the viewer on the display. That is precisely the difference between the two open commands above: with Edit.Open, the viewer will open in the user track and with System.Open in the system track. The user, however, can indicate where the viewer should open by means of the pointer. Regardless of where Oberon would have opened the viewer, it will open in the track of the pointer and its top edge will be at the height of the pointer.

Verify those assertions by yourself, placing the pointer in any of the user or system tracks and clicking on System.OpenLog. Remove these viewers by clicking on the menu command "System.Close".

An opened viewer may be resized or relocated with its title bar.

Mouse commands

• Mouse Left key - ML: point i.e. set the caret (mark the insertion point)
• Mouse Middle key - MM: execute a command pointed at by the mouse focus
• Mouse Right key - MR: select (character, word, stretch of text, line, paragraph)

Cursor in main text area

Oberon abandons the notion of a program, atomic actions are called Commands. Commands are executed by pressing and releasing the middle mouse key while pointing at the command name. As visual feedback the command name is underlined while the middle mouse key remains pressed.

   
    Notes:
        (1)    There are two variants of copy:
                Left + middle: Copy an existing selection to the caret.
                    The caret is set with this interclick.
                Right + middle: Make a selection and copy it over to the caret.
                    The caret must have been set earlier.
        (2)    Font and color of the text at the caret location are copied.
        (3)    This interclick is specially useful when developing software.

Cursor in scroll bar

Cursor in title bar

Large selection

(1)    Select the beginning of the desired large selection in one viewer. An arbitrary piece of the beginning may be selected - just one character is sufficient.

(2)    Select the end of the desired large selection in the other viewer. As before, an arbitrary large piece of the end may be selected. Interclick commands can be given while selecting the tail piece. They operate on the whole large selection.

Now the entire text, including the invisible portion between the beginning of the first and the end of the second sub-selection, is selected.
Note: The entire large selection is NOT highlighted in reverse video. Only the two sub-selections are.

Taking control of Oberon

To see an example corresponding to the first case click on this command System.Time . It is a command producing this output text in the System.Log (look at the upper part of the system track):
            System.Time dd.mm.yy hh:mm:ss.

To see an example corresponding to the second case click on this command System.ShowModules. It is a command producing an output text in a System.ShowModules viewer which is opened in the system track.

And now click on the 'System.Close' command which appears in the title bar of that viewer.

Command definition and syntax

where Procedure is the name of a procedure exported by a module named Module. You have just seen three examples of that.

Parameter

• text following the command name
• text contained in the selection
• the viewer from which the command is executed
• the marked viewer, i.e. designated by the pointer.

No parameter

Single name as parameter

        name = namePart{"."namePart}.
        namePart = letter{letter | digit}.
        letter = "A" | "B" | ... | "Z" | "a" | "b" | ... |"z".
        digit = "0" | "1" | ... | "9".

Thus, if a name is expected, any special symbol terminates the name. For example, System.Open EmptyViewer.Text~. Upper and lower case letters are considered distinct.

The following are examples of structured names:

Oberon3TUI.html the name of a file containing this tutorial and the name of this document: look at its name plate at the top left corner.

Sample.Mod the name of a file containg the source text of the module Sample, written in the Oberon language.

List of names as parameter - {nameList} ~

List of name pairs as parameter - {namePair} ~

    System.RenameFiles A.Mod => a.Mod B.Text => b.Text ~

The arrow composed of the character "=" immediately followed by ">" that the file "A.Mod" is being renamed to "a.Mod" and not the other way round.

Selection as parameter - ^

Re-using a recent example, select a few initial characters in -> EmptyViewer.Text and click on System.Open ^.

Warning! Watch this pitfall: Do not place the selection in the system log viewer. Many commands write to it and as you know the selection may be cleared before this last parameter is processed.

Marked viewer as parameter - *

Using the standard editor

Opening a text viewer - Edit.Open

Exercises:
        Edit.Open Sample1.Mod and close it.
Select a portion or whole of Sample1.Mod .
        Edit.Open ^ and close it.
        Edit.Open
and close it.

Showing a string in a module - Edit.Show

Exercise:
Edit.Show Examples.InsertAt opens a viewer displaying the source text in the file Examples.Mod.

Storing a text - Edit.Store

Undo last delete - Edit.Recall

Note: Deletion and Edit.Recall can be used in combination to move text from one place to another (cut and paste).
    (1) Delete text to be moved.
    (2) Place the caret at the insertion point.
    (3) Execute Edit.Recall

Caution: After having deleted the text to be moved, do NOT use the backspace key to correct a typing error, e.g. while typing "Edit.Recall". The deleted text is lost and replaced by the last character deleted.

Changing the color - Edit.ChangeColor

Changing the font - Edit.ChangeFont

Copying the font - Edit.CopyFont

Searching a pattern - Edit.Search

Note: Repeated execution of this command searches for subsequent occurrences of the pattern.

Locating a position - Edit.Locate

Printing a text - Edit.Print

On workstations directly connected to a printer ServerName is the name of the printer port (e.g. LPT1 on a PC, or QuickDraw on an Apple Macintosh).

Clearing a viewer - Edit.Clear

Replacing text - Edit.Replace

Replacing all text occurrences - Edit.ReplaceAll

Using the file system

- Bak: Back-up files; if the contents of a viewer (text editor, graphics editor, ...) are saved (e.g. with Edit.Store) and if a file with the viewer's name already exists, then the old file is kept under the name "name.Bak".

- Fnt: Font file; a font file name usually has the following structure:
        <name of font family> <size and attribute> "." <output device> ".Fnt".

Example: Syntax12i.Scn.Fnt - A 12 point italic display font of the Syntax font familiy

- Mod: Oberon module (source program text)
- Obj: Oberon module (object files)
- Pict: picture file
- Text: text file
- Tool: Working menu, which is freely editable (e.g. Backup.Tool)
- Graph or Graphic: graphics document

The facilities for file administration are provided by the command module System.

Directory management commands

System.ChangeDirectory [path]name | .. | ^ changes the current subdirectory to the one specified.

System.DeleteDirectory [path]name | ^ deletes the specified subdirectory.

System.Directory [template[\d] | ^] opens a viewer named "System.Directory" displaying a list of file names. The names selected are those matching the template, a text string with no blank character, in which the "*" is used as a wildcard - that is, a character matched by any string of non-blank characters. If the option \d follows the template without blanks, the listing includes the date and the time of file creation and file size in bytes. In the case of a ^ following the command name the parameter is taken from the current selection. The viewer is opened in the system track unless the pointer is set.

Examples of templates are as follows:

   String    Files selected
   *          All files
   *.*        All files with a name containing at least two parts, separated by a dot
   *.Mod      All files with suffix "Mod"
   Test.*     All files with first name part "Test"
   *.Scn.*    All files with second name part "Scn"

    MODULE Sample1;
        IMPORT Oberon, Texts;
        VAR W: Texts.Writer;

        PROCEDURE Hello*;
        BEGIN
            Texts.WriteString(W, "hello, world");
            Texts.WriteLn(W);
            Texts.Append(Oberon.Log, W.buf)
        END Hello;

    BEGIN
        Texts.OpenWriter(W)
    END Sample1.

Now be prepared to close the viewer which will open when you click on System.Directory Sample*/d.

File management commands

System.RenameFiles {name1} => name2 ~ | ^ A list of name pairs name1 and name2 is processed. The pairs are separated by "=>". The directory entry name1 is renamed to name2. If a file name2 already exists, it is overwritten.

Exercise: System.RenameFiles Sample1.Mod => Sample3.Mod ~

System.DeleteFiles {name} ~ | ^ deletes all the files named the parameter list.
Caution: Don't forget to terminate the parameter list with a "~". Any file whose name appears after the intended name list will be deleted without a request for confirmation or the possibility of undoing the operation.

Exercise: System.DeleteFiles Sample2.Mod Sample3.Mod ~

Using a diskette - Native Oberon

Selecting a diskette drive - Backup.SetDriveA

Formatting a diskette - Backup.Format

Backup.Format [/D] | /H formats a 2-sided double density (DD) or respectively a high density (HD) diskette in the selected drive. In both cases the diskette has the proprietary Oberon format.

Initializing in DOS format - Backup.InitDOS

Initializing in Oberon format - Backup.InitOberon

Viewing the contents of a diskette - Backup.Directory

For an empty formatted diskette the following information is displayed:
    DD - 720KB    after formatting        free 112 entries/ 713 KB
                        after initializing        free 111 entries/ 713 KB
    HD - 1.44MB after formatting        free 223 entries/ 1423 KB
                        after initializing        free 222 entries/ 1423 KB

Reading all files from a diskette - Backup.ReadAll

Reading files from diskette - Backup.ReadFiles

Writing files to diskette - Backup.WriteFiles

Deleting files from diskette - Backup.DeleteFiles

Using a DOS formatted diskette

Importing from DOS - System.CopyFromDOS

Exporting to DOS - System.CopyToDOS

Caution: File names may be changed (capitalized and truncated).

Using a diskette - Oberon for Windows

DOSBackup is the backup utility for Oberon for Windows. It maintains on diskette an extra file _TRANS.TBL containing a translation table of Oberon long names to DOS names.

Macintosh Note:

You can only use this tool on your Macintosh if you installed MacOS 7.5 or any tool that extends you computer with the capability of reading MSDOS diskettes (e.g. PC Exchange).

Initializing a diskette - DOSBackup.Init

Backup.Init erases all the Oberon files and the translation table file on the diskette in the selected drive. Note that all the other DOS files stored on the diskette are not affected.

Viewing the contents of a diskette - DOSBackup.Directory

File management commands

DOSBackup.ReadFiles {name} ~ | ^ reads all files specified by the parameter list from the diskette to the hard disk.
Caution: If a file name on the diskette matches a file name on the disk, that file is overwritten.

DOSBackup.WriteFiles [%] {name} ~ | ^ writes all files specified by the parameter list to the diskette and updates the translation table file. If the option % is used, the files are compressed (using the LZW compression algorithm). Compressed files have a special header that is recognized by the commands ReadFiles and ReadAll; that is, no option is required by these commands.
Caution: If a file name on the disk matches a file name on diskette, that file is overwritten.

DOSBackup.DeleteFiles {name} ~ | ^ deletes all files specified by the parameter list from the diskette and updates the translation table file.
Caution: Do not forget to terminate the parameter list with a "~".

System commands

- file administration
- open documents (i.e. document viewers) and the Oberon log
- close, copy and enlarge viewers and tracks, recall previously closed viewers
- display system state information
- unload modules and force garbage collection

Controlling the viewers in the tracks

System.Copy opens a copy of the viewer in which System.Copy is executed (from the title bar or from the main text). The copy displays the same data as the original viewer. Almost exclusively used from the title bar. The command that makes a large selection possible. But, click here System.Copy you will be surprised! You now have cloned your desktop: whatever you do in one is reflected in the other. Please middle click on the "Close" button under "Oberon.Desk" to remove the copy.

System.Grow enlarges the viewer in which the command is executed (from the title bar or from the main text). An overlay track is opened and the viewer grows to cover the whole track or, if applied to a viewer already filling a track, to cover the whole display. The enlarged viewer displays the same data as the original one.

In the overlay track, other viewers may open and close in the usual manner. If the last viewer in the overlay track closes, the underlying track is restored.

System.Close removes a viewer from the display: if executed from the title bar, it removes the viewer containing the title bar, and if executed from a main text, the marked viewer. The viewer adjacent (on top) to the one which is closed reclaims the freed display area. If the track is an overlay, the underlying track is recovered.

Note: The viewer's contents are NOT saved to disk. If the viewer is erroneously closed before saving to disk (Store), data may be permanently lost, but the viewer may be reopened with System.Recall.

Controlling the Oberon log

System.ClearLog clears the contents of the Oberon log, regardless of its visibility.

Reopening the viewer closed last - System.Recall

Closing a track - System.CloseTrack

Displaying / setting time and date - System.Time

Displaying free memory space - System.Watch

Initiating a garbage collection - System.Collect

Unloading modules - System.Free

Freeing libraries - System.FreeLibraries

Show commands exported by a module - System.ShowCommands

Show loaded libraries - System.ShowLibraries

Displaying loaded modules - System.ShowModules

Displaying the active tasks - System.ShowTasks

Displaying a module's state - System.State

The Internet tools use the module 'NetSystem' which is controlled by a section of the oberon.ini file. Issue the command 'System.State NetSystem' to verify its presence.

Controlling the global text attributes

System.SetColor colorNumber | ^ applies the color specified by the parameter to subsequently typed characters. The parameter must be an integer denoting a color in the color palette.

System.SetOffset offsetNumber | ^ applies the vertical offset specified by the parameter to subsequently typed characters. The parameter must be an integer designating the vertical character offset.

The Registry

System.Set ^ | section key := [ value ] enter a section and key in the registry and associate a value with it. If a value is not given, the entry for the given section and key is removed from the registry. Section, key, and value may be either names or strings.

System.Get ^ | section [ key ] inspect the value of a given section and key in the registry. If a key is not given, all keys contained in the section are listed together with their associated values. Section and key may be either names or strings.

What's next?