CS21: Lab 7

Please read through the *entire* lab before starting.

Run update21 to create your cs21/labs/07 directory and create your programs for lab 7 in this directory.

Introduction

Over the next two weeks you will write a program that plays the game Mastermind. This week you will focus on using top-down design to create the overall structure of the program. Once your proposed structure has been reviewed by your professor, you will use bottom-up implementation and unit testing to incrementally implement and test the full program (due March 28).

The wikipedia page about Mastermind describes the game and also some ineteresting results obtained by computer scientists who have studied the game. If you take more computer science courses at Swarthmore, you will learn about NP-complete problems in our Algorithms and Theory courses. Also, you can try playing the game on-line (but our version won't use graphics!).

Mastermind

Mastermind is a code-breaking game for two players. For our text-based version, the computer will be the code maker and the user will be the code guesser or breaker.

At the start of the game the computer will create a 4-letter code, where each letter is one of 6 possible letters (abcdef). Possible codes are ABCD, AAAA, BCBF, and so on. The user then has 12 chances to guess the code. After each guess, the computer tells the user how many exact and partial matches they achieved.

An exact match means the guessed letter and its position in the code are correct.
A partial match means the letter is correct, but the position is wrong.
Note: the user is *not* told which letters are matches, only how many exact and partial matches there were.

To make things more concrete let's consider some examples. Below is an example of just part of the game -- a code (usually not shown!) and multiple guesses, to show exact and partial matches.

code = "DDEC"

 1: abcd
                        0 exact matches
                        2 partial matches
--------------------
 2: deff
                        1 exact match
                        1 partial match
--------------------
 3: dddd
                        2 exact matches
                        0 partial matches
--------------------
 4: eedd
                        0 exact matches
                        3 partial matches
--------------------

Below are more details about specific requirements for the full mastermind program. Next we list the Top-Down-Design (TDD) requirements. Remember, the design is due this week, the full program next week.

Top-Down Design

The focus of this assignment is for you to practice using top-down design to construct your solution incrementally. This assignment spans two weeks. In the first week, you are required to design your solution and implement minimalistic function stubs for your design. In the second week, you will finish implementing and testing the full game.

Note: Once you have your top-level design done you should run handin21 and send me an email that you have completed your top-level design. I will look at your design and email you with feedback on your design within 24-48 hours. Please wait to hear back from me before continuing with the implementation of the full game (I may ask you to re-think your design). The earlier you handin your design, the earlier you can continue working on your full program.

For the design of the program in the first week, you should have:

main() completely written
functions called from main() all stubbed out with parameters, comment, and a sample return statement
clear use of data structures and variables in main() and the stubbed-out functions
a design that runs without errors (although it doesn't play the game yet)
your program should have at least 4 functions besides the main function (mine has 6).
each function, including main, should be function-worthy. This means its full implementation should have several python statements, which may include calls to other functions.

Here is a simple example of a top-down design.

Mastermind Examples

Here are a few examples of a working program. Please look through the examples and note the details of how this program should work (e.g., how both upper and lowercase input is accepted, or what the special inputs ("quit" and "dbug") do).

Example 1
Example 2

Requirements for the full mastermind game

The requirements for a working mastermind game are:

The program prints out a welcome message and the game rules for the player
The computer generates a secret code
The user enters up to 12 guesses
After each guess, the program prints out the number of exact and partial matches
The game ends if the user enters the correct code
The program prints out a win or lose message to the player. If the player loses, it should print out the secret code.
Your program needs to ensure that only valid input values are entered by the user (see the examples above)
See the above examples for additional requirements...

Helpful tips

As you work on this program, write and test each function, one at-a-time!!! Make sure each function works before you move on to the next function.
For your design, you should have main() completely written and all functions stubbed-out. This does not qualify as a good top-down design:
```
def main():
  playgame()

def playgame():
  """will do lots of work here to play the game"""
  return
```
Do NOT write the full program, then create the design later by taking out all code in the functions!
Study the examples to see all requirements of your code (e.g., what happens when the player quits early?, what happens when they enter an invalid code?, etc)
strings are immutable, lists are mutable
In python you can test if a character is in a given string or list with the in operator:
```
if 'a' in mystring:
   ...
```
Use not in to test if a character is not in a string or list.

Sometimes it is useful to make a copy of a list. This is easily done in python with the list() function:

>>> L = list("abcd")
>>> print L
['a', 'b', 'c', 'd']
>>> LCOPY = list(L)
>>> LCOPY[0] = 'X'
>>> print LCOPY
['X', 'b', 'c', 'd']
>>> print L
['a', 'b', 'c', 'd']

To convert a list into a string, you can use the join() method:

>>> word = "apple"
>>> charList = list(word)
>>> print charList
['a', 'p', 'p', 'l', 'e']
>>> rejoined = ''.join(charList)
>>> print rejoined
'apple'

the index() method might be useful. It works on both strings and lists:
```
>>> print L
['a', 'b', 'c', 'd']
>>> L.index('c')
2
```

Submit

Once you are satisfied with your programs, hand them in by typing handin21 at the unix prompt. Don't forget to send us an email when you handin your design!

CS21 Lab 7: Mastermind

Mastermind