CSE 5402 Fall 2025


Lab 2: "They have their exits and their entrances"

Points: 100, weighted as 15% of semester grade

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

Due: by 11:59pm Friday October 23, 2026


Purpose and Objectives

The purpose of this assignment is to give you experience using modules and stucts to collect and organize different data types and the functions and operations that use or manipilate them. We will use those additional 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 extend your Lab 1 solution with additional features including coordinating the entrances, exits, and speaking parts across consecutive fragments of scenes in a play. It is again possible that the program may encounter lines that are badly formed, and if so the program should simply skip that line in many cases (though it may print out a warning message saying it did that) and proceed to subsequent steps.

Throughout this assignment, you will again work with input files in particular formats, which the program you are writing will use as described below. You will refactor your code from the previous lab assignment so that it can work with input files whose contents are expanded compared to those from the previous lab assignment, to perform a portion of a play that spans multiple scene fragments and manages the entrances and exits of the characters in those fragments as well as the lines that they speak.

For example, the first part of Act II from William Shakespeare's "Hamlet, Prince of Denmark" (text obtained from the Literature Page web site at http://www.literaturepage.com/read/shakespeare_hamlet.html), can be represented within a script file (e.g., partial_hamlet_act_ii_script.txt) that contains an ordered sequence of [scene] directives, each of which is followed by the name(s) of one or more configuration files (e.g., hamlet_ii_1a_config.txt, hamlet_ii_1b_config.txt, and hamlet_ii_2a_config.txt) for scene fragments that in the play are delimited by character entrances and/or exits (e.g., hamlet_act_ii_scene_1a.txt, hamlet_act_ii_scene_1b.txt, and hamlet_act_ii_scene_2a.txt).

We'll implement a simple version of character entrances and exits in this lab in which the entrance of any character that was not in the previous scene fragment (e.g., all of the characters in the first scene fragment given in a script file) is announced before any lines are spoken; similarly, after the last line is spoken in a scene fragment the exit of any character that is not in the subsequent scene fragment (e.g., all of the characters in the last scene fragment given in a script file) is announced: such entrances and exits across two script fragments are illustrated in hamlet_act_ii_scene_1.txt. We will then extend this feature further in lab 3.

As in the previous lab assignment, each scene fragment's configuration file gives the name of each character in the scene fragment along with their corresponding part file (e.g., Polonius_hamlet_ii_1a.txt and Reynaldo_hamlet_ii_1a.txt in hamlet_ii_1a_config.txt, Polonius_hamlet_ii_1b.txt and Ophelia_hamlet_ii_1b.txt in hamlet_ii_1b_config.txt, and King_hamlet_ii_2a.txt and Queen_hamlet_ii_2a.txt and Rosencrantz_hamlet_ii_2a.txt and Guildenstern_hamlet_ii_2a.txt in hamlet_ii_2a_config.txt).

