The Requirements Document is split into three sections, which deal with the screen appearance, match functions, and auxiliary functions which are needed to define a context within which to use the match functions.
The screen is divided into two areas: display, and message.
This is for the prototype functions only; in a CBT environment, it would be better to place some, if not all, messages (and instructions) in the centre of the screen, probably using a window which overlays text, and then removes it when the student has read the message (indicated by pressing a key) or complied with an instruction/command.
There are three stages in the matching process:
These processes were split, even though it is not always necessary to do this, so that collection and analysis of answers need not be in the same section of a program. This also aids when deciding where to branch (the analyse functions would be replaced by branch instructions in a fully functioning system).
getanswer(length) --> answer_string
This gets an answer (ie answer_string) from the keyboard. It will not accept answers longer than the allowed length (80 characters in this prototype). The function writes a continuous line, 'length' characters long, under the location where the answer must be typed. (The location of the start of the line can be set using the set-cursor function). The cursor is put at the beginning of the line, and is not allowed to travel past the end of it, thus constraining the length of the answer. (A message to this effect is generated in the message area). The line is not erased as the student writes the answer.
mc(question_stem, optionlist) --> result
This uses a moving block cursor to accept a multiple choice answer. The block is moved by pressing the up/ down arrows; the movement is cyclical, so if the block is on the last option, and the down arrow is pressed, the block will move to the first option. The block always appears on the first option when the function is called. An option is selected by pressing the enter key.
The optionlist consists of a list of strings. There must be between two and six, otherwise on calling the function an author error message will be generated.
The stem, and answer options can have a maximum length of 80 characters (ie one line) each.
The length of the moving block is set to the length of the longest answer option.
The stem and the answer options are written to the screen, starting on the row following the current cursor location, in column one, and separated by one line. It is the author's duty to ensure that scrolling does not occur, by clearing all or part of the screen if necessary, prior to calling the multiple choice match function. (if the function automatically cleared the screen an author would not have the option of leaving previous text on display).
'Result' is a character, either corresponding to an integer in the range 1 to length(optionlist), or '?', which indicates that the "don't know" function key was pressed. The advantage of having a matchresult that returns the student's selection, rather than just a more general acceptance or rejection, is that very specific branching action can be taken if desired. Note that if the result were to be only one of acceptance or rejection, then the function would need to be given the number of the correct option in the optionlist.
This is a prototype; a more advanced function would cater for a stem and answer options of possibly many different lines each, and would alter the cursor block accordingly. There might be provision for more than six answer options. Rather than having an optionlist of character strings, these strings could previously be assigned to string variables, so that they could be re-used easily in other parts of the program.
alphamatch(model, answer, [match_params]) --> result
This function looks for an exact character match bet- ween the model and answer, but punctuation, spaces,' case, and spelling errors will be ignored, unless spec- ified otherwise in the match parameters (described below).
result is one of:
T : required character match found.
F : characters do not match.
? : "don't know" function key pressed.
findword(model, answer, [match_parameters]) --> result
This function determines whether the model is contained in the answer. Punctuation, spaces, case, and spelling errors will be ignored, unless specified otherwise in match-parameters (described below).
result is one of:
T : model contained in answer.
F : model not contained in answer.
? : "don't know" function key was pressed.
match any(n, model, answer, [match_params]) --> result
Searches for any n words from a list, n indicates the minimum number acceptable. The order of the words in the answer is not important. Punctuation, spaces, case, and spelling errors will be ignored, unless specified otherwise in the match_parameters. n must be between two and the number of words in the model (inclusive), and also it must always be less than 10, otherwise an author error will be generated when the function is called. (So for this prototype an author cannot search for more than nine words in a text string). If an author wishes to search for just one word, s/he should use the function findword.
result is one of:
T : (true), the required number of words has been found.
F : (false), total failure, no match found.
? : the "don't know" key was pressed.
i : (where i is a character corresponding to an integer in the range I to 8, and i is less than the input parameter, n). i corresponds to the number of words matched, and indicates that a complete match for the required number of words was not found.
match ordered(n, model, answer, [match_params]) --> result
This is similar to match_any, except that the order of words in the answer is important. Punctuation, spaces, case, and spelling errors will be ignored, unless specified otherwise in the match_parameters. n must be between 2 and the number of words in model (inclusive), and also it must always be less than 10, otherwise an author error message will be generated when the function is called. (So for this prototype an author cannot search for more than nine words in a text string). If an author wishes to search for just one word, s/he should use the function findword.
result is one of:
T : (true), the required number of words in the correct order has been found.
F : (false), total failure, no match found.
Z : the "don't know" key was pressed.
i : (where i is a character corresponding to an integer in the range 1 to 8, and i is less than or equal to the input parameter, n). i corresponds to the number of words matched, and indicates that a complete match for the required number of words was not found and/or the order of words found was incorrect.
MATCH PARAMETERS
The match_parameter list applies to all the match functions, and is optional in all cases (this is indicated by []). Any combination, or all (which is equivalent to the E option) may be chosen. If there is no list, then the default will chosen. The default can be set by the author at the start of the program, using the set match parameters function. If this is not done, then the default is to ignore Blanks (spaces), Case, Punctuation, and Spelling.
E = exact character match required
B = blanks (spaces) important
C = case important
P = punctuation important
S = spelling important
In addition to these parameters, there are the wildcard and wildcharacter symbols which can be used in the model answer. These take precedence over the E and S options for the word(s) they occur in.
In the case of spelling errors that the function is able to deal with, a message will appear in the message area, saying (for each word in which an error was found) that the word is acceptable, on the assumption that the student meant to type the model.
Exclusions are not specifically dealt with in these functions, to reduce the complexity as perceived by the author. To check for these the author merely has to call the function twice with the same student answer, the first time looking for any exclusions).
These functions do not handle ranking or matching question types well. Future work could focus on the development of a ranking function which ideally (from pedagogic and Human-Computer Interface viewpoints) would use visual/graphic means to accept an answer and demonstrate the correct/best results. For example, lines could be drawn between pairs of items to be matched; with a mouse this would be easy for the student.
The user has specifically requested two functions; one to deal with real, and one to deal with integer numbers. At a later stage, a combined function which accepts either form of answer, and a function to deal with fractions could be written.
matchinteger(model, answer, [matchtype]) --> result
This will search for a valid integer number within a text string. The integer may be preceded by a plus (+), or minus (-) sign. If. no number, or an incorrectly written integer number, or more than one number is found, an appropriate error message (with an example of an integer number) will be displayed, and the student will be asked to re-enter the answer. The company supervisor made the final decision regarding what should be considered valid and invalid input.
Examples of valid and invalid input:
| valid | 123 | |
| valid | <text>123<text> | |
| invalid | 1 23 | (space considered as text) |
| invalid | 1w23 | (two integers, separated by text) |
| invalid | 123.0 | (real number) |
MATCH TYPE
| E | exact |
| Rn-m | range(n lower, m = upper) |
| An | absolute accuracy, + or - n |
| Pn | percentage accuracy, n = percentage |
Rn-m and An are not both necessary, since An is subsumed by Rn-m. However, the distinction makes the author's job a little easier, inasmuch as An is simpler, and is likely to be used more frequently. An alternative to specifying the model and the absolute upper and lower limits would be to specify just the limits. However, an advantage to the former method is that the two types of success (exact, within limits) detailed below are possible.
If matchtype is not specified (either when the function is called, or using the set -match_parameters function, then the default is for an exact match.
matchreal(model, answer, [matchtype]) --> result
This will search for a valid real number within a text string. The number may be preceded by a plus (+) , or minus (-) sign. If no real number, or an incorrectly written real number, or more than one real number is found, or an integer number is found, an appropriate error message (with an example of a real number) will be displayed, and the student will be asked to re-enter the answer. This function will accept both the British format and the European format for real numbers.
Examples of valid and invalid input:
| valid | 123.0 | British format |
| valid | 123,0 | European format |
| valid | 123456.0 | British format |
| valid | 123,456.7 | British format |
| valid | 123 456.7 | British format |
| invalid | 123 456,7 | European format does not use spaces |
| invalid | 123 | integer number |
| invalid | 123m456.7 | separated by text |
| invalid | 123,456,7 | British format, no decimal point |
| invalid | 123.456.7 | European format, no decimal comma |
| invalid | 123,4.5 | British format, digits must be in groups of three working from the right of the decimal point |
MATCH TYPE
| E | exact |
| D | number of decimal places required for exact match |
| An | absolute accuracy, + or - n |
| Pn | percentage accuracy, n = percentage |
If matchtype is not specified (either when the function is called, or using the set - match_parameters function), then the default is for an exact match, where D = number of digits after decimal point in the model.
There is a difficulty with allowing both European and British formats for real numbers. Consider "123,45". This could be an integer number (British format), or a real number (European format). In order to overcome this, there is function (used at the beginning of a session) which asks the student which format he/she would prefer to use.
result (applicable to both number match functions)
T = (true) exact match found
0 = Ok, within allowed limits
F = fail, number not matched
? = "don't know" function key was pressed.
These functions could have been bundled into one large package; there are no theoretical constraints regarding cohesion or coherence (section 6.1), since these functions are for an end user (ie author), and should be structured according to his/her needs/wants. However, the company's project supervisor preferred separate functions.
analyse_mc(model, match result) --> message
model is the correct option number for any given multiple choice optionlist. Match - result is the student's selection (or '?' if the "don't know" key was pressed).
IF match result = model
THEN output 'correct' message (incorporating model)
IF match result = ?
THEN output 'help' message (incorporating model)
ELSE output 'wrong answer' message (incorporating model)
analyse_number(model, match result) --> message
model is the model sup-plied to the number match function. match-result is a character, one of {T, 0, F, ?}, returned by the number match function.
IF match result = T
THEN output 'correct' message (incorporating model)
IF match result = 0
THEN output 'acceptable' answer, message (incorporating model)
IF match result = F
THEN output 'wrong answer' message (incorporating model)
IF match result = ?
THEN output 'help' message (incorporating model)
analyse_string(model, match result) --> message
model is the model supplied to the string match function. match_result is a character, one of T, F, ?, 1, 2, 3, 4, 5, 6, 7, B. This function deals with match_results for all the string match functions.
IF match-result = T
THEN output 'correct' message (incorporating model)
IF match result = F
THEN output 'wrong answer' message (incorporating model)
IF match result = ?
THEN output 'help' message (incorporating model)
ELSE output 'partially correct answer' message (incorporating model and match result). Logically, match result must be in {1, 2, 3, 4, 5, 6, 7, 8} and therefore indicates the number of words found in match_any or match_ordered.
The following functions are used in conjunction with the match functions. In no way are they comprehensive, but for the purposes of development of the match functions, they suffice to give a context within which to work.
clearall
Clears the whole screen, including message area. The cursor is set to row 1, column 1.
cleardisplay
Clears the display area (main screen), but not the message area. The cursor is set to row 1, column 1 in the display area.
clear(row_n, row_m)
Clears the display screen between row n and row m inclusive. If the cursor is outside the area to be cleared, its position is not changed, otherwise it is set to row n, column 1 in the display screen.
Allowed values: n >= m AND n >=l, AND m <= 19 (depends on screen).
message(text)
Clears the message area, and then writes text (maximum four lines for twenty-five line screen). The cursor location in the display area is not changed.
pause
This waits for the user to press any key to continue. A standard message in the message area is generated telling the user to do this. The cursor position is not changed.
putcursor(row_x, column_y)
Locates the cursor at row x, column y in the display area. If the coordinates are outside the range available, a message is generated.
set_match_params(parameter_list)
Sets up standard parameters to be used (where applicable) in all the match functions. These may be overridden by specifying match parameters in a function call (these will not change the standard parameters. In fact, they must not, otherwise problems will arise when branching takes place).
write(text)
Writes text of any length, starting at the current cursor location, and changes the current cursor position to the screen position following the message. If the number of text rows plus the current row number is greater than the available screen rows, scrolling will occur. For any one line, if the number of text columns plus the current column number is greater than the width of the screen (or window), wrapround will occur.
Preface | Contents | 1 Introduction | 2 Review | 3 Req. analysis | 4 Req. documents (4A, 4B) | 5 Specification | 6 Design | 7 Verification | 8 Discussion | 9 PAL manual | Appendix A | Appendix B | Appendix C | Glossary | References | Index