|
| 1 | +Herbert |
| 2 | +======= |
| 3 | + |
| 4 | +Herbert is a game I first saw in the `Imagine Cup 2008 Algorithm Invitational <https://en.wikipedia.org/wiki/Imagine_Cup>`_. |
| 5 | + |
| 6 | +The game requires you to solve a series of levels by writing small programs to |
| 7 | +control a robot named Herbert. The simpler and more elegant your solution, the |
| 8 | +more points you get. |
| 9 | + |
| 10 | +It challenges your ability to see patterns and create algorithms to produce |
| 11 | +those patterns. |
| 12 | + |
| 13 | +Here's my clone of Herbert. |
| 14 | + |
| 15 | +.. image:: https://github.com/dwayne/herbert-python/blob/master/data/images/herbert.png |
| 16 | + |
| 17 | +Enjoy! |
| 18 | + |
| 19 | +Installation |
| 20 | +------------ |
| 21 | + |
| 22 | +To install, simply use pip (or `pipenv`_): |
| 23 | + |
| 24 | +.. code-block:: bash |
| 25 | +
|
| 26 | + $ pip install herbert |
| 27 | +
|
| 28 | +Usage |
| 29 | +----- |
| 30 | + |
| 31 | +To run :code:`herbert` you need a **level** to solve and a **program**, that you |
| 32 | +write, that attempts to solve the level. |
| 33 | + |
| 34 | +Suppose the level is stored in :code:`level.txt` and that you wrote and saved |
| 35 | +your solution in :code:`sol.h`. Then, you'd run :code:`herbert` as follows: |
| 36 | + |
| 37 | +.. code-block:: bash |
| 38 | +
|
| 39 | + $ herbert level.txt sol.h |
| 40 | +
|
| 41 | +It will open a `curses <https://en.wikipedia.org/wiki/Curses_%28programming_library%29>`_ |
| 42 | +based text user interface that allows you to run your program against the level |
| 43 | +to determine if it solves the level and how many points your solution is worth. |
| 44 | + |
| 45 | +**N.B.** The `data/example <https://github.com/dwayne/herbert-python/blob/master/data/example>`_ |
| 46 | +directory contains an example level along with 3 attempted solutions to the |
| 47 | +level. You can use it to help you understand how the game works. |
| 48 | + |
| 49 | +**An overview of the game** |
| 50 | + |
| 51 | +A level consists of empty spaces (:code:`.`), walls (:code:`*`), white |
| 52 | +(:code:`w`) and gray (:code:`g`) buttons, and a robot (:code:`u` means the robot |
| 53 | +is facing upwards, :code:`r` means the robot is facing towards the right, |
| 54 | +:code:`d` means the robot is facing downwards, or :code:`l` means the robot is |
| 55 | +facing towards the left). |
| 56 | + |
| 57 | +**N.B.** You can find an example level `here <https://github.com/dwayne/herbert-python/blob/master/data/example/level3.txt>`_. |
| 58 | + |
| 59 | +On each level there are some white buttons. To solve a level you must press all |
| 60 | +the white buttons. Your goal then is to program Herbert, in a language called |
| 61 | +"h", to press all the white buttons while avoiding obstacles such as walls and |
| 62 | +gray buttons (walls block Herbert's path and gray buttons reset any previously |
| 63 | +pressed white buttons to their unpressed state). |
| 64 | + |
| 65 | +You are only allotted a certain number of "bytes" (a unit of program size) per |
| 66 | +level. Your program must use no more than this number of bytes. |
| 67 | + |
| 68 | +Points are awarded for each white button pressed, a bonus is awarded for solving |
| 69 | +the level, and extra points are awarded for solutions that use less than the |
| 70 | +allotted maximum number of bytes. |
| 71 | + |
| 72 | +**The "h" language** |
| 73 | + |
| 74 | +It is a simple language that contains statements, procedures with zero or more |
| 75 | +parameters and recursion. Check out the tutorial `here <https://github.com/dwayne/herbert-python/blob/master/data/resources/Tutorial.aspx.html>`_ |
| 76 | +to get a better understanding of the language. |
| 77 | + |
| 78 | +You can find examples of the language in use `here <https://github.com/dwayne/herbert-python/blob/master/data/example/sol3a.h>`_, |
| 79 | +`here <https://github.com/dwayne/herbert-python/blob/master/data/example/sol3b.h>`_ |
| 80 | +and `here <https://github.com/dwayne/herbert-python/blob/master/data/example/sol3c.h>`_. |
| 81 | + |
| 82 | +**Challenge** |
| 83 | + |
| 84 | +Try to solve the following levels (see `data/levels <https://github.com/dwayne/herbert-python/blob/master/data/levels>`_): |
| 85 | + |
| 86 | +- `Level 1 <https://github.com/dwayne/herbert-python/blob/master/data/levels/level1.txt>`_ |
| 87 | +- `Level 2 <https://github.com/dwayne/herbert-python/blob/master/data/levels/level2.txt>`_ |
| 88 | +- `Level 3 <https://github.com/dwayne/herbert-python/blob/master/data/levels/level3.txt>`_ |
| 89 | +- `Level 4 <https://github.com/dwayne/herbert-python/blob/master/data/levels/level4.txt>`_ |
| 90 | +- `Level 5 <https://github.com/dwayne/herbert-python/blob/master/data/levels/level5.txt>`_ |
| 91 | + |
| 92 | +Development |
| 93 | +----------- |
| 94 | + |
| 95 | +Recommended tools: |
| 96 | + |
| 97 | + - `pyenv <https://github.com/pyenv/pyenv>`_ |
| 98 | + - `pipenv`_ |
| 99 | + |
| 100 | +Clone the repository and install the dependencies: |
| 101 | + |
| 102 | +.. code-block:: bash |
| 103 | +
|
| 104 | + $ git clone git@github.com:dwayne/herbert-python.git |
| 105 | + $ cd herbert-python |
| 106 | + $ pipenv shell |
| 107 | + $ pipenv install --dev |
| 108 | +
|
| 109 | +You're now all set to begin development. |
| 110 | + |
| 111 | +Testing |
| 112 | +------- |
| 113 | + |
| 114 | +Tests are written using the built-in unit testing framework, `unittest <https://docs.python.org/3/library/unittest.html>`_. |
| 115 | + |
| 116 | +Run all tests. |
| 117 | + |
| 118 | +.. code-block:: bash |
| 119 | +
|
| 120 | + $ python -m unittest |
| 121 | +
|
| 122 | +Run a specific test module. |
| 123 | + |
| 124 | +.. code-block:: bash |
| 125 | +
|
| 126 | + $ python -m unittest tests.test_interpreter |
| 127 | +
|
| 128 | +Run a specific test case. |
| 129 | + |
| 130 | +.. code-block:: bash |
| 131 | +
|
| 132 | + $ python -m unittest tests.test_interpreter.ExamplesTestCase.test_example10 |
| 133 | +
|
| 134 | +Resources |
| 135 | +--------- |
| 136 | + |
| 137 | +- `Herbert Programming Challenge <https://herbert.wildnoodle.com/>`_ by `Wild Noodle <http://www.wildnoodle.com/>`_ |
| 138 | +- `Herbert Online Judge <http://herbert.tealang.info/>`_ |
| 139 | +- `uHerbert <http://membres-lig.imag.fr/benyelloul/uherbert/index.html>`_ |
| 140 | + |
| 141 | +.. _pipenv: https://github.com/pypa/pipenv |
0 commit comments