Notation

Unless otherwise specified, anything prefixed with a $ character in a code block is a command, and all other content is command output. ... may be used to snip irrelevant output for brevity. # is used as an inline comment, and is neither a command nor output.

Most flags have both short and long forms. For instance, the flag to get the program version may be specified by either -V (capital V) or --version. This document will mostly provide flags in their long form, as their purpose is always more clear that way.

Note: All of the command syntax assumes that you have added the executable to your path, which is highly recommended. If you have not, make sure you prefix all invocations with the binary's qualified path, like in the following example, where grader is located in the ~ directory:
$ ~/grader lab1-2

...

Students Only

Example usage:

$ grader lab1-2

Remarks: More coming soon... Read the output of --help for now

Professor Only

Warning: Behavior is undefined if multiple students have the same first and last names.

Example usage:

$ profgrader lab1-2 --search-path ~/Documents/lab1-2-submissions

Short Form Output

For less verbose output to just get a list of student scores, invoke with the -q|--quiet flag.

$ profgrader lab1-2 -q
Jane Doe: Output score 100.00% (7/7 points)
John Doe: Output score 71.43% (5/7 points)
Alice Liddell: Could not locate executable
Bob Roberts: Output score 57.14% (4/7 points

Student Database

The student database contains a list of students' first and last names, and is used to aid in locating student lab submissions as well as to provide diagnostics for students with a missing submission. It is recommended to provide a student database; see not providing a database for more info.

By default, a database named students.csv in the current working directory will be used if it exists. To specify a database manually, provide the --database argument, like as follows:

$ profgrader lab1-2 --database ~/my-custom-database.csv

Not Providing a Database

Without a database, profgrader will search for submissions according to the specified assignment and file matcher RegEx. By default, the searching behavior is essentially identical to if a database had been provided, except that a student name may be matched by any sequence of alphabetic characters.

For example, the following invocation of profgrader will only match the files doejane_0000_0000_lab1-2.out and doejohn_0000_0000_lab1-2.out.

$ ls
doejohn_0000_0000_lab1-2.out    liddellalice_0000_0000_lab3-1.out  
doejane_0000_0000_lab1-2.out    robertsbob_0000_0000_lab5-3.out  
 
$ profgrader lab1-2

Remarks: More coming soon... Read the output of --help for now

Advanced Usage

For details on all supported arguments, use the --help flag.

$ grader --help

...

To check what version of the library you have, use the --version flag. When possible, versioning adheres to the semver spec. The field after -g is the hash of the latest git commit when built.

$ grader --version

AsmGrader v0.0.0-g123456789abcdef

Output Verbosity Level

To increase or decrease the level of output verbosity use the -v|--verbose or -q|--quiet flags, respectively. These flags may be repeated. --silent is an alias for the minimum level of verbosity.

$ grader <lab-name> --verbose
...
$ grader <lab-name> --quiet
...
$ grader <lab-name> -vvv
...
$ grader <lab-name> -qq
...
 
# etc. You get the idea
 
$ grader <lab-name> --silent
<no output>

Description of Levels

Professor mode is generally one level "quieter" than student mode for the output of each individual student
Each level includes all output from levels below, possibly formatted a little differently e.g., Setting the verbosity to FailedOnly results in all output described in: FailedOnly, Summary, and Quiet (though not the retcode from Silent)

Silent

Student - Nothing on stdout. Program return code = # of failed tests
Professor - Nothing on stdout. Program return code = # of students not passing all tests

Quiet

Student - Overall test results only (# of tests and requirements passed/failed)
Professor - Overall statistics only (# of students passed/failed, etc.)

Summary (default)

Student - Lists the names of all tests, but only failing requirements
Professor - Pass / fail stats for each individual student (like Quiet in student mode)

FailsOnly

Student - Same as Summary
Professor - Lists the names of all tests, but only failing requirements for each individual student

All

Student - Lists the result of all tests and requirements
Professor - Same as above, but for each individual student

Extra

(Not yet implemented)

Max