The University of Queensland
School of Information Technology and Electrical Engineering
CSSE2310/CSSE7231 — Semester 2, 2022 Assignment 1 (version 1)
Marks: 75 (for CSSE2310), 85 (for CSSE7231) Weighting: 15%
Due: 6:00pm Friday 26 August, 2022
Introduction 1
The goal of this assignment is to give you practice at C programming. You will be building on this abil- 2 ity in the remainder of the course (and subsequent programming assignments will be more difficult than 3 this one). You are to create a program (called wordle-helper) which helps users play the Wordle game 4 (www.nytimes.com/games/wordle/). More details are provided below but you may wish to play the game 5 to gain a practical understanding of how it operates. The assignment will also test your ability to code to a 6 particular programming style guide, and to use a revision control system appropriately. 7
Student Conduct 8
This is an individual assignment. You should feel free to discuss general aspects of C programming and 9 the assignment specification with fellow students, including on the discussion forum. In general, questions like 10 “How should the program behave if ⟨this happens⟩?” would be safe, if they are seeking clarification on the 11 specification. 12
You must not actively help (or seek help from) other students or other people with the actual design, structure 13 and/or coding of your assignment solution. It is cheating to look at another student’s assignment code 14 and it is cheating to allow your code to be seen or shared in printed or electronic form by others. 15 All submitted code will be subject to automated checks for plagiarism and collusion. If we detect plagiarism or 16 collusion, formal misconduct actions will be initiated against you, and those you cheated with. That’s right, if 17 you share your code with a friend, even inadvertently, then both of you are in trouble. Do not post your 18 code to a public place such as the course discussion forum or a public code repository, and do not allow others 19 to access your computer – you must keep your code secure. 20
You must follow the following code referencing rules for all code committed to your SVN repository (not 21
just the version that you submit):
Code Origin
Code you have personally written this semester for CSSE2310/7231 (e.g. code written for A1 reused in A3) Code examples found in man pages on moss.
Code (in any programming language) that you have taken inspiration from but have not copied.
Usage/Referencing
May be used freely without reference. (This assumes that no reference was required for the original use.)
May be used provided the source of the code is referenced in a comment adjacent to that code. (Code you have taken inspiration from must not be directly copied or just converted from one programming language to another.)
22
23
Code provided to you in writing this semester by CSSE2310/7231 teaching staff (e.g. code hosted on Black- board, posted on the discussion forum, or shown in class).
May be used freely without reference. (You must be able to point to the source if queried about it.)
Code you have personally written in a previous enrolment in this course or in another ITEE course and where that code has not been shared or published.
Other code – includes: code provided by teaching staff only in a previous offering of this course (e.g. previous A1 solu- tion); code from websites; code from textbooks; any code written by someone else, or partially written by someone else; and any code you have written that is available to other students.
May not be used. If the source of the code is referenced adjacent to the code then this will be considered code without academic merit (not misconduct) and will be removed from your assignment prior to marking (which may cause compilation to fail and zero marks to be awarded). Copied code without adjacent referencing will be considered misconduct and action will be taken.
Uploading or otherwise providing the assignment specification or part of it to a third party including online 24 tutorial and contract cheating websites is considered misconduct. The university is aware of these sites and 25
1
many cooperate with us in misconduct investigations. 26 The course coordinator reserves the right to conduct interviews with students about their submissions, for 27 the purposes of establishing genuine authorship. If you write your own code, you have nothing to fear from this 28 process. If you are not able to adequately explain your code or the design of your solution and/or be able to 29 make simple modifications to it as requested at the interview, then your assignment mark will be scaled down 30 based on the level of understanding you are able to demonstrate. 31 In short - Don’t risk it! If you’re having trouble, seek help early from a member of the teaching staff. 32 Don’t be tempted to copy another student’s code or to use an online cheating service. You should read and 33 understand the statements on student misconduct in the course profile and on the school web-site: https: 34 //www.itee.uq.edu.au/itee-student-misconduct-including-plagiarism 35
Specification 36
Your program is to suggest a list of words that might be suitable for playing in a Wordle game, given some 37 constraints. The length of the word may be set on the command line (between 4 and 9 characters inclusive) 38 but defaults to 5 if no length is specified. The constraints on the word might include particular letters that 39 have to be in particular locations in the word, particular letters that must be found somewhere in the word, or 40 particular letters that must not be found in the word. 41
Full details of the required behaviour are provided below. 42
Command Line Arguments 43
Your program (wordle-helper) is to accept command line arguments as follows: 44
./wordle-helper [-alpha|-best] [-len word-length] [-with letters] [-without letters] [pattern]45 46
In other words, your program should accept 0 to 8 arguments after the program name. The square brackets 47 ([]) indicate optional arguments. The pipe symbol (|) indicates a choice. The italics indicate placeholders for 48 user-supplied arguments. 49
Some examples of how the program might be run include the following1: 50
./wordle-helper
./wordle-helper
./wordle-helper
./wordle-helper
./wordle-helper
./wordle-helper
./wordle-helper
./wordle-helper
./wordle-helper
51 -alpha 52 -best 53 -len 6 54 -with abB 55 -without xyZ 56 R___E 57 -alpha -len 6 -with os -without Xyz r_p__e 58 r_P__e -alpha -without XyZ -len 6 -with OS 59
any order, as shown in the last example, but handling such arguments will only be 60 The meaning of the arguments is as follows: 62
• -alpha – if specified, this argument indicates that the output words must be sorted in alphabetical order2 63 and all duplicates must be removed. If this option is specified, then the -best option must not be specified. 64
• -best – if specified, this argument indicates that the output words must be sorted in decreasing order of 65 likelihood (as determined by the provided guess_compare() function – described later). Words with the 66 same likelihood must be sorted alphabetically. Duplicates must be removed. If this option is specified, 67 then the -alpha option must not be specified. 68
• -len – if specified, this argument must be followed by an integer between 4 and 9 inclusive that indicates 69 the length of the word to be used. If the argument is not specified, a default word length of 5 shall be 70 used. 71
• -with – if specified, this argument is followed by a set of letters that must be present in matching words. 72 Letters can be listed in any order and with any case (i.e. uppercase and/or lowercase). If a letter is 73
1This is not an exhaustive list and does not show all possible combinations of arguments.
2Alphabetical order means the order as determined by strcasecmp() – or strcmp() for words of the same case.
Arguments can be in
assessed as part of advanced functionality – see below. 61
2
listed more than once then it must be present at least that number of times in matching words. The 74 set of letters may be empty – which is the same as not specifying the -with argument. All matching is 75 case-independent – e.g. an ‘A’ or ‘a’ in this set will match an ‘A’ or ‘a’ in the word. 76
• -without – if specified, this argument is followed by a set of letters that must not be present in matching 77 words. Letters may be listed more than once but this has the same effect as listing them once. Letters 78 may be listed in any order or with any case. The set of letters may be empty – which is the same as not 79 specifying the -without argument. All matching is case-independent – e.g. an ‘A’ or ‘a’ in this set means 80 that neither ‘A’ nor ‘a’ should be present in the word. 81
• pattern – if specified, this argument must be a string of the same length of words to be matched. The 82 string must contain only letters (any case) and underscores. Words must match the pattern – i.e. must 83 contain letters in the same position as letters that are present in the pattern, and any letter may match 84 an underscore. A pattern of the right length consisting only of underscores is the same as not specifying 85 a pattern (i.e. everything of the right length is a match). All matching is case independent. 86
Prior to doing anything else, your program must check the command line arguments for validity. If the 87 program receives an invalid command line then it must print the message: 88
Usage: wordle-helper [-alpha|-best] [-len len] [-with letters] [-without letters] [pattern] 89
to standard error (with a following newline), and exit with an exit status of 1. 90
Invalid command lines include (but may not be limited to) any of the following: 91
• An argument begins with the character ‘-’ but it is not one of -alpha, -best, -len, -with, or -without. 92
• The -len argument is given but it is not followed by a positive integer between 4 and 9 inclusive. 93
• The -with or -without argument is given but is not followed by an argument that contains only uppercase 94 or lowercase letters (or is the empty string3.) 95
• Both the -alpha and -best arguments are given 96
• Any argument is present more than once (e.g. -len is repeated, or there is more than one pattern 97
argument) 98
Checking whether the pattern argument (if present) is valid is not part of the usage checking – that is 99 checked after command line validity – see the next section. The pattern argument can be assumed to be the 100 first argument that does not begin with ‘-’ (and is not the argument immediately following -len, -with or 101 -without). 102
Pattern Checking 103 If the command line arguments are valid, then the pattern argument (if supplied) must be checked for validity. 104
If the pattern is invalid, then your program must print the message: 105 wordle-helper: pattern must be of length N and only contain underscores and/or letters 106
to standard error (with a following newline), and exit with an exit status of 2. The placeholder ‘N’ in the 107 message must be replaced by the expected word length. 108 Invalid patterns are: 109
• those whose length does not match the expected word length (the value given after -len or default 5), 110 and/or 111
• those that contain characters other than underscores and/or letters (uppercase and/or lowercase). 112 Dictionary File Name Checking 113
By default, your program is to use the dictionary file /usr/share/dict/words. However, if the 114 WORDLE_DICTIONARY environment variable is set then your program must use the dictionary file whose name is 115 specified in that environment variable. 116
If the environment variable is set but the given dictionary filename does not exist or can not be opened for 117 reading, your program should print the message: 118
3Note that an empty string is not the same as a missing argument. An empty string can be passed from the shell command line as "". Running ./wordle-helper -with "" is valid; running ./wordle-help -with is not.
3
wordle-helper: dictionary file "filename" cannot be opened 119
to standard error (with a following newline), and exit with an exit status of 3. (The italicised filename is 120 replaced by the actual filename i.e. the value of the WORDLE_DICTIONARY environment variable. The double 121 quotes must be present.) This check happens after the command line arguments and pattern (if supplied) are 122 known to be valid. 123
The dictionary file is a text file where each line contains a “word”. (Lines are terminated by a single newline 124 character. The last line in the file may or may not have a terminating newline.) You may assume there are no 125 blank lines and that no words are longer than 50 characters (excluding any newline)4, although there may be 126 “words” that contain characters other than letters, e.g. “1st” or “don’t”. The dictionary may contain duplicate 127 words and may be sorted in any order. The dictionary may contain any number of words (including zero). 128
Program Operation 129 If the checks above are successful, then your program should output all words in the given dictionary file that 130
satisfy the following: 131
• the word length matches that required (see the description of the -len command line argument above); 132
• the word contains only letters – which can be uppercase or lowercase or a combination of both; 133
• the word must contain those letters specified after the -with argument (if specified, see description above); 134
• the word must not contain those letters specified after the -without argument (if specified, see description 135 above); and 136
• the word must match the given pattern from the command line (if specified, see description above). 137 Program Output 138
Your program must output (to standard output) all matching words in uppercase (i.e. any lowercase letters in 139 matching words must be printed as uppercase letters). 140 By default, if neither the -alpha nor -best arguments are present, then words must be output in the order 141 they are found in the dictionary file. This may include duplicate words if the word is found more than once in 142 the dictionary file. 143 If either the -alpha or -best argument is present, then the output must be sorted as described in the 144 command line arguments section above. 145 If at least one matching word is found and output then your program must exit with exit status 0, indicating 146 a successful run. If no matching words are found then your program must exit with exit status 4 – but nothing 147 should be printed to standard output or standard error. 148 Your program must output nothing to standard output or standard error other than the output/messages 149 described above. Your program will never print a message to both standard output and standard error during 150 the same run. (You may print debugging information to standard output or standard error when developing 151 your program, but make sure you delete all such print statements prior to submission. Extraneous output text 152 will cause you to lose marks.) 153
Advanced Functionality 154 Some of the behaviour described above is more advanced and it is recommended that you delay implementation 155
of this functionality until you have other functionality implemented: 156
• Implementation of sorting (using the -alpha or -best arguments) will require the use of dynamically 157 allocated memory to store all matching words so they can be sorted before being output. Without 158 this sorting functionality, you can just process words from the dictionary line by line and output them 159 immediately if they match (or not, if they don’t). If you do not implement the sorting functionality, you 160 should still check for and accept the -alpha and -best command line arguments (in order to get marks 161 for command line argument handling) – but just output the words in dictionary order. 162
4A statement that you may assume these things means that your program does not have to handle situations where these assumptions are not true – i.e. your program can behave in any way it likes (including crashing) if there are blank lines present in the dictionary and/or any words in the dictionary are longer than 50 characters.
4
• Allowing command line arguments to appear in any order complicates command line argument processing 163 so this is considered more advanced functionality. For most functionality marks, testing will only take 164 place with command line arguments (if present) in the order given in the usage strings above. For the 165 advanced command line argument processing marks, your program must accept command line arguments 166 in any order (parameters associated with option arguments, e.g. -len 6 will still be together with that 167 option argument). 168
Example Runs 169 Consider a dictionary with the following content:
raise
rogue
ridge
range
Range
rafted
RANGER
reaper
rented
redeem
Assume that this content is in the file $HOME/example-dictionary. The user can use this dictionary by setting the WORDLE_DICTIONARY environment variable as shown below. Note also that in the examples below, the $ character is the shell prompt – it is not entered by the user.
Example 1: Matching all 5 letter words
Example 2: Specifying that a letter must be present or not
Example 3: Sorting the output – note the removal of the duplicate word
Example 4: Specifying a pattern – note the case insensitive pattern matching
Example 5: Specifying a different length, and using repeated letters in the -with argument
$ WORDLE_DICTIONARY=$HOME/example-dictionary ./wordle-helper
RAISE
ROGUE
RIDGE
RANGE
RANGE
$ WORDLE_DICTIONARY=$HOME/example-dictionary ./wordle-helper -with g -without d
ROGUE
RANGE
RANGE
$ WORDLE_DICTIONARY=$HOME/example-dictionary ./wordle-helper -alpha -with g -without d
RANGE
ROGUE
$ WORDLE_DICTIONARY=$HOME/example-dictionary ./wordle-helper r__Se
RAISE
$ WORDLE_DICTIONARY=$HOME/example-dictionary ./wordle-helper -len 6 -with eE
REAPER
RENTED
REDEEM
5
Example 6: Conflicting constraints – no output, but not an error
$ WORDLE_DICTIONARY=$HOME/example-dictionary ./wordle-helper -len 6 -with eE -without e
Provided Library: libcsse2310a1 170
A library has been provided to you with the following function which your program must use if you implement 171 the -best sorting functionality: 172 int guess_compare(const char* word1, const char* word2); 173 The function is described in the guess_compare(3) man page on moss. (Run man guess_compare.) 174 To use the library, you will need to add #include to your code and use the compiler flag 175 -I/local/courses/csse2310/include when compiling your code so that the compiler can find the include 176 file. You will also need to link with the library containing this function. To do this, use the compiler arguments 177 -L/local/courses/csse2310/lib -lcsse2310a1. 178
Style 179 Your program must follow version 2.2.0 of the CSSE2310/CSSE7231 C programming style guide available on 180
the course Blackboard site. 181
Hints 182
1. The string representation of a single digit positive integer has a string length of 1. 183
2. You can use the function getenv() to retrieve the value of an environment variable. 184
3. You may wish to consider the use of the standard library functions isalpha(), islower(), isupper(), 185 toupper() and/or tolower(). Note that these functions operate on individual characters, represented as 186 integers (ASCII values). 187
4. There is no expectation that you write your own sorting routine. It is recommended that you use the 188 qsort() library function. 189
5. Some other functions which may be useful include: strcasecmp(), strcmp(), strlen(), exit(), fopen(), 190 fprintf(), and fgets(). You should consult the man pages for these functions. 191
6. The style guide shows how you can break long string constants in C so as not to violate line length 192 requirements in the style guide. 193
7. Removal of duplicate items from a list is best done after sorting a list – duplicate items will be adjacent 194 to each other. 195
8. It is strongly recommended that you do not try to use getopt() to parse command line arguments as the 196 form of arguments specified here is not amenable to parsing by getopt(), e.g. short forms of arguments 197 are not to be supported, duplicate arguments are not permitted, arguments beginning with -- are not 198 permitted, etc. 199
Suggested Approach 200
It is suggested that you write your program using the following steps. Test your program at each stage and 201 commit to your SVN repository frequently. Note that the specification text above is the definitive description 202 of the expected program behaviour. The list below does not cover all required functionality. 203
1. Write a program that outputs the usage error message and exits with exit status 1. This small program 204 (just a couple of lines in main()) will earn marks for detecting usage errors (category 1 below) – because 205 it thinks everything is a usage error!5 206
5However, once you start adding more functionality, it is possible you may lose some marks in this category if your program can’t detect all the valid command lines.
6
2. Detect the presence of the -len command line argument and, if present, check the presence/validity of 207 the argument that follows it. Exit appropriately if not valid. 208
3. Detect the presence of the -with command line argument and, if present, check the presence/validity of 209 the argument that follows it. Exit appropriately if not valid. 210
4. Detect the presence of the -without command line argument and, if present, check the presence/validity 211 of the argument that follows it. Exit appropriately if not valid. 212
5. Detect the presence of a sort method argument (-alpha and -best) and make sure only one is present. 213 Exit appropriately if not valid. 214
6. Detect the presence of a pattern argument and check whether it is valid or not. Exit appropriately if not 215 valid. 216
7. Check whether the dictionary can be opened for reading or not (both the default dictionary and one 217 specified using the environment variable). Exit appropriately if not. (If it can be opened, leave it open – 218 you’ll need to read from it next.) 219
8. Read the dictionary line by line, convert it to uppercase and just print out each word that is the right 220 length (i.e. initially assume all words of the right length match). 221
9. Check the words to make sure they only contain letters. 222
10. If a pattern is given, check each word matches the pattern before outputting it. 223
11. If the -with argument is given, check each word contains only those letters. It is easiest to do this by 224 counting the number of each letter in the word and comparing that with the number of each letter in the 225 -with set. 226
12. If the -without argument is given, check each word does not contain those letters (you can use the count 227 of each letter that you’ve already determined). 228
13. Implement remaining functionality as required . . . 229
Forbidden Functions 230
You must not use any of the following C functions/statements. If you do so, you will get zero (0) marks for the 231 assignment. 232
• goto 233 • longjmp() and equivalent functions 234 • system() 235 • popen() 236 • execl() or any other members of the exec family of functions 237 • POSIX regex functions 238
Submission 239 Your submission must include all source and any other required files (in particular you must submit a Makefile). 240
Do not submit compiled files (eg .o, compiled programs) or dictionary files. 241 Your program (named wordle-helper) must build on moss.labs.eait.uq.edu.au with: 242
make 243 Your program must be compiled with gcc with at least the following options: 244
-pedantic -Wall -std=gnu99 245 You are not permitted to disable warnings or use pragmas to hide them. You may not use source files other 246
than .c and .h files as part of the build process – such files will be removed before building your program. 247 7
If any errors result from the make command (i.e. the wordle-helper executable can not be created) then you 248 will receive 0 marks for functionality (see below). Any code without academic merit will be removed from your 249 program before compilation is attempted (and if compilation fails, you will receive 0 marks for functionality). 250
Your program must not invoke other programs or use non-standard headers/libraries. 251
Your assignment submission must be committed to your subversion repository under 252
https://source.eait.uq.edu.au/svn/csse2310-sem2-sXXXXXXX/trunk/a1 253
where sXXXXXXX is your moss/UQ login ID. Only files at this top level will be marked so do not put source 254 files in subdirectories. You may create subdirectories for other purposes (e.g. your own test files) but these 255 will not be considered in marking – they will not be checked out of your repository. 256
You must ensure that all files needed to compile and use your assignment (including a Makefile) are commit- 257 ted and within the trunk/a1 directory in your repository (and not within a subdirectory) and not just sitting 258 in your working directory. Do not commit compiled files or binaries. You are strongly encouraged to check out 259 a clean copy for testing purposes. 260
To submit your assignment, you must run the command 261
2310createzip a1 262
on moss and then submit the resulting zip file on Blackboard (a GradeScope submission link will be made 263 available in the Assessment area on the CSSE2310/7231 Blackboard site)6. The zip file will be named 264 sXXXXXXX_csse2310_a1_timestamp.zip 265 where sXXXXXXX is replaced by your moss/UQ login ID and timestamp is replaced by a timestamp indicating 266 the time that the zip file was created. 267 The 2310createzip tool will check out the latest version of your assignment from the Subversion repository, 268 ensure it builds with the command ‘make’, and if so, will create a zip file that contains those files and your 269 Subversion commit history and a checksum of the zip file contents. You may be asked for your password as 270 part of this process in order to check out your submission from your repository. 271 You must not create the zip file using some other mechanism and you must not modify the zip file prior 272 to submission. If you do so, you will receive zero marks. Your submission time will be the time that the file 273 is submitted via GradeScope on Blackboard, and not the time of your last repository commit nor the time of 274 creation of your submission zip file. 275 We will mark your last submission, even if that is after the deadline and you made submissions before the 276 deadline. Any submissions after the deadline7 will incur a late penalty – see the CSSE2310/7231 course profile 277 for details. 278
Marks 279
Marks will be awarded for functionality and style and documentation. Marks may be reduced if you are asked 280 to attend an interview about your assignment and you are unable to adequately respond to questions – see the 281 Student conduct section above. 282
Functionality (60 marks) 283
Provided your code compiles (see above) and does not use any prohibited statements/functions (see above), and 284 your zip file has been generated correctly and has not been modified prior to submission, then you will earn 285 functionality marks based on the number of features your program correctly implements, as outlined below. 286 Partial marks will be awarded for partially meeting the functionality requirements. Not all features are of equal 287 difficulty. If your program does not allow a feature to be tested then you will receive 0 marks for 288 that feature, even if you claim to have implemented it. For example, if your program can never open a file, we 289 can not determine if your program can determine word validity correctly. If your program takes longer than 10 290 seconds to run any test8, then it will be terminated and you will earn no marks for the functionality associated 291 with that test. The markers will make no alterations to your code (other than to remove code without academic 292 merit). 293
6You may need to use scp or a graphical equivalent such as WinSCP, Filezilla or Cyberduck in order to download the zip file to your local computer and then upload it to the submission site.
7or your extended deadline if you are granted an extension.
8Valgrind tests for memory leaks (category 11) will be allowed to run for longer.
8
Marks will be assigned in the following categories.
1. Program correctly handles invalid command lines
2. Program correctly handles invalid patterns (with various -len options)
3. Program correctly handles dictionary files that are unable to be read
4. Program correctly outputs words of the right length from various dictionaries with either no arguments or just a -len argument and valid length
5. Program correctly matches specified patterns (with various -len options and dictionaries but no other options)
6. Program correctly implements -with argument (with various -len options and dictionaries but no other options)
7. Program correctly implements -without argument (with various -len options and dictionaries but no other options)
8. Program correctly matches words with various combinations of arguments (in usage message order if present) and various dictionaries
9. Program correctly matches and sorts words with -alpha or -best and various dictionaries and combinations of other arguments (in usage message order if present)
10. Program behaves correctly with various arguments in non-standard order (with various dictionaries but no sorting arguments)
11. Program behaves correctly and frees all memory when used with a sorting argument
(-alpha or -best) and various dictionaries and various other arguments in non-standard order
294
(8 marks) 295 (6 marks) 296 (3 marks) 297
298 (4 marks) 299
300 (6 marks) 301
302 (6 marks) 303
304 (6 marks) 305
306 (6 marks) 307
308 (6 marks) 309
310 (6 marks) 311
312 (3 marks) 313
It is unlikely that you can earn many marks for categories 8 and later unless your program correctly matches 314 patterns, including support for the -with and -without arguments. 315
Style Marking 316
Style marking is based on the number of style guide violations, i.e. the number of violations of version 2.2 of 317 the CSSE2310/CSSE7231 C Programming Style Guide (found on Blackboard). Style marks will be made up of 318 two components – automated style marks and human style marks. These are detailed below. 319
You should pay particular attention to commenting so that others can understand your code. The marker’s 320 decision with respect to commenting violations is final – it is the marker who has to understand your code. To 321 satisfy layout related guidelines, you may wish to consider the indent(1) tool. Your style marks can never be 322 more than your functionality mark – this prevents the submission of well styled programs which don’t meet at 323 least a minimum level of required functionality. 324
You are encouraged to use the style.sh tool installed on moss to style check your code before submission. 325 This does not check all style requirements, but it will determine your automated style mark (see below). Other 326 elements of the style guide are checked by humans. 327
All .c and .h files in your submission will be subject to style marking. This applies whether they are 328 compiled/linked into your executable or not9. 329
Automated Style Marking (5 marks) 330
Automated style marks will be calculated over all of your .c and .h files as follows. If any of your submitted 331 .c and/or .h files are unable to be compiled by themselves then your automated style mark will be zero (0). 332 (Automated style marking can only be undertaken on code that compiles. The provided style.sh script checks 333 this for you.) 334
If your code does compile then your automated style m