9 Syntax10.Scn.Fnt ZParcElemsAlloc Syntax14.Scn.Fnt70qPopupElemsAllocOberonV1.Guide.Text#Syntax10.Scn.FntDoc.Open OberonV1.Guide.Text6Syntax12.Scn.Fnt Z Syntax20.Scn.FntSyntax12i.Scn.FntgOW^qi Z Syntax16.Scn.Fnt zg! _  Z mSyntax12b.Scn.Fntu   jQ C  n ) "_  ! F  ; K  / `H 2 Q "Qzw  .K Y j K Z  Z [A %  NOOPZ A Fk  N wA? @Q 'G+ 092.$_NO[ Mp"Re:W5URoPlease read the older but longer version of this text () to get more infomation how to programm the System. The Oberon Guide Jrg Gutknecht [Updated for Release 4.0, Michael Franz, 25.10.93] This guide provides an introductory description of the Oberon system on the user's level. Advanced users are referred to the official Oberon documentation published by Addison_Wesley: N. Wirth and M. Reiser: Programming in Oberon. Steps beyond Pascal and Modula_2. ISBN 0-201-56543-9. Tutorial for the Oberon programming language and concise language reference. M. Reiser: The Oberon System. User Guide and Programmer's Manual. ISBN 0-201-54422-9. User manual for the programming environment and reference for the standard module library. N. Wirth and J. Gutknecht: Project Oberon. The Design of an Operating System and Compiler. ISBN 0-201-54428-8. Program listings with explanations for the whole Oberon system, including the compiler for NS32000. Introduction History Oberon is simultaneously the name of a project and of its outcome. The project was started by Niklaus Wirth and the author late in 1985 with the goal of developing a modern and portable operating system for personal workstations. Its results are an implementation of the system for the Ceres computer and a programming language (see section Literature). The development of the language Oberon needs perhaps a short justification. It became quite inevitable because the type-system of available languages turned out to be too restrictive to express the desired data model in a natural and safe way. We refer to report for a definition of the new language, and to the third and fourth chapter of this text for some examples of its application. Design Principles For the present, we focus on the system Oberon, beginning with a brief overview of its design principles. The underlying dynamic model is extremely simple. There exists a single process acting as a common carrier of multiple tasks. This process repetitively interprets commands, which are the official entities of execution in Oberon. Commands are atomic actions operating on the global state of the system. Unlike customary interactive programs, they rigorously avoid direct dialogs with the system user. The following typical examples indicate the bandwidth covered by the concept of command: Placing the caret, inserting a character into a text, selecting a piece of text, deleting a selected piece of text, applying a new font to a piece of text, searching a pattern in a text, compiling a software module, opening a viewer, backing up a sequence of files to diskette, and displaying a directory. We emphasize that the execution of a command always results in non-volatile information. For example, in the last example, this means that the displayed directory is a text that might immediately undergo further processing. Typically, commands report the outcome of their execution in the form of an entry in the system-log. Therefore, the log provides a complete protocol of the current session. Commands are initiated by input actions. Apart from a few universal operations, every input action is connected with a displayed viewer, to which its further handling is delegated. A viewer in Oberon is a rectangular area on the screen that can display any kind of data. Most viewers feature a thin frame and a title-bar containing a menu. Any mouse-oriented input is handled by the viewer the mouse points to. Data from the keyboard is immediately passed over to the current so-called focus-viewer. We notice that command interpretation is a highly decentralized activity in Oberon and, as such, is a substantial contribution to what we consider as Oberon's most important quality, namely unlimited extensibility. Implementing a new viewer type is a very powerful but also quite far-reaching method to extend the Oberon system. It is only appropriate in conjunction with the installation of a new class of displayable objects (for example graphics or tables). The fourth chapter will provide more insight into this topic. A more moderate way to increase the system's functionality consists in adding new commands operating on objects of an already existing class (for example a language compiler operating on text). We shall see in the third chapter that Oberon's open and coherent modular architecture provides effective support for that. Practically all system ingredients and resources are directly accessible and usable via modular interfaces on as high a level of abstraction as possible. We should deduce from the foregoing that there is no symbolic wall in Oberon separating actual users from developers. Users are encouraged to customize the system and tailor it to their individual needs by designing and implementing private commands and facilities. Little is "hardwired" in the system. However, there are several general conventions and existing tools. They are presented in the next chapter. Acknowledgement I gratefully acknowledge Niklaus Wirth's initiative and willingness for travelling through the adventures of designing and building a new workstation, a new language, and a new operating system, escpecially under the given severe restrictions of personal resources. Without his competence and extraordinary commitment this mammoth-project could not have been successfully completed. I am also very grateful for the possibility to include an extract of Niklaus Wirth's Draw guide in the first chapter. My thanks further go to the Oberon user's community, in particular to Martin Reiser, Hans-Peter Mssenbck, and Beverly Sanders for their constructive critisism and valuable suggestions for improvements. User's Guide Commands and Tools Among the classes of possible objects to be handled by a computer system the class of texts plays a key role. Not only are input and output data frequently represented as text, but also objects and commands are often identified by their name. Text is, therefore, a predefined class of objects in Oberon. This manifests itself immediately after system startup, when, besides of the log-viewer, a so-called tool viewer is automatically opened on the screen. It contains a list of command names, some of them followed by parameters. Command names in Oberon are of the form M.P, where M designates a module (package) and P a procedure (operation) that is provided by the module. A user activates a command simply by pointing to its name with the mouse and clicking the middle mouse key. For example, activating the command Edit.Open will result in a new viewer showing some default text. More often than not, the execution of a command is parameterized. For example, the opening of another tool needs the specification of its name, as in System.Open Edit.Tool or in System.Open Backup.Tool. Although typical, this is not by far the most general case of a parameter specification. Some commands accept an entire list of names following the command name and execute repeatedly for each member of the list. In principle, a text obeying an arbitrary syntax (understood by the command) could be passed over equally well. Commands may even expect as parameters objects of any kind currently existing in the system such as viewers, text selections, caret, and a global star-shaped pointer. Some commands even allow different ways of paramewter specification. For example, if System.Open or Edit.Open is called with a "^"-symbol instead of a file name following the command name, then the file name is taken from the most recent selection. In general, a "^"-symbol following a command name always refers to the current selection. It is noteworthy that tools are ordinary texts distinguishing themselves from more usual texts only by their structure and contents. In particular, tools are amenable to editing operations. Looking at this differently, we recognize that commands like Edit.Open Explanations.Text may well slip into a prose text and be activated directly in situ. Obviously, no limits are set to fantasy exploiting this universal scheme of command interpretation. One rather moderate application of the universal scheme discussed above is the construction of interconnected texts. As a matter of fact, the set of standard tools is structured as a tree with the System.Tool as ancestor and the tools listed in the System.Tool as its descendants. We recall that the hierarchical tool system may easily be customized on the fly by adjusting command lists (including parameters) to personal requirements, reconfiguring the tool hierarchy, installing new tools, or even providing on-line documentation. We now discuss editing operations. Recall first that most commands are interpreted individually by viewers. There are, however, a few more universal operations, which are handled directly by the central system. For example, when you type escape, all marks on the display are removed, including caret and text selections. Or, when you type ctrl shift del the system immediately terminates the execution of the current command and opens a trap-viewer displaying the state of the interrupted process. Notice that we have just identified you as the reader of this guide with a user of the system. In order to simplify phrasing, we shall henceforth occasionally do so tacitly. Next we turn to viewers and display-specific operations. Oberon uses a tiling viewer system. The display is divided into vertical tracks, and each track is further subdivided into viewers. In reality, the structure of viewers is three-dimensional. A new track may in fact overlay one or, more generally, an integral number of existing tracks. The original configuration will be reestablished when the overlaying track is later removed. Although the global screen layout can be changed, we relate our current explanations to the standard layout showing two tracks, a larger user track on the left and a narrower system track on the right. In principle, viewers are allocated automatically by the respective commands using a little heuristics. For example, tool viewers are opened in the system track, and document viewers in the user track. However, you can override any automatic allocation by first placing the pointer at the location where you desire the top of the new viewer to be placed. The pointer is a star-shaped marker, and it is placed by moving the mouse to the desired location and then hitting the SETUP key. In order to change the size of an existing viewer, simply point to its title-bar, press the left mouse key, and move the mouse up or down accordingly. You can also conveniently move a viewer to any different place on the display screen by starting exactly as just explained, then interclicking the middle mouse-key, dragging the mouse to the new location, and releasing all keys there. Interclicking means clicking (pressing and releasing) a secondary mouse button at an arbitrary time while a primary mouse key is being held down. In general, interclicking is an efficient and versatile tool to multiply the expressiveness of the mouse. In Oberon, interclicking is applied according to a systematic underlying pattern. You will find out more about this pattern in the following chapters. Perhaps the easiest and most important rule says that the current command is nullified, if all remaining mouse-keys have been interclicked (not necessarily simultaneously) during the action. By convention, most viewers (so-called menu-viewers) show a header consisting of a title and a list of selected commands (menu). These commands automatically refer to their own viewer. In the case of ordinary text viewers, commands are included from the System tool-package and the Edit tool-package. System.Close removes the viewer, Edit.Copy opens a new viewer displaying the same instance of text, Edit.Grow lets the viewer grow to the size of a full track or of the whole display, Edit.Locate locates a text position, and Edit.Store stores the text on file. We shall explain these commands in greater detail in the following sections on tools. First, we fix some terminology and general conventions. We shall call marked an object or a location if it is visibly or invisibly marked by the earlier introduced star-shaped pointer. Visibility of the pointer is irrelevant in most cases. As an exception we mention the explicit allocation of a viewer, which requests the pointer to be visible. Note that an explicitly allocated viewer is automatically marked. Also note that the pointer is initially invisible and placed in the lower left corner of the display. By convention, the title of a viewer is normally either the name of the displayed object or the name of the command that opened this viewer. Further, if a list of names is passed to a command as a parameter, it must be terminated by a symbol other than a name, for example by the character "~". By another convention, the upper right corner of the display is reserved for the log viewer reporting on the progress and result in the execution of a command. Finally, there are several default extensions of file names. Among them are Text, Graph and Pict for file copies of texts, graphics, and bitmap pictures respectively. In the following sections we shall use the terms parameter and parameter list in the restricted sense of "item following the command name" and "list of items following the command name" respectively. The Edit Tool Package We have stated earlier that extensibility was a key objective in the design of Oberon. It was therefore enticing to realize also system-oriented commands as extensions of the system-core on a highest possible level in the modular hierarchy, thereby achieving maximal flexibility. Such a strategy is particularly appropriate for text editing. It manifests itself in the existence of an edit tool package providing an extensible set of powerful editing commands. Nevertheless, several built-in commands are interpreted directly by text frames. They include positionning the text within its viewer, placing the caret, inserting a typed character, selecting a part of text, deleting a selected part of text, copying a selected part of text, copying attributes and, most importantly, executing an arbitrary command which is specified by its name. We should point out that all of these built-in commands are applicable in particular to menu-bars (which, in fact, are ordinary text frames featuring an inverted background color). Mouse Commands Text positionning. In order to reposition a text within a viewer, move the mouse into the viewer's scrolling-zone. This is a vertical bar along the left borderline of about 0.5 cm width. You can scroll forward by pressing the left mouse key, moving the mouse, and releasing the key when the text line that you want to become the top line is underlined. Notice that every text viewer shows a small crossbeam indicating the current position of the displayed section within the entire text. You can position a text directly by clicking the middle mouse key at the location where you want the crossbeam to be. If you wish the beginning of the text to be displayed, you can alternatively simply click the right mouse key anywhere within the scroll-bar. Placing the caret. If you want to place the caret, move the mouse to the desired text, press the left mouse button and, while keeping it down, move the caret to the desired position. Any subsequently typed characters are then inserted at this position. Selecting text. You can select any contiguous stretch of text by moving the mouse to the desired beginning, pressing the right mouse button and, while holding it down, dragging the selection to the end. If you click twice at the beginning, the selection is automatically extended to the origin of that text line. If a piece of text is too large to be selectable within a single viewer, use Edit.Copy to open an adjacent second viewer. Then select the beginning of the stretch of text in the upper viewer and its end in the lower viewer separately. Note that a separate selection may be active for each displayed text section, including headers of viewers. If several selections exist simultaneously on the display, commands normally refer to the most recent one or to the most recent ones. There are the following interesting interclick-variants of caret placing and text selection that combine these marking operations effectively with text editing. Remember the general rule saying that any mouse-controlled operation that is currently under execution can be nullified by interclicking all remaining mouse-keys. Copying text. If you interclick the middle mouse button while you are placing the caret, the most recent selection is automatically copied to the caret's position as soon as you release the left button. This feature is particularly convenient for copying a specific template to several different places. Alternatively, if the caret is already set and you click the middle mouse key while you are selecting a piece of text, the selected text is copied to the caret's position when you release the select-button. This option is most conveniently used in order to copy a given string to various places. In order to neutralize (undo) any "interclick", simply click the remaining third button while still holding down the primary key. Copying attributes. If you interclick the right mouse button while you are placing the caret, the character attributes (font, color, vertical offset) of the character by the caret is automatically applied to the most recent selection as soon as you release the left button. Deleting text. If you click the left mouse-button while selecting a text, the selected text is eventually deleted. Here also, the interclick can be undone by an additional interclick of the middle mouse-key. Notice that the above described editing operations are applicable to a header of a viewer only restrictedly. A header cannot be changed. Nor can the caret be placed in a header. Further notice that the copy variant and the delete variant of the select command apply also in the case of large selections involving split viewers. Activating a command. Activating a named command from within a text viewer is generic and therefore the most general built-in operation. In order to do it simply point to the command's name and click the middle mouse key. Sometimes (e.g. in a test phase) it is important that the newest version of the module providing the desired command is loaded before the command is actually executed. In order to force this, simply interclick the left key while you are pressing the middle mouse key and pointing to the command's name. If command execution fails, the system falls into a trap. There is no interactive debugger currently available under Oberon. However, a trap handler is automatically called whenever a trap has occurred. It displays the state of the interrupted process, including the stack of procedure activations. It also relates the location of trap to a position in the source program text. In order to find the failing statement simply display the source program and mark its viewer. Then select the position number in the trap viewer and invoke Edit.Locate. The following table summarizes the basic meanings of the three mouse-keys: The left key is the point-key. It is used to focus a certain location, i.e. to place the caret. The middle key is the execute-key. Pressing and releasing it causes the appropriate command interpreter to be called. The right key is the select-key. It is used to select objects within a viewer. Summary of mouse commands  primary button left middle right ----------------------------------------------------------------- secondary button none set caret execute select left - free and execute delete middle copy selection - copy this selection right copy attributes - -  According to Oberon's basic scheme, additional functionality is provided by the text edit tool package. It contains the following commands. Edit Commands Edit.Open opens a viewer in the user track displaying the specified text. The text is alternatively specified by a parameter on the command line or, if a "^"-symbol follows the command name, by the most recent selection of a name. If none exists, a default name is taken. In order to override automatic allocation, place the pointer anywhere on the screen. Edit.Show M.X opens a viewer in the user track displaying the specified object X of module M. If the implementation of M is available, the implementation of X is shown, otherwise X's definition is displayed. Edit.Store writes the text in the marked viewer to the file with the name defined by the parameter, or, if called from the menu line of a text viewer, writes the displayed text to the file with the name of the viewer. Edit.Recall inserts the most recently deleted piece of text at the position of the caret. Edit.CopyFont transfers the font from the marked location to the most recent text selection. Edit.ChangeFont applies the font specified by the parameter to the most recent text selection. Edit.ChangeColor applies the color specified by the parameter to the most recent text selection. Edit.ChangeOffset applies the vertical offset specified by the parameter to the most recent text selection. Edit.Search searches a pattern in the marked text. The pattern is defined by the most recent text selection. If none exists, the previous pattern is used. Searching is started at the position of the caret. If none exists in the marked text, searching starts at the beginning. The initial value of the pattern is the space character. Edit.Locate positions the text in the marked viewer according to the position-number indicated by the most recent text selection. Leading non-numerical items in the text selection are ignored. Edit.Print ServerName ["%"] { (TextFileName | "*") ["/" NofCopies] } sends all texts specified by the parameter list to the print server whose name is taken from the first entry in the parameter list. Names in the parameter list refer to text files, the symbol * to the text in the marked viewer. The symbol % specifies the vanilla-print option. If active, the texts are printed in a single monospaced small Font (Gacha10l). This option is typically used for printing source program listings. NofCopies optionally specifies the desired number of copies. It must be a single-digit number. This command assumes that the correct user identification has previously been installed (by calling System.SetUser). The System Tool Package This package features system related commands. Among them are procedures to display tools in the form of viewers, to close viewers and tracks, to define and display all kinds of system oriented parameters, and to provide basic utilities for the manipulation of named files. In addition, the system tool package contains a trap handler that is implicitly called after a trap has occured. It displays the current state of the system stack. System.Open opens a viewer in the system track displaying the specified tool. The tool is alternatively specified by a parameter on the command line or, in the case of a "^" following the command name, by the most recent selection of a name. If none exists, a default name is taken.. System.OpenLog opens a viewer in the system track displaying the system-wide log. Notice that the log is updated regardless of its visibility. Therefore, the log always shows the complete history of the current session. System.Copy opens a copy of the original viewer displaying the same instance of contents. System.Grow lets the viewer grow to the size of a whole track or, if applied to a viewer already filling a track, to the size of the whole display. Note that the original constellation will be reestablished when the grown viewer is later removed. System.Close removes the marked viewer from the display, or, if called from the menu line of a text viewer, removes the own viewer. System.CloseTrack closes the marked track, i.e. removes all viewers in this track. System.Recall reopens the most-recently (perhaps erronously) closed viewer.. System.Time displays the current date and time. If date and time parameters dd.mm.yy hh.mm.ss (day, month, year and hour, minute, second) immediately follow the command name, System.Time first sets date and time accordingly. System.Watch displays the amount of currently used disk space and memory resources. System.Collect initiates a subsequent garbage collection. System.Free unloads every module specified by the parameter list. If a module name is immediately followed by *, imported modules are also unloaded. System.ShowModules displays a map of all currently loaded modules. System.ShowCommands ModName displays a list of all commands exported by this module. System.State ModName displays the global data of the specified module. System.SetUser accepts the user's identification in the form UserName "/" Password without echoing it on the display. UserName is up to eight characters long (initials in most cases). The password is an arbitrary string. System.Directory displays the selection of all disk files whose name match the template specified by the parameter. The parameter is a string and may contain the symbol "*" as a wildcard. If option "d" is specified ("/d" immediately following the parameter) additional information about file sizes and dates is displayed. In the case of a "^" following the command name the parameter is taken from the current selection. System.CopyFiles processes a parameter list of pairs A => B. Copies each file A to B. In the case of a "^" following the command name the parameter is taken from the current selection. System.RenameFiles processes a parameter list of pairs A => B. Renames each file A to B. In the case of a "^" following the command name the parameter is taken from the current selection. System.DeleteFiles deletes each file specified by the parameter list. In the case of a "^" following the command name the parameter (a single file name) is taken from the current selection. System.SetFont applies the font specified by the parameter to subsequently typed characters. System.SetColor applies the color specified by the parameter to subsequently typed characters. System.SetOffset applies the vertical offset specified by the parameter to subsequently typed characters. The Compiler Tool Package This package contains the Oberon compiler. The result of compilations is shown in the log viewer. Possible errors are listed in the log viewer together with their position in the source text. In order to locate the error within the source text, use Edit.Locate in the log viewer's title menu. The compiler tool exports a single command: Compiler.Compile compiles all texts specified by the parameter list. Names in the parameter list refer to text files, the symbol * to the text in the marked viewer. In the case of a "^" following the command name the parameter list is taken from the current selection. The Compiler.Tool describes the compiler options that are available. The Miscellaneous Tool Package This package provides utilities to convert files and determine statistical data. Miscellaneous.ConvertBlanks converts all text files specified by the parameter list by replacing pairs of leading spaces by tab characters. "^" following the command name refers to the current selection (a single file name). Miscellaneous.ConvertTabs converts all text files specified by the parameter list by replacing leading tab characters by pairs of spaces. "^" following the command name refers to the current selection (a single file name). Miscellaneous.CountLines counts the lines of all text files specified by the parameter list. "^" following the command name refers to the current selection (a single file name). Miscellaneous.GetObjSize extracts code size and data size from all object files specified by the parameter list. "^" following the command name refers to the current selection (a single file name). The Backup Tool Package This package handles the transfer between main disk and diskette. The diskette must be in drive 1. Backup.Directory displays the directory of the currently loaded diskette. Backup.DeleteFiles deletes all files specified by the parameter list from the currently loaded diskette. Backup.ReadAll reads all files from the currently loaded diskette. Backup.ReadFiles reads all files specified by the parameter list from the currently loaded diskette. Backup.WriteFiles writes all files specified by the parameter list to the currently loaded diskette.