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:
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.
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.
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;
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.
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.
lab1/declarations.rs file declare:
Play type that is a vector of tuples, with each tuple
consisting of a usize element reflecting the order in which the
line is given in the play, a String element for the name of the
character by which the line is given, and another String element
with the text of the line itself;
usize for the minimum and
maximum number of command line arguments (including the program name) that the
program will accept (valued 2 and 3 respectively) and for the positions within
the command line at which to find the program name, the name of the configuation
file, and an optional argument telling the program to complain about problems
it can handle (valued 0, 1, and 2 respectively);
u8 for program return
values indicating unrecoverable problems due to a badly formed command line or
a failure to generate a script (valued 1 and 2 respectively); and
AtomicBool that
is initialized to false and that indicates whether or not the program should
complain about any problems it handles successfully.
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]
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.
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).
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_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:
PlayConfig type that is a vector of tuples with each tuple
consisting of a String element for the name of a character in the
play, and another String element for the name of a text file
containing the lines that the character will deliver; and
usize for the (0 based)
index of the line in a configuration file that will give the title of the play
and the index of the first line of the configuration file where characters
names and names of files containing their lines will appear (valued 0 and 1
respectively), for the indexes of the token elements in a configuration line
where the character's name and the name of the file containing their lines
(also valued 0 and 1 respectively) and for the number of tokens a configuration
line is expected to contain (valued 2).
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.
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.
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.
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.
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.
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.
The first section of your ReadMe.txt file should include:
The second section of your ReadMe.txt file should provide detailed instructions for how to:
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.