Note that for this lab the titles of the scenes have moved from the individual configuration files into the script file's [scene] directives.


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 lab2 and in that package's src directory copy over the directories and .rs files from your Lab 1 solution. Make sure that you rename the lab1 directory to be lab2 instead, and as needed update statements in your .rs files so that they say lab2 (e.g., use lab2::declarations::WHINGE_MODE;) instead of lab1.

    Modify all places in the code that only call println! in whinge mode, so that they instead use eprintln! to print those complaint messages out the the standard error stream rather than the standard output stream.

    Then add any necessary use statements to your files so that your code compiles and runs as it did in your original Lab 1 solution when using the input files from that lab assignment, except that now whingeing is directed to standard error rather than standard output.

    Structs and their implementations

  2. In the mod.rs file in the lab2 directory declare two more modules, one for a Play struct and its implementation, and one for a Player struct and its implementation, i.e.,
    pub mod play;
    pub mod player;
    and in that same lab2 directory create play.rs and player.rs files for those modules, respectively.

  3. Remove the Play type declaration from the declarations.rs file, and at the top of the player.rs file declare a new type named PlayLines that is a vector of tuples of usize (for the line number) and String (for the text of the line itself). Below that in the player.rs file declare a Player struct and declare an implementation block for that struct. The struct should have a String field for the name of the character being played, a PlayLines field for that character's lines, and a field of type usize for an index for the current entry in the player's PlayLines container.

    Within the implementation block declare an associated public new function that takes a reference to a String and returns a Player initialized with the passed String for the name of the character, an empty PlayLines container, and an index value of 0.

    Move the add_script_line function out of the script_gen.rs file and into the implementation block for the Player struct, and make it a private method of that struct by changing its signature so that it takes in a reference to itself and a single reference to a String for a line from a part file that contains the line number and text (but does not take in a reference to a string for the character name). The logic of the function should remain the same except that the tuple it generates (1) should be pushed into that Player struct's PlayLines container, and (2) should consist only of a number and a reference to a String for the text of the line (but not the character name, which is now already stored in a field of the Player struct).

    Add an associated public prepare method to the implementation block for the Player struct, which takes a mutable reference to itself and a reference to a String with the name of a part file, and returns a Result<(), u8>. Move the portion of the process_config function from your previous lab's solution that reads and processes part files into this prepare method, and refactor it to use the Player struct's add_script_line method, and return a Result indicating success or failure appropriately. To tolerate out-of-order lines in the part file, once all line tuples have been added to the player's container, the prepare method should call the container's sort method to order its entries in ascending line number order.

    Add an associated public speak method to the implementation block for the Player struct, which takes a mutable reference to itself and a mutable reference to a string with the name of the player who spoke most recently. The method should check whether the Player struct's index is less than the number of elements in its PlayLines container: if it is not the method should simply return. Otherwise, the the method should check whether the name that was passed in is the same as its name and if not should assign its name to the passed variable and print out a blank line and then a line with its name; in either case the method should then print out another line with the text at its current index, and increase its index by one.

    Add an associated public next_line method to the implementation block for the Player struct, which takes an immutable reference to itself and returns an Option<usize>. The method should check whether the Player struct's index is less than the number of elements in its PlayLines container: if it is, the method should return Some() with the line number at the current index; if it is not, the method should return None.

  4. Move the PlayConfig type declaration from the script_gen.rs file to the top of the play.rs file. Below that in the play.rs file declare a Play struct and below that declare an implementation block for that struct.  The struct should have a String field for the title of the scene fragment being presented, and a vector of Player structs for the characters speaking in it.

    Add an associated new function to the implementation block for the Play struct that takes no parameters and returns a Play with an empty title field and an empty vector of Player structs.

    Move the remainder of the process_config function that wasn't moved into the implementation of the Player struct, out of the script_gen.rs file and into the implementation block for the Play struct. Modify its signature so that it is a method for the Play struct. For each of the PlayConfig tuples, the process_config method should create a new instance of the Player struct using the tuple's character name field, push the new Player into the Play struct's vector, and pass the tuple's part file name into a call to the new Player struct's prepare method - if the call to the prepare method fails, the process_config method should return an appropriate error.

    Move the add_config and read_config functions out of the script_gen.rs file and into the implementation block for the Play struct.

    Move the script_gen function out of the script_gen.rs file and into the implementation block for the Play struct. Change its name to prepare and modify its signature so that it is a method of the Play struct with a mutable reference to self as its first argument, and an immutable reference to a String with the name of a configuration file as its second argument.

    Move the recite function out of the main program file and into the implementation block for the Play struct. Modify the recite function's signature so that it is a method of the Play struct that takes no parameters (besides a reference to itself). The recite method should iterate through all of the Player structs in the Play struct, keeping track of the next line number to be spoken, and using the Player structs' next_line and speak methods to deliver all of the lines in order.

    The recite method should handle duplicate or missing line numbers by delivering each of the duplicate numbered lines consecutively, and skipping over any missing numbers, but if whinge mode is turned on should complain (to the standard error stream) about each such case. The program should assume 0 to be the starting line number and if whinge mode is on and the first line starts at 1 (as it does in the provided example files) or higher it should complain about the missing line 0.

  5. Modify the main function's implementation so that after a successful call to the parse_args function, it creates a new Play struct and passes the configuration file name into a call to the play's prepare method - if that call fails the main function should return an error indicating that script generation failed, or if that call succeeds should call the play's recite method.

    Move any constants or other declarations that a single module depends on, out of the script_gen.rs file and into that module. Move any constants or other declarations that multiple modules depend on, out of the script_gen.rs file and into the declarations.rs file. Again add any necessary use statements to your files so that your code compiles and runs as it did in your original Lab 1 solution when using the input files from that lab assignment, except that now whingeing is directed to standard error rather than standard output.

  6. In your ReadMe.txt file please add a subsection titled "Structs" and in it please summarize how you refactored your code into structs and their implementations, and any design challenges you encountered and how you addressed those.

    Adding a return wrapper for the result of the main function

  7. In the lab2 directory create a return_wrapper.rs file and in it declare a ReturnWrapper struct with a single field of type u8. In that same file declare an impl block for the Termination trait for the ReturnWrapper struct. Within that block define a method with signature fn report(self) -> ExitCode that checks whether the struct's field's value is non-zero and if so uses the eprintln! macro to print an error message formatted like Error: 3 using the value of the struct's field. The method should then call ExitCode::from with the struct's field to produce its return value.

    Add the line pub mod return_wrapper; to the mod.rs file.

    Change the main function's return type to ReturnWrapper, and inside that function wrap each Result expression (i.e., Ok() or Err()) that is returned by the main function with a call to ReturnWrapper::new.

    Again add any necessary use statements to your files so that your code again compiles and runs as it did in your original Lab 1 solution when using the input files from that lab assignment, and test different use cases to generate different return values from the program and use echo $? to confirm that each distinct return value is passed from the program to the terminal shell environment.

  8. In your ReadMe.txt file please add a subsection titled "Return Wrapper" and in it please summarize how you implemented and used the return wrapper, including any design challenges you encountered and how you addressed those.

    Handling a script file and announcing entrances and exits

  9. To make a vector of Player structs sortable, in the player.rs file implement the PartialEq, Eq, PartialOrd, and Ord traits for the Player struct. Two players are equal if neither of them has any lines to speak (both are silent characters) or if they both have lines to speak and have the same first line number (as indicated by the line number value in the tuple at the 0th position in their vector of lines to speak). A player is strictly less than another player (and the other player is thus strictly greater) if (1) they have no lines to speak and the other player does, or (2) both have lines to speak and they have a lower first line number than the other player.

  10. In the lab2 directory copy the play.rs file to a file named scene_fragment.rs, and update mod.rs accordingly. In the scene_fragment.rs file change all occurrences of the Play type to be SceneFragment instead.

    modify the associated new function so that it takes a reference to a String and uses that reference to initialize the SceneFragment struct's title field. Also modify the appropriate place in the SceneFragment struct's associated recite method that prints out the struct's title string, so that it only prints it if it is non-blank (has at least one non-whitespace token).

    Modify the SceneFragment struct's prepare method so that after all the Player structs have been added to its vector, it call's the vector's sort method to order them in the order in which they deliver their first lines in it (based on the trait implementations you added for the Player struct earlier).

    Add an enter method to the SceneFragment struct's implementation block, that takes a reference to itself and a reference to another SceneFragment struct. The method should print out messages listing the entrances of all players that were not in the other (previous) scene fragment, in the order in which they first speak in the current scene (i.e., in the order in which they are sorted in the SceneFragment), formatted like

    [Enter Polonius.]
    [Enter Reynaldo.]

    Add an enter_all method to the SceneFragment struct's implementation block, that takes a reference to itself and prints out messages listing the entrances of all players in the scene (again in order).

    Move the code that prints out the struct's title if (and only if) it is non-blank (has at least one non-whitespace token) out of the recite method, and duplicate it in the enter and enter_all methods so that the title (if there is one) is printed out before the player entrances.

    Add an exit method to the SceneFragment struct's implementation block, that takes a reference to itself and a reference to another SceneFragment struct. The method should print out messages listing the exits of all players that will not be in the other (subsequent) scene fragment, in the reverse of the order in which they first speak in the current scene (i.e., opposite the order in which they are sorted in the SceneFragment), formatted like

    [Exit Guildenstern.]
    [Exit Rosencrantz.]

    Add an exit_all method to the SceneFragment struct's implementation block, that takes a reference to itself and prints out messages listing the exits of all players in the scene (again in reverse order).

  11. At the top of the play.rs file remove the Players and PlayConfig type declarations and replace them with a declaration of ScriptConfig type that is a vector of (bool, String) tuples, and a Fragments type that is a vector of SceneFragment structs.

    Replace the fields of the Play struct with a single field of type Fragments, and modify the associated new function so that it initializes the struct with an empty Fragments field. Throughout the Play struct's implementation block, replace all uses of the previous Players field to use the Fragments field instead, and replace all uses of the PlayConfig type with the ScriptConfig type instead.

    Modify the implementation of the Play struct's associated process_config method so that it maintains a title string with which to initialize each new SceneFragment it creates. The method should destructure each tuple in the ScriptConfig argument that was passed to it, into a boolean variable indicating whether the text field represents the title of a new scene (true) or the name of a configuration file (false). If the text is a new title the method should use it to update its title string; otherwise it should (1) use the title string to push a new SceneFragment into the Play struct's vector of fragments, (2) set the title string to be an empty string (so a new title is only announced by the first fragment of the scene), (3) pass the text from the current configuration tuple into a call to the new fragment's prepare method, and (4) match on the result of that call. If that call failed, the process_config method should return an error indicating that script generation failed - otherwise if the call succeeded the process_config method should continue to the next tuple.

    Modify the implementation of the Play struct's associated add_config function so that it ignores blank lines. If the first token is exactly [scene] and there are no other tokens then it should also skip the line, but if whinge mode is on it should complain about the missing scene title. If the first token is exactly [scene] and there are additional tokens in the line, they should be concatenated with spaces between them into a string that is used to push a tuple with (1) true (to indicate a new scene) and (2) that string, into the ScriptConfig argument that was passed into the function. If the first token is anything else it should be treated as the name of a configuration file and used to push a tuple with (1) false (to indicate a new scene is not starting) and (2) that token, into the ScriptConfig argument that was passed into the function - if there are additional tokens after the configuration file name token, and whinge mode is on, the add_config function should complain about the additional tokens in the line.

    Modify the implementation of the Play struct's associated read_config function so that it only takes in a reference to a String with the name of a script file, and a mutable reference to a ScriptConfig. If the script file cannot be opened or no lines were read from it, the function should use eprintln! generate an appropriate error message and then should return an error indicating that script generation failed. Otherwise, the function should use the associated add_config function to add tuples to the ScriptConfig that was passed in, and should then return Ok(()).

    Modify the implementation of the Play struct's associated prepare method so that it uses the new version of the associated read_config function (i.e., only passes in the script file name that was passed to it, and a newly created ScriptConfig. At the end of the Play struct's associated prepare method, if there are fragments in its Fragments field and the first fragment has a title, it should return Ok(()). Otherwise it should use eprintln! to generate an appropriate error message and should return an error indicating that script generation failed.

    Modify the implementation of the Play struct's associated recite method so that it iterates through its vector of scene fragments and calls each one's enter then recite then exit methods, except that for the first fragment it should call enter_all instead of enter, and for the last fragment it should call exit_all instead of exit. All calls to enter should pass in a reference to the previous fragment in the vector, and all calls to exit should pass in a reference to the subsequent fragment in the vector.

  12. Modify the usage function in your main program file so that instead of mentioning a configuration file it instead mentions a script file, e.g.,
    usage: ./lab2 <script_file_name> [whinge]

    Also update the names of any constants and variables the main function uses that refer to it handling a config file, so that instead they refer to it handling a script file.

  13. In your ReadMe.txt file please add a subsection titled "Scene Fragments" and in it please summarize how you extended your solution to manage multiple consecutive scene fragments, including any design challenges you encountered and how you addressed those.

    Testing

  14. To test your program, you should please make sure it compiles with no errors or warnings, and run it (and check the output to make sure it appears correct) with relevant script files, scene fragment configuration files, and part files, such as: partial_hamlet_act_ii_script.txt), hamlet_ii_1a_config.txt, hamlet_ii_1b_config.txt, hamlet_ii_2a_config.txt, Polonius_hamlet_ii_1a.txt, Reynaldo_hamlet_ii_1a.txt, Polonius_hamlet_ii_1b.txt, Ophelia_hamlet_ii_1b.txt, King_hamlet_ii_2a.txt, Queen_hamlet_ii_2a.txt, Rosencrantz_hamlet_ii_2a.txt, and Guildenstern_hamlet_ii_2a.txt.

    You are also encouraged to generate your own script file, configuration files and part files for segments of 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., and also shuffling the lines in part files so that they are out of order and also selectively removing lines from some part files, to test your program's handling of key use cases across a wide range of possible inputs.

  15. In your ReadMe.txt file please add a subsection titled "Testing" and in it please summarize how you tested your solution, including any problems your testing detected, and how you addressed those.

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 2")
  2. the names and e-mail addresses of all team members
  3. an overview of how your program was designed, 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 developed and tested your solution, including each stage of how you refactored and extended your lab 1 solution to implement this lab assignment. Please also describe the kinds of script, 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:

Page updated Friday October 17, 2025, by Chris Gill.