© 1997-1998. Joseph Bergin. All Rights Reserved.

Karel++ World for Macintosh (Preliminary Documentation)

Joseph Bergin, Pace University


Karel++ World is a simulator to accompany Karel++: a Gentle Introduction to the Art of Object-Oriented Programming by Bergin, Stehlik, Roberts, and Pattis. The simulator is currently under construction and is being Beta tested. Karel++ World implements all aspects of the language as described in the text. It permits the user to build robot worlds and test robot programs within them. The Karel++ World works with Macintosh and Power Macintosh computers. Porting to other platforms is scheduled for later. The program will be available from John Wiley & Sons when it is complete. A notice will appear here when it is ready.

I hope you enjoy using Karel++ World and that it helps you learn from the book.

What You Will Need

To run Karel++ World, you need a Macintosh or a Power Macintosh, of course. You will need about 2 megabytes of disk space to hold the files that come with the distribution and the files that you create yourself. You will also need an editor program that can be used to create text files. Any such editor will do, including SimpleText, which comes with the Macintosh system software.

Getting Started

To use the World, you should create a new folder on your Hard Disk and name it something like Karel++. Then copy all files from the distribution disk to this folder. It would be a good idea to make and use a back-up copy of the distribution disk and keep the original in a safe place.

Running Your First Karel++ Program

You need two files in order to run a program. One file contains the robot program itself. The other describes the robot world with any walls and beepers. To run a program in a world when both of these have been prepared previously, you need to open both files in the Karel++ World. The program and world on page 11 of the text are with the distribution files. The program is called "First.kpp", and the corresponding world is named First.wol.

(Image of first world with one beeper)

Figure 1. A World Window with one Beeper

Find the file First.wol in your Karel++ folder. You can either double click this file or drag it onto the application Karel++ icon. This will start the simulator. You can also start the Karel++ World simulator by double clicking on its icon. You can then select Open from the File menu and navigate to the First.wol file in the file dialog and select and open it.

However you run the World, you should now see a page with the Street and Avenue grid, with a single beeper at 1st Street and 4th Avenue. This window is shown in Figure 1. Note the Street numbers to the left and the Avenue numbers across the top. This window can be scrolled and resized. There are 1000 streets and 1000 avenues in this world. If a robot moves outside this world it can't be seen.

(Image of the program view window)

Figure 2. The Program Window

Next, you need to open a Karel++ program to be used within this world. You can go back to the desktop, without quitting the simulator, and double click on the file First.kpp, or you can select Open from the File menu and navigate to this file and open it. This will open another window after a few seconds while the World analyzes the program. This new window will contain the text of the program. You may need to resize this window, but it should look like Figure 2. The window can be moved so that it doesn't cover the world.

To run this program you use the controls in the Control menu. These controls are graphical rather than textual, however. The Control menu is a tear-off menu and you can drag the menu off of the menu bar so that it becomes a floating window lying over your other windows. We then call it the Control Palette.

(Control Palette)
Pause Stop
Run Fast Run
Step Step Over

Figure 3. The Control Palette

The Control palette is shown in Figure 3. It has six controls that are suggestive of the controls found on a VCR.

  The upper left button will Pause a running program. It can be continued after a Pause.

The upper right button will Stop a running or paused program. A program can be restarted from the beginning after a Stop, but it cannot be continued.

The left button on the middle row will Run a program automatically, executing one instruction after the other until the end. You can pause the program at any time by hitting the Pause button. You can also Stop it with the Stop button. While a program runs the instruction that is about to be executed next will be highlighted in the program window.

The right button on the middle row, FastRun, will run a program as fast as you computer can execute it. You can also Pause or Stop the execution. The program window will not indicate the instruction being executed during a fast run, however. A short program like First.kpp will probably execute so fast in this mode that you won't have a chance to Pause it.

The buttons on the bottom row are used to Step through the program. The left button will Step through a program, one instruction at a time, pausing at the end of a single instruction. Each instruction will be highlighted in the program window each time it is executed. This is often the most useful way to see what a program is doing in detail. It is also useful to step through a program that has execution errors.

The right button on the bottom row is the StepOver button. It will completely execute whatever is highlighted in the program window without stepping through the individual steps of whatever is highlighted. It will then Pause. Since the entire main task block can be thought of as an instruction, and it is initially highlighted at the beginning of an execution, hitting this button at that time will FastRun the entire program.

After you execute a program using the buttons on the Control Palette, you can execute it again and again until you close it or open another program. You can have several world windows open at the same time, but only one program window. With one program and several worlds, you can execute the same program in different worlds.

(Image of first world with a robot and a beeper)

Figure 4. The World After a Robot has Been Delivered.

When a robot program is in execution, the robots will appear in it after their delivery specifications have been executed. The robot shows the direction it is facing in the world by the triangle shown on its chest, and, more subtly, by the direction that its eyes point. The robot in Figure 4 is at 1st Street and 2nd Avenue and it is facing East. After a robot executes a turnOff instruction, it will be shaded to indicate that it cannot execute more instructions.

You Do It. Run the First.kpp program in the First.wol world using each of the four run modes: Run, FastRun, Step and StepOver. In Step mode, you will need to hit the Step button several times. You can also go back and forth between the various modes. Try to Run the program with the Run button and then quickly Pause it. From there you can Step through it for example.

You Do It. Run the program Stair.kpp in the world Stair.wol. This is the program on page 31 of the text. It is a program that uses new instructions written by a robot programmer. You can find these files in your Karel++ folder also.

Note that, as a shortcut, If you have a world and a program open and you have selected any of the Control tools, then clicking the mouse on the world window is the same as clicking on the Step button. Similarly, if you click while holding the Option key down, you will execute StepOver. The cursor shows what will occur by its shape.

Writing Your Own Karel++ Programs

To write your own robot programs, you need a text editor. Any text editor will do, such as SimpleText, QUED/M, or BBEdit. You should be careful about indenting lines in your programs so that they are easy for you and others to read. The part of the simulator called the Parser that reads the program will ignore your indentation, however.

When you prepare a program with a text editor, you won't be able to open it in the Karel++ World by double clicking it. This is because it will have the editor's document icon. You can open it from the File menu of the Karel++ World, or you can drag the file icon over the application icon and release it.

If you want to make a program file open automatically in the Karel++ World instead of in the editor, you can use a file manipulation program to change the creator type to "KL++". The file will then get the Karel++ World document icon and will open in the World by double clicking. One program that can be used to do this is ResEdit. This is available from Apple Computer. Another is called TypeChanger. This is available on the web and in various shareware collections. You should probably change the creator to KL++ only after you are sure that you will be making no more changes to it, since after doing so it won't open automatically in the editor. You will still be able to open it from the editor's File menu however, or by using drag and drop.

If you write a program that has lexical or syntax errors then Karel++ World will find these and report them to you when you try to open the program file. These must be corrected before you can continue. After you make corrections you can open the file containing the robot program again.

Building Your Own Worlds

Karel++ World can be used to build robot worlds. To do so requires the use of the tools in the Place menu/palette. Like the Control menu, the Place menu can be "torn off" of the menu bar and placed anywhere on your screen. The Place palette is shown in Figure 5.

(Object Place Palette)
Horizontal Wall Segment
Vertical Wall Segment
Place Single Beepers
Place Infinitely Many Beepers

Figure 5. The Place Palette

The tools in the Place palette are used to place wall and beeper objects in the world. You select a tool from the Place palette or menu with the mouse. Note that you may need to click the mouse once on the palette to select the window and again to select the tool in the menu.

The first tool is None. It is not used to place anything in the world. Select this if you don't want to modify the current world by accident when you press the mouse down in a world window.

The second tool is used to place horizontal wall segments between Streets. When you select this tool, the cursor changes to a similar shape. You can then click the mouse between streets and across an avenue to place a single wall segment. Click several times in several places to create more wall segments.

The third tool is used to place vertical wall segments between Avenues. Its use is similar to the horizontal wall tool.

The fourth tool is used to place single beepers at a corner in the world. Figure 5 shows a view in which this tool has been selected. The large + sign indicates that beeper numbers on a corner will be increased when the mouse is clicked there. To place a beeper click the mouse on a corner after selecting this tool. To place several beepers on one corner, click several times.

The last tool is used to place an infinite number of beepers on a corner. Its use is similar to the two tools above it.

Sometimes you place a wall or beeper in the wrong place. Each of the tools can be used to remove objects as well as place them. There are two ways to accomplish this. First, you can double click on a tool in the Place palette to change it to a tool that removes objects of that kind. The cursor will change to a form indicating this use. For example the Place Beeper tool uses a cursor that looks like either a + sign or a - sign to indicate whether it is adding or removing beepers. The Place palette also changes to show the new use. For example, when you have selected the Remove Vertical Wall tool by double clicking, the Place palette looks like Figure 6.

(Object Place Palette)

Figure 6. The Place Palette when the Remove Vertical Wall Tool is Selected.

The second way to remove objects is to have any tool selected and then hold down the option key on the keyboard. The cursor will change to a remove tool, and the effect of a click will be to remove objects of that kind. Also, if you have a remove tool selected, then the option will change the effect to a place tool instead. The mouse cursor will always be changed to show the current effect.

By the way. The Remove Infinite Beepers tool will remove all beepers on a corner if there are several or if there are an infinite number.

Once you have built a world you can save it. You can either select Save or Save As from the File menu, or you can press Command-S from the keyboard. You will be prompted for a name with the standard file dialog.

You Do It. Build a world like Figure 2-5 in the book. It is on page 20. Don't forget to save your file.

You Do It. Build the worlds in Figure 1-4 in the book. They are on page 5.

Putting It All Together

Use a text editor to create the program on page 20 of the book. Then use the world you built above in which to execute the program. The program has errors, of course. Now use the text editor to correct the program.

Next you want to execute the corrected program. But you still have the old program open in the Karel++ World. To execute the changed version, you just need to open the program again. When you open a program file and you already have one open, you will be presented with a confirmation dialog. To avoid this, you can close the original program first, either by selecting Close from the file menu (assuming the program window is on top), or by clicking in the window's close box. Figure 8 shows a typical screen while the user is executing a Karel++ robot program.

You Do It. Correct the errors in the program on page 20 of the book and execute the changed program.

Printing Worlds and Programs

You can print a world if it is the top window. Currently only a single page is printed: the page that contains the lower-leftmost corner shown on the screen. You can print the program file that you opened if the top window is the Program Window.

Other Features

If you write programs that use several robots, the Robot Window will be very helpful. It shows the class, name, and current position of all robots in the world, including the direction they face and the number of beepers in their beeper bags. This window is continuously updated as the Robot Program runs. Figure 7 shows three robots from two different classes. It is from a solution to Problem 5.27.

(Robot view window)

Figure 7. The Robot Window, showing three Robots.


For advanced users, the resource types of Karel++ Robot programs are KL++ for the creator and TEXT for the file type. Karel++ worlds have KL++ for the creator and kwrl for the file type.

If you move Karel++ programs and worlds back and forth between the Macintosh and the PC, it will be helpful to establish the appropriate file associations in PC Exchange. Associate the DOS extension .WLD with kwrl and .KPP with TEXT. You should also name your world files with the extension .WLD and your Robot programs with the extension .KPP. This will make the transitions back and forth very easy.

Karel++ World for the Macintosh was built on a Power Macintosh using Codewarrior.


(Image of world)

Figure 8. Karel++ World in Action

Note that there is a restriction in the Karel++ language as currently implemented in its simulator. All robot declarations must come before any other statements in the main task block. I may be able to remove this restriction in the future.

Last Updated: December 28, 2002