Descriptions of <B>Alice</B> Commands

# Descriptions of Alice Commands

This chapter describes all the commands of Alice. Each description gives the name of the command (as it might be typed on a command line), the default binding of the command (if one exists), and the names of menus where the command can be found. (Some commands may be found on more than one menu.)

The command descriptions are grouped into classes of similar commands. These parallel the menus that are used to organize Alice commands, but are not exactly the same. For example, Alice has separate menus for commands that delete things from source code and commands that add things. For the purposes of this manual, however, we have grouped both types of commands under the heading ``Editing Commands''. Appendix B summarizes the various menus of Alice.

## Menu Commands

These commands call up various kinds of menus.

### CHANGE

Associated with Key: `[F5]`

Found on: Master Menu

Shown on menu as: Change Structures

This calls up the Changes Menu, a menu containing various commands for changing your source code.

### DELMENU

Associated with Key: `[F3]`

Found on: Master Menu

Shown on menu as: Deletions

This calls up the Delete Menu, a menu containing various commands for deleting things from your program.

### IO

Associated with Key: `[F8]`

Found on: Master Menu, Misc Menu

Shown on menu as: File Operations

This calls up the File Menu, a menu containing commands for saving and loading programs, as well as quitting Alice.

### HELP

Associated with Key: `[F9]`

Found on: Master Menu

Shown on menu as: Help

This calls up the Help Menu, a menu of commands that provide various kinds of help about Alice and Pascal.

### INSMENU

Associated with Key: `[F4]`

Found on: Master Menu

Shown on menu as: Insertions

This calls up the Insert Menu, a menu of commands for adding things to your program.

### DEBUG

Associated with Key: `[F6]`

Found on: Master Menu

Shown on menu as: Running the Program

This calls up the Run-Time Menu, a menu of commands for running your program and using various debugging facilities.

### MENU

Associated with Key: `[F7]`

Found on: None

Shown on menu as: Master Menu

The Master Menu lists all the other important menus provided by Alice. Choosing a selection from the Master Menu summons the associated menu.

### MISC

Associated with Key: `[SHIFT-F9]`

Found on: Master Menu

Shown on menu as: Misc

This calls up the Miscellaneous Menu, a menu of commands that deal with a variety of special operations.

### CURSOR

Associated with Key: `[ALT-G]`

Found on: Master Menu

Shown on menu as: Move Cursor

This calls up the Move Menu, a menu of commands for searching, moving the cursor, and marking places in your source code.

## Editing Commands

These commands change the source code of your program in various ways.

### EXTEND

Associated with Key: `[CTRL-E]`

Found on: Insert Menu

Shown on menu as: Extend

This expands a list by adding an empty placeholder of the same type as the other elements of the list. For example, if you are expanding a list of variables that are declared in a variable declaration, Alice will add an empty `Name` placeholder. If you are expanding a list of statements, Alice will add an empty `Statement` placeholder. The empty placeholder is added after the list item that the cursor is on, and the cursor is moved to the new placeholder.

Note that Alice extends the smallest list containing the cursor. For example, if the cursor is on the variable name of a variable declaration, EXTEND will extend the list of variable names for that declaration. If, however, the cursor is on the `Type` field of a variable declaration, EXTEND will create a new `Variable-Declaration` placeholder. Alice cannot extend the `Type` into a list of types because that is not legal in Pascal; therefore, it extends the list of variable declarations.

### INSERT

Associated with Key: `[INS]`

Found on: Insert Menu

Shown on menu as: Insert

This is exactly like `Extend` (EXTEND), except that the new placeholder is added BEFORE the list item that the cursor is on.

### CLIP

Associated with Key: `[CTRL-P]`

Found on: Delete Menu, Select Menu

Shown on menu as: Clip

CLIP deletes something from your program, leaving behind an appropriate placeholder. Normally, you must select (highlight) a portion of your source code before issuing the CLIP command. The highlighted code will then be deleted. However, if you are only deleting a single symbol, comment, or constant, just position the cursor on the thing you want to clip, then issue the command (you do not have to select code in this case).

### DELETE

Associated with Key: `[DEL]`

Found on: Delete Menu, Select Menu

Shown on menu as: Delete

DELETE deletes something from your program. Normally, you must select (highlight) a portion of your source code before issuing the DELETE command. The highlighted code will then be deleted. However, if you are only deleting a single symbol, comment, or constant, just position the cursor on the thing you want to delete, then issue the command (you do not have to select code in this case). DELETE usually does not leave an empty placeholder in the place where code was deleted. However, if a placeholder is necessary for the program to remain correct, DELETE leaves behind an appropriate placeholder.

### EDIT

Associated with Key: `[ALT-E]`

Found on: Changes Menu, Select Menu

Shown on menu as: Edit

This command allows you to edit things that were filled into `Value` placeholders (expressions). It can also be applied to string constants and comments.

Normally, you must select (highlight) the expression you wish to edit, using the normal code selection methods. Once you have done this, you can issue the command. However, if you are only editing a single symbol, comment, or constant, you do not have to highlight the thing you want to edit -- just move the cursor to the desired location, and issue the EDIT command. You can even position the cursor in the middle of the item, in which case the cursor will be at that location when you begin editing.

The selected area will be marked in a different colour if you have a colour screen, more brightly if you have a monochrome screen. The Simple Text Editor will then be invoked and you can use the features described in Chapter 1 to edit the marked material (e.g. backspacing, CTRL-D, CTRL-W).

To show that you have finished editing the marked material, move the cursor off the material (e.g. with TAB, `[CTRL-rightarrow]`, or an arrow key).

### ENCLOSE

