CIT 590 Assignment 9: Flash Cards
Spring 2010, David Matuszek

Purposes of this assignment

• To give you more experience with classes and objects
• To give you some experience writing String manipulation
• To give you some experience with file I/O

General idea of the assignment

If you have ever used flash cards, you know that they are an aid to memorization. People often have to learn pairs of things that go together (in psychological jargon, paired associates). Given one of them (the stimulus), the person has to come up with the other (the response). For example:

• What's Dr. Dave's phone number? (stimulus: Dr. Dave; response: 8-8122)
• What's the capital of Pennsylvania? (stimulus: Pennsylvania; response: Harrisburg)
• What's the German word for mountain? (stimulus: mountain; response: der Berg)
• What do you get when you multiply six by nine? (stimulus: 6 * 9; response: 54 (or 42 for HHG fans))

The same flash cards will be used repeatedly, in approximately the same order, until all the cards have been learned. The program considers an item "learned" if the user has gotten it correct some number of times in a row.

As your customer, I want a program to help me memorize lists of things--for example, German vocabulary words. In addition, I want the program to help me construct these lists in the first place.

Details

In this assignment there will be two "main" classes, that is, classes with a public static void main(String[] args) method. One of them, the Study class, will be used to study the flash cards. The other, the CardEditor class, will be used to create and edit the sets of flash cards.

The Study class

When the program is started from the Study class:

1. The program asks for a file containing the "flash cards" to be studied, then selects STUDY_SIZE cards from that file.These cards will be put into a studyList and used repeatedly until the program quits, or the user asks for a new set of cards.
2. The program goes into a loop, as follows:
   1. Select the next card from the studyList, present the stimulus, and wait for the user to type in some response.
   2. If the response is correct,
      1. The program say Right! and marks the item as "correct".
      2. If the item has been marked correct three times in a row (no intervening wrong responses), it is removed from the studyList.
      3. The program goes on to the next pair.
   3. If the response is wrong,
      1. The program marks the item as "incorrect".
      2. The program says No, and tells the user the correct response.
      3. The program reads in the new response from the user; if still incorrect, go to step a.
      4. Once the user has typed the correct response, the program goes on to the next pair.
   4. If there are fewer than MIN_STUDY_SIZE (about 5) items left in studyList, or if the user types QUIT, the program will save the results back to the original file, then it will ask the user if he/she really wants to quit or wants to use a different study list.
   5. When all cards have been presented from the studyList, the studyList is shuffled "slightly" (each card has a 50% chance of being interchanged with its neighbor), and study continues from the beginning of the studyList.

Instead of a response, the user can type QUIT at any time.

Brief partial example:

         Computer:  Michigan
                 User:  Lansing
         Computer:  Right!

         Computer:  Pennsylvania
                 User:  Pittsburg
         Computer:  No, Harrisburg
                 User:  Harisburg
         Computer:  No, Harrisburg
                 User:  Harrisburg
         Computer:  Right!

Behind the scenes (studying)

At the beginning of a study session, , the data is read in from a file. Each item on the file consists of three parts: the stimulus, the response, and the count of how many times in a row the user has gotten the item right (initially zero). Each line will be formatted as:
           stimulus :: response :: count
The studyList will be made up of the first STUDY_SIZE unlearned items that have been read in, where an "unlearned" item is one with a count less than 3. Items beyond that number are not used. If there are not that many acceptable items, but at least MIN_STUDY_SIZE items, the program will use as many as there are,

The program keeps track of how many times in a row that the user has gotten each item right. It considers that a user has learned a pair if she right three times [careful: magic number] in a row. Hence, every pair has an associated number 0 to 3, meaning (approximately) how well the pair has been learned: 0 is not learned at all, 3 is fully learned.

Regardless of how many item pairs there are, a study session should use a maximum of STUDY_SIZE items at a time (20 is about right). The program just cycles through these cards, presenting them to the user one at a time. Each time an item is "learned", it is removed from the studyList.

At the end of the study session, the (updated) data is written out to the file again. No file I/O goes on during the study session.

The CardEditor class

In addition to helping the student study, the program should help the "teacher" build lists of paired items. Here's a list of things the program needs to allow the user to do:

• Create a new list of flash cards.
• Read in an existing list of flash cards.
• Save a list of flash cards.
• Add a new stimulus/response pair, with an inital count of zero.
  • No two items should be allowed to have the same stimulus. For example, you can't have both [German] stimulus "klein :: small" and "klein :: little" , because the user won't know what response to make to klein. If this happens, you have to warn the user and let him/her decide what to do.
    
    It is OK for two different stimuli to have the same response, though.
    
    
• Edit an existing item (because errors do happen and need to be fixed). Again, no two items should be allowed to have the same stimulus.
• Remove an item.
• Search for a given item.
• Suppose the user doesn't know exactly what's on the list (and the list might be hundreds of items long!). Perhaps the user wants to read through the list looking for errors. Provide some way to let the user see what's on the list (more than one item at a time, which would be extremely tedious).

Since I haven't told you exactly how the user is supposed to interact with the editor, you have to tell me. If it's simple enough, the editor can simply print out instructions when it starts out. If it's not that simple, you can supply a readme.txt file with the instructions--but still have the program print out a brief summary.

Program organization:

Item

Each stimulus/response/count item should be an object. Let's call this an Item. Each Item should have a way of editing its stimulus and response parts (getter and setter methods should be good enough for this), and updating its count. As I've sketched the program so far, a correct response adds one to the Item's count, and an incorrect response resets the count to zero--but I might change my mind on this. So, instead of getter and setter methods for the count, provide a method for updating the count when there is a correct response, and another method for updating the count when there is an incorrect response. Also provide a way of checking whether the item has been "learned"

StudyList

This class does no printing or interacting with the user--it just keeps track of data. Data consists of all the Items from the file, and the studyList of those items currently being studied. This class would have (at least) the following methods:

• ArrayList<Item> read() -- Reads in a file of items.
• void save() -- Saves the items into the same file that they were read from.
• void saveAs() -- Saves the items onto some file chosen by the user.
• Item nextItem() -- Returns the next item in the list.
• int getCount() -- Returns the number of items still in the studyList.

Additional methods will be needed by the CardEditor class.

Study

Start from this class in order to study. Contains a public static void main(String[] args) method.

CardEditor

Start from this class in order to create and edit lists of flash cards.Contains a public static void main(String[] args) method.

Grading:

Each member of your team should do one of the two "main" classes (Study and CardEditor). Specify (with the @author tag in the class) who did each class. You should both contribute to the other classes (Item and StudyList). The Study class is less work than the CardEditor class, so the partner who writes the Study class should probably do most of the work in the other classes--but that's up to you and your partner. Your grade will be based 50% on your part and 50% on the whole thing.

This is a team programming assignment. It's not quite a pair programming project, because each of you is responsible for part of the code, and both of you are responsible for part of it. However, the program has to work. Programs that don't work are worth zero points. So in order to get credit for your GUI user interface--not only the layout, but also the work it does--the program as a whole has to work.

Since the StudyList contains some methods that will mostly be used by the Study and others that will mostly be used by the CardEditor, you might want to divide up the work along these lines.

I recommend that you spend the lab period deciding who does what parts, and making a very specific outline of class responsibilities: constructors, method names, and parameters. Work together as much as you can, including helping each other with the main classes.

Testing

Have a clear separation between methods that do computation and methods that do I/O. Write tests for all of the former. Whoever writes the methods should write the tests for those methods.

Due date:

Thursday, April 1, before midnight. Again, please submit one .zip file (or .jar file) per partnership containing all necessary files. There will be a penalty for submitting .rar files when .zip files are required.