The Personal Self-Assessment Environment

PSAE File Format

Last modified: Wed Oct 13 10:39:26 HST 1999

Overview

This document specifies the format for PSAE (.qa) files. Note that this specification will be updated over the course of the semester with extensions to the syntax. However, the extensions will always be in a downward compatible format. In other words, files created with the syntax specified now will also be valid when the syntax is extended.

Recent additions to this specification are noted in italics.

Line orientation

PSAE files are line oriented. Blank lines are ignored. Lines whose first character is the "#" character are considered comments and are ignored. Lines whose first character is the ":" character indicate a declaration line. Lines whose first character is not a "#" or ":" are considered the textual data for the preceding declaration.

Syntax

A valid PSAE file consists of a set of question definitions. Each question definition consists of a set of declarations. Each question definition always begins with a :TYPE declaration. Other required declarations include :CAT, :TITLE, and :QUESTION.

A line containing only a ":" is considered an illegal line, since its first character is ":" (indicating a declaration" but there is no declaration defined as consisting of only the character ":".

A line containing ": TYPE" or ":TY PE" is also illegal, since there is no declaration consisting of only ":" and no declaration called ":TY".

Declarations can take arguments. These arguments are provided by adding a ":" to the end of the declaration followed by the argument. For example, ":TYPE:MC:N" and ":CAT:Anatomy and Physiology" are declarations with arguments. Valid arguments include the empty string (i.e. ":CAT:") and a string consisting of one or more blanks (":CAT: ").

The following sections detail the syntax of the current defined declarations. More declarations may be specified at a later date.

:TYPE

:TYPE is a required declaration. Any line beginning with :TYPE indicates the start of a new question declaration. All :TYPE declarations must contain an argument specifying the type of question.

The following arguments to :TYPE are supported:

"MC:N" This argument specifies that the question is of type multiple choice, where an arbitrary number of answers may be specified as correct. Note: you use the literal "N", not a number. You do not have to specify exactly how many answers there may be, only that more than one may be correct. (The implementation implication is that the GUI must use checkboxes rather than radio buttons.)

A legal question can contain only one :TYPE declaration.

:CAT

:CAT is a required declaration. :CAT specifies the category of the question. All :CAT declarations must contain an argument which is the name of the category. The category name must be contained on the remainder of the line containing the :CAT declaration. For example, a line containing ":CAT:Blue Bayou" declares the category of the question to be Blue Bayou.

A legal question can contain only one :CAT declaration.

:TITLE

:TITLE is a required declaration. :TITLE specifies a short title for the question. All :TITLE declarations must contain an argument which is the name of the title. The title name must be contained on the remainder of the line containing the :TITLE declaration. For example, a line containing ":TITLE:Package Defs" declares the title of the question to be Package Defs.

A legal question can contain only one :TITLE declaration.

Every title string must be unique. If you attempt to load a question with the same title as a previously loaded question, then you should signal an error during loading that a question with a duplicate title was encountered, discard this question, and continue loading the the next question.

:QUESTION

:QUESTION is a required declaration. It currently takes no arguments, but may take them in the future.

All lines following the line containing the :QUESTION declaration, up until the next occurrence of a line containing a declaration, are interpreted as the text of the question. Important note: The text of a question declaration must be formatted to ensure that no lines in the question begin with a ":" or a "#", otherwise the line will be interpreted as a command or a comment, respectively.

There must be at least one non-blank, non-comment line following a :QUESTION declaration and before the next declaration. In other words, the text of a question cannot be empty.

A legal question can contain only one :QUESTION declaration.

:ANSWER

:ANSWER is an optional declaration. It currently takes a single argument, which is a number from 0 to 100 specifying the percentage of credit to be awarded for checking that answer. To create a multiple choice question with a single right answer, the right answer should get 100 and all of the rest should get 0. To create a question with two right answers, the two right answers should get 50 each (or 60 and 40, etc.) and the wrong answers should get zero.

A legal question may have zero, one, or many :ANSWER declarations.

All lines following the line containing the :ANSWER declaration, up until the next occurrence of a line containing a declaration, are interpreted as the text of the answer. Important note: The text of an answer declaration must be formatted to ensure that no lines in the question begin with a ":" or a "#", otherwise the line will be interpreted as a command or a comment, respectively.

There must be at least one non-blank, non-comment line following a :ANSWER declaration and before the next declaration. In other words, the text of an answer cannot be empty.

:DIFFICULTY

:DIFFICULTY is an optional declaration. It currently requires a single argument, which is a number from 0 to 100 specifying the difficulty of the question. (0 represents least difficult, 100 represents most difficult.) If a question does not contain the :DIFFICULTY declaration, then that question is assumed to have a difficult value of 0.

A legal question can contain only one :DIFFICULTY declaration.

Example File

Here is an example file containing PSAE declarations.

# example.qa
# Author          : Philip Johnson
# Created On      : Fri Aug 27 13:56:07 1999
# Last Modified By: Philip Johnson
# Last Modified On: Fri Aug 27 14:02:09 1999

#First question

:TYPE:MC:N

:CAT:Leap stuff

:TITLE:Leap acronym

:DIFFICULTY:50

:QUESTION
What does the Leap acronym stand for?

:ANSWER:0
Lipid, executable, antisocial, potable
:ANSWER:0
Langurous, ecommerce, attitudinal, pernicious
:ANSWER:100
Lightweight, empirical, anti-measurement dysfunction, portable

#end of question 1
:TYPE:MC:N
:CAT:Leap stuff
:TITLE:Leap language
:QUESTION
Which of the following programming languages were used
in the development of Leap?
:ANSWER:0
C
:ANSWER:0
PERL

#end of second question

Philip Johnson