(*
 * 2.7. Grading (grade.rsl) 
 * Module Grade defines the object and operations related to grading tests
 * in the Test Tool system.
 *
 * Jonathan Kees
 * CSC 205 - G. Fisher
 * 12/8/04
 *)

module Grade;

from StudentTesting import all;
from Question import all;
from Test import GeneratedTest;

object GradedTest inherits from CompletedTest
	components: GradedQuestion* and CompletedQuestion* and TotalPointsEarned and GradedTime and PostedTime and 
		    InstructorComment*;
	description: 
		(*
		 * This is a Test that has gone through Automatic grading and 
		 * manual grading if needed, has a final score, and also contains
		 * any comments from the instructor as well as a time it was Graded,
		 * Edited, and Posted.  TotalPointsEarned correlates to the total score of the test.
		 *);
end GradedTest;

object TotalPointsEarned is integer;

object Comment is string;

object GradedTime is string;

object PostedTime is string;


operation AutoGradeTest is
	inputs: CompletedTest*;
	outputs: GradedTest*;

	precondition:
		(* There exists a completed test to be Automatically graded.*)

		(CompletedTest != nil);

	postcondition:
		(* All True/False, Multiple Choice, Matching, and Fill in the Blank questions are
		 * graded automatically by comparing the student's answer with the key answer. *)

		(forall (i:integer | (i >= 1) and (i < #(CompletedTest)))
			(if (CompletedQuestion.ManuallyGrade = 0) then
				(CompletedQuestion = GradedQuestion)
				(if (StudentAnswer = KeyAnswer) then 
					(PointsEarned = PointsPossible)
				else (PointsEarned = 0))));

		(* If there are no questions not graded, a GradedTime is added to the GradedTest. *)

		(*(if (not (exists (CompletedQuestion in GradedTest))) then (GradedTest.GradedTime = CurrentTime));*)

	description:
		(*
		 * AutoGradeTest takes all types of questions that can be graded
		 * Automatically (True/False, Multiple Choice, Matching, Fill in the Blank)
		 * and grades them accordingly for the list of tests given to it using the Key.
		 * If the test is completely graded with the Automatic grading, a GradedTime is
		 * posted for the tests.
		 *);
end AutoGradeTest;

		
operation PostGrade is
	inputs: GradedTest*;
	outputs: gtest':GradedTest*, GradedTestStudentFile*;

	precondition:
		(* All questions in GradedTest are graded with a score. *)

		(GradedTest.GradedTime != nil);

	postcondition:
		(*
		 * All GradedTests information is transfered to a test file which the students may view
		 * with their grades and instructor comments included, and PostedTime field is updated.
		 *)

			(forall (i:integer | (i >= 1) and (i < #(GradedTest)))
				(GradedTest = GradedTestStudentFile) and GradedTest.PostedTime = CurrentTime);

	description : 
		(*
		 * PostGrade takes the student's graded tests and posts them for the students to receive,
		 * as well as giving them the option to notify the students via E-Mail as included in the
		 * Student information.  A PostedTime field is entered into the student's tests.
		 *);
end PostGrade;


operation EditScore is
	inputs: GradedTest, CompletedQuestion, PointsEarned, NewPointsEarned;
	outputs: GradedTest', GradedQuestion, PointsEarned';

	precondition: (* There exists a question for the PointsEarned to be changed to NewPointsEarned. *)

		(GradedTest.CompletedQuestion != nil) and (NewPointsEarned != nil);

	postcondition: 
		(* The PointsEarned for the selected question are changed to the input of
		   NewPointsEarned.  The total score for the test is changed as well. *)

		(CompletedQuestion.PointsEarned = NewPointsEarned) and
		(GradedTest.TotalPointsEarned = GradedTest.TotalPointsEarned + (NewPointsEarned - CompletedQuestion.PointsEarned));

	description:		
		(*
		 * EditScore takes an individual student's score (either for a particular question or for
		 * the total score of the test) and changes it to the value that the instructor chooses.
		 * An EditedTime field is entered with the respective test.
		 *);
end;


object NewPointsEarned is integer;


operation EditScoreAll is
	inputs: GradedTest*, GradedQuestion, PointsEarned*, PointChangeAmount;
	outputs: gtest':GradedTest*, pearned:PointsEarned*;

	precondition: 
		(* There exists a Graded Question in the list of GradedTests. *)

		(GradedTest.GradedQuestion != nil) and

		(* The PointChangeAmount is not 0. *)

		(PointChangeAmount != nil) and (PointChangeAmount != 0);

	postcondition:
		(* The PointsEarned of a particular question for a group of GradedTests is altered 
		 * by a PointChangeAmount. *)

		(GradedQuestion.pearned = (GradedQuestion.PointsEarned + PointChangeAmount)) and
		
		(* The respective GradedTests' TotalPointsEarned are changed to reflect PointChangeAmount. *)

		(GradedTest.TotalPointsEarned = (GradedTest.TotalPointsEarned + PointChangeAmount));

	description : 
		(*
		 * EditScoreAll takes an individual question's score or the total score for all of the 
		 * student's tests and either adds a certain amount to the respective grade, or subtracts
		 * a certain amount.  An EditedTime field is entered into every student's test.
		 *);
end EditScoreAll;


object PointChangeAmount is integer;


operation AddComment is
	inputs: GradedTest*, GradedQuestion, InstructorComment;
	outputs: gtest':GradedTest*;

	precondition:
		(* There exists a GradedTest with a selected GradedQuestion and a Comment to be added. *)

		(GradedTest != nil) and (InstructorComment != nil);

	postcondition:
		(* A Comment is added to the specific GradedQuestion or the GradedTest as a whole for a
		 * group of GradedTest.  The EditedTime field is updated for every GradedTest. *)

		(InstructorComment in gtest');

	description : 
		(*
		 * AddComment allows the instructor to insert a comment to either a specific question or
		 * the test as a whole, and have this visible to either a particular student, a group of
		 * students, or the entire class as a whole.
		 *);
end;


operation ViewByQuestion is
	inputs: GradedTest*;
	outputs: GradedTest*, GradedQuestion*;

	precondition:
		(* There exists a list of GradedTest*. *)
		
		(GradedTest != nil);

	postcondition:
		(* Test is shown with the grades displayed for each student for each question in alphabetaical order. *)

		(forall (i:integer | (i >= 1) and (i < #GradedTest))
			(GradedTest[i].StudentID < GradedTest[i+1].StudentID));

	description:
		(*
		 * Sorts the test grades by Question, showing each question along with the total in a list
		 * which the use can traverse, and for each question shows a table of each student that took 
		 * the test with their grade for the respective question.  This shows the test for all the
		 * students at one time.
		 *);
end;


operation ViewByStudent is
	inputs: GradedTest;
	outputs: GradedTest', GradedQuestion*;

	precondition:
		(* There exists a single selected GradedTest. *)

		(GradedTest != nil);

	postcondition:
		(* Test is shown for 1 student at a time. *)

		(GradedTest = GradedTest');

	description:
		(*
		 * Sorts the test grades by Students, in which there is a list of students that the user
		 * can traverse, with a second list of each question and the total for the student that can
		 * also be traversed.  This shows the test grades one student at a time.
		 *);
end ViewByStudent;


end Grade;