Quantitative Requirements

This section describes the performance and IP requirements for the PuzzleMuncher software.

• All programs MUST NOT crash, core dump, dump a stack trace, or throw an exception on any input.
• In the case of a RECOVERABLE ERROR, a program MUST issue a warning statement and continue processing. The program MAY choose to issue the warning statement to standard error or to a log file. If the warning is issued to a log file, the log file name and location MUST be a user-specifiable parameter to the program.
• In the case of an UNRECOVERABLE ERROR, a program MUST issue an error statement and terminate with a non-zero error condition. The program MAY use different exit codes to indicate different error conditions, but such codes MUST be documented in the user manual. The error message MUST be logged to the same destination that warning messages (from RECOVERABLE ERRORS) are.
• In the case of any termination (whether normal, because a SEARCH-CTRL bound was met, or because of an UNRECOVERABLE ERROR), the program must cleanly flush and close all open files. No other data may be lost or destroyed.
• All normal output MUST be sent to the file(s) specified by the OUTFILE, ERRFILE, and LOGFILE commands. No other output may be generated, by default.
• The programs MAY provide additional output for debugging purposes, but such output must be disabled by default. Any program MAY provide a command-line switch to enable debugging support when desired.
• The search routine MUST recognize MONOTONIC heuristics and employ the most efficient possible search algorithm for them.
• The OPEN LIST data structure MUST be able to support the operations insert, remove-first, remove, and reinsert in $O(\log n)$ time for a list containing $n$ nodes. For extra credit, it MAY support one or more of these operations in $O(1)$ or amortized $O(1)$ time. To receive the extra credit, this feature MUST be documented in the user and API documentation for the search engine, the reasons for the improved performance MUST be described, and some performance documentation MUST be provided demonstrating the claimed time bounds.
• For full credit, the PuzzleMuncher program MUST NOT use or reference any of the built-in lexical analyzers provided by the JDK (i.e., java.util.StreamTokenizer, java.util.StringTokenizer, or java.util.regex.*).
• The PuzzleMuncher program MAY use the gnu.getopt.Getopt and gnu.getopt.LongOpt classes to assist in handling command-line options, if the programmer feels that it is useful to do so.
• The PuzzleMuncher program MAY assume that all valid input is standard ASCII text in the range (char)0-(char)127, inclusive. If a program encounters a character outside this range, it MAY treat it it as a RECOVERABLE or UNRECOVERABLE ERROR or silently ignore it. If such characters are treated as RECOVERABLE or ignored, they MUST NOT disrupt the otherwise normal functioning of the program.
• The program MUST NOT assume that the input is syntactically correct. If a syntax error occurs, the program MAY treat it as a RECOVERABLE or UNRECOVERABLE ERROR or silently ignore it. In all cases, the program MUST handle the error gracefully, reporting it only to the LOGFILE destination and terminating cleanly if necessary. It MUST NOT crash, core dump, or generate a stack trace. Any files that are open at termination MUST be cleanly flushed and closed.
• The programmer MAY ask permission of the instructor or the TA to use any classes outside the JDK that have not already been mentioned. The final programs MUST NOT use any class outside the JDK that have not been explicitly allowed.
• All user documentation MUST be grammatically correct and include correct spelling and usage.
• The programmer MUST document any areas in which her or his software suite does not meet this specification. WARNING! The grade penalty will be higher if the instructors discover an undocumented program shortcoming or bug than if it is documented up front.