CIT 590 Assignment 5: Black Box
Fall 2015, David Matuszek

Purposes of this assignment

Give you experience with lists and with lists of lists
Give you experience with careful formatting of output

General idea of the assignment

In this assignment you will write a program to let you play the Black Box "game." Although called a game, Black Box is actually a kind of puzzle, where the computer sets up the puzzle, and you try to solve it, by figuring out where things are inside the "box".

Wikipedia has a good description of the game.

The basic idea is this: The computer "hides" four atoms somewhere on an 8x8 grid. You, the player, try to figure out where the balls are by shooting in "rays" from any of the 32 positions along the sides of the grid (8 on each side, including the top and the bottom), and seeing where the ray comes out, or if it comes out at all. For each ray you send in, there are three cases:

The ray hits an atom, and never comes out again. (Mark this with anH.)
The ray comes out the same place it went in. This is called a "reflection". (Mark it with an R.)
The ray, for whatever reason, comes out a different place than it went in. Use lowercase letters for this, marking the entrance and the matching exit with the same lowercase letter--a and a for the first time it occurs, b and b for the second time, c and c for the third time, etc. There is no need to mark which is the entry and which the exit.

Details

If the game board looks like this*:

You could represent it like this:

[ [ False, False, False, False, False, False, False, False ],
  [ False, False, False, False, False, False, False, False ],
  [ False, True,  False, False, False, False, True,  False ],
  [ False, False, False, False, False, False, False, False ],
  [ False, False, False, False, False, False, False, False ],
  [ False, False, False, True,  False, False, False, False ],
  [ False, False, False, False, False, False, False, False ],
  [ False, False, False, False, False, False, True,  False ] ]

Or like this:

[(2, 1), (2, 6), (5, 3), (7, 6)]

Or like this:

{(2, 1), (2, 6), (5, 3), (7, 6)}

It is up to you to choose the best way to represent the game board, and the results of shooting in rays. Some representations will be much easier to work with than others, so it is worth your while to think about various approaches, and not just do the first thing that comes into your head. You won't be graded on choosing the "best" representation.

We aren't doing graphics, so the display of the board will be just text.

This is how the board prints out initially:	This is what it might look like after shooting in a few rays:
`1 2 3 4 5 6 7 8 ----------------- 1 \| - - - - - - - - \| 1 2 \| - - - - - - - - \| 2 3 \| - - - - - - - - \| 3 4 \| - - - - - - - - \| 4 5 \| - - - - - - - - \| 5 6 \| - - - - - - - - \| 6 7 \| - - - - - - - - \| 7 8 \| - - - - - - - - \| 8 ----------------- 1 2 3 4 5 6 7 8`	`1 2 3 4 5 6 7 8 H ----------------- 1 a\| - - - - - - - - \|a 1 2 \| - - - - - - - - \| 2 3 \| - - - - - - - - \| 3 4 \| - - - * - - - - \|H 4 5 b\| - - - - - - - - \| 5 6 \| - - - - - - - - \| 6 7 \| - - - - - - - - \| 7 8 \| - - - - - - - - \| 8 ----------------- b R 1 2 3 4 5 6 7 8`

The user needs to be able to:

Shoot rays into the "black box." A ray may be shot into any row or any column, from any side. To indicate where to shoot a ray, the user should enter a number 1 to 8, followed by a letter L for left, R for right, T for top, and B for bottom. (Also allow lowercase letters l, r, t, b.) In the second picture above, rays have been shot in from 1L (or lR), 4T, 4R, 5L (or 3B), and 6B.
Mark where he/she thinks an atom may be. In the above, an atom is marked at row 4, column 4, presumably this is consistent with the results of 5L (b) and 4T (H). To mark a location, the user should enter a row number followed by a column number, such as 44 (or 4 4) in the above example. Do not limit the user to four marks.
Unmark a previously marked location, by entering a row and column number of a marked location.
Finish and ask that the game be scored.

Scoring: 1 point for each mark along a side (7 in the above example), plus 10 for each error (no mark where there is an atom, or mark where isn't one). If the mark at 4 4 in the above example is correct, that will be 30 points for the three atoms that haven't been marked.

The game board should be printed out after each user input, showing the effects of shooting rays, and the markers that the user has placed. After scoring the game, the program should tell the user where the atoms are actually hidden, preferably with a similar kind of output.

Normal people don't start counting with zero. Only programmers do that. So when you print the board, you should add 1 to all the row numbers and all the column numbers, and when you get row or column numbers from the user, you should immediately subtract 1 from them. Inside the program we'll use 0 to 7, not 1 to 8.

After each game, the program should ask the user whether he/she wants to play again.

Required methods

You should test all your methods except those devoted to reading input or displaying results. Since we also want to do some testing, we need to be able to set up a game and "play" it from our test methods. For this purpose, please supply the following methods:

new_game(location1, location2, location3, location4)

Sets up a new game board with "atoms" in the four locations specified, where each location is a (row, column) tuple. Row and column numbers are 0 to 7. Clears any leftover data from any previous game. Returns None.

shoot(entry)

"Shoots" a "ray" into the game, where entry is a string using the same syntax that a user would type in ('1L', etc.). Returns the exit point of the ray in the same syntax, or None in the case of a "hit."

toggle(row, column)

Marks or unmarks the specified location in the game. Row and column numbers are 0 to 7. Returns None.

toggle marks where the user thinks the atoms may be; it does not affect where they actually are.
The user may toggle any number of locations, any number of times.

score()

Returns (as an integer) the current score. Does not end the game.

Notes

Since information must be maintained between calls, you will need to keep information about the current state of the game in global variables. Use as many as you need, but try not to use more than that.
It is up to you how to store the game board (I've made some suggestions above) and its related information. The above four methods are neutral in this respect--they don't impose any particular representation.
You should keep the methods that do computation separate from those that do input or output, and you should unit test the computational methods (including the four above).
You can assume that I will call the above required methods only with legal parameters.

Coda

At the end of your Python program (after all your function definitions), insert the following lines:

if __name__ == "__main__":
  main()  # or whatever your starting method is

Due date

Turn in your one zip file to Canvas by 6am Wednesday, September 30.

Notes on submitting your work:

Please put your name as a comment at the beginning of your program.
Please do not use non-ASCII characters in your program or in the name of your program or in the name of the folder containing your program.
If you are zipping an entire folder, rename the zipped folder to have your (ASCII) name as part of the name of the folder.
Do not zip individual files, only folders or groups of files.

* "BlackBoxSample1" by Life of Riley - Own work. Licensed under GFDL 1.2 via Commons -https://commons.wikimedia.org/wiki/File:BlackBoxSample1.svg#/media/File:BlackBoxSample1.svg