Overview

* Get project source code from bitbucket.org:

     hg clone https://bitbucket.org/paolini/ulisserobot

  This will create a directory named "ulisserobot" in the current directory. You can move the directory
  elsewhere if you want to.

* Compile the project and documentation (without eclipse):

  1. enter directory src
  2. javac *.java
  3. javadoc *.java
  4. java UlisseRobot

* To import the project into eclipse:

  1. start eclipse
  2. File -> New -> Java Project
  3. Write Project Name: Ulisse Robot
  4. Uncheck "use default location"
  5. Select the "ulisserobot" directory as your "Location"
  6. Press "Finish"

* UlisseRobot Documentation:

Ulisse the Robot is a robot living in a rectangular room. The room is
composed by cells possibly divided by invalicable walls. On the floor
there might be diamonds. With the graphical user interface in the
"edit" tab you can modify the room to change dimensions, place walls and place
diamonds. Click on a cell to place a diamond, click on the boundary of
a cell to place a wall. Right-click to remove diamonds and walls.

In the "play" tab you can move Ulisse interactively. Ulisse can take
diamonds from the ground and can place diamonds. Ulisse has a bag with
infinitely many diamonds. Ulisse will die if it:
- bumps into a wall
- takes a diamond when no diamond is on the ground

In the "code" tab you can write code to command Ulisse. The language
understood by Ulisse is composed by elementary commands, compound
statements and functions.

Elementary commands are the following:

advance
turnLeft
turnRight
take_diamond
drop_diamond
front_is_clear
left_is_clear
right_is_clear
diamond_is_present
facing_east
facing_north
facing_west
facing_south
true
false

The first 5 commands cause Ulisse to actually make some action. The
other commands return a true/false status which can be used by Ulisse
to take decisions. These last commands might be used in control
statements:

  if [not] <condition> 
    <block of statements>

  while [not] <condition>
    <block of statements>

where a <block of statements> is a single command or statement or a
sequence of statements enclosed by curl braces {...}.

Examples:

  while front_is_clear advance

  while not diamond_is_present {
    drop_diamond
    if front_is_clear 
       advance
  }

In the while loop the statements: "break" and "continue" can be used to
restart the loop or to end the loop.

A function can be defined as follows:

function_name = <block of statements>

the function can the be used (called) as any elementary statement
after the point of definition (also recursively). The function
can be terminated with the "return" statement. The function can be
used in a if/while statement: the last true/false condition
checked by the function is used in the if/while statement. 

You must define a function named "main" which is the function executed
by Ulisse when you press the "Run" button.

Comments are introduced by the '#' character.

Here is a simple complete example:

# this program makes Ulisse 
# clean all diamonds in a room without walls

take_all_diamonds = {
  while diamond_is_present {
    take_diamond
  }
} 

clean_to_wall = {
  take_all_diamonds
  while front_is_clear {
    advance
    take_all_diamonds
  }
}

advance_to_wall = {
  while front_is_clear {
    advance
  }
}

main = {
  advance_to_wall
  turn_left
  advance_to_wall
  turn_left
  
  # here Ulisse is in a corner, with a wall on right-hand side
  
  while true {
    clean_to_wall
    turn_left
    if not front_is_clear {
       return # mission accomplished!
    }
    advance
    turn_left
    clean_to_wall
    turn_right
    if not front_is_clear {
       return # mission accomplished!
    }
    turn_right
  }
}