# 2 Invoking the OPI

This chapter describes how to invoke the OPI, i. e., how to access its functionality.

## 2.1 Invoking the OPI in the Unix Environment

The easiest way to start the OPI is to type the following command at the shell prompt1:

> `% oz` <emacs args>

After setting up the necessary environment variables, this starts up an Emacs process, passing to it all arguments given on the command line, creates a new buffer named Oz, and starts a Mozart sub-process.

Which Emacs to Use

The command used to invoke Emacs is determined through the following steps:

1. If the environment variable `OZEMACS` is set, its contents is used.

2. Else, if a command named `emacs` is found in the `PATH`, this is used.

3. Else, if a command named `xemacs` is found in the `PATH`, this is used.

4. Else, if a command named `lemacs` is found in the `PATH`, this is used.

## 2.2 Invoking the OPI Under Windows

The installation procedure will have created a program group for the Mozart system. The OPI is started by launching the Mozart item. This item is a shortcut to the `oz.exe` program within the `bin` subfolder of the installation folder; as under Unix, any arguments given to it are passed on to the invoked Emacs.

Which Emacs to Use

The command used to invoke Emacs is determined through the following steps:

1. If the environment variable `OZEMACS` is set, its contents is used.

2. Else, if the registry indicates where GNU Emacs is installed, this is used.

3. Else, if the registry indicates where XEmacs is installed, this is used.

## 2.3 Invoking the OPI From Within Emacs

You can also configure your Emacs so that you can use all of the OPI's functionality without using the `oz` script. Here's what you would typically add to your Emacs startup file (usually called `~/.emacs` under Unix and `C:\_emacs` under Windows 95; under Windows NT, it is located in your home directory):

>     (or (getenv "OZHOME")
>         (setenv "OZHOME"
>                 "/usr/local/oz"))   ; or wherever Mozart is installed
>     (setenv "PATH" (concat (getenv "OZHOME") "/bin:" (getenv "PATH")))

>     (setq load-path (cons (concat (getenv "OZHOME") "/share/elisp")
>                           load-path))

>     (setq auto-mode-alist
>           (append '(("\\.oz\\'" . oz-mode)
>                     ("\\.ozg\\'" . oz-gump-mode))
>                   auto-mode-alist))

>     (autoload 'run-oz "oz" "" t)
>     (autoload 'oz-mode "oz" "" t)
>     (autoload 'oz-gump-mode "oz" "" t)
>     (autoload 'oz-new-buffer "oz" "" t)

Don't worry if you don't understand all of this (yet).

## 2.4 The Oz Major Modes

All of the OPI's functions are accessible in the following two major modes:

`oz-mode` [command]

  This is the major mode for editing Oz code. Loading a file with extension `.oz` automatically puts a buffer into Oz mode. You can tell a buffer is in Oz mode by the string `Oz` in its mode line.

`oz-gump-mode` [command]

  This is the major mode for editing Oz code with embedded Gump specifications (see ``Gump - A Front-End Generator for Oz''). Loading a file with extension `.ozg` automatically puts a buffer in Oz-Gump mode. You can tell a buffer is in Oz-Gump mode by the string `Oz-Gump` in its mode line.

Oz Mode Hook

To both of these, the following hook applies.

`oz-mode-hook` [user option]

  A list of functions to be run when one of the Oz modes is activated. These functions are applied without arguments. Change using Emacs functions `add-hook` and `remove-hook`.

## 2.5 Inspecting the OPI's Commands and User Options

The Oz Menu

The Oz major modes add a menu called `Oz` to the menu bar (see Figure 2.1); this menu is also accessible by pressing the right mouse button in an Oz buffer. Many of the commands described in the next chapters are accessible through this menu.

Emacs Conventions

The Oz modes conform to the following Emacs conventions:

- Nearly all functions and variables start with `oz-`...

- If the documentation string of a variable starts with an asterisk, then its value is meant for the user to modify at will (a so-called user option). The documentation string of a variable can be inspected with M-x describe-variable (C-h v).

- If a function has a documentation string, then it is meant for the user to use directly if she so wishes. Inspect the documentation string of a function with M-x describe-function (C-h f); if a command is bound to a key, you can examine its documentation string with M-x describe-key (C-h k).

- The OPI provides the feature `(provide '``oz``)`. See Emacs' `(``require` function for more details.

Customization

New Emacsen offer a feature called customization, which serves the purpose of setting the user options pertaining to a mode in a structured way. You can access this feature by M-x customize; look at the group Programming/Languages/Oz. You can also access this group directly via M-x customize-group RET oz.

Key Bindings

A short description of the current major mode and its key bindings can be obtained through Emacs' M-x describe-mode (C-h m). In this manual, the key sequences a command is bound to by default will always be shown in parenthesis following the command name.

`oz-mode-map` [user option]

  Keymap used in the Oz modes.

Generally, Oz-specific commands are made available both with C-. and C-c . as prefix. This manual always lists only the first of these. However, some terminals may not be able to generate C-.; this is why the second one is provided.

Figure 2.1: The Oz Menu.

1. The percent sign (`%`) represents the shell prompt; it is not part of the command.