7. Running Algae

The Algae interpreter assembles your Algae statements into its own opcodes and then executes them. When you are working interactively, it does this one statement (or one block of statements) at a time. When its input comes from a file, the entire file is assembled before execution of it begins.

7.1 Startup Files
7.2 The Command Line
7.3 Errors
7.4 The algae Prompt
7.5 Signals

7.1 Startup Files

When Algae begins execution, it normally tries to read and execute two startup files. The first one it tries is the file in which it expects some of its standard functions to be defined. A default name for this file is given when Algae is compiled--usually it's something like `/usr/local/lib/algae/4.3.6/algae.A'. That name can be overridden with an environment variable called ALGAE_RC0.

Without this file, some of Algae's standard functions will be missing. For this reason, Algae will emit an error message and quit if it can't find the file. (That is, unless the `-S' option is specified on the command line.)

After Algae reads its standard functions, it looks for the file `.algae' in your home directory and executes it if it's there. This file's name can be overridden with the ALGAE_RC1 environment variable. Execution of this file is inhibited by the `-s' command line option. No startup files at all are read if the `-S' option is given.

7.2 The Command Line

Algae supports command line arguments to request various actions. Arguments starting with `-' are options. Other arguments specify files to execute.

Option flags always begin with a hyphen. Algae supports both traditional single-letter options and mnemonic long option names. Long option names are indicated with `--' instead of `-'. Abbreviations for option names are allowed as long as they are unique.

Options which change Algae's behavior take effect before any files are executed. The order of the arguments is unimportant, with the following two exceptions:

1. Any input scripts given (with the `-e' or `--script' option) are executed in the order that they appear on the command line. This occurs after the startup files are executed and before any other files are executed.

2. Any input files named on the command line are executed in the order in which they appear.

Below is a list of options accepted by Algae. Both the short and long option names are indicated.

`-D'

`--disassemble'

This option turns on the disassembler, which prints Algae's opcodes to stderr in a form like assembly language. You'll probably want to combine this with the `-S' option; otherwise, you'll get more than 800 lines of opcodes from the standard functions.

`-d i'

`--debug i'

This option sets the debug level to i, where i is an integer. It is normally of use only for debugging the Algae implementation.

`-e commands'

`--script commands'

This option allows you to provide a script for Algae to execute from the command line, rather than from a file or from standard input. Such a script is executed after any startup files but before any other files are executed. Any number of `-e' (or `--script') options may be given, and the specified scripts are executed in the order in which they appear on the command line.

`-h'

`--help'

Print a brief description of the command line arguments.

`-i'

`--interactive'

This option causes Algae to use interactive mode when reading from the standard input device "stdin". Without this option, Algae uses interactive mode only when its input appears to be from a terminal. In interactive mode, input is parsed a line at a time and exceptions do not cause Algae to exit.

`-n'

`--nowhite'

This option changes the way that scalars are displayed. The printing statements (that is, statements that are terminated by either a newline or a `?' character) normally precede the scalar's value with a tab, and follow it with a newline. With this option set, neither the tab nor the newline is printed. (For character scalars, the quotation marks are also omitted.) This option affects the printing statements only, and has no effect on the functions like printf.

`-p'

`--profile'

This option enables execution profiling--a means for determining the execution time characteristics of your Algae program. When profiling is enabled, the profiler periodically interrupts Algae and records the line that is currently being executed. When Algae exits, it records this data in the file `algae.out' in the current directory.

Use the prof function to read the `algae.out' file and summarize it by file and by line number.

You may wish to use the strip function in conjunction with profiling. Since strip removes the line and file information from a function, any time spent in a call to that function gets charged to the line from which it was called.

We've encountered several systems on which operating system bugs prevent the execution profiler from working correctly. These include a DECstation and a Titan, both with MIPS architectures. If you have such a system, then Algae should have been installed with the execution profiler disabled. In that case, you'll get an error message if you try to use the `-p' option.

`-R'

`--restrict'

This option causes Algae to run in restricted mode. The system function is disabled, as are "pipes" (i.e., file names that begin with the `!' character).

Restricted mode should be used whenever you deal with untrusted Algae code. Without it, a malicious provider of such code could cause major damage.

`-r'

`--noreadline'

If the GNU Readline facility is available, Algae normally uses it for interactive command line editing and history. The `-r' option forces Algae to skip Readline processing. Readline's editing commands are similar to emacs: C-f forward, C-b backward, C-p up, and C-n down. You can change to vi style by typing M-C-j.

`-S'

`--nostartup'

If this option is given, none of Algae's startup files are read. This means that many of the standard functions will be unavailable.

`-s'

`--norc'

This option skips reading the user's startup file.

`-V'

`--version'

This option prints version and date information.

`-x'

`--nostdin'

This option causes Algae not to read stdin by default when no file names are given on the command line.

Any file names given on the command line are executed as input to Algae. If no file names are given (and the -x option is not present), input comes from stdin. You can specify stdin explicitly with a single hyphen, so a command line like

algae init.A -

has Algae execute `init.A' first and then read from standard input.

7.3 Errors

Several types of errors may be encountered when running Algae. The two most common are parse errors and run time errors. Parse errors occur while Algae is parsing its input statements. Run time errors occur while Algae is executing its code. In both cases, Algae prints a file name and line number associated with the error.

7.4 The algae Prompt

When executing interactively, Algae displays the primary prompt when it is ready to read a command, and the secondary prompt when it needs more input to complete a command. You can customize the prompt simply by assigning a character vector to the global variable $prompt. Its first two elements specify the primary and secondary prompts. By default, $prompt is ( "> ", " " ). Assigning something other than a character vector to $prompt is not an error--Algae just won't give you a prompt. (Wouldn't it be fun to accept a function? Hmm, maybe someday.)

If the GNU Readline facility is available (that is, linked with Algae during installation), Algae normally uses it for interactive command line editing and history. Readline's editing commands are similar to emacs: C-f forward, C-b backward, C-p up, and C-n down. You can change to vi style by typing M-C-j. The `-r' command line option forces Algae to skip Readline processing.

7.5 Signals

If Algae receives an interrupt signal (because you pressed a C-c on the keyboard, for example), it stops what it's doing and returns to the prompt. (If it isn't running interactively, it simply exits.) On Unix systems, you can also use the kill command to send a signal to a process.

The implementation of interrupt signal handling in Algae is necessarily a compromise. We want it to respond promptly, but not at the expense of our performance. As a result, it sometimes happens that Algae does not respond promptly to an interrupt signal. (If you find a case like this; please report it. Sometimes it's the result of an oversight.)

Sending Algae a quit signal causes an immediate, clean exit. There are various other signals which will cause Algae to terminate, but this is the one to use if you want your files closed properly, etc.