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.

Over the next two weeks you will write a program that plays the game Mastermind. For lab 7, 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 as lab 8.

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 here

We will implement a slightly modified version of the Mastermind game:

Mastermind

Mastermind is a code-breaking game for two players. For our version, the computer will be the code maker and the program 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). To simplify the game, our version will not allow a letter to be used in the code more than once. Possible codes are abcd, eafb, cbaf, and so on. The user then has 10 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 correct.
• A partial match means means the letter is correct, but the position is wrong.

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 = "eadb"

Enter guess number 1: abcd
             0 exact matches (letter *and* position correct)
             3 partial matches (letter correct, position incorrect)
Enter guess number 2: efab
             2 exact matches (letter *and* position correct)
             1 partial match (letter correct, position incorrect)
Enter guess number 3: cdef
             0 exact matches (letter *and* position correct)
             2 partial matches (letter correct, position incorrect)
Enter guess number 4: cabe
             1 exact match (letter *and* position correct)
             2 partial matches (letter correct, position incorrect)

In the lab 8 assignment we will give you more details about specific requirements for the mastermind program, but here we list the general requirements for your solution to help you solve the Top-Down-Design part for lab 7.

The main requirements for a working program:

1. The program prints out a welcome message and the game rules for the player
2. The computer generates a secret code to guess
3. The user enters up to 10 guesses, after each guess the program prints out the number of exact and partial matches
4. The program prints out a win or lost message to the player, and if the player loses, it should print out the secret code.
5. Your program needs to ensure that only valid input values are entered by the user (we will explain this more in lab 8)

Also, to help with your Top-Down-Design for lab 7, here is an example run of a completed mastermind program (a lab 8 solution.)

For this lab you will turn in your top-down design (TDD) before fully implementing any of the functions.

You should create a file mastermindTDD.py containing your design and email it to your professor (the email directions are in the Submit section below.) We will then look over your design, make comments on it, and send it back. If we think your design is inadequate we will ask you to fix and resubmit it. Once we have approved your top-down design, you can implement the full program, which will be described in more detail in lab 8.

Here are the top-down design requirements:

• main() should perform the big, high-level steps of the program. That is, main should not concern itself with the small details of the game, but instead call functions each of which implement a high-level step of your program's functionality. These functions, may, in turn, make calls to helper functions that implement sub-steps of each larger steps, and so on.

  Think about a paper outline as you apply Top-Down-Design to determine which functions you will add to your program. Start with the functions that main calls, and once you have stubbed out these initial functions needed by main , continue to refine your design. Do these functions need further helper functions? Keep dividing up the work required into additional functions until all of your functions seem like they may be relatively straightforward to implement.

• All functions should be stubbed out, meaning they are defined with a name and parameters, but not yet implemented. They should, however, include a clear comment, explaining what inputs they receive, what they return, and their purpose. They should also return a temporary value of the correct type so the main function runs. If a function has no return value then it should simply have an empty return.

  Also, add a print "inside function XYZ" statement inside each function, so that when you run the stubbed out program you can "see" its control flow. You will remove these print statements after fully implementing each function.

• The general control flow of your program should be implemented (smaller control flow can be absent). This includes calls to the function stubs you write in the correct order of a complete program. In particular, the main game playing loop should be implemented with calls to its helper function stubs in the appropriate places. The main game playing loop may be in main or in another function you write, but wherever it is, make sure that you have this part of the code sketched out in your TDD solution.
• Your submitted lab 7 solution to TDD should run, however, it should not do anything more than print out a stream of "inside function X" messages; what you submit is a set of function stubs for the functions you will have in your program, with very highlevel flow of control that may have calls to your function stubs that just print out a message and possibly return a bogus return value.
• Your program should have at least 4 functions besides the main function.
• 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. For example, this is NOT a function-worthy function (it adds no more functionality than just calling randrange):

  def getRandomInt(start,stop):
    val = randrange(start,stop)
    return val
  

• Every function should encapsulate some well-defined piece of functionality (i.e. this could be a step or sub-step in your TDD solution). Also, think about good generic design when appropriate (i.e. this may help you determine what values need to be passed into a function (how many parameters and what type), and what value is returned from a function.

Here is an Example TDD stubbed out program that includes the main control flow of the program. Your TDD solution should be similarly structured.

Special Submission for lab 7: once you have your TDD solution, with all functions stubbed out and the main flow implemented with calls to your stubbed out functions, you will send us your solution via email.

Send us your program using email like this:

         $ cd cs21/labs/07
         $ mail newhall < mastermindTDD.py 

Once you email us your design, we will try to get comments back to you within 24-36 hours. However, if everyone emails us their design at the same time, it may take longer. You are encouraged to start your design early, so you have enough time to get our helpful comments and still implement the full program.