CSE 332 Lab 1: Letters, Tiles, and Dictionaries

Lab dates: Wednesday September 2 and Wednesday September 9, 2009
Due by Tuesday September 15 at 11:59 pm
(deadline for e-mailing a zip file with your solution)
Final grade percentage: 5 percent

Objective:

• C++ header files and source files,
• C++ STL input and output streams,
• C++ functions,
• C++ precompiler directives,
• basic C++ data types (including C style and C++ style strings), and
• basic uses of structs

To do this, you will implement a simple C++ program that can (1) read in and parse command line arguments, (2) open a dictionary file and read in strings from it, and (3) open another file and parse it for the definitions of a set of "letter tiles" (like in the game Scrabble). Your program will print out what was read from each of the files so you can check easily that it worked correctly.

In subsequent lab assignments you will use these features to generate permutations of letter tiles, check each permutation against a dictionary, and generate a score for each matching permutation.

Assignment:

Part I - Readings:

1. The following readings in the optional text books may be useful as reference material while working on this lab assignment, and though we'll touch on most of the issues in the next few studio sessions, selectively looking up topics and/or reading ahead (on demand as you encounter issues while working on the lab) is encouraged:
   • C++ data representation, storage, and movement: Prata pp. 65-143, 424-437, 858-872, 951-1032, 878-889, 910-913; Deitel pp. 334-358, 379-384, 620-624, 777-808, 1080-1083
   • C++ execution control: Prata pp. 177-278; Deitel pp. 134-223
   • C++ functions: Prata pp. 279-340, 362-365; Deitel pp. 245-316

2. The output stream, C++ string class, and input and output stringstream examples in the C++ Data and I/O lecture slides also may be helpful when implementing parts this lab.

3. Please read the following CSE 332 Programming Guidelines which are relevant to this lab, and please follow them as you implement your solution: A.1-A.6, A.9-A.11, A.17, B.7, B.9, B.13, B.15, B.16, B.20-B.23, B.25, B.30, B.33, B.34, C.1-C.4 and C.6-C.9.

   Part II - Program Design and Implementation:

4. Open up Visual Studio, and create a new Win32 Console Application Visual C++ project for lab 1.