Associated with Key: None

Found on: Insert Menu, Select Menu

Shown on menu as: Enclose

This command encloses a set of instructions inside some other sort of construction. For example, you can enclose a set of instructions in an if statement so that the instructions are only executed if a particular condition is true. Before executing this command, you must select (highlight) a portion of code in the executable part of your program. You may then issue the command. Alice creates a `Block Statement` placeholder where you should type the keyword for the construct that will enclose the selected instructions. For example, if you type if in this placeholder, Alice will make the enclosing statement an if statement.

### RAISE

Associated with Key: None

Found on: Delete Menu, Select Menu

Shown on menu as: Raise

This is the opposite of the ENCLOSE command. Before you execute RAISE, you must select (highlight) an instruction which contains other instructions (e.g. a while loop or an if statement). When you issue the command, the containing instruction will disappear but the contained instructions will be left behind. For example, if you do this to a while loop, the line containing the word `while` and the `end` that marks the end of the loop will disappear, but the instructions that were inside the loop will remain. In this way, they are ``raised'' out of the enclosing loop.

Warning: if you raise an if-else construct, the code for both the if part and the else part will be raised. In many cases, you will want to delete one part or the other from your code.

### SPECIALTIES

Associated with Key: None

Found on: Changes Menu, Misc Menu, Master Menu, Select Menu

Shown on menu as: Special Changes

This command can change one type of statement to another. For example, suppose you have an if statement that contains a number of statements and you realize that the if should be a while. You could RAISE the code, then ENCLOSE it with a while, but the SPECIALTIES command lets you do this operation in one step instead of two.

Highlight the statement you want to change, then choose the `Special Changes` from any menu where the selection appears. Alice will provide you with a list of the kinds of statement that the highlighted statement can be converted to. Select the appropriate thing from the list, and Alice will make the change.

Statements contained in the block will remain unchanged. Conditions (e.g. in while statements) are discarded if the new type of statement doesn't contain a condition. For example, if you change a while to an if, the `Condition` will be kept, but if you change a while to a for the `Condition` will be discarded.

If you highlight a list of statements and execute the SPECIALTIES command, Alice will enclose those statements in the type of statement you choose. For example, if you choose while from the list of possibilities, the statements will be enclosed by a while loop.

The SPECIALTIES command also lets you change a function into a procedure, and vice versa.

## Moving Through Your Program

These commands are associated with moving the cursor and searching for pieces of code in your program. Many of these are found on the ``Move and Search Menu'', which we have abbreviated to ``Move Menu'' in the following descriptions.

### BLOCK

Associated with Key: `[HOME]`

Found on: Move Menu

Shown on menu as: Top of block

This moves the cursor to the top of the block (program or procedure or function or immediate mode block) that contains the current cursor location. Issuing this command repeatedly will eventually get you back to the program statement. (Typing `program` will also get you back to the program statement.)

### PARENT

Associated with Key: `[CTRL-6]`

Found on: Move Menu

Shown on menu as: Up to Parent

This moves the cursor to the parent (container) of the current cursor location. The parent is the smallest construct that contains whatever the cursor points to. For example, if the cursor is pointing to the `a` in `a+b` , the parent is the `+` , since the addition expression contains the variable `a` .

### DECL

Associated with Key: None

Found on: Move Menu

Shown on menu as: Go to Declaration

This command allows you to go to where a particular name is declared. Move the cursor to the desired name, then issue the command. Alice will jump up to the point where the name was declared (or else say it is unable to do so).

### POPBACK

Associated with Key: `[CTRL-B]`

Found on: Move Menu

Shown on menu as: Former Cursor Loc

This command moves the cursor back to its previous location. This is particularly useful if you have just done a DECL in order to check out the declaration of a symbol, then want to go back to where you were. It is also useful after you have finished searching through your program for appearances of a variable, or after any other major cursor motion. Just issue the POPBACK command and you will go back. Several POPBACK commands in a row will pop back through the sequence of most recent cursor positions.

### PAGEDOWN

Associated with Key: `[PgDn]`

Found on: Move Menu

Shown on menu as: Page down

This moves the cursor down through the source code a distance that is one line short of the length of the terminal screen. In other words, the bottom line of source code becomes the top line. This allows you to move quickly through your program.

### PAGEUP

Associated with Key: `[PgUp]`

Found on: Move Menu

Shown on menu as: Page up

This moves the cursor backwards through the source code a distance that is a little less than the length of the terminal screen. In other words, it moves back about a screen's length. This allows you to move quickly back through your program.

### SEARCH

Associated with Key: `[CTRL-F]`

Found on: Move Menu

Shown on menu as: Search

This searches through your source code for the next occurrence of a character string (e.g. a symbol name). When you issue the command, Alice will ask what string of characters you want to search for. Type this in, then press `[ENTER]`. Alice will move the cursor to the next line that contains the string you want to find.

The second time you issue a SEARCH command, Alice will show the string that you searched for in the previous command. If you want to search for the same thing, just press `[ENTER]`; otherwise, type in the new string you want to find, then press `[ENTER]`.

SEARCH begins looking at the current cursor position and goes forward through your program. Alice gives you an error message if the string cannot be found at all.

Due to the internal tree structure, Alice behaves oddly if you ask to find the keyword end at the end of a block (e.g. a while loop). Alice will place the cursor at the beginning of the block instead at the keyword end.

The ``?'' can be used as a wild card character when specifying the string to search for. The ``?'' will match any character. For example, ``i?t'' will match words like ``integer'', ``list'', and ``dictionary''.

### RSEARCH

Associated with Key: None

Found on: Move Menu

