CSSE2310/CSSE7231 Assignment 1

Hello, dear friend, you can consult us at any time if you have any questions, add WeChat: daixieit

School of Information Technology and Electrical Engineering

CSSE2310/CSSE7231 — Semester 2, 2021

Assignment 1 (version 1.0)

Introduction

The goal of this assignment is to give you practice at C programming. You will be building on this ability in the remainder of the course (and subsequent programming assignments will be more difficult than this one). You are to create a program (called unjumble) which searches a dictionary of words to find words that can be made from a given collection (jumble) of letters. For example, you might use such a program to find all the words that can be made out of the letters ‘aeebcddh’, or perhaps just the longest word(s) (‘beached’ in this case, if the program is searching a standard English dictionary). The assignment will also test your ability to code to a particular programming style guide, and to use a revision control system appropriately.

Student conduct

This is an individual assignment. You should feel free to discuss general aspects of C programming and the assignment specification with fellow students, including on the discussion forum. In general, questions like “How should the program behave if hthis happensi?” would be safe, if they are seeking clarification on the specification.

        You must not actively help (or seek help from) other students or other people with the actual design, structure and/or coding of your assignment solution. It is cheating to look at another student’s assignment code and it is cheating to allow your code to be seen or shared in printed or electronic form by others. All submitted code will be subject to automated checks for plagiarism and collusion. If we detect plagiarism or collusion, formal misconduct proceedings will be initiated against you, and those you cheated with. That’s right, if you share your code with a friend, even inadvertently, then both of you are in trouble. Do not post your code to a public place such as the course discussion forum or a public code repository, and do not allow others to access your computer - you must keep your code secure.

        Uploading or otherwise providing the assignment specification or part of it to a third party including online tutorial and contract cheating websites is considered misconduct. The university is aware of these sites and they cooperate with us in misconduct investigations.

        You may use code provided to you by the CSSE2310/CSSE7231 teaching staff in this current semester and you may use code examples that are found in man pages on moss. If you do so, you must add a comment in your code (adjacent to that code) that references the source of the code. If you use code from other sources then this is either misconduct (if you don’t reference the code) or code without academic merit (if you do reference the code). Code without academic merit will be removed from your assignment prior to marking (which may cause compilation to fail) but this will not be considered misconduct.

        The course coordinator reserves the right to conduct interviews with students about their submissions, for the purposes of establishing genuine authorship. If you write your own code, you have nothing to fear from this process. If you are not able to adequately explain your code or the design of your solution and/or be able to make simple modifications to it as requested at the interview, then your assignment mark will be scaled down based on the level of understanding you are able to demonstrate.

In short - Don’t risk it! If you’re having trouble, seek help early from a member of the teaching staff. Don’t be tempted to copy another student’s code or to use an online cheating service. You should read and understand the statements on student misconduct in the course profile and on the school web-site: https://www.itee.uq.edu.au/itee-student-misconduct-including-plagiarism

Specification

Command Line Arguments

Your program (unjumble) is to accept command line arguments as follows:

./unjumble [-alpha|-len|-longest] [-include letter ] letters [dictionary ]

        In other words, your program should accept between one and five command arguments – option argument(s) followed by a set of letters, then optionally followed by a dictionary filename. The program will search the given dictionary file (or a default dictionary if a dictionary filename is not specfied – see below) for words that can be formed from the given set of letters.

        The set of letters is the only required argument. This argument can only include upper case or lower case letters (all matching is independent of case so it doesn’t matter what case is used) and letters must be repeated if they are able to be used more than once. There must be at least three letters specified (because the minimum matching word length is three – see ‘Program Operation’ below).

        At most one of -alpha, -len, or -longest may be specified. This argument determines the type of output as follows:

● (none of these arguments present) – matching words are to be output in the same order as they appear in the dictionary;

● -alpha – matching words are to be output in alphabetic (lexicographic) order (with words that are the same alphabetically to be output in ASCII order, e.g. “Ace” would be output before “ace”);

● -len – matching words are to be output in descending order of length (i.e. longest words first), with words of the same length to be output as per -alpha sorting;

● -longest – only the longest word(s) are to be output, with words of the same length to be output as per-alpha sorting.

        If the -include argument is given, it must be followed by a single letter (A to Z – upper case or lower case). This argument indicates that the given letter must be included in any matching words.

        The last argument (if present) is the path name of the dictionary file, i.e. the name of a file containing words – one per line. Each line (including the last) is assumed to be terminated by a newline character (\n) only. You may assume there are no blank lines and that no words are longer than 50 characters, although there may be words that contain characters other than letters, e.g. “1st” or “don’t”. The filename can be relative to the current directory or absolute (i.e. begins with a /). Some examples are:

/usr/share/dict/words

../dictname

mydictionary (refers to a file with this name in the current directory)

        If the filename is not specified, the default should be used (/usr/share/dict/words).

Examples

Consider a dictionary file (named sample_dict) with the contents below:

Listing 1: Sample dictionary file (sample_dict)

Ace   ached   are   ace   beach   aced   area   example   arena   beaded   CSSE2310   decade   ACE

The listings below show the output expected for the given command lines.

Listing 2: Output of ./unjumble abcde sample_dict

Ace   ace   aced   ACE

Listing 3: Output of ./unjumble -alpha abcde sample_dict

ACE   Ace   ace   aced

Listing 4: Output of ./unjumble -len aeebcdhd sample_dict

beaded   decade   ached   beach   aced   ACE   Ace   ace

Listing 5: Output of ./unjumble -longest aeebcdHD sample_dict

beaded   decade

Listing 6: Output of ./unjumble -include D -len aeebcdhd sample_dict

beaded   decade   ached   aced

Program Operation

The program is to operate as follows:

● If the program receives an invalid command line then it must print the message:

Usage: unjumble [-alpha|-len|-longest] [-include letter] letters [dictionary]

to standard error, and exit with an exit status of 1.

Invalid command lines include (but may not be limited to) any of the following:

– an argument prior to the letters argument begins with ‘-’ but is not one of -alpha, -len, -longest or -include

– one of the valid option arguments (-alpha, -len, -longest or -include) appears more than once in the command line

– more than one of -alpha, -len or -longest is present

– the argument following -include is not a single letter

– the letters argument is not present

– there are one or more arguments after the dictionary file name

● If the given dictionary filename does not exist or can not be opened for reading, your program should print the message:

unjumble: file "filename " can not be opened

to standard error, and exit with an exit status of 2. (The italicised filename is replaced by the actual filename i.e. the full argument given on the command line. The double quotes must be present.)

● If the letters argument contains fewer than 3 characters, then your program should print the message: 

unjumble: must supply at least three letters

to standard error, and exit with an exit status of 3.

● If the letters argument contains characters other than upper or lower case letters then your program should print the message:

unjumble: can only unjumble alphabetic characters

to standard error, and exit with an exit status of 4.

● Note – if there is not a usage error (i.e. the program is not exiting with exit status 1) and more than one of the other errors applies, then any one (and only one) of the applicable error messages can be output. Note also that all error messages must be terminated by a single newline character.

● If none of the errors above are present, then your program must then print all words in the dictionary file that are at least 3 letters long and that can be formed from the set of letters provided (ignoring the case of the letters, i.e. ‘a’ matches ’A’ etc.). Each provided letter can be used at most once. Words are output to standard output with a single newline after each word (including the last). When all matches have been printed, your program must exit. If at least one match was printed, your program should exit with an exit status of zero. If no matches were reported, your program should output nothing and exit with an exit status of 10. By default, matches are printed in the same order they are found in the dictionary file. (See Advanced Functionality below for other output options.) Your program must not change the capitalisation of the words in the dictionary – words must be output as found in that file. Words in the dictionary that contain characters other than letters (e.g. numbers or punctuation characters) will never be reported as matches.

● Your program must output nothing to standard output or standard error other than the output/mes-sages described above. Your program will never print a message to both standard output and standard error during the same run. (You may print debugging information to standard output or standard error when developing your program, but make sure you delete all such print statements prior to submission. Extraneous output text will cause you to lose marks.)

Advanced Functionality

● If the -include argument is present, then the single letter given after it must be present in the words being output. Only words that contain that letter (upper case or lower case) are to be output.

● If the -alpha argument is present, then the matching words must be sorted in alphabetic (lexicographic) order with words that are the same alphabetically to be output in ASCII order, e.g. “Ace” would be output before “ace”).

● If the -len argument is present, then the matching words are to be output in descending order of length (i.e. longest words first), with words of the same length to be sorted as per -alpha sorting.

● If the -longest argument is present, then only the longest matching word(s) are to be output. (Multiple words are output only if they all have the same length.) The words must be sorted as per the -alpha sorting described above.

Style

Your program must follow version 2.1 of the CSSE2310/CSSE7231 C programming style guide available on the course BlackBoard site.

Hints

1. One way of determining whether a word can be built from a set of letters is to count the number of each letter (‘A’ to ‘Z’) in both the word and the available letters and see if the word uses more than the number of each letter available.

2. You may wish to consider the use of the standard library functions isalpha(), islower(), isupper(), toupper() and/or tolower(). Note that these functions operate on integers (ASCII values) so you will need to cast characters to integers and vice versa as appropriate to avoid compiler warnings. For example, given that variable c is of type char, the following code will convert the character stored in c to upper case (without compiler warnings):

c = (char)toupper((int)c);

3. Note that implementation of the advanced functionality (sorting) will require the use of dynamically allocated memory (i.e. with malloc() etc.) to store the list of words for sorting. Use of dynamically allocated memory is not required if you do not implement the sorting functionality (though you may use it if you wish).

4. Some other functions which may be useful include strcasecmp(), strcmp(), strlen(), exit(), fopen(), fgets(), fprintf() and qsort(). You should consult the man pages for these functions.

Forbidden Functions

You must not use any of the following C functions/statements. If you do so, you will get zero (0) marks for the assignment.

● goto

● longjmp() and equivalent functions

● system()

● execl() or any other members of the exec family of functions

● POSIX regex functions

Submission

Your submission must include all source and any other required files (in particular you must submit a Makefile). Do not submit compiled files (eg .o, compiled programs) or dictionary files.

Your program (named unjumble) must build on moss.labs.eait.uq.edu.au with:

make

Your program must be compiled with gcc with at least the following switches:

-pedantic -Wall -std=gnu99

        You are not permitted to disable warnings or use pragmas to hide them. You may not use source files other than .c and .h files as part of the build process – such files will be removed before building your program.

        If any errors result from the make command (i.e. the unjumble executable can not be created) then you will receive 0 marks for functionality (see below). Any code without academic merit will be removed from your program before compilation is attempted (and if compilation fails, you will receive 0 marks for functionality).

        Your program must not invoke other programs or use non-standard headers/libraries.

        Your assignment submission must be committed to your subversion repository under

https://source.eait.uq.edu.au/svn/csse2310-sem2-sXXXXXXX/trunk/a1

where sXXXXXXX is your moss/UQ login ID. Only files at this top level will be marked so do not put source files in subdirectories. You may create subdirectories for other purposes (e.g. your own test files) but these will not be considered in marking – they will not be checked out of your repository.

        You must ensure that all files needed to compile and use your assignment (including a Makefile) are commit-ted and within the trunk/a1 directory in your repository (and not within a subdirectory) and not just sitting in your working directory. Do not commit compiled files or binaries. You are strongly encouraged to check out a clean copy for testing purposes.

        To submit your assignment, you must run the command

2310createzip a1

on moss and then submit the resulting zip file on Blackboard (a GradeScope submission link will be made available in the Assessment area on the CSSE2310/7231 Blackboard site). The zip file will be named

sXXXXXXX_csse2310_a1_timestamp.zip

where sXXXXXXX is replaced by your moss/UQ login ID and timestamp is replaced by a timestamp indicating the time that the zip file was created.

        The 2310createzip tool will check out the latest version of your assignment from the Subversion repository, ensure it builds with the command ‘make’, and if so, will create a zip file that contains those files and your Subversion commit history and a checksum of the zip file contents. You may be asked for your password as part of this process in order to check out your submission from your repository.

        You must not create the zip file using some other mechanism and you must not modify the zip file prior to submission. If you do so, you will receive zero marks. Your submission time will be the time that the file is submitted via GradeScope on Blackboard, and not the time of your last repository commit nor the time of creation of your submission zip file.

        If you make a submission prior to the deadline then your final submission prior to the deadline will be the submission that we mark – i.e. your last “on-time” submission will be marked. If your first submission is after the deadline (i.e. your submission is late) then that first submission will be the submission that we mark. A late penalty will apply in this case – see the CSSE2310/7231 course profile for details.

Marks

Marks will be awarded for functionality and style and documentation. Marks may be reduced if you are asked to attend an interview about your assignment and you are unable to adequately respond to questions – see the Student conduct section above.

Functionality (60 marks)

Provided your code compiles (see above) and does not use any prohibited statements/functions (see above), and your zip file has not been modified prior to submission, then you will earn functionality marks based on the number of features your program correctly implements, as outlined below. Partial marks will be awarded for partially meeting the functionality requirements. Not all features are of equal difficulty. If your program does not allow a feature to be tested then you will receive 0 marks for that feature, even if you claim to have implemented it. For example, if your program can never open a file, we can not determine if your program can unjumble letters correctly. If your program takes longer than 10 seconds to run any test, then it will be terminated and you will earn no marks for the functionality associated with that test. The markers will make no alterations to your code (other than to remove code without academic merit).

Marks will be assigned in the following categories.

1. Program correctly handles invalid command lines    (10 marks)

2. Program correctly handles dictionary files that are unable to be read    (3 marks)

3. Program correctly handles invalid sets of letters    (5 marks)

4. Program correctly unjumbles letters (without sorting)    (12 marks)

5. Program correctly unjumbles letters with the -include option (without sorting)    (8 marks)

6. Program correctly handles -alpha sorting (with and without -include)    (8 marks)

7. Program correctly handles -len sorting (with and without -include)    (8 marks)

8. Program correctly handles -longest output/sorting (with and without -include)    (6 marks)

It is unlikely that you can earn any marks for 6, 7 or 8 unless your program can correctly unjumble letters.

Style Marking

Style marking is based on the number of style guide violations, i.e. the number of violations of version 2.1 of the CSSE2310/CSSE7231 C Programming Style Guide (found on Blackboard). Style marks will be made up of two components – automated style marks and human style marks. These are detailed below. For assignment one, there is no weighting associated with human style marking – but you will be given feedback so that you can improve your style for later programming assignments.

        You should pay particular attention to commenting so that others can understand your code. The marker’s decision with respect to commenting violations is final – it is the marker who has to understand your code. To satisfy layout related guidelines, you may wish to consider the indent(1) tool. Your style marks can never be more than your functionality mark – this prevents the submission of well styled programs which don’t meet at least a minimum level of required functionality.

        You are encouraged to use the style.sh tool installed on moss to style check your code before submission. This does not check all style requirements, but it will determine your automated style mark (see below). Other elements of the style guide are checked by humans.

        All .c and .h files in your submission will be subject to style marking. This applies whether they are compiled/linked into your executable or not.

Automated Style Marking (5 marks)

Automated style marks will be calculated over all of your .c and .h files as follows: Let

● W be the total number of distinct compilation warnings and errors recorded when your .c files are individually built (using the correct compiler arguments)

● A be the total number of style violations detected by style.sh when it is run over each of your .c and .h files individually.

Your automated style mark S will be

S = 5 − (W + A)

        If W + A ≥ 5 then S will be zero (0) – no negative marks will be awarded. Note that in some cases style.sh may erroneously report style violations when correct style has been followed. If you believe that you have penalised incorrectly then please bring this to the attention of the course coordinator and your mark can be updated if this is the case.

Human Style Marking (5 marks) – not included in the assignment one total mark

Your human style mark will not be included in your total mark for assignment one, but feedback will be given so that you are better prepared for the later programming assignments.

● V will be the number of additional style violations detected by human markers. Violations will not be counted twice (e.g. if a poorly named variable is used multiple times it will count as a single violation).

Your human style mark H will be

H = 5 − V

        If V ≥ 5 then H will be zero (0) – no negative marks will be awarded. If your code has many style violations, human style marking may be incomplete, e.g. the marker may stop after reaching 5 violations.

SVN commit history assessment (5 marks) – not included in the assignment one total mark

Your SVN commit history mark will not be included in your total mark for assignment one, but feedback will be given so that you are better prepared for the later programming assignments.

        Markers will review your SVN commit history for your assignment up to your submission time. This element will be graded according to the following principles:

● Appropriate use and frequency of commits (e.g. a single monolithic commit of your entire assignment will yield a score of zero for this section)

● Appropriate use of log messages to capture the changes represented by each commit

        We understand that you are just getting to know Subversion, and you won’t be penalised for a few “test commit” type messages. However, the markers must get a sense from your commit logs that you are practising and developing sound software engineering practices by documenting your changes as you go. In general, tiny changes deserve small comments – larger changes deserve more detailed commentary.

Documentation (10 marks) – for CSSE7231 students only

CSSE7231 students must submit a PDF document containing a written overview of the architecture and design of your program. This must be submitted via the Turnitin submission link on Blackboard.

        Please refer to the grading criteria available on BlackBoard under “Assessment” for a detailed breakdown of how these submissions will be marked. Note that your submission time for the whole assignment will be considered to be the later of your submission times for your zip file and your PDF design document. Any late penalty will be based on this submission time and apply to your whole assignment mark. This document should describe, at a general level, the functional decomposition of the program, the key design decisions you made and why you made them. It must meet the following formatting requirements:

● Maximum two A4 pages in 12 point font

● Diagrams are permitted up to 25% of the page area. The diagram(s) must be discussed in the text, it is not ok to just include a figure without explanatory discussion.

        Don’t overthink this! The purpose is to demonstrate that you can communicate important design decisions, and write in a meaningful way about your code. To be clear, this document is not a restatement of the program specification – it is a discussion of your design and your code.

        If your documentation obviously does not match your code, you will get zero for this compo-nent, and will be asked to explain why.

Total mark

Let

● F be the functionality mark for your assignment (out of 60).

● S be the automated style mark for your assignment (out of 5).

● H be the human style mark for your assignment (out of 5) – not counted for assignment one.

● C be the SVN commit history mark (out of 5) – not counted for assignment one.

● D be the documentation mark for your assignment (out of 10 for CSSE7231 students) – or 0 for CSSE2310 students.

Your total mark for the assignment will be:

M = F + min{F, S} + min{F, D}

out of 65 (for CSSE2310 students) or 75 (for CSSE7231 students).

For future programming assignments, your total mark will be:

M = F + min{F, S + H} + min{F, C} + min{F, D}

out of 75 (for CSSE2310 students) or 85 (for CSSE7231 students).

        In other words, you can’t get more marks for style or SVN commit history or documentation than you do for functionality. Pretty code that doesn’t work will not be rewarded!

Late Penalties

Late penalties will apply as outlined in the course profile.

Specification Updates

Any errors or omissions discovered in the assignment specification will be added here, and new versions released with adequate time for students to respond prior to due date. Potential specification errors or omissions can be discussed on the discussion forum or emailed to [email protected].