CSE 5402 Fall 2025


Lab 1: "The play's the thing"

Points: 100, weighted as 10% of semester grade

Submit: files uploaded to the assignment page for this lab in Canvas

Due: by 11:59pm Friday September 25, 2026


Purpose and Objectives

The purpose of this assignment is to give you experience using functions, references, and different data types, and also to take an early look at basic file I/O in Rust. We will use different abstractions from the Rust language and libraries, and the design, implementation, testing, documentation, and debugging skills you'll develop using them, repeatedly throughout the semester.

In this assignment you will work in a group of 1, 2, or 3 people (but not more) to write, test, and document a Rust program that can:

  1. read the name of a configuration file (and optionally a special text string that causes a static atomic Boolean variable to be set to true instead of false) from the command line;
  2. open that file and from it read (1) the title of the play (or fragment of a play), and (2) the names of the characters speaking the different parts in the play and the names of the files where the lines each character speaks for their part are defined;
  3. read in numbered lines from the individual part files and insert them into a common data structure consisting of tuples; and then
  4. print out a script that is properly ordered by the line numbers (but without printing the line numbers themselves) and shows the alternation of which lines are spoken by whom, for the entire fragment of the play.

It is possible that the program may encounter lines that are badly formed, e.g., with only blank space or with only a single whitespace delimited token when more are expected, or in a part file if the first token does not contain an unsigned integer value. In any such case the program should simply skip that line (though it may print out a warning message saying it did that) and proceed to the next line.

It is also possible that the program may see no well formed numbered lines spoken by some or all of the characters in the play fragment, which also is a reasonable case that the program should be able to handle (e.g., when testing the initial version of your program before you have finished implementing the script generation functions, or in later labs to allow silent characters to enter and leave a scene) as long as it does recognize well formed lines if there are any.

Throughout this assignment, you will work with input files in particular formats, which the program you are writing will use as described above. For example, based on a portion of William Shakespeare's "Hamlet, Prince of Denmark", ACT II, Scene II, "A room in the Castle" the script fragment hamlet_act_ii_scene_2.txt can be represented by the configuration file hamlet_ii_2_config.txt and the corresponding part files Guildenstern.txt, King.txt, Queen.txt, and Rosencrantz.txt.