Shown on menu as: Search Backwards

This is similar to the SEARCH command except that it searches backwards from your current cursor location instead of forwards.

### AGAIN

Associated with Key: `[CTRL-A]`

Found on: Move Menu

Shown on menu as: Search Again

AGAIN repeats a previous search. If the last searching command was SEARCH, AGAIN will search forward through your program for the same string that the SEARCH tried to find. If the last searching command was RSEARCH, AGAIN will search backwards through your program for the same string that RSEARCH tried to find.

### MARK

Associated with Key: None

Found on: Move Menu

Shown on menu as: Mark Position

This allows you to mark the current cursor position and give the position a name. This has nothing to do with the source code -- the name is only used by Alice. Names consist of a single letter, and Alice does not pay attention to whether the name is upper or lower case. Thus ``A'' is the same as ``a''.

When you issue the MARK command, you will see

>     Mark?

appear on the bottom line of the screen. The first letter you type will be taken as the name of the mark -- pressing `[ENTER]` is not required.

Once you have marked the position, you may ask Alice to go to the position at any time using the GO command (described below). When you issue GO, Alice will ask the name you wish to go to, and will go to that mark. The purpose of this is to let you move quickly to important parts of your code.

If you issue the MARK command on a command line (by pressing `[CTRL-X]` and then typing `mark` ), the command will take the name of the mark as an argument, as in

>     mark A

In this case, Alice does not prompt you for a name the way it usually does.

### GO

Associated with Key: None

Found on: Move Menu

Shown on menu as: Go to mark

This moves the cursor to a location in your source code that has been previously marked by the MARK command. Alice will ask what mark you want to go to by prompting

>     Mark?

at the bottom of the screen. The first letter you enter will be taken as the name of the mark -- you do not have to press `[ENTER]`.

You can also issue the GO command by pressing `[CTRL-X]`, then entering `go` . In this case, you can give an argument to the command, as in

>     go a

You must press `[ENTER]` at the end of the line.

### LSIB

Associated with Key: None

Not found on menus

The LSIB command can only be invoked by pressing `[CTRL-X]` and entering `lsib` . It moves the cursor from the current node to the node's left sibling (in the program tree). It is intended primarily for use in custom development.

### RSIB

Associated with Key: None

Not found on menus

RSIB is similar to LSIB except that it moves the cursor to a node's right sibling instead of its left.

### CHILD

Associated with Key: None

Not found on menus

This is similar to RSIB and LSIB. It moves the cursor to the first child of the current node. It is intended primarily for internal use.

### NEXT

Associated with Key: `[CTRL-rightarrow]`

Not found on menus

This moves the cursor to the next placeholder or error. If there are no placeholders or errors between the current cursor position and the end of the program, NEXT will ``wrap around'' to the top of the program and look for the first placeholder or error.

### PREV

Associated with Key: `[CTRL-leftarrow]`

Not found on menus

This moves the cursor to the closest preceding placeholder or error. If there are no placeholders or errors between the current cursor position and the beginning of the program, PREV will ``wrap around'' to the bottom of the program and look for the last placeholder or error.

### FWD

Associated with Key: TAB

Not found on menus

This moves the cursor forward in the program. It does not wrap around from the bottom of the program to the top.

### BACK

Associated with Key: SHIFT-TAB

Not found on menus

This moves the cursor backwards in the program. If the cursor is at the beginning of the program, BACK will wrap around to the end of the program.

## File Commands

These commands deal with reading and writing material from files.

### LOAD

Associated with Key: `[ALT-L]`

Found on: Files Menu

Shown on menu as: Load New File

This loads a Pascal program from a file. Anything you were working on (in this workspace) is overwritten and lost. Alice will offer a File Name Menu (as described in Chapter 2), asking you to indicate which file contains the program you want to load.

If the name of the file you're loading ends in ``.pas'', Alice will assume that the file contains a Pascal program in normal text format and will convert this to the special internal format Alice uses. This is done by calling a program named APIN. Since Alice is in memory at this time, APIN might not have enough memory to convert a large program to the required format. Thus it is often better to run APIN on its own, rather than to attempt conversions from inside Alice. Chapter 5 describes how to run APIN on its own.

If the name of the file you're loading does not end in ``.pas'', Alice will assume that the program is already in the proper Alice format. If you are typing in the name of the file, you do not have to enter the usual ``.ap'' suffix; Alice will automatically add the suffix if necessary.

Loading a program gets rid of whatever you are currently working on in this workspace; therefore if you already are working on a program, Alice will offer the menu

>     Go back to editing this workspace
>     Load, forgetting changes to this workspace

If you don't want to lose the current contents of this workspace, choose the first selection above. This lets you go back to your program and save it, before you load in a new program.

Once you have loaded in a new file, you may not UNDO the action. See the ``History List'' section in Chapter 5 for details.

If you issue the LOAD command on a command line (by pressing `[CTRL-X]` and then typing `load` ), the command will take the file name as an argument, as in

>     load myprog.ap

If you specify the file in this way, the usual file name menu will not be offered.

If the LOAD operation fails because Alice can't find the file you want to load, the current workspace will not be changed. If the LOAD operation fails for any other reason, you will find that the current workspace contains an empty program template.

### SAVE

Associated with Key: `[ALT-S]`

Found on: Files Menu

Shown on menu as: Save

This saves your current program in a file. If this program was originally loaded from a file, Alice will write it back to the same file. If you want it to go to a different file, use the FILENAME command (described below).

If this is a new program, Alice will offer a File Name Menu as described in Chapter 2. This menu will not give the names of any existing files, on the theory that you won't want to save a new program in a file that contains an old program. If you want to save the new program in an existing file, you will have to enter the file name explicitly.

Note that Alice automatically puts ``.ap'' on the end of a new file name, if the file name does not have a ``.'' in it. This identifies the file as a Alice Pascal program.

If you issue the SAVE command on a command line (by pressing `[CTRL-X]` and then typing `save` ), the command will take the save file name as an argument, as in

>     save myprog.ap

If you specify the file in this way, the usual file name menu will not be offered.

### TEXT

Associated with Key: None

Found on: Files Menu

Shown on menu as: Save to Text File

This writes your current program into a file in text format. In this way, you can save your program in text format instead of the special format Alice uses to represent programs. Once you use this command, you can print the program on a printer, submit the program to another Pascal compiler, etc.

The name of the file that Alice uses is the same as the name of the Alice-format file associated with the program, except that the ``.ap'' on the end is changed to ``.pas''. For example, if the Alice-format program is stored in ``prog.ap'', the text format will be stored in ``prog.pas''. If the current save file does not have the extension ``.ap'', TEXT writes the text version directly to this file and does not add the ``.pas'' extension.

If you issue the TEXT command by pressing the `command` key `[CTRL-X]` and typing `text` , you may specify a file name as an argument as in

>     text file.pas

If you do not give a file name, Alice will use the current save file name with the extension ``.pas'' instead of ``.ap''.

### MERGE

Associated with Key: None

Found on: Files Menu

Shown on menu as: Merge (Load Library)

MERGE lets you combine a saved program with the program you are already editing. MERGE works the same way that LOAD does; however, instead of getting rid of whatever is in the current workspace, Alice keeps the current program and adds the selected program to it. The declarations of the saved program are added to the program being edited; any statements in the saved program are added at the beginning of the statements in the program being edited.

The MERGE facility offers a way to create ``libraries'' of useful routines. Such a library would be a set of declarations and subprograms that could be merged into programs that need to use the library routines. For more information, see the section on ``Merge Libraries'' in Chapter 5.

### FILENAME

Associated with Key: None

Found on: Files Menu

Shown on menu as: Set Filename

This allows you to set the name of the file where the current program should be saved. When you issue this command, you will be presented with a File Name Menu. Existing files are not shown on this menu. Choose a directory or enter a new file name.

If you issue the FILENAME command on a command line (by pressing `[CTRL-X]` and then typing `filename` ), the command will take the new file name as an argument, as in

>     filename myprog.ap

If you specify the file in this way, the usual file name menu will not be offered.

## Help Commands

These commands offer help with various aspects of Alice and Pascal.

### PHELP

Associated with Key: `[ALT-P]`

Found on: Master Menu, Help Menu

Shown on menu as: Information about Pascal

This will provide you with information about the parts of the Pascal language that you are currently working on. You will be offered a menu of help on the current node, whatever contains the current node, the container of the container, and so on. Note: asking for PHELP on a built-in symbol will include the symbol in the list of help.

### SYMBOL

Associated with Key: None, but `[END]` has this effect

Found on: Insert Menu, Master Menu

Shown on menu as: Symbol

This command will list all the symbols that could be entered in the current location of the cursor. For example, if you are on a `Variable` placeholder, Alice will give you a list of all the variables defined at this point. If you choose a name from this menu, the name will be filled into the placeholder.

If you highlight a built-in symbol name on this kind of symbol list and press `[F9]`, Alice will provide help on that symbol.

### TOKLIST

Associated with Key: `[ALT-T]`

Found on: Help Menu, Insert Menu, Master Menu

Shown on menu as: What Can I Type Here

This gives a menu of what you can type to fill in the current placeholder. If you select something from this list, Alice will enter your selection in the current placeholder.

The sort of information displayed in the list depends on the type of the current placeholder. For example, if you are on a `Statement` placeholder, Alice will display the various kinds of Pascal statements. If you are on a `Name` placeholder, Alice will display a list of the names declared in your program that could legally be filled into the placeholder.

You may highlight any token on the list provided by TOKLIST, then press `[F9]`, and Alice will provide a description of what will happen if you choose that token.

### ERRHELP

Associated with Key: None

Found on: Help Menu

Shown on menu as: What does my error message mean?

When you make an error, Alice usually gives a one line description of what went wrong. If this is not enough for you to understand the problem, you can issue this command and Alice will give you a fuller description of what the error message means.

The description given by ERRHELP pertains to your most recent error message, even if that message has disappeared from the display screen. If you want a reminder of what that error was, use the LASTERROR command (see below).

### LASTERROR

Associated with Key: None

Found on: Help Menu

Shown on menu as: What was the last error?

This repeats the most recent error message that Alice gave you. This lets you refresh your memory once the error message goes off the screen.

## Running a Program

These commands deal with running Pascal programs and saving their output.

### CONTINUE

Associated with Key: None

Found on: Run-Time Menu

Shown on menu as: Continue

This command runs your program. If you are already part way through execution of a program, it will continue execution from the point you left off.

One reason you might be part way through execution is because you have hit a breakpoint (see `Set Breakpoint` (BREAKPOINT)). After CONTINUE, the program will keep going until it hits another breakpoint or it finishes. Another reason you might be half way through a program is if you are single-stepping with STEP or SUPERSTEP. In this case, CONTINUE will run the rest of the program immediately. If you are part way through a program, this command will appear as `Continue` on the Run-Time Menu; otherwise, it will appear as `Run Program` .

### RUN

Associated with Key: `[F1]`

Found on: Run-Time Menu

Shown on menu as: Pop Suspend & Run

This runs your current program, regardless of whether or not you are already partly through another run of the program (e.g. through single-stepping).

### RUNIT

Associated with Key: `[ALT-F1]`

Found on: Run-Time Menu

Shown on menu as: Run Program

If you already have a program in the middle of execution, RUNIT will continue its execution like the CONTINUE command. If you do not have a partly executed program, RUNIT will run the program from the beginning like the RUN command.

### STEP

Associated with Key: `[F2]`

Found on: Run-Time Menu

Shown on menu as: Single Step

This executes a single instruction in your program. If you are already part way through running your program, it will execute the next instruction in the program. Otherwise, it will execute the first instruction in the program. The cursor will always show you the next statement that will be executed, not the one that has just been executed.

In between steps, you may issue ``Immediate mode'' instructions to examine, modify, or test parts of your program.

If the code being executed contains a subprogram call, STEP will execute the subprogram one step at a time as well. For some people, this may be too slow. The `Big Step` (SUPERSTEP) command works like Single-Step (STEP), except that it executes subprogram calls as a single action.

STEP automatically splits the display screen into two halves, one showing source code and the other showing output from your program. The `Debug Off` selection from the Run-Time Menu restores the screen to its normal appearance.

If you have single-stepped into the middle of your program and want to start stepping from the beginning again, issue the POP command to clear away the partly executed program. (POP is described later in this chapter.)

### SUPERSTEP

Associated with Key: None

Found on: Run-Time Menu

Shown on menu as: Big Step

This runs a program one instruction at a time, much like the single-step (STEP) command does. However, with SUPERSTEP, a whole program block (e.g. a loop or a procedure call) counts as a single step. If a SUPERSTEPped block contains a goto out of the block, the SUPERSTEP will fail.

### LOG

Associated with Key: None

Found on: Run-Time Menu

Shown on menu as: Log Output to File

This command lets you save your program's output in a file. Once you have issued this command, you can run a program and its output will be written to a file named ``log''. The output will also be displayed on the screen as usual.

The first time you run a program with ``logging'' turned on, the current contents of ``log'' will be deleted and replaced with your program's output. If you keep ``logging'' turned on, output from subsequent program runs will be APPENDED to the ``log'' file. Therefore you can capture the output of several programs by running them one after another.

If you want the output of a program run to replace the current contents of ``log'' instead of being appended, turn logging off, then turn it back on again. Alice always cleans out ``log'' when ``logging'' is turned on.

If you issue the LOG command by pressing `[CTRL-X]` and typing `log` , you may specify an argument. This argument gives the name of a file that should be used for logging instead of the usual ``log'' file. For example,

>     log myfile

will log output to ``myfile'' instead of ``log''.

### NOLOG

Associated with Key: None

Found on: Run-Time Menu

Shown on menu as: Don't Log Output to File

This command turns off output ``logging''. For further information, see the explanation of the LOG command.

## Debugging Features

These commands control the debugging features of Alice.

### BUGON

Associated with Key: None

Found on: Run-Time Menu

Shown on menu as: Debug On

This starts up a number of the debugging facilities that are available with Alice. For example, breakpoints in a program will not be triggered unless you turn on debugging. Turning on the debugging facilities also splits the display screen into two parts: the top part shows source code in your program, while the bottom is used to display output of various kinds.

Debugging is automatically turned on when you start single-stepping through your program, when you issue the EXECUTE command, or when you turn on cursor following.

### BUGOFF

Associated with Key: None

Found on: Run-Time Menu

Shown on menu as: Debug Off

This turns off the ability to use a number of the debugging facilities that are available through Alice. It also restores the screen to full-screen editing (in debug mode, half the screen shows your program's source code while the other half shows output of various kinds).

### POP

Associated with Key: None

Found on: Run-Time Menu

Shown on menu as: Pop suspended state

This selection only appears on the menu when a program has stopped part way through because it has an error, you were single-stepping, you were using immediate mode, or a breakpoint went off. When this happens, the program stays around in a frozen or ``suspended'' state. This lets you look at parts of the program. For example, you can use immediate mode to print out the values of variables so you can see what they are.

If you are in immediate mode, you have to pop out of the immediate block before you can resume single-stepping or normal execution. This is what the POP command does.

It is possible that you can be suspended inside a suspended state. The number of suspended states you have is indicated by the number that follows `SUSPEND` on the status line whenever you are in a suspended state. You must issue one POP command for each suspended state you want to clean away.

### SETFOLLOW

Associated with Key: None

Found on: Run-Time Menu

Shown on menu as: Cursor Following On

If this command is issued before you run a program, Alice will put you in debugging mode. As the program runs, the cursor will move through the source code in the top half of the screen, showing which instructions are being executed. This lets you ``see'' your program executed.

Once you have issued this command, Alice will always use the cursor to show your program executing until you issue the BUGOFF or CLEARFOLLOW command. The screen will remain split in two until you issue the `Debug Off` command from the Run-Time Menu.

### CLEARFOLLOW

Associated with Key: None

Found on: Run-Time Menu

Shown on menu as: Cursor Following Off

This command stops cursor following.

### IMMEDIATE

Associated with Key: None

Found on: Misc Menu, Run-Time Menu

Shown on menu as: Immediate Mode Block

Immediate mode allows you to execute instructions immediately, instead of incorporating them as part of a program.

When you issue the IMMEDIATE command, Alice will create an ``immediate block''. This will hold the immediate instructions that you type in, allowing you to execute a series of instructions (e.g. a for loop to print the contents of an array). As soon as you press `[ENTER]` at the end of an immediate instruction, Alice will execute the instruction.

Immediate mode will often be used when you are paused in the middle of execution (after single-stepping through some instructions or stopping at a breakpoint). Immediate mode lets you examine the value of variables and test program operations. When you are finished with immediate mode, you can return to program execution by issuing the CONTINUE command or by single-stepping again. If you have a partly finished program and want to return to program editing, issue the POP command.

The immediate block does not disappear when you leave it. If you go back into immediate mode, you can re-execute a command in the immediate block by positioning the cursor on the command and pressing `[ENTER]`.

If you issue the IMMEDIATE command and there is already an immediate block in the current scope, Alice will move you to the end of the existing immediate block and create a `Statement` placeholder there.

Immediate mode blocks are deleted like normal pieces of code: select (highlight) the block and issue the DELETE command.

### EXECUTE

Associated with Key: `[SHIFT-F1]`

Found on: Run-Time Menu

Shown on menu as: Execute this Statement

The EXECUTE command lets you execute a single instruction in immediate mode. Before issuing the EXECUTE command, you must select (highlight) the instruction you want to execute. This can be inside or outside an immediate mode block. When you issue the EXECUTE command, Alice will execute the instruction.

If you have a program running at the time, the statement will be executed in the context of the program (e.g. using variable values as they are set at this point in the program). Debugging mode is automatically turned on.

The EXECUTE command creates a special additional suspended state if necessary. However, this is automatically popped off again if the EXECUTE works. If the EXECUTE didn't complete the execution (either because of an error, a breakpoint, or pressing `[CTRL-BREAK]`), this additional suspended state will have to be popped off (with POP) before other interrupted execution can continue.

### BREAKPOINT

Associated with Key: None

Found on: Run-Time Menu

Shown on menu as: Set Breakpoint

This sets a breakpoint at a selected location of a program. If the program reaches this point while it is running in Debug Mode, execution will stop. You can then examine, modify, or test parts of your program (e.g. check the value of variables).

Before you issue this command, you must select (highlight) the instruction where the breakpoint will be set. You must select the entire instruction. For example, you cannot set a breakpoint on a `writeln` instruction by selecting only the symbol `writeln` . You must make sure you have highlighted the whole line.

Once you have done this, you may issue the command. A comment of the form

>     {Breakpoint}

will be displayed to the right of the selected instruction. During program execution, the breakpoint will also be triggered immediately before the selected instruction.

When you have done everything you want after stopping at a breakpoint, you may start the program up from where it left off by issuing the `Continue` (CONTINUE) command from the Run-Time Menu. You may also begin single-stepping through the program using STEP or SUPERSTEP.

Stopping at a breakpoint does not get rid of the breakpoint. The next time the program reaches a marked breakpoint, it will stop again.

Breakpoints do not work if debugging has been turned off (with the BUGOFF command). When debugging is turned off, all

>     {Breakpoint}

change to

>     {Breakpoint (Debug ONLY)}

to indicate that the breakpoints are no longer active.

### CLRPOINT

Associated with Key: None

Found on: Run-Time Menu

Shown on menu as: Clear Breakpoints

This command is used to clear breakpoints that have been set by `Set Breakpoint` (BREAKPOINT). Before issuing the command, you must select (highlight) a section of code. Issuing the command will then clear any breakpoints set in the code that you have highlighted.

### CHECK

Associated with Key: `[CTRL-T]`

Found on: Run-Time Menu

Shown on menu as: Typecheck Program

This command runs through your program to check the data types involved in all declarations, instructions, and subprogram calls. If any types do not match properly (e.g. assigning a real value to an integer), the problem will be highlighted.

Most of the time, this operation is done automatically as Alice works, so you won't have to issue this command yourself. However, you should do it explicitly after changing a declaration, so that Alice can locate any errors that the change may have caused. You can also specify a ``checking frequency option'' on the command line that invokes Alice -- see the description of ``f='' in Chapter 5.

### TRACEBACK

Associated with Key: None

Found on: Run-Time Menu

Shown on menu as: Who Called Me?

If you have a suspended program, this selection will appear on the Run-Time Menu. When a program is suspended, the cursor will be on the statement that was executing when the program stopped execution. Issuing the TRACEBACK command moves the cursor to the statement that called the subprogram that was executing at the time of the suspension. If you issue TRACEBACK again, the cursor moves to the caller's caller, and so on. If you go all the way back to the mainline and issue another TRACEBACK, the cursor will return to where it started, in the currently executing subprogram.

To find out how far you have traced back, check the status line. After the `SUSPEND(N)` you will see two numbers separated by a slash. The second number tells how many subprograms were stacked up at the time of the suspension. The first number tells which of these subprograms you are looking at. For example, if you see `9/10` , there were 10 subprograms stacked up at the time execution was suspended, and the cursor is currently on the ninth subprogram (the one that called the current subprogram).

## Workspace Commands

These commands deal with various aspects of workspaces.

### WS

Associated with Key: None

Found on: Misc Menu

Shown on menu as: Change Workspace

This moves from one workspace to another. Alice will give you a menu showing the existing workspaces. You can choose one of these or ask to go to a new workspace. If you ask for a new workspace, the workspace will be created with a blank program template. If you choose an old workspace, you will go to that workspace and the cursor will be placed where it was the last time you were in this workspace.

If you issue the WS command on a command line (by pressing `[CTRL-X]` and then typing `ws` ), the command will take the workspace name as an argument, as in

>     ws newwork

If you specify the workspace in this way, the usual menu of workspaces will not be offered.

### NEW

Associated with Key: None

Found on: Delete Menu

Shown on menu as: Clear This Workspace

This command clears away your current program and sets up for a new program (in the same workspace). Note that this command CANNOT be undone with UNDO. Because of this, NEW will confirm that you really want to get rid of the program before it performs the operation.

### COPY

Associated with Key: `[ALT-C]`

Found on: Changes Menu, Select Menu

Shown on menu as: Copy to workspace

This command copies code from one workspace to another. Before you can execute the command, you must select (highlight) the portion of code to be copied. Once you have done this, you can issue the command. Alice will give you a menu of existing workspaces; one of the selections on this menu allows you to specify a new workspace. If the workspace doesn't already exist, Alice will create it. If the workspace does already exist, whatever the workspace contained will be lost (overwritten). Alice issues a warning message in this case, so you can UNDO the action if you wanted to keep the workspace's contents.

If you issue the COPY command on a command line (by pressing `[CTRL-X]` and then typing `copy` ), the command will take the workspace name as an argument, as in

>     copy oldwork

If you specify the workspace in this way, the usual menu of workspaces will not be offered.

### GET

Associated with Key: `[CTRL-plus]`

Found on: Insert Menu

Shown on menu as: Get workspace

This obtains the contents of another workspace and deposits them in the current workspace. Before you issue the command, you must place the cursor on an empty placeholder that has a type which matches the contents of the workspace you will be getting. For example, if the workspace contains a number of statements, the cursor should be on a `Statement` placeholder, NOT a declaration or something else.

When you issue the command, Alice will offer a menu of the workspaces currently available. Once you have chosen the workspace you want from this menu, the code from the other workspace will be deposited in the current workspace in place of the empty placeholder.

If you issue the GET command on a command line (by pressing `[CTRL-X]` and then typing `get` ), the command will take the workspace name as an argument, as in

>     get oldwork

If you specify the workspace in this way, the usual menu of workspaces will not be offered.

### MOVE

Associated with Key: `[CTRL-minus]`

Found on: Delete Menu, Select Menu

Shown on menu as: Move to workspace

This command lifts code out of one workspace and puts it in another. It is equivalent to COPYing the code, then deleting it.

Before you can execute the command, you must select (highlight) the portion of code to be moved. Once you have done this, you can issue the command. Alice will offer you a menu of existing workspaces, and also allow you to type in the name of a new workspace. If the workspace doesn't already exist, Alice will create it. If the workspace does already exist, whatever the workspace contained will be lost (overwritten). An empty placeholder will be left in the current workspace to show where the moved code used to be.

If you issue the MOVE command on a command line (by pressing `[CTRL-X]` and then typing `move` ), the command will take the workspace name as an argument, as in

>     move newwork

If you specify the workspace in this way, the usual menu of workspaces will not be offered.

### EXECWS

Associated with Key: None

Not found on menus

The only default way to execute this command is to press `[CTRL-X]` and enter

>     execws name

where `name` is the name of a workspace that contains a program. Alice runs the program in that workspace, but applies the effects of that program to the current workspace.

To understand we mean, we should explain that Alice comes with a number of subprogram libraries, and one of these libraries contains routines that issue Alice commands or edit source code stored in Alice workspaces. Using these library routines, you can write an editing program in workspace A and then apply that program to the source code stored in workspace B. To do this, you go to workspace B using the WS command, then press `[CTRL-X]` and type

>     execws A

The code in B will be edited according to the instructions in A.

We expect that users will create special EXECWS workspaces for their own purposes and bind EXECWS commands to keys with MAP. For further information on subprogram libraries, see the section called ``Merge Libraries'' in Chapter 5.

## Miscellaneous Commands

These commands perform a variety of operations.

### UNDO

Associated with Key: `[CTRL-U]`

Found on: Changes Menu

Shown on menu as: Undo

This ``undoes'' the most recent action that changed program source code. By issuing UNDO several times in a row, you can undo several sets of changes. The REDO command ``undoes'' an UNDO -- if you do something, then take it back with UNDO, you can do it again with REDO.

### REDO

Associated with Key: `[CTRL-R]`

Found on: Changes Menu

Shown on menu as: Redo

This reverses the effect of an UNDO command, if you decide that you don't want to undo things after all. You must issue the REDO immediately after the UNDO command -- if you have changed your program in any way since the last UNDO, REDO will not work.

### COMOUT

Associated with Key: None

Found on: Changes Menu, Select Menu

Shown on menu as: Comment Out

Occasionally users insert instructions into code which help debug the program but which are not needed in the final version of the program. Such code may be ``commented out'' when it is no longer needed. From the user's point of view, the code is surrounded by brace brackets so that it may be thought of as a comment instead of active code. Commenting out code is often handier than deleting the code entirely, since the code can easily be brought back if it becomes necessary in future. (Comments around commented-out code may be removed with the RAISE command.)

Before executing this command, the user must select (highlight) the portion of code to be commented out. This code must be made up of list elements which are complete instructions; you cannot comment out declarations or part of a line. Once the code has been selected, the command may be issued.

The commented-out code will be displayed like a comment, enclosed by braces. Note that it is possible for the commented-out code to contain comments. This works fine with Alice, but it violates the usual Pascal rules against nesting comments. Therefore, you may get an error if you save your program as text, then try to run the program through some other Pascal compiler/interpreter.

### AUTOSAVE

Associated with Key: None

Found on: Misc Menu

Shown on menu as: Autosave

The AUTOSAVE command tells Alice to save your program automatically every few operations. For the purposes of AUTOSAVE, an ``operation'' is a command, a cursor movement, or the entering of a complete token.

When you issue the AUTOSAVE command, Alice will ask you to enter a number N. Enter the number and press `[ENTER]`. From that point onward, Alice will save your program after every N commands. If, for example, you enter a 2, Alice will save your program every other command. Specifying 0 for N turns autosaving off.

Alice will give you a warning if there is no file name associated with the current workspace. Without such a file name, Alice cannot perform the save operation.

If you execute the AUTOSAVE command by pressing `[CTRL-X]` and typing `autosave` , you may specify the number N on the command line, as in

>     autosave 2

The AUTOSAVE command always considers its file name to be relative to the current directory. Thus if you switch current directories, you will begin autosaving in the new directory.

### NOP

Associated with Key: None

Found on: Most menus

Shown on menu as: Do nothing

The `Do nothing` selection appears on most menus. Choosing this command simply returns you to whatever you were doing before you summoned the menu. This allows you to return to normal editing if you decide you don't want to select a particular action from the menu. This command is also known by the name NOP (standing for no-op or ``no operation'').

### HIDE

Associated with Key: `[ALT-H]`

Found on: Changes Menu, Select Menu

Shown on menu as: Hide

This command hides a section of source code. It is intended to help you simplify the way that your code is displayed on the terminal screen.

Before executing the command, you must select (highlight) the portion of code to be hidden. You may then issue the command. The code will disappear on the terminal screen and be replaced by

>      ... {Comment} ...

The comment should be filled in with something explaining the nature of the hidden code.

The code is only hidden, not deleted. If the program is executed, the hidden code will perform normally. If you are single-stepping through the program (using STEP), the hidden code counts as one step. If you use the TEXT command to save your program as text, hidden code will be revealed in the text output.

### REVEAL

Associated with Key: `[ALT-R]`

Found on: Changes Menu

Shown on menu as: Reveal

The Reveal command brings back code that was hidden by HIDE. The comment

>      ... {Comment} ...

remains in your program at the top of the revealed code.

### SHELL

Associated with Key: `[SHIFT-F3]`

Found on: Files Menu

Shown on menu as: DOS Command

This allows you to execute a command through the DOS operating system shell. When you issue the SHELL command, Alice will open up a line at the bottom of the screen where you can type the command. The command may be edited with backspacing. Pressing `[ENTER]` will send the command to the command interpreter for execution. After the command is finished, Alice will wait for you to press any key, and will then restore the screen to whatever it displayed before you issued the SHELL command. (Note that the program "command.com" must be on your boot disk or SHELL will not work properly.

If you enter the SHELL command by pressing `[CTRL-X]` then typing `shell` , you can type the DOS command on the same line. There must be a space between the word `shell` and the DOS command you want to execute. Again, the DOS command will be executed when you press `[ENTER]`.

When using this command in a macro, you may wish to use the special \f escape code. See the section on Calling Other Versions of Pascal for more details.

### EXIT

Associated with Key: `[ALT-Q]`

Found on: Files Menu

Shown on menu as: Quit Alice

This lets you quit Alice. If you have not saved the source code in any workspace since the last time you changed the code, Alice will not quit immediately. The assumption is that you probably want to save everything you have created and all the changes you have made in this session. Therefore, if there are some things that you have not saved, Alice will display the following menu.

>     Go back to Alice
>     Quit, forgetting all the changes

The first option is equivalent to the usual `Do nothing` . The other option quits Alice without preserving the changes you have made since you last saved the program.

You can avoid the ``do you really want to quit'' menu by pressing `[CTRL-X]`, then typing `exit` followed by any argument. For example,

>     exit now

causes an immediate exit, regardless of whether your workspaces have been saved.

### MAP

Associated with Key: None

Found on: Misc Menu

Shown on menu as: Set Macro

This lets you bind a string of characters to a key. Alice begins by asking you to press the key. You will then be asked to type in the string of characters that will be bound to that key. To show the end of the string, press `[ENTER]`. Once you have set things up like this, you may type the key or key sequence and Alice will replace it with the string that is bound to it.

If you want a carriage return inside the bound string, type \n at the place in the string where the ``new-line'' should be. Similarly, if you want the effect of pressing the command key, put \c at the appropriate place in the string. For example,

>     \cimmediate\n

gives you the effect of pressing the command key, then entering `immediate` to invoke the IMMEDIATE command. (Note that you must have a `\n` whenever you have `\c` in a macro string. Other special sequences that can be included in key bindings are given in Chapter 5.

### RECOVER

Associated with Key: None

Found on: Delete Menu

Shown on menu as: Recover Memory

This command cleans up inside Alice to make more room in memory. In particular, it throws away the information Alice needs in order to perform UNDO commands. This leaves more memory available to hold your program. At the same time, it means that you cannot UNDO anything that happened before the RECOVER command. Because of this, RECOVER will confirm that you really want to get rid of the ``undoing'' information before it performs the operation.

### CLEAR

Associated with Key: `[CTRL-HOME]`

Found on: Misc Menu

Shown on menu as: Redraw Screen

This redraws the screen the way it should appear. This command is needed from time to time if the screen gets fouled up somehow (e.g. if you mistakenly type something on a blank line and your typing is not erased after the error is issued).

### OPTION

Associated with Key: None

Not found on menus

The OPTION command can only be invoked by pressing `[CTRL-X]` and typing `option` . It takes one argument. This argument takes the form of an option that could be specified on the command line that invokes Alice. For example, you could say any of

>     option -i
>     option f=2
>     option ca=4

These commands set the appropriate option, so that the remainder of your Alice session will continue with that option in effect.

Note that some possible option arguments may not make sense when executed inside Alice. For example, it is not be possible to change the amount of stack space in the middle of an Alice session. At present, Alice does not give diagnostic messages about such problems, so beware.

A complete list of command line options is given in Chapter 5 of this manual.