Karel J. Robot
A preprocessor that translates a simplified Java-syntax into 100% pure Java code.
The simplifications are penned by Joseph Bergin et al. in their manuscript
Karel J. Robot. This work was used in the basic course
"Basics of Computer Science I" winter 2001 and
winter 2002 at Darmstadt University of Technology.
Karel J. Robot is an interesting approach for teaching object oriented programming using Java.
The manuscript is by Joseph Bergin, Mark Stehlik, Jim Roberts and Richard Pattis. For details
on Karel J. please refer to the
The manuscript uses some simplifications which I will describe later. Joseph
Bergin also offers a runtime environment for programming robots as described
in Karel J. Though you have to use pure Java then and can't take advantage of
the simplifications. My work is mainly a preprocessor which translates the simplifications
into pure Java.
After using the
first version of my preprocessor and
Mr. Bergin's runtime environment for the "Introduction
to Computer Science" lecture at the "Darmstadt University
of Technology", we found some shortcommings which I tried
to fix in a second version of the preprocessor. I also wrote a new runtime environment
whose premier advantage is its small interface. We only used Karel J. as an
introduction into Java, so we essentially used the first chapters. My new r.
e. only offers the most basic functionality which is actually all we used. I
also wrote a new r. e. to solve some problems we had with the graphic interface.
A third cause for rewriting it is that we assigned exercises using Karel
J. The new runtime environment will offer the correctors some help.
- A new version of the Simulator is available for download (afternoon Sep. 16. 2002) -
KarelSim.jar - KarelRT.jar
- KarelRTsrc.zip - sample.task
- Added the clone method to ur_Robot
- Now all constructors of robots have the signature (street, avenue, direction,
- Now you can use non-absolute paths for the source files in the commandline
- Fixed the frontIsClear() method to return false if the robot faces the edge
of the world (i.e. west of the first avenue or south of the first street)
- I forgot to mention that I compiled the classes using the jdk 1.4. This
means you also have to use the virtual mashine of the jdk 1.4 to run the simulator.
I will work on this but it will take a while until a version for earlier jdk
releases is available.
- Now you can change the World implementation to be used via the commandline.
There is a new commandline option available:
-worldimpl <fully qualified
- I added a manifest to the KarelSim.jar file. Now you can start the simulator
java -jar KarelSim.jar your.task, but only the current directory
and KarelSim.jar will be in the classpath then. If you want to add other directories
or archives, you still have to use
java -classpath KarelSim.jar;inst;%CLASSPATH%
- Updated the sample.task file to use the right constructor (see above), too.
- Standard directory for instrumented and compiled files is now the current
directory. If you want to use another one, be sure to have it in your classpath.
- There still might be a problem in the file finding mechanism. If the simulator
looks for a class and finds a file which is named like the file, it stops
looking any further. If this file doesn't really contain the searched class
(which is possible if you don't use public classes) it might be a problem.
- I reprogrammed the file finding mechsanism. Now the "Karel"-Constructor
is not added if a the super class has a constructor with four ints as parameters
but if it is a direct or indirect subtype of ur_Robot. Also if you didn't
explicitely imported the "keareltherobot" package, the simulator
didn't work. That should be fixed now.
- There was an error in the commandline I gave as example to start the Simulator.
The right one is:
java -classpath KarelSim.jar;inst;%CLASSPATH% Simulator
- I added the Robot class which is part of the original core by Mr. Bergin.
The new preprocessor now parses the denoted file and all files containing depending
classes. It does that in similar ways as javac. You can only have one public
class per file (in that case the file also must have the same name as the class),
but you can have as many non-public classes per file as you like and they can
have any name you like. That might, though, cause problems finding some types
(it might be that my way of finding types is not always correct). The simplest
way of success is that you only have one class per file and name the file the
same as the class. The preprocessor finds files with the extensions ".java"
How it works
The Proprocessor makes several changes:
- Aadd "import kareltherobot.*;" to all files.
- Add kareltherobot.Directions to the implemented interfaces of all classes.
- If the superclass of a class has a constructor like (int, int, int,
int) this constructor is added, calling the super constructor. This is because
in the manuscript subtyping is explained without constructors. And as every
robot needs this kind of constructor it is simply added if it isn't there. (at
the moment, this is buggy. consider: A extends ur_Robot, B extends A. Then B
wouldn't get the constructor ... I will fix this soon).
- Every method without visibility modifiers is set to be public. Otherwise,
if the method is inherited and was originally public, javac would say, that
it is redefined with weaker access rights.
- The new loop-statement of the Karel J. language is replaced by a for-statement.
Variables of the form "_i" + some counter are used so be careful not to use
identifiers like this yourself.
- The task-declaration of the Karel J. language is used to create a class. It
is called KarelTask and the clock of the task declaration becomes the body of
its main method. This class is public and it is added to the file containing
the task. So don't put a task into a file containing a public class (I might
change this, though). If a class KarelTask already exists within the classpath
it might cause some confusion. If you encounter problems like changes you made
don't appear, please look for KarelTask.java or KarelTask.class files and delete
How to use it
To use the preprocessor, you have to download this jar-archive.
It contains the Preprocessor and the runtime environment (which can also be
downloaded separately). To start the simulator type
java -classpath KarelSim.jar;inst;%CLASSPATH% Simulator
your.task. This will cause the preprocessor to do its modifications
to all necessary files, write the changed files into directory "dist", compile
them and run the task in an empty world. You can use the following commandline
For you to get started, I prepared a sample Karel J. .task
file. The directory in which the instrumented files (i.e. the generated
java files) are put, must exist and must be included in the classpath (the default
"inst"). If the -d argument is used, the specified directory must also be within
the classpath. I will not make the source code of the simulator publicly available,
as I am using a framework, I am developing myself,
for the preprocessor. This framework is not yet ready to be published. You can
download the source of the runtime environment
The delay between robot movements in milliseconds
The directory to temporarily output instrumented files
The name of the world file to be loaded at startup
The number of streets to be visible
The number of avenues to be visible
The directory where to place generated class files
Specify where to find input source files
The World implementation to be used
The runtime is very similar to the one by Mr. Bergin. Actually it should
be the same except for the missing parts and a few extensions that are merely
optional to use. I also put the classes in the same package which is for downwards-compatibility
reasons. I intend that the programs we used last year can simply run using
the new r. e. and that the original r. e. can be used with my new simulator.
For documetation on the api I will add a JavaDoc generated docu soon. You
can also refer to the the Karel J. pages which also include a
The main difference between both implementations is the World. In my implementation
World has most of the static methods the original one has, but it just delegates
them to an instance of a World-object which also can be accessed using World.getWorld().
It is a singleton and therefor only one instance per virtual machine exists.
Because World is really an object for me, other implementations of World can
be used. Actually two already exist. World is only offers the functionality
for keeping book about walls, beepers and robots. The GUIWorld offers a graphical
interface for presenting the world. The protected method "registerWorld()"
is used by subclasses of World to set themselves as the World-Object. This
should be done within the static initializer to load a World implmentation
by using 'Class.forName( "WorldImplementation" );' just like for JDBC drivers.
I will add some documentation on World implementation later. For now please
refer to the source code of the r. e. The simulator automatically selects
Where possible, my simulator mimics or uses javac or java behaviour. There
are three types of errors: syntax errors, semantic errors and runtime errors.
Syntax and semantic errors appear during compiletime. The error messages have
the following format:
filename:line,column:message. Where filename
is given as url (using the simulator) and denotes the file within which the
error occurred, line and column name the position within this file. As my
simulator parses the code itself, the syntax errors appear during parsetime
of the simulator. That means, the simulator doesn't generate original javac
error messages for them. the error messages then name the token the parser
found and a list of tokens that were expected to find. After transforming
the code, it is printed into the specified directory and compiled using javac.
The error messages generated by javac are translated by the parser. I.e. the
original source file and the original position of the error are printed out.
If an error occurred within code that was generated by the simulator
in generated code is printed as errormessage followed by the filename
and position where the error occurred. This doesn't denote the original file
but the generated one. Javac also prints the line within which the error occurred
in the error message. This code sample is taken from the generated file so
it might look different from the respective line in the original code. The
runtime errors (or exceptions) are not especially handled by the simulator
and thus the sourcecode positions given in runtime error messages always name
the position within the generated file.
As mentioned before, we don't want that the students use arrays. Also, as
Karel J. introduces the loop statement, the for statement should not be used
in Karel J. programs. Also the '&&' and '||' operators don't exist in the
Karel J. language. So my simulator warns if it encounters any of those language
The graphic of my new runtime, also is completely based on .gif images.
So it can be completely customized. The images are within the jar archive.
This is simply a zip archive within which you can replace the .gif files.
The graphic routine seperates the world into rectangles which represent the
crosroads the robots move on. The images are always stretched to fit exactly
into such rectangles. You can use a transparent color. I suggest, you use
images of the same resolution and. The robot and beepers should not fill the
image and be centered. You need to put your customized images back into the
jar archive for the simulator to find them. If you think your images are nice,
please send them to me, I'll publish them on this page.
Unfortunately using .gif images introduced a new probley, I was not yet
able to solve. The images are loaded asynchronously and thus it may happen
that an image is not displayed the first time it should be.
I am still in the testing phase, but also I have some ideas of funtionality
I'd like to add. So if you tried this program and encountered problems or
have ideas yourself what is missing, please let
me know. Also if you miss something in this docu, please tell me. If you
are interested in the simulator please check this page regularly as it will
(hopefully) change a lot within the next time.