Skip to content
/ karel Public
forked from alts/karel

A Python Karel the πŸ€– for teaching programming basics πŸ–₯

License

Notifications You must be signed in to change notification settings

xsebek/karel

Β 
Β 

Folders and files

NameName
Last commit message
Last commit date

Latest commit

Β 

History

69 Commits
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 

Repository files navigation

Karel the Robot (now in Python)

Python Version PyPI Code style: black

Karel is a pretty snazzy environment for learning to program. You can read about it here.
I decided to write a Karel environment for Python, after seeing that all of the others had too many dependencies for beginners.

Stephen Altamirano (alts/karel)

Installation

Installing should be as simple as opening your terminal and writing:

pip3 install karel_robot

Write simple Karel programs

Coding in Python is super fast and easy! Save a text file example.py in this folder, use import and start coding!

from karel_robot.run import *
# you can call imported functions
turn_left()

# or use Python, like loops ('while') or logical 'not'
while not front_is_blocked():
    move()

For a true unix executable, add the shebang, then the right to execute with chmod +x example.py and run it as ./example.py.

If you break a Karel program, it should not leave your terminal screen broken in retaliation, otherwise please file an Issue. More advanced or courageous programmers are welcome to look into the karel_robot folder and read about the details.

Karel functions

These are the functions you can use to command Karel after importing from karel_robot.run:

Function Result
Movement
move() Karel moves in the direction he is facing
turn_left() Karel turns left
turn_right() Karel turns right
Beepers
pick_beeper() Karel tries to pick up a beeper
put_beeper() Karel puts down a beeper (if he has any)
beeper_is_present() True iff Karel stands on a beeper
Walls
front_is_blocked() True iff Karel can't move forward
front_is_treasure() True iff Karel is standing in front of a Treasure
Direction
facing_north() True iff Karel is facing north (^)
facing_south() True iff Karel is facing south (v)
facing_east() True iff Karel is facing east (>)
facing_west() True iff Karel is facing west (<)
Execution
set_karel_beepers(None) Set Karel's beepers, with None as inf.
set_speed(100) How fast Karel moves, 0 to 100
pause() Pause execution, press any key to continue
message(text, pause) Show a text message to user.
save() Save the map in file specified by --output.
exit() End execution

Note that the map is loaded and screen started in the moment of import:

from karel_robot.run import *

If you only need raw objects and methods see the directory karel_robot.

Karel world

There are many maps in world directory. Karel maps are simple text files and look like this one:

1..#...
#....^.

Karel is represented by the arrow (^) looking up on the empty tile (.).
There are two walls (#) and one beeper in the upper right corner (1). There is no treasure ($).

This does not allow us to use more then 9 beepers and place Karel on beeper or other non-empty tile.

New Karel map format

A new map format has file extension .km2 but it is still plain text file βˆ’ you can change it to .txt:

KAREL 2 1 > N
#  1  .  #  #  .  . 21
#  #  9  .  #  .  #  #
6  .  .  .  .  .  .  #

The above map places Karel right on the 9 beepers. Note that there are 21 beepers in the upper right corner in one tile, which the original format does not support. The mysterious N in Karel's header sets the number of beepers he starts with to unlimited, which is the most fun.

Editor support

Do you want to write or edit maps? Check out the vim highlighting!

Run your program

Open the terminal and write this command:

python3 YOUR_PROGRAM.py  # -m YOUR_MAP.km or other options

Press Q to quit or P to pause program. Program pauses when Karel tries to make an illegal move.

Example treasure πŸ’°

Click to expand! Run the program `treasure.py` (also below) with worlds `00` - `03_window`. Karel will walk to the wall and then search for a treasure in the walls.

Karel finds the treasure. Karel cycles. Karel goes around. Karel hits the wall.

The idea comes from a paper on cooperative learning in CS1.

Karel searching for treasure Python code
from karel_robot.run import *

while not front_is_blocked():
    move()

while not front_is_treasure():
    turn_left()
    if front_is_blocked():
        turn_left()
    # FIX: add else
    move()
    turn_right()

Langton's ant 🐜

Click to expand!

Here is a short animation of Karel playing Langton's ant.[wiki]

langton_optimized

The program `ant.py` (also below) uses a single beeper to mark a tile as "Black" and Karel can pick it up to make it "White". The ant moves seemingly randomly, but makes a nice picture in about 11000 steps. The command to recreate the recording is:
programs/ant.py -x 70 -y 50 --karelpos 35 25 --kareldir ^ --output langton.km2
Langton's ant Python code
from karel_robot.run import *
set_speed(100)

while True:  # repeat
    if beeper_is_present(): # At a black square
        pick_beeper()           # flip the color of the square
        turn_left()             # turn 90Β° left
        move()                  # move forward one unit
    else:                   # At a white square
        put_beeper()            # flip the color of the square
        turn_right()            # turn 90Β° right
        move()                  # move forward one unit

Try out your map with interactive

Run the karel script with any of the options:

karel --help                       # 0. prints the actual usage
karel                              # 1. opens in infinite map, fills the whole screen
karel -m "world/1_window.km"      # 2. opens the simple text file map in world directory
karel --ix -m "world/easy/tiny.km2"  # 3. simillar to 2., but forces the

You can now use your keyboard to control Karel.

Key Function
↑ move()
← turn_left()
β†’ turn_right()
I pick_beeper()
U put_beeper()
Q stop()

There is also W for saving to file (specified by --output) and couple of keys for cheating testing!

Recursive Karel

You can try your wits in creating iterative programs with only if statements, procedure definition and recursion! It is pretty mind bending so lets look at an example:

DEFINE MAIN
    IFWALL PUT MOVE
    IFWALL SKIP MAIN
END
RUN MAIN

After the program is parsed and run, the MAIN function will call itself again until it reaches a wall. When that happens, Karel will put down a beeper and the execution stops.

Here is a more complex recursive program searching through a maze for a tile with two beepers:

Recursive program to find treasure

You can define new procedures by writing DEFINE new_name and then writing names of procedures and statements into its body, which you then END.

These statements are the simple building blocks you can use and combine with your new procedures:

Statement Note
MOVE Karel steps forward.
LEFT Karel turns 90Β° left - note that there is no RIGHT :)
PUT Karel puts down one beeper.
PICK Karel picks up one beeper.
SKIP Does nothing - like pass in Python.
IFWALL βœ“ 𐄂 If front_is_blocked() then run the first procedure else the second
IFMARK βœ“ 𐄂 If beeper_is_present() then run the first procedure else the second

The interpret in karel_robot.parsers.interpret is used by the karel executable script:

karel --program programs/graph/3_treasure.ks --map world/maze/treasure/07.km2 --speed 20

Credits πŸ€–

The original author is Stephen Altamirano (@alts). Recently this has been updated by @Tetragramm and @xsebek.

The package on PyPI is maintained by @xsebek.

If you want to contribute, check out the karel_robot folder README.

LICENSE

This project is released under GNU GPLv3 (or later) license in hopes that it will be useful. You are encouraged to share this freely and can even sell it provided everyone will still be able to read and modify the source code (just like you are) and keeps the license. πŸ˜‰

About

A Python Karel the πŸ€– for teaching programming basics πŸ–₯

Resources

License

Stars

Watchers

Forks

Packages

No packages published

Languages

  • Python 97.4%
  • Shell 2.0%
  • Vim Script 0.6%