America's Most Wanted Problem

( Latest Revision: Sat Oct 10, 2015 )

Lists, Strings, Dictionaries: A Program that Helps Search for America's Most Wanted Criminals

PRELIMINARIES:

Working on this problem will give you practice programming with lists, strings, binary search trees, and C++ classes. You will gain understanding of sorting and searching algorithms too. You must be familiar with the directions and examples here: http://www.cs.csustan.edu/~john/Classes/General_Info/progAsgRules/

THE ASSIGNMENT:

Your assignment is to write a program for a (pretend) police department. The program maintains a database of information on various "shady characters." Each shady character has a set of attributes, such as shifty eyes, a limp, or a parrot on his shoulder. A user of the program can run commands that help narrow down the list of possible suspects in a crime investigation.

INPUT:

The program works with a (plain text) database file which must have this name:

character.txt.

This database file must contain a series of zero or more records. Each record must consist of data about one person - one particular 'shady character'. The record must contain the name of the shady character and a list of attributes associated with the character, together with whatever additional fields you find helpful for making things work. It is your responsibility to design the format you will use for character.txt.

When the program begins execution, it must input the previously-saved character.txt file as one of its very first tasks.

While the program is running, it must maintain a version of the database in primary memory, implemented as as a binary search tree (BST). The keys used for this BST must be the names of the shady characters. Right after the program starts up, when it inputs the character.txt file, it must use the information in the file to create the BST, by starting with an initially empty BST object in primary memory, and successively inserting a series of nodes into that tree. Each node must contain the information from one of the records in the database file.

Note: When character.txt contains zero records, the program must detect this and begin its execution with an empty collection of shady-character information.

After the program gets the data from character.txt it must begin an interaction with the user. The user inputs commands from standard input in the format shown below in the examples. (Standard input is the keyboard, by default.)

All strings used for commands, names, code names, and attributes must be of length no more than 30 characters. (See below for the definitions of these things.)

The program must not be case sensitive with respect to any input strings. For example, all the strings in this set: {JOSEPH, JosEpH, Joseph} must be treated by the program as if they were identical.

To simplify the processing, we assume that everyone in the world has a different name.

PROCESSING AND OUTPUT:

The user of the program can add a new shady character to the program's collection using the ADD command.
The user signals the start of an inquiry with the INQUIRY command.
An inquiry consists of a set of TIP, CHECK, and PRINT commands pertaining to a search for the perpetrator of a single crime.
After starting an inquiry, the user signals the end of the inquiry when s/he gives the program an ADD, QUIT, or a new INQUIRY command. (You must write the program so that it is possible for the user to start an inquiry, change her mind, and end the inquiry immediately before issuing any TIP, CHECK, or PRINT commands.)
Do NOT provide a way for the user to suspend or save an inquiry (so s/he can continue to work on it later).
TIP, CHECK, and PRINT commands may be issued ONLY during an inquiry.

Below is a list of the interactive commands to which the program must be able to respond. The QUIT command may write a new character.txt file. Otherwise these commands do all reading from standard input and all writing to standard output. (By default standard input is the keyboard, and standard output is the terminal screen.)

ADD

This command adds a shady character to the in-memory list of shady characters. In other words, it adds another node to the BST - a node that contains the name and the list of attributes of a new shady character. The program must prompt the user for the shady character's name and attributes.

INQUIRY

The program must prompt the user for the code name of this inquiry. Other actions will probably be necessary, but their nature depends on your choice of implementation. For example, in response to the INQUIRY command, part of what the program may do is to make an in-memory copy of the BST of shady characters. On the other hand, instead of doing that, it may traverse the original in-memory BST, marking each node in some way.

As was said earlier in these directions, after starting an inquiry, the user signals the end of the inquiry when s/he gives the program an ADD, QUIT, or a new INQUIRY command. To make this work may require a bit of slightly tricky coding, so give the problem due attention. We can discuss possible approaches. Questions in class (or outside of class) are always welcome. (Naturally it's nice to be able to help multiple students by answering a question someone asks in class).

TIP

This is one of the commands that is allowed ONLY during an inquiry. The program must prompt the user for the tip information -- a particular attribute. The program then processes the tip. It reduces the set of current suspects by eliminating suspects who do not match the attribute. If, after doing this reduction, there is only one matching suspect, or no matching suspects left, the program prints out an appropriate message. (It either tells the user who the only remaining suspect is, or tells the user that there are no suspects left.) When you program this message, be sure to include the suspect's name (if there is one) and the inquiry's code name. You may decide to implement the TIP command by doing deletions from an in-memory copy of the BST, or you may do it by marking nodes in the original BST as "eliminated."

CHECK

This is one of the commands that is allowed ONLY during an inquiry. The program prompts the user for a shady character's name. It then checks to see if that name matches any of the names of the active suspects (the ones who have not yet been eliminated by a TIP command). The program prints out an appropriate response.

PRINT

This is one of the commands that is allowed ONLY during an inquiry. The program prints the names of all the active suspects (those who have not yet been eliminated).

QUIT

This command causes the program to terminate. However, if any new shady characters were added during the current execution of the program, the program must first write a new version of the character.txt file, so that it now contains the most recent version of the collection of shady characters.

'EXTRA' COMMANDS

Your program must respond to the commands listed above exactly as specified.

If you want to implement additional commands, for example, to help you with your efforts to debug and/or check the operation of your program, you may do that, as long as the additional commands do not cause the assigned commands to behave in ways that are not allowed.

SAMPLE INTERACTION:

In this particular example, the character.txt file is empty at the time the program begins its run. All the shady characters are inserted with ADD commands performed by the user of the program. The inputs made by the user are shown in boldface. The output of the program is shown in plain typeface (not bold).


ADD

OK, we are now adding a character to the database.

Name of Character:     Quickdraw McGraw
Attributes:            has a Texas accent
                       has a body guard
		       is computer literate

ADD

OK, we are now adding a character to the database.

Name of Character:     Twingun Morgan
Attributes:            has a New York accent
                       has red hair
		       smokes cigars

ADD

OK, we are now adding a character to the database.

Name of Character:     Jackda Ripper
Attributes:            has a body guard
                       bites his fingernails
		       carries a knife
                       is computer literate
		       
ADD

OK, we are now adding a character to the database.

Name of Character:     Annie Getcher Gunn
Attributes:            has a New York accent
                       has red hair
		       eats bullets
                       smokes cigars

ADD

OK, we are now adding a character to the database.

Name of Character:     Slowdrawl Raul
Attributes:            has a Texas accent
                       carries a knife
		       is computer literate
                       eats bullets
		       
ADD

OK, we are now adding a character to the database.

Name of Character:     Sloan de Uptake
Attributes:            has a body guard
                       has red hair
		       bites his fingernails
                       is computer literate

INQUIRY

OK, we are now conducting an inquiry.

Enter a Code Name for this Inquiry:    Bang Bang
TIP
Enter Tip Info:                        has a New York accent
CHECK
Enter Name of character:               Quickdraw McGraw
Quickdraw McGraw is not a match.
TIP
Enter Tip Info:                        has red hair
CHECK
Enter Name of character:               Annie Getcher Gunn
Annie Getcher Gunn matches.
TIP
Enter Tip Info:                        eats bullets
ALERT! That leaves only one
suspect in the Bang Bang inquiry:      Annie Getcher Gunn

INQUIRY

OK, we are now conducting an inquiry.

Enter a Code Name for this Inquiry:    Holdup
TIP
Enter Tip Info:                        has a Texas accent
CHECK
Enter Name of character:               Slowdrawl Raul
Slowdrawl Raul matches.
CHECK
Enter Name of character:               Sloan de Uptake
Sloan de Uptake is not a match.
TIP
Enter Tip Info:                        is computer literate
INQUIRY

OK, we are now conducting an inquiry.

Enter a Code Name for this Inquiry:   Tough Stuff
TIP
Enter Tip Info:                       bites his fingernails
PRINT
The remaining matches are:
Ripper, Jackda
Uptake, Sloan de
CHECK
Enter Name of character:              Twingun Morgan
Twingun Morgan is not a match.
TIP
Enter Tip Info:                       has a body guard
CHECK
Enter Name of character:              Slowdrawl Raul
Slowdrawl Raul is not a match.
TIP
Enter Tip Info:                       carries a knife
ALERT! That leaves only one
suspect in the Tough Stuff inquiry:   Jackda Ripper

QUIT
OK, saving database to file "character.txt" ... Done.  Goodbye.

THINGS TO NOTICE ABOUT THE SAMPLE INTERACTION:

During an ADD command, the user signals to the program that s/he has finished entering attributes by depressing the enter key twice after the last attribute.
The user signals the end of an inquiry by entering an ADD command, QUIT command, or a new INQUIRY command. That is the only way to end an inquiry. In particular, an inquiry does not end automatically if the number of possible suspects is narrowed down to 1 or 0.

DATA STRUCTURES:

There is no upper bound to the number of shady characters in the collection or number of attributes a given shady character may have. You cannot use static allocation for lists of shady characters or lists of their attributes.

When it comes to implementing your lists of attributes, you needn't take the word "list" too seriously. Choose a data structure that supports all the operations you need, or augment an existing data structure to give it the additional capabilities you require. Consider that the program has to search for attributes of characters. You may implement a "list" of attributes as an unordered list, as an ordered list, ... even a binary search tree, or some other way.

Be careful of the traversal order you use to write the list of shady characters to your character.txt file. Pre-order may be the best and easiest one to use here. Based on your study of binary search trees, can you say why?

If you prune a copied tree in response to the TIP command, there are "risks". You need to take some extra precautions. If your program will traverse the tree while deleting some nodes, then the deletion of a node could cause the traversal to go "off track" - do you see why? For a job such as this it's wise to use a post-order traversal.

TEST FILES:

You are responsible for deciding what tests to do to check your program for correctness. Do thorough "black box" testing, so as to have a reasonably good chance of catching possible errors. This means that you think of "average" kinds of inputs and "boundary" kinds of inputs, and test both kinds.

Just as an example, and just in the case of the INQUIRY command, thorough black box testing would include a test of an inquiry that ends with all suspects eliminated; an inquiry that ends with just one suspect left; an inquiry that is started but ended before any TIP, PRINT, or CHECK commands are issued; and one or more inquiries where the input is more "average."

A significant portion of your grade will be based on your testing procedures. The sample inputs illustrated in this document are not adequate for thorough testing. You must design other kinds of test inputs. It's probably a good strategy to think about each command individually, and decide what kinds of inputs are needed to test each command adequately. After that, you could design sets of inputs. To keep the total amount of testing from being excessive, you could try to make sets of inputs combine features that test more than one command in the ways you feel are necessary.

You will need to consider how much direct interaction you need to do with your program in order to create an adequate test script. For example, if you redirect standard input to a file of prepared, inputs, the reader of your script will probably not be able to easily follow the interaction between the program and the data. So you must not do that. If you do a run of the program where it reads from a character.txt file that contains data, then make it a SMALL file. Also cat character.txt to the screen before running the program, so that the reader of the script will not have to guess what's in it.

On the other hand, you can probably save some time by preparing files of inputs and by pasting sections of these files into your shell-window while running your program. We can discuss this and other testing "tricks" in class.

As part of the testing for this assignment you also must ask at least one other person to operate your program, get his or her opinion of the interface, and try to use any suggestions the person may give you to improve the interface. (This does not change existing rules regarding who is allowed to look at portions of your code.)

Testing and grading the programs of a group of students is generally a challenging and time-consuming process. Part of my plan is to utilize prepared files of inputs. I may start with an empty file named character.txt, and place commands for standard input in a file (just as an example, suppose the file is named myinput) and that I run your program with a command like this:

myNameForYourProgram < myinput > myoutput

That command uses unix redirection, so that the program will read from the file called myinput instead of the keyboard, and the program will write to the file called myoutput instead of to the screen. To see if your program executed correctly, I can examine the contents of myoutput to see if it differs significantly from the output file that I get when I run my own solution program.

I will probably run your program again, after it has created a character.txt file, to see if it deals correctly with reading data from character.txt when it starts up.

If I have to change my input files or the names of my input files in order to get your program to accept them, I will take away a significant amount of credit. The way I will set up my testing, I expect there should be no problems

if your program uses the correct name for this input file: character.txt,
if it implements the program commands in complete agreement with the specifications given above, and
if, in executing the commands, it does NOT do any extra input or output for which the specifications did not ask.

If you have any questions about testing issues or anything else, feel free to ask me. Consider asking your question during class time, because of the possible benefit to the other students.

WHAT TO TURN IN:

You will be turning in two hardcopy versions of your program and you will be sending me two e-mail messages.

With regard to the e-mail please follow these rules:

Always send me e-mail as plain text in the main message body. Never send me attachments.
Always use the exact subject line I specify for each message. (I often get hundreds of e-mail messages in a week. The subject line allows me to find, filter and sort messages.) You will lose a significant number of points on the assignment if you use the wrong subject line.
Be very careful when typing the command to send e-mail. You may use the instructions in your Hello World! lab excercise for guidance. Of course, you will need to make the obvious changes to those directions -- you have to use the correct subject line and filename.
Always send yourself a copy of each e-mail message you send to me, and check to see if you receive the message intact. You are responsible for sending e-mail correctly.

Here is the list of things you have to turn in:

At the start of class on first due date, turn in hardcopy of a level two version of the source code. Don't include code from the assignment directory (code I gave you) that you are incorporating into your program, but do include the rest of your source code.
Send the following items to me by e-mail before midnight on the first due date:

A level two version of the source code and a script showing your test runs. In the e-mail include all the source files (*.h files and *.cpp files) that are required to compile the program into an executable image -- everything I need so that I can compile and test your program. Combine all the source files and the script into one shell archive file and e-mail me the archive file with the subject line:

CS3100Prog3.2
At the start of class on the second due date, turn in a hardcopy of a final level version of the source code. Don't include code from the assignment directory (code I gave you) that you are incorporating into your program, but do include the rest of your source code.
Send the following items to me by e-mail before midnight on the second due date:

A final version of the source code and a script showing your test runs. In the e-mail include all the source files (*.h files and *.cpp files) that are required to compile the program into an executable image -- everything I need so that I can compile and test your program. Combine all the source files and the script into one shell archive file and e-mail me the archive file with the subject line:

CS3100Prog3.f

Note that there are no spaces in the subject lines given. It is important that you do not insert any spaces. My e-mail address is: john@ishi.csustan.edu.

DUE DATES:

For the due dates, see the class schedule.