5. In the header file and a source files that were created in your project (and if you'd like to add additional header and source files feel free to do so), you will declare and define (respectively) the functions, structs, and other features of your program as you implement this assignment. As you develop your code, please use good modularity: for example, if a function's logic has several separable parts (or is long enough to fill the editor's window) you may want to break it up into other smaller functions.

   Note:the details of this assignment are intentionally somewhat under-specified, leaving you some room to choose what you think is the best way to implement them, as long as what you do is reasonable and you explain your design decisions in comments in the code and in your Readme.txt file.

6. Declare and define a helpful "usage message" function that (1) prints out (to the program's standard output stream) the program's name followed by a helpful usage message telling the user how to run the program correctly with a "-D" or "-d" followed by the name of a dictionary file (for example dictionary_example.txt) and a "-T" or "-t" followed by the name of a tile definition file (for example tile_defs.txt), and (2) returns a non-zero value.

   Hint: it's a lot easier to construct C++ style strings from C style strings and then do comparisons, concatenation, etc. using their operators and methods, rather than trying to do that with the original C style strings.

7. Declare and define a struct to represent a "letter tile" that has a character (type char) for the letter itself, and an unsigned integer (type unsigned int) for a score to be associated with that letter.
8. Declare and define a function for reading in a dictionary file (for example dictionary_example.txt), that takes a reference to a vector of C++-style strings (of type vector<string> &) and a C-style string (of type char *); This function should open a file stream using the C-style string given in the second function parameter as the name of the file to open, read one string at a time from that file, and push back each string into the vector as it's read. If the file cannot be opened or the function encounters any other problems during its execution it should print out a helpful error message indicating the problem and return a non-zero value; otherwise it should return 0 to indicate success.

   Note: in keeping with the spirit of giving you freedom to innovate in designing your programs, for this function and the next one you could pass a reference to a C++-style string (of type string &) instead of passing a C-style string as the second parameter to the function. If you do that, however, please note that C++ file streams expect a C-style string for a file name, which you can get by calling the C++-style string's c_str method.

9. Declare and define a function for reading in letter tile definitions, that takes a reference to a vector of letter tiles (for example of type vector<LetterTile> & if you named your struct type LetterTile) and a C-style string (of type char *); This function should open a file stream using the C-style string given in the second function parameter as the name of the file to open (for example tile_defs.txt), and read one line at a time from that file (Hint: the C++ getline function can help with this, as can using C++ STL string streams to read values out of strings). From each line of the file, the function should (1) read in a character and then a score for that character, and then a quantity indicating how many letter tiles to create with that character and score; and (2) push back a letter tile with that character score into the vector, as many times as the quantity indicates. If the file cannot be opened or the function encounters any other problems during its execution it should print out a helpful error message indicating the problem and return a non-zero value; otherwise it should return 0 to indicate success.
10. For your project's main function:

    • Modify the signature of your main function so that it matches the one shown in the second example given in the C++ program structure and development environment lecture slides (the one that uses the variable names argc and argv).

    • Check that exactly four arguments have been passed to the program (in addition to the program's name), and that the first argument passed is either "-D" or "-d" and the third argument passed is either "T" or "-t": if not, your program should return the result of calling the usage function described above (optional: feel free to extend your program to accept the "-t" or "-T" as the first argument and the "-d" or "-D" as the third argument, though that's not required).

    • Declare a vector of C++ style strings, and pass that vector and the program argument that follows the argument containing "-d" (or "-D") to the function that reads the dictionary file. If that function returns a non-zero value the program should return that value, and otherwise it should continue.

    • Iterate through the vector of C++ style strings, and print out each string in it on a separate line, to the standard output stream.

    • Declare a vector of letter tiles, and pass that vector and the program argument that follows the argument containing "-t" (or "-T") to the function that reads the letter tile definitions file. If that function returns a non-zero value the program should return that value, and otherwise it should continue.

    • Iterate through the vector of letter tiles, on a separate line for each tile print out that tile's character and then score (with a space between them), to the standard output stream.

    • Upon completion, if no other errors have occurred, the program should return 0 to indicate success.
11. Build your project, and fix any errors or warnings that occur. Please be sure to note all of the different kinds of errors or warnings you ran into (though you don't have to list every instance of each kind) in your ReadMe.txt file. If you were fortunate enough not to run into any errors or warnings, please note that instead, where you would have listed errors or warnings in your ReadMe.txt file.

12. Open up a Windows console (terminal) window and change to the directory where your program's executable file was created by Visual Studio (see the first studio exercises document for more details on this, if you don't remember them).

13. Run the executable program through a series of trials that test it with good coverage of cases involving both well formed and badly formed inputs. For this lab one especially useful test is to check whether the output printed by your program consistently represents the contents of valid dictionary and tile definition files it was given. In your ReadMe.txt file please document which cases you ran (i.e., what the command lines were) and summarize what your program did and whether that is correct behavior, in each case.

14. In your ReadMe.txt file, make sure that your name and the lab number (lab 1) are at the top of the file, and that you've documented whether you ran into any errors or warnings while developing your solution (and if so what they were) and what the executable program did for each of the trials you ran. Be sure to save your changes to your ReadMe.txt file, as well as those to your source (and header) file(s) before preparing your solution zip file.

15. Prepare a zip file that contains your project's source, header, and ReadMe.txt files (except for stdafx.h, stdafx.cpp or other Windows-generated files you did not modify), by:
    • Creating a new lab1 folder on your Windows desktop;
    • Copying the appropriate files (here, ReadMe.txt, and the source and header files where you wrote your code) from Visual Studio into that folder; and then
    • Right-clicking on the folder and selecting the Send To->Compressed (zipped) Folder item in the menu that appears.

    Send the zip file containing your lab 1 solution as an e-mail attachment to the course e-mail account (cse332@cec.wustl.edu) by the submission deadline for this assignment. If you need to make changes to your lab solution you are welcome to send a new zip file, and we will grade the latest one received prior to the deadline (according to the time stamp the server puts on the e-mail).

    Part III - Linux Programming Environment: (optional, worth up to 5% extra credit)

    The goal of this optional part of the assignment is to practice using the Linux environment to compile and run your program on grid.cec.wustl.edu or the Lopata 400 Linux lab machines. For extra credit, please add a section marked "Extra Credit" at the end of the ReadMe.txt file you submit with your solution, and copy the results of compiling and running your code on Linux (as described below) from the secure shell window into that section.

    Please ask for help from your professor or teaching assistants if you are uncertain about how to do this extra credit part or if you run into any difficulty with it:

    • Click on your computer's Start->Internet->SSH Secure Shell->Secure Shell Client menu item to open up a secure shell protocol (SSH) terminal window. Click on the Quick Connect tool bar item near the top of that window. In the dialog box that appears, type grid.cec.wustl.edu for the Host Name, enter your CEC login id (without @cec.wustl.edu) and press the Connect button. Type in your password and click OK, in the window that appears. You should then see a Linux command prompt (a string of characters including possibly some combination of your id, the machine's name, and the current directory). Copy and past that command prompt string into your ReadMe.txt file as the answer for this exercise.

    • Use the mkdir command to create a cse332 directory where you will store your programs during the course, i.e.,
      
      mkdir cse332

      Change to that directory, create a lab1 subdirectory in it, and change to that subdirectory:
      
      cd cse332
mkdir lab1
cd lab1
      

      Note that you can also issue multiple commands in sequence by placing semicolons between them:
      
      mkdir cse332 ; mkdir cse332/lab1 ; cd cse332/lab1

    • Click on your computer's Start->Internet->SSH Secure Shell->Secure File Transfer Client menu item to open up a secure file transfer window, and log in as you did in the secure shell window described above. It should bring up a listing of your main account directory, with the cse332 directory underneath. Open up the cse332 directory and then the lab1 directory inside of it by double clicking on them.

    • On your Windows machine, open up the folder where Visual Studio put your source and header files for the project (except for stdafx.h and stdafx.cpp), and drag and drop them into the lab1 directory in your secure file transfer window. Also download the following Makefile to your desktop, and drag and drop it into the lab1 directory window of the secure file transfer client as well.

      Back in the secure shell client, use the mv command change the name of the file you just added from Makefile.txt to just Makefile (Windows "helpfully" adds the .txt extension even though the name Makefile is what the make command you'll use expects the file's name to be).

    • In the secure shell client, use an editor to open up the files you have just transfered into the Linux lab1 directory, and update them as follows:
      • In the Makefile, fill in what you want the name of the executable program file to be, at the end of the line where it says EXECUTABLE =
      • In the Makefile, add the names of your source file(s), separated by spaces if more than one of them, to the end of the line where it says CMPL_SRCS =
      • In the Makefile, add the names of your header file(s), separated by spaces if more than one of them, to the end of the line where it says HEADER_FILES =
      • Wherever you have included the stdafx.h file (or for that matter any other windows-specific) in your source and/or header files, comment out that line (but only on the Linux platform - uncomment those lines on Windows).
    • After saving the changes to your Makefile, exit the editor and run the make command to build your program. Please document any errors or warnings you encountered on Linux, or if there were none please indicate that instead, in the extra credit section of your ReadMe.txt file. Fix any errors or warnings you see on Linux, and please ask for help from your Professor or TAs if you have any difficulty with this.

    • Once your program compiles with no errors or warnings, run the same trials you ran in the Windows environment, on Linux.

      Hint:Many terminal window shells in the Linux environment require you to put a leading ./ (saying to find the program in the current directory) before the name of the executable program when you run it, as in:
      
      ./lab1.exe -d dictionary.txt -t tiledefs.txt
      
      Copy the results of those trials into your ReadMe.txt file, in the extra credit section.