The program should use its first command line argument (immediately following the program's name) to identify a configuration file formatted like hamlet_ii_2_config.txt, and read one line at a time from it (ignoring any lines that only contain whitespace), storing important information that it will use in the rest of its operation.

If it is run without a configuration file name your program should print out a helpful usage message (before ending gracefully and returning a unique non-zero error code). Otherwise, the program should store the file's first non-blank line in its entirety in a mutable String variable as the name of the play, and should use each non-blank line after that to configure a particular character's part.

If a line in the configuration file or in the file of lines for a part in the play fragment does not have enough tokens (or if one of the tokens is incorrectly formatted), the program should skip that line and continue looking for well formed ones. If the line has extra tokens following the required ones, the program should use the required ones and ignore the extra ones. In either of those cases, the program should check the static atomic Boolean variable and if (and only if) it is true should generate an appropriate warning message.

The first line of the configuration file, which contains the title of the play, can have any number of whitespace delimited tokens. After that each line of the configuration file should have two whitespace delimited tokens, both of which should be stored in String elements of a tuple. The first String is the name of the character, and the second should be used as the name of a valid input text file that contains the character's lines - the program should test whether or not the file exists and can be opened correctly for reading - if not the program should consider the character definition line to be badly formed, and continue to the next line.

If the configuration file cannot be opened or does not contain at least one valid character definition (including the proper opening of that character's input file), the program should generate an error message and return a unique non-zero error code for the kind of failure it experienced.


Compilation and Execution

For full credit on the assignment, the code for your lab solution must compile without warnings or errors with the Rust version 1.71.0 tools that are installed on the Linux Lab machines (and are accessed by adding module rust-2023) this semester, and must run correctly on those machines. You are free to use other platforms and compilers to develop your code, but before submitting your solution you should please make sure it also compiles without warnings or errors and runs correctly on the Linux Lab machines, which is where your solution will be graded.


Assignment

To complete this assignment please implement the following features:

  1. Log in to one of the Linux Lab machines, and in your directory for this course create a new Rust package for this assignment: e.g., cargo new lab1 and in that package's src directory edit your program's main function so that its return type is Result<(), u8> and that by default (unless a problem occurred that the program could not handle) it returns the result of Ok(()) to indicate success. Near the top of that file (above the program's main function) give access to command line iterators and other standard features of the program's environment by adding the line use std::env;

    Modular structure of types, functions, constants, and static variables

  2. In the src directory for your Lab 1 project, create a lab1 directory and in that directory use an editor (e.g., emacs or vi) to create (1) a file named declarations.rs in which you will declare types, constants, and static variables that will be used throughout the program, and (2) another file named script_gen.rs in which you will declare types and constants, and define functions, for generating the play's script.

    In the main.rs file in the src directory for your Lab 1 project, add a declaration of that module, e.g., pub mod lab1;. Add a file named mod.rs to the lab1 directory and in it declare the other two modules that are contained within it, e.g.,

    pub mod declarations;
    pub mod script_gen;

    As you develop your Lab 1 solution (and your subsequent lab solutions), make sure that (1) any types, constants, functions, etc. that are only used within one file are declared within that same file, and (2) any types, constants, functions, static variables, etc. that are used by code in multiple files are declared to be public. Keep in mind the nesting of namespaces that is inherent in how the code directories and files are structured, e.g., you may need to add statements that look like use super::declarations::WHINGE_MODE; to files in the lab1 directory and statements that look like use lab1::declarations::WHINGE_MODE; in your main.rs file.

  3. In your ReadMe.txt file please add a subsection titled "Modules" and in it please summarize how you organized your code in different modules. As you develop your solution to this lab assignment, please add text to that subsection to document any design challenges you encountered because of that (including any you may have run into as you set up that modular structure) and how you addressed those.

    Program-wide declarations of types, constants, and static variables

  4. In your lab1/declarations.rs file declare:

    Processing the command line

  5. In your main program file, but outside the main function, write a usage function that takes a shared (immutable) reference to a String variable that contains the program's name and uses that variable to print out (to the program's standard output) a usage message formatted like:

    usage: ./lab1 <configuration_file_name> [whinge]

  6. In that same file and again outside the main function, write a parse_args function with a return type of Result<(), u8> that takes a mutable reference to a String variable (for the name of the configuration file).

    The parse_args function should declare a mutable vector of String variables to hold the command line argument tokens, obtain an iterator over the command line arguments by calling the env::args() library function, and use a for loop to push each command line argument string into the vector it declared.

    If fewer than 2 or more than 3 command line arguments (including the name of the program) were provided, or if 3 command line arguments were provided but the last one is not equal to the text string "whinge" (Australian or Brittish slang for complaining) the program should pass the program name string (position 0 in the vector) into a call to the usage function and then use Err() to return a non-zero value indicating that bad command line arguments were provided.

    Otherwise, the parse_args function should store the first command line argument (position 1 in the vector) in the passed String variable, and then if "whinge" (without the quotation marks) was provided as the third command line argument it should store the value true into the static atomic Boolean variable with sequentially consistent ordering (Ordering::SeqCst), after which the function should use the result of Ok(()) as its return value, to indicate success.

    Reciting the play's lines

  7. Also in that same file and outside the main function, write a recite function that takes a shared (immutable) reference to a String variable that holds the title of the play, and a shared (immutable) reference to a Play variable, prints out the title of the play to the program's standard output and then and repeatedly prints out the lines in the play by using match to destructure each tuple in the Play variable to obtain descriptively named references to the name of the character speaking a line and the text of the line itself. An example of the kind of syntax you'd use to destructure a tuple using match is shown at the bottom of slide 6 in the Expressions lecture slides; the BOT textbook introduces match expressions and statements on pages 29 and 34 in Chapter 2, and discusses them in greater depth on pages 140-142 in Chapter 6 and pages 241-254 in Chapter 10.

    The recite function should keep track of which character is currently speaking, and whenever a change occurs (including when visiting the first tuple of the first character to speak) it should print out (1) a blank line and (2) a line with the name of the new character (with a period at the end) before printing out the new character's subsequent lines (without re-announcing the character while that same character is still speaking).

    The main function's logic

  8. Your program's main function should declare a mutable String variable for the name of the configuration file, and should pass a mutable reference to that variable into a call to the parse_args function. The main function should check (using e.g., if let or match) the result of that call and if an error was returned should return an error value indicating that bad command line arguments were provided to the program. An example of using if let to capture the result of a function call is shown at the bottom of slide 5 in the Expressions lecture slides; the BOT textbook discusses if let expressions and statements on page 142 in Chapter 6.

    Otherwise, the main function should declare a mutable String variable for the name of the play (or play fragment) and a mutable Play variable to hold the structured lines from the play. It should then pass an immutable reference to the String variable with the configuration file name, and mutable references to the String variable for the play's title and to the Play variable into a call to the script_gen function described below. The main function should check the result of that call and if an error was returned should return an error value indicating that script generation failed.

    Otherwise, the main function should call the sort method on the Play variable, pass immutable references to the String variable for the play's title and to the Play variable into a call to the recite function, and then use the result of Ok(()) as its return value, to indicate success.

    Script generation

  9. Near the top of the script_gen.rs file in the lab1 directory, add the following lines to give access to key I/O features:
          use std::fs::File;
          use std::io::BufReader;
          use std::io::BufRead;
        
    Just below that then declare:

  10. In your script generation code file write an add_script_line function that takes a mutable reference to a Play variable, a shared (immutable) reference to a String that contains an unparsed line from a character's file of lines, and a shared (immutable) reference to a String that contains the name of the charater's part.

    If the length of the passed line string is greater than zero, the function should capture (e.g., using if let Some(())) references to the first token in the line string and to the rest of the line string that result from calling the split_once method with char::is_whitespace on the line string, and then within the if block also call the trim method on the token with the rest of the line to remove any leading and trailing whitespace from it.

    The if block should then call the parse<usize> method on the reference to the first token. If that fails (i.e., if the token does not represent a well formed usize value), it should call the load method with Ordering::SeqCst on the static AtomicBool variable and if (and only if) it obtains true should use the println! macro to print out a warning message showing the token and complaining that it does not represent a valid usize value.

    Otherwise (if a valid usize was obtained from the call to parse<usize>), it should push a tuple consisting of the usize value, the part name string that was passed into the function, and a string with the rest of the line after the first token, into the Play variable.

  11. In your script generation code file write a grab_trimmed_file_lines function with a return type of Result<(), u8> that takes a shared (immutable) reference to a String that contains the name of a file, and a mutable reference to a vector of Strings (for lines from the file). The function should call File::open using the name of the file, and if that fails should print out an appropriate error message and then return an error value indicating that script generation failed.

    Otherwise, the function should declare a mutable BufReader initialized with the resulting file variable (captured, e.g., by the Ok branch of a match on the result of that call), and a mutable String variable to hold lines read from the file. It should then repeatedly: call the clear method on the String variable and then call the read_line method with the String variable on the BufReader. If that call fails the function should print out an appropriate error message and return an error value indicating that script generation failed. Otherwise it should check the call's return value (captured e.g., by the Ok branch of a match on the result of the call): if it is 0 the function should return Ok(()) to indicate success, or otherwise it should call the trim method on the string read from the file and push the result into the vector of lines and repeat the loop.

  12. In your script generation code file write a process_config function with a return type of Result<(), u8> that takes a mutable reference to a Play variable, and a shared (immutable) reference to a PlayConfig variable. The function should iterate through the tuples in the PlayConfig variable, using match to destructure them into appropriately named references to the name of the part and the name of the file containing the lines that will be spoken by that part in the play. The function should declare a vector of strings in which to store lines read from the part file and call grab_trimmed_file_lines with the part file name. If that call fails, the function should return an error value indicating that script generation failed. Otherwise, the function should add those lines to the play by iterating through the vector of lines that were read and at each line calling add_script_line with the reference to the Play and a reference to the line.

  13. In your script generation code file write an add_config function that takes a shared (immutable) reference to a String for a line from a configuration file, and a mutable reference to a PlayConfig variable. The function should declare a vector of shared references to text strings (of type Vec<&str>) that is initialized by calling the collect method on the result of calling the split_whitespace method on the reference to the string that was passed into the function (after which the vector will contain references to all the whitespace delimited tokens that were in the string).

    If fewer or more than two tokens were obtained, then if calling the load method with Ordering::SeqCst on the static AtomicBool variable returns true, the function should print out an appropriate warning message to complain about that. If at least two tokens were obtained the function should then push a tuple consisting of strings for the part name and the part file name (at positions 0 and 1 respectively, in the vector) into the PlayConfig variable.

  14. In your script generation code file write a read_config function with a return type of Result<(), u8> that takes a shared (immutable) reference to a String for the name of a configuration file, a mutable reference to a String for the title of the play, and a mutable reference to a PlayConfig variable.

    The function should declare a vector of strings in which to store lines read from the part file and call grab_trimmed_file_lines with the part file name. If that call fails, or if fewer than two lines were obtained, the function should return an error value indicating that script generation failed. Otherwise, the function should store the first line into the string for the title of the play and then add the remaining lines to the play configuration data structure by iterating through the vector of lines that were read and at each line calling add_config with a reference to the line and the reference to the PlayConfig.

  15. In your script generation code file write a script_gen function with a return type of Result<(), u8> that takes an immutable reference to the String variable with the configuration file name, and mutable references to the String variable for the play's title and to the Play variable.

    The function should declare a mutable PlayConfig variable and then call the read_config function, passing in the references to the strings for the configuration file name and the play title and a mutable reference to the PlayConfig variable. If that call fails, the function should return an error code indicating that script generation failed.

    Otherwise, the function should call the process_config function, passing in the reference to the Play variable and a shared (immutable) reference to the PlayConfig variable. If that call fails, the function should return an error code indicating that script generation failed, and otherwise the function should return Ok(()) to indicate success.

    Testing

  16. To test your program, you should please run it at least several times with different combinations of configuration and part files, to confirm the output it generates is correct. You are encouraged to generate your own configuration file and part files for other plays, and to fuzz some or all of them by adding extra tokens, badly formed lines, badly formed tokens, extra whitespace, blank lines, etc. to test your program across a wide range of possible inputs.


What to Submit

ReadMe.txt

As you work on your program, please write down the design decisions you faced, and describe both the solutions you chose to address them and the rationale for the choices you made, in a ReadMe.txt file.

The first section of your ReadMe.txt file should include:

  1. the number of the lab (e.g., "CSE 5402 Fall 2025 Lab 1")
  2. the names and e-mail addresses of all team members
  3. a brief discussions of how your program was designed (including a subsection titled "Summary" that gives an overview of your solution approach and a subsection titled "Modules" that describes the organization of your code into different modules), and
  4. insights, observations and questions you encountered while completing the assignment.

The second section of your ReadMe.txt file should provide detailed instructions for how to:

  1. unzip or otherwise unpack your files,
  2. build your program(s), and
  3. run your program(s) on the CEC Linux Lab machines where your lab solutions will be evaluated.
Important:Your programs must be able to be unpacked, built, and run using only the instructions in your ReadMe.txt file and the 1.71.0 versions of rustc and cargo and other tools already present on the CEC Linux Lab machines.

The third section of your ReadMe.txt file should provide a reasonably detailed description of how you tested your solution, including the kinds of configuration and character part files you used and their formats (including well formed and badly formed content to test how your program handled those variations), and any other scenarios that you tested that you consider important.

Electronic Submission

Please submit your solution by uploading (on the assignment page for this lab in Canvas):
  1. your source code files,
  2. any example files you think useful (for example, the different configuration and character part files you used to test your solution),
  3. output from at least one significant test of your programs, and
  4. your ReadMe.txt file.


Grading

Please treat this assignment as you would a commercial or research product that you are shipping to a large group of customers. Please take the time to test, document, and check your work to make sure all parts are shipped, are of high quality, and behave resonably under a range of different operating conditions. Grading will focus both on the quality of your solution and on the quality of the product itself, as submitted. To ensure the best possible result (and accordingly the highest possible grade), please pay attention to the following issues:

Correct Compilation and Operation

Your program must compile and run correctly on the CEC Linux Lab machines using the source files you provide. Please make sure to fix all compilation errors and warnings before submitting your lab solution. Missing files will be handled with a 5 point deduction (possibly per file) if you need to supply a new file in order for your solution to build successfully.

Design Quality

Design decisions are largely yours to make, and as long as the design is concise, coherent, consistent, and addresses all design forces in the assignment, you will receive full credit. One key area to consider is whether each abstraction in your design does a single job, does that job completely, and collaborates appropriately with other abstractions. Minor deductions (1-3 points, but please be aware minor deductions can add up) will be made for abstractions that are unnecessarily large or have inappropriate inter-dependencies. Major deductions (5-15 points) will be made for larger problems like neglecting key requirements of the assignment, code that does not compile or that has a run-time error when it runs, etc.

Implementation Quality

We will take into account different approaches to implementation. Minor deductions will be made for things your program may get away with but are not good, like neglecting to check the return value from a function call. Major deductions will be made for problems that produce incorrect or extremely inefficient behavior of the program. The former kinds of errors should be eliminated during your coding and code review phases, and the latter kinds of errors should be eliminated during your testing phase, which should include running different combinations of configuration and character part files containing well formed and/or badly formed contents.

Coding Style

Please code clearly with both the reader of the code and the user of the program in mind. Please use consistent indentation and placement of braces, and comment your code thoroughly. Use whitespace liberally - it's free and it makes it a lot easier to read your code. When grading, tagged comments may be added to the code indicating areas where particular issues to mention were found, whether or not points are deducted. Except in extreme cases, only minor deductions will be made for each style issue (though again, those may add up).

Documentation

Please make sure you provide adequate instructions on how to build and run your program. Also, please make sure to document your solution. Minor or even major deductions will be made for inadequate explanation of how your solution does what it does, why you made key design choices, or how the user (or grader) can successfully build and run your program. Even if how you did something is obvious to you, please assume it is not obvious to the reader.

Missing Files

Missing files in the delivered software make it difficult or impossible to evaluate your solution. An automatic deduction of up to 5 points may be applied for each missing or corrupted file that is submitted later on request.

Late Submission

Labs recieved within 24 hours after the deadline will be graded with an automatic 10 point deduction. Labs received more than 24 hours after but within 48 hours of the deadline will be graded with an automatic 20 point deduction. Labs received more than 48 hours past the deadline may not be graded, except under extenuating circumstances. If you are running late completing the assignment, please let me know about the trouble as soon as you can (and it may be possible to give you a brief extension if you request it in advance of the deadline), and please turn in as much as you can before each deadline so at least some credit can be given for the work you have done.

Grading Issues to watch out for

As you develop your lab solution, please follow the programming guidelines for this course, and especially please avoid the following practices, which may result in deductions: