(****
 *
 * Module Test Grading defines the objects and operations related to Grading a Test.
 * These operations and objects consist of connecting to a specific server and receiving
 * a grade file which is then edited or viewed.
 *
 *)

module TestGrading;

  from TestTaking import TakenTest, AnsweredQuestion, Server;
  from Publishing import PtsAvailable;
  from AdvancedTest import TestTitle;
  export all;

  object TestGrading is
    components: serverAuthentication:ServerAuthentication and availableTests:AvailableTests and editing:Editing;
    description: (*
      Test grading allows the user to fetch a specfic test and edit each
      students answers.
    *);
  end TestGrading;

  object ServerAuthentication is
    components: serverAddress:ServerAddress and userName:UserName and password:Password;
    description: (*
		The server authentication allows a user to securly connect a 
		specific server via UserName and Password.
    *);
  end ServerAuthentication;

  object AvailableTests is
    components: takenTest:TakenTest*;
    description: (*
		The AvailableTests allows a user to select a specific taken test
		to view or edit.
    *);
  end AvailableTests;

  object Editing is
    components: student:Student* and grading:Grading;
    description: (*
		The Editing allows a user to select a student's test and
		view or edit the grades or comments.
    *);
  end Editing;

  object ServerAddress is string
    description: (*
      Server address can be any type of acceptable address to a server 
      including IP address, Domain Name, etc.
    *);
  end ServerAddress;
  
  object User is
    components: userName:UserName and password:Password;
      description: (* A user has a name and a password. *);
  end User;

  object UserName is string
    description: (* User name on the specific server address. *);
  end UserName;

  object Password is string
    description: (* Specific server password the corresponds to the username. *);
  end Password;
  
  object Student is string
    description: (*
      A Student is a string in the typical CalPoly format (first intial 
      followed by the first few last name characters).
    *);
  end Student;

  object GradedQuestion inherits from AnsweredQuestion 
    components: grade:Grade and comment:Comment;
    description: (*
		A Graded Question takes an anwsered question and adds the score and comment.
    *);
  end GradedQuestion;
  
  object Grading is
    components: grade:Grade and comment:Comment;
    description: (*
		This allows the user to change to grade or leave a
		comment with gradign details or opinions.
    *);
  end Grading;
  
  object Grade is 
    components: response:Response and ptsReceived:PtsReceived and ptsAvailable:PtsAvailable;
    description: (*
      A grade is the spcific answer along with the number of points
      received and the total question point value.
    *);
  end Grade;
  
  object Comment is string
    description: (*
      A comment is a string that the teacher fills in to give
      hints or recomendations for the epcific question.
    *);
  end Comment;

  object Response is 
    components: correct:Correct or answer:Answer;
    description: (*
      The response is a short evaluation of the students answer. It will 
      display correct or the correct answer depending on the students answer.
    *);
  end Response;
   
  object PtsReceived is integer
    description: (*
      Points received is the total number of points the student received
      on the specific question.
    *);
  end PtsReceived;
  
  object TotalScore is integer
    description: (*
      Total score is the total number of points received for the whole test.
    *);
  end PtsReceived;
  
  object Correct is string;
  
  object Answer is string;
  
  object GradedTest inherits from TakenTest
    components: gradedQuestion:GradedQuestion* and totalScore:TotalScore;
    description: (*
      GradedTest is a TakenTest with comments and a grade assigned
      to each question.
    *);
  end GradedTest;

  operation GetGradedTest is
    inputs: serverAuthentication:ServerAuthentication and availableTests:AvailableTests;
    outputs: gradedTest:GradedTest;
    precondition: (* Make sure the list of available tests is not nil. *)
                  availableTests!=nil;
                  
    postcondition: (* Make sure the output test file was in the available tests to begin with. *)
                   gradedTest in availableTests;
                   
    description: (*
      The GetGradedTest operation will fetch a grade file from the entered server information
      and selected grade file.
    *);
  end GetGradedTest;

  operation ChangeComment is
    inputs: gradedTest:GradedTest and comment:Comment and gradedQuestion:GradedQuestion;
    outputs: gradedTest': GradedTest and gradedQuestion':GradedQuestion;
    precondition: (* The new comment can not equal the old comment *)
                  comment!=gradedQuestion.comment;
                  
    postcondition: (* The new comment is accurately transfered to the new gradedQuestion *)
                   comment=gradedQuestion'.comment;
                   
    description: (*
      The ChangeComment operation will take an existing GradedTest and overwrite
      the comment with the new comment.
    *);
  end ChangeComment;

  operation ChangeGrade is
    inputs: gradedTest:GradedTest and grade:Grade and gradedQuestion:GradedQuestion;
    outputs: gradedTest':GradedTest and gradedQuestion':GradedQuestion;
    precondition: (* The new grade can not equal the old grade *)
                  grade!=gradedQuestion.grade;
                  
    postcondition: (* The new grade is accurately transfered to the new gradedQuestion *)
                   grade=gradedQuestion'.grade;
                   
    description: (*
      The ChangeGrade operation will take an existing GradedTest and overwrite
      the grade with the new grade.
    *);
  end ChangeGrade;

  operation GradingLogin is
    inputs: server:Server and userName:UserName, password:Password, serverAddress:ServerAddress;
    outputs: takenTest:TakenTest*;
    precondition: (* 
                     Login to the given server to access the graded tests. If the user name
                     and password exist on the server's user list, then return the graded
                     test, otherwise nil.
                  *)
                  exists (user in server.user) (user.userName = userName) and (user.password = password)
                     and
                  (* Make sure the user specifies a userName. *)
                  userName!=nil
                      and
                  (* Make sure the user specifies a password. *)
                  password!=nil
                      and
                  (* Make sure the user specifies a server address. *)
                  serverAddress!=nil;
    postcondition: ;
    description: (*
      Login to the given server to access its list of taken tests. If the user name
      and password exist on the server's user list, then return the taken tests, otherwise
      nil.
    *);
  end GradingLogin;

 end TestGrading;