(****
 *
 * Module Question defines the objects and operations related to using the
 * Add / Edit Question Dialog to Add a new question to the database or modify an
 * existing one.
 *)

module Question;

  export all;

  object RawQuestion is
    components: questionTitle:QuestionTitle and questionClassName:QuestionClassName and questionType:QuestionType and questionDifficulty:QuestionDifficulty and questionTimeToComplete:QuestionTimeToComplete and questionKeywords:QuestionKeywords and questionBody:QuestionBody and questionAnswer:QuestionAnswer;
    description: (*
    *);
  end RawQuestion;

  object QuestionTitle is string
    description: (*
      Title of the Question. Must exist and cannot be a duplicate of another in database
    *);
  end QuestionTitle;

  object QuestionClassName is string
    description: (*
      Class for which question applies to. Can be left blank.
    *);
  end ClassName;

  object QuestionType is trueOrFalse:TrueOrFalse or numerical:Numerical or multipleChoice:MultipleChoice or matching:Matching or fillInTheBlanks:FillInTheBlanks or essay:Essay or embeddedCode:EmbeddedCode
    description: (*
      The type of question determines the type of answer provided by the instructor, and submitted by the student
    *);
  end QuestionType;

  object TrueOrFalse
    description: (*
      Question Type
    *);
  end TrueOrFalse;

  object Numerical
    description: (*
      Question Type
    *);
  end Numerical;

  object MultipleChoice
    description: (*
      Question Type
    *);
  end MultipleChoice;

  object Matching
    description: (*
      Question Type
    *);
  end Matching;

  object FillInTheBlanks
    description: (*
      Question Type
    *);
  end FillInTheBlanks;

  object Essay
    description: (*
      Question Type
    *);
  end Essay;

  object EmbeddedCode
    description: (*
      Question Type
    *);
  end EmbeddedCode;

  object QuestionDifficulty is integer
    description: (*
      Range is from 1-10.
    *);
  end QuestionDifficulty;

  object QuestionTimeToComplete is integer
    description: (*
      Average time it should take a student to complete the question. Must be at least one second for test-generation purposes.
    *);
  end TimeToComplete;

  object QuestionKeywords is string
    description: (*
      Used for organizational purposes. An optional field.
    *);
  end Keywords;

  object QuestionBody is
    components: bodyText:BodyText;
    description: (*
      Contains the text to present the question. May be
    *);
  end HeaderAndBody;

  object BodyText is bodyString:string and isHTML:IsHTML
    description: (*
      The entire body of the question. Included HTML tags if desired.
    *);
  end BodyText;

  object IsHTML is boolean
    description: (*
      Indicates to program whether or not to ignore HTML tags in the QuestionBody string
    *);
  end IsHTML;

  operation ParseHTML is
    inputs: stringToParse:string;
    outputs: bodyText:BodyText;
    description: (*
      Checks body text string for proper supported HTML tags. If no tags present, BodyText.isHTML set to FALSE. If improper tag usage detected, sends an error.
    *);
  end ParseHTML;

  object QuestionAnswer is trueOrFalseAnswer:TrueOrFalseAnswer or numericalAnswer:NumericalAnswer or multipleChoiceAnswer:MultipleChoiceAnswer or matchingAnswer:MatchingAnswer or fillInTheBlanksAnswer:FillInTheBlanksAnswer or essayAnswer:EssayAnswer or embeddedCodeAnswer:EmbeddedCodeAnswer
    description: (*
      Determined by value of QuestionType.
    *);
  end QuestionAnswer;

  object TrueOrFalseAnswer is
    components: isTrue:IsTrue;
    description: (*
      Instructor answer input for True Or False Questions
    *);
  end TrueOrFalseAnswer;

  object IsTrue is boolean
    description: (*
      Set to true if the TrueOrFalse question is a true statement
    *);
  end IsTrue;

  object NumericalAnswer is
    components: correctAnswer:CorrectAnswer and allowAnswerFuzziness:AllowAnswerFuzziness and answerFuzzinessType:AnswerFuzzinessType;
    description: (*
      Instructor answer input for Numerical Questions
     *);
  end NumericalAnswer;

  object CorrectAnswer is real
    description: (*
      The exact answer of a Numerical question
    *);
  end CorrectAnswer;

  object AllowAnswerFuzziness is boolean
    description: (*
      Set to true if one of the approximation techniques for accepting Numerical answers is to be enabled.
    *);
  end AllowAnswerFuzziness;

  object AnswerFuzzinessType is bounded:Bounded or significantDigits:SignificantDigits
    description: (*
      Determines the type of approximation technique used. Currently supports: Bounded and Significant Digits
    *);
  end AnswerFuzzinessType;

  object Bounded is
    components: boundedCondition:BoundedCondition and minBound:MinBound and maxBound:MaxBound;
    description: (*
Contains the information used in the Bounded approximation technique.
    *);
  end Bounded;

   object BoundedCondition is
    components: useMinBound:UseMinBound and useMaxBound:UseMaxBound;
    description: (*
      Determines whether the minimum and maximum bounds are enabled for the Bounded approximation technique. Any combination may be used.
    *);
  end BoundedCondition;

  object UseMinBound is boolean
    description: (*
      Determines whether the minimum bound is enabled for the Bounded approximation technique.
    *);
  end UseMinBound;

  object UseMaxBound is boolean
    description: (*
      Determines whether the maximum bound is enabled for the Bounded approximation technique.
    *);
  end UseMaxBound;

  object MinBound is real
    description: (*
      Contains the value for the minimum bound used in the Bounded approximation technique.
    *);
  end MinBound;

  object MaxBound is real
    description: (*
      Contains the value for the maximum bound used in the Bounded approximation technique.
    *);
  end MaxBound;

  operation CheckBounds is
    inputs: bounded:Bounded and correctAnswer:CorrectAnswer;
    outputs: checkBoundsState:boolean;
    description: (*
      Determines if the correct Numerical answer falls within the boundary specified by MinBound and MaxBound
    *);
  end CheckBounds;

  object SignificantDigits is
    components: numSignificantDigits:NumSignificantDigits;
    description: (*
      Contains the number of digits in the SignificantDigits approximation technique.
    *);
  end SignificantDigits;

  object NumSignificantDigits is integer
    description: (*
      The minimum amount of digit precision needed to accept a correct answer in the SignificantDigits approximation technique.
    *);
  end NumSignificantDigits;

  object MultipleChoiceAnswer is
    components: numResponses:NumResponses and responses:Responses*;
    description: (*
      Instructor answer input for Multiple Choice questions
    *);
  end MultipleChoiceAnswer;

  object NumResponses is integer
    description: (*
      The number of responses that have been inputted by the professor in a Multiple Choice question
    *);
  end NumberResponses;

  object Responses is
    components: responseText:ResponseText and isCorrect:IsCorrect and percentage:Percentage;
    description: (*
      The list of responses in a Multiple Choice question
    *);
  end Responses;

  object ResponseText is string
    description: (*
      The text shown for each response in a Multiple Choice questions
    *);
  end ResponseText;

  object IsCorrect is boolean
    description: (*
      Set to true if the response to a Multiple Choice question is a correct one
    *);
  end IsCorrect;

  object Percentage is integer
    description: (*
      A value (from 0-100%) which is multiplied by the point value of a Multiple Choice question to determine the amount of points rewarded when question is graded.
    *);
  end Percentage;

  operation AddResponse is
    inputs: responses:Responses* and responseText:ResponseText and isCorrect:IsCorrect and percentage:Percentage;
    outputs: Responses*;
    description: (*
      Adds a new Multiple Choice response to the collection of responses
    *);
  end AddResponse;

  operation DeleteResponse is
    inputs: responses:Responses*, whatResponse:integer;
    outputs: responses':Responses*;
    description: (*
      Removes a selected Multiple Choice from the collection of responses
    *);
  end DeleteResponses;


  object MatchingAnswer is
    components: numMatches:NumMatches and numCompleteMatches:NumCompleteMatches and matches:Matches*;
    description: (*
      Instructor answer input for Matching questions
    *);
  end MatchingAnswer;

  object NumMatches is integer
    description: (*
      The number of matches that have been inputted by the professor in a Matching question
    *);
  end NumMatches;

  object NumCompleteMatches is integer
    description: (*
      The number of matches that have been inputted by the professor in a Matching question that contain both a subject and definition
    *);
  end NumCompleteMatches;

  object Matches is
    components: subject:Subject and definition:Definition;
    description: (*
      The list of matches, containing a subject and definition string
    *);
  end Matches;

  object Subject is string
    description: (*
      The subject of a match. Optional field.
    *);
  end Subject;

  object Definition is string
    description: (*
      The definition of a match. Required field (if the subject is left blank, this definition will be used as an incorrect match)
    *);
  end Definition;

  operation AddMatch is
    inputs: matches:Matches* and subject:Subject and definition:Definition;
    outputs: matches':Matches*;
    description: (*
      Adds a new matching pair to a collection. Subject may be NULL.
    *);
  end AddMatch;

  operation DeleteMatch is
    inputs: matches:Matches*;
    outputs: matches':Matches*, whatMatch:integer;
    description: (*
      Removes a matching pair from a collection.
    *);
  end DeleteMatch;

  object FillInTheBlanksAnswer is
    components: fillInTheBlanksText:FillInTheBlanksText and fillInTheBlanksProcessed:FillInTheBlanksProcessed;
    description: (*
      Instructor answer input for Fill In The Blanks questions. (NOTE think of better wording for this)
    *);
  end FillInTheBlanks;

  object FillInTheBlanksText is string
    description: (*
      The text, including tagged blanks, for a Fill In The Blanks questions.
    *);
  end FillInTheBlanksText;

  object FillInTheBlanksProcessed is
    components: fillInTheBlanksTextParsed:FillInTheBlanksTextParsed and blank:Blank*;
    description: (*
      The object containing the text as seen in a published test, and the correct responses for the blanks
    *);
  end FillInTheBlanksProcessed;

  object FillInTheBlanksTextParsed is string
    description: (*
      The text, as seen in a published text, for a Fill In The Blanks questions.
    *);
  end FillInTheBlanksTextParsed;

  object Blank is string*
    description: (*
      The collection of correct responses for a particular blank
    *);
  end Blank;

  operation ParseFillInTheBlanksAnswer is
    inputs: fillInTheBlanksText:FillInTheBlanksText;
    outputs: fillInTheBlanksProcessed:FillInTheBlanksProcessed;
    description: (*
      Reads through the instructor input to a Fill In The Blanks Question. Any blanks, indicated by '<' and '>' tags are taken out of the text, and added to a new Blank object. Appropriate amounts of underline characters are placed at the positions of the stripped tags.
    *);
  end ParseFillInTheBlanksAnswer;


  object EssayAnswer is
    components: essayKeyWords:EssayKeywords;
    description: (*
      Instructor answer input for Essay questions
    *);
  end EssayAnswer;

  object EssayKeywords is string
    description: (*
      Contains a list of keywords, seperated by commas, that an instructor would expect to see in a student's submitted essay response.
    *);
  end EssayKeywords;

  object EmbeddedCodeAnswer is
    components: initialCode:InitialCode;
    description: (*
      Instructor answer input for Embedded Code questions
    *);
  end EmbeddedCodeAnswer;

  object InitialCode is string
    description: (*
      Contains "skeleton code" that includes any declerations and definitions that instructor wishes the student to initially have available when answering an Embedded Code question
    *);
  end InitialCode;

end Question;