(****
 * 
 * Module InstructorInterface defines the basic objects and operations used by the instructor
 * interface. The instructor interface defines a workspace which will be used to open multiple documents.
 * Some of those documents include the Tests, QuestionBank(Shared and Local). Also the instructor uses the interface
 * to administer tests and upload them to the grader tool. These operations are defined in their respective modules in detail.
 * The interface simply provides the means for those documents to exist in the workspace. 
 *)
module InstructorInterface;

from TestGeneration import Test,Wizard;
from InstructorFile import FilePermissions;
from StudentInterface import length;
from InstructorEdit import PreviousState;
from TestAdminister import TeacherView;
from TestGrading import TestGradingView;
from QuestionBankModule import QuestionBank,QuestionBankSettings,LocalQuestionBank,SharedQuestionBank;
export TestFile, InstructorWorkspace,FileSaveDialog, Text, HighlightedText,
	FileName, Location, FileOpenDialog, FileSaveDialog,InstructorUserName, InstructorPassword,InstructorLogOnScreen, IsValid;

object TestFile is
	components: fp:FilePermissions and t:Test and lqb:LocalQuestionBank and sqb:SharedQuestionBank;
	operations: Save,SaveTestAs,OpenTest;
	description: (*
		A TestFile is the file representation of a test. The InstructorWorkSpace
		uses TestFile objects to open or save tests modified in the student
		interface. A TestFile must be readable and writable and can be saved
		on a computer accessible to the instructor.
	*);
 end TestFile;

object Text is 
	components: str:string and ps:PreviousState;
	operations: CopyText,PasteText;
	description:(* Text is simply a string on which edit operations can be performed
	*);
end Text;

 object HighlightedText is
	components: str:string and l:length;
	operations: CutText,CopyText;
	description: (*
		A HighlightedText object is a section or an entire body of text selected
		to be edited. The text can be cut, copied, erased, or replaced by another
		section or body of text. Any text that is highlighted should stand out from
		the rest of the text. The text should be bolded or be displayed in a different
		color than the rest of the text so the student can distinguish between
		highlighted and non-highlighted text.
	*);
 end HighlightedText;
object InstructorUserName is 
	components: str:string and valid:IsValid;
	operations: InstructorLogOnScreen, ExportToGrader;
	description: (*
		An InstructorUserName is a unique string that instructors use to authenticate 
		themseleves as and when needed in the Instructor Interface
 	*);
 end InstructorUserName;

 object InstructorPassword is 
	components: str:string and valid:IsValid;
	operations: InstructorLogOnScreen,ExportToGrader;
	description: (*
		A Password is a unique single encrypted string. Instructors use their individual passwords 
		along with their user names to authenticate themselves as and when needed in the  
		instructor interface.
	*);
 end InstructorPassword;
object IsValid is boolean
	operations: ServerLocation,ExportToGrader;
	description:(*
        	     * This is the variable that is set after the instructor's username and password are vaidated by the system
	     	     *);
end IsValid;
object InstructorLogOnScreen is
	components: un:InstructorUserName and ps:InstructorPassword;
	description: (*
		An instructor types in their Calpoly User ID and password into the Log on screen
		to gain access to components of the Instructor interface.
	*);
 end LogOnScreen;

object InstructorWorkspace is
	components: t:Test and lqb:LocalQuestionBank and sqb:SharedQuestionBank and los:InstructorLogOnScreen and wiz:Wizard and tv:TeacherView 
		    and qbs:QuestionBankSettings and tgv:TestGradingView and qb:QuestionBank;
	operations: NewTest,OpenTest,ExitInstructorInterface,AdministerTest,GradeTest,PassBackTest,closeGradedTests,ExportToGrader,OpenQuestionBankSetting,
		    OpenLocalQuestionBank,OpenSharedQuestionBank;
	description: (*
		      * The InstructorWorkSpace is the work space the instructor uses to generate tests,
		      *	connect to questions banks, edit tests, and grade tests within the instructor interface.
		      * It displays the operations of the InstructorFile, InstructorEdit, InstructorTests ,
                      * and InstructorQuestions modules as menu items titled
		      *	"File", "Edit", "Tests", and "Questions". The previous_state component is used to support
		      * one level of command undo. The Clipboard is used with the cut, copy, and paste operations. 
		      *);
end InstructorWorkspace;

object FileName is string
	description:(*The name of a file that can be opened in the workspace*);
end;

object Location is string
	description:(*Location specifies where the file is located*);
end;

object FileOpenDialog is
	components: FileName and Location;
	description: (*
		      * The FileOpenDialog is the dialog interface where a student may select only
		      * a test file to open into the student interface from a specific directory.
                      *);
end FileOpenDialog; 

object FileSaveDialog is
	components: FileName and Location;
	description: (*
		      * The FileSaveDialog is the dialog interface where an instructor may save the test
		      * or a question bank displayed in the instructor interface to a specific directory.
	              *);
end FileSaveDialog; 

end InstructorInterface;



(****
 * 
 * Module Instructor File defines the operations related to generating a new test,
 * opening an existing test, saving , printing , and exiting from the instructor
 * interface. The following objects are taken from the Calender Tool program: FilePermissions,
 * IsReadable, IsWritable, FileType, TestType, FileData, RequiresSaving.
 *)
module InstructorFile;

from InstructorInterface import TestFile, Test, FileSaveDialog, InstructorWorkspace;
from TestGeneration import Wizard;
from QuestionBankModule import QuestionBank, SharedQuestionBank,LocalQuestionBank;
export FilePermissions, IsReadable, IsWritable, FileType, TestType, FileData, RequiresSaving;

object FilePermissions is
	components: ir:IsReadable and iw:IsWritable;
	operations: OpenTest;
	description: (* 
		      * FilePermissions are permissions indicating if a file is readable and/or
		      * writable.
	              *);
end FilePermissions;

object IsReadable is boolean
	operations: OpenTest;
	description: (*
		      * A flag indicating if a file is readable, which must be true to carry out the
		      * OpenTest operation.
	              *);
end IsReadable;

object IsWritable is boolean
	operations:OpenTest,Save,SaveTestAs;
	description: (*
		      * A flag indicating if a file is writable, which must be true to carry out the
		      * SaveTest and SaveTestAs operations.
	              *);
end IsWritable;

object FileType is TestType
	operations: OpenTest;
	description: (*
		      * The type of file used by the student interface where data is of TestType 
	              * and can be stored in a file.
	              *);
end FileType;

object TestType is
	operations: OpenTest;
	description: (*
		      * File data tag that indicates if a file contains Test data made by the Test
		      * Tool program.
	              *);
end TestType;

object FileData is Test
	operations: OpenTest;
	description: (*
		      * FileData is a representation of a Test object. When implementing FileData,
		      * any file data object may be used that accurately holds a Test object.
	              *);
end FileData;

object RequiresSaving is boolean
    description: (*
                  * NeedsSaving is true if a test has been edited, which is true if one or more
                  * successful edit operations has been performed on the displayed test since the
                  * most recent save. The test edit operations are Undo, Redo, Cut, Copy, and Paste.
    *);
end RequiresSaving;

operation NewTest is
    	inputs: iws:InstructorWorkspace;
    	outputs: iws':InstructorWorkspace;

    	description: (*
        	      * Activates the test generation wizard
                      *);

    	precondition: true;
		
    	postcondition:
        (*
         * The workspace has a new wizard. It will require saving.
         *)
        (iws = iws');
end NewTest;

operation OpenTest is
	inputs: iw:InstructorWorkspace and tf:TestFile and permissions:FilePermissions and fd:FileData
		and ft:FileType and ir:IsReadable and tt:TestType;
	outputs: t:Test, iw':InstructorWorkspace;
	description: (*
		      * OpenTest will open a test file from a specific directory and display it in
		      * the instructor interface. The student may only open test files in the
		      * operation and not any other type of file.
	              *);
 	precondition:
	       (*
	 	* A test file must exist and be located in a directory that is accessible by the
	 	* student. The file must also be readable and the type of the file must be of type
	 	* test. This precondition is taken from the precondition of the FileOpen operation
	 	* of the Calander RSL specification.
	 	*)
		(exists (tf:TestFile) (tf.fp.ir));

 	postcondition:
	       (*
	 	* The test file is opened into the instructor interface filling in the entire
	 	* instructor interface area.
	 	*)
		(iw'.t = tf.t);
end OpenTest;

operation Save is
	inputs: t:Test and fsd: FileSaveDialog and iw:IsWritable;  
	outputs: tf':TestFile;
	description: (*
		      * SaveTest will save any changes made to the currently displayed Test in the
		      * instructor interface to the test file that contains the test. This option only
		      * updates the test file with the new changes that are not contained in the
		      * old test file and the file must be writable.
	              *);	
precondition:
	(*
	 * A test file must exist and be present within the instructor interface. IsWritable must
         * be true. 
	 *)
	(exists (tf:TestFile) (tf'.t = t) and (tf'.fp.iw = iw));

postcondition:
	(*
	 * Changes must have been made to the test in the instructor interface that are not
	 * contained in the old test file, or the test was newly created.
	 *)
	(tf'.t = t) and (tf'.fp.iw) and (tf'.fp.ir);
		
end Save;

operation SaveTestAs is
	inputs: t:Test and qb:QuestionBank and fsd:FileSaveDialog and iw:IsWritable;
	outputs: tf':TestFile;
	description: (*
		SaveTestAs will save the test file currently displayed in the instructor's interface
		as a new file in a specific directory. This operation can either create a new
		file with a new name or overwrite an old file that is writable with the same name. 
		If overwriting a file with the same name, the instructor must be prompted that saving
		the test file will overwrite the old file and if he wishes to continue.
	*);

 precondition:
	(*
	 * A test object must exist as an object that can be saved as a file and be displayed 
	 * in the instructors interface.
	 *)
	(t != nil) and (qb != nil);

 postcondition:
	(*
	 * A test file is made from the test object currently displayed in the instructors interface
	 * under a file name of the his choosing. The test file is saved in a directory
	 * accessible by the instructor.
	 *)
	(tf'.t = t) and (tf'.fp.ir) and (tf'.fp.iw);

 end SaveTestAs;

object UserWantsToSave is boolean
	description: (*
		UserWantsToSave is a state that tells the instructor interface if the instructor
		wants to save the changes made to a test.
	*);
 end UserWantsToSave;
operation ExitinstructorInterface is
	inputs: iw:InstructorWorkspace and tf:TestFile and uwts:UserWantsToSave;
	outputs: tf':TestFile;
	description: (*
		ExitinstructorInterface will close the Instructor interface and exit the program. If
		there is a test or a question bank in the Instructor interface that has been changed but not saved,
		a prompt will appear asking the Instructor if he would like to save the changes
		to the test before exiting the Instructor interface. 
	*);

 precondition:
	(*
	 * The Instructor can exit the application anytime during a session.
	 *)
	 true;

 postcondition:
	(*
	 * If a test or a question bank is displayed in the Instructor interface that has been changed but not saved,
	 * the Instructor is asked if he would like to save the changes to it before exiting.
	 *)
	if(iw.t != nil) or (iw.lqb != nil) or (iw.sqb != nil) then
		(if (uwts) then
			(tf'.fp.iw and tf'.fp.ir and tf'.t = iw.t)
			and
			(tf'.fp.iw and tf'.fp.ir and tf'.lqb = iw.lqb)
			and
			(tf'.fp.iw and tf'.fp.ir and tf'.sqb = iw.sqb)
			
		else
			(tf' = tf))
	else
		(tf' = nil);

 end ExitInstructorInterface;

end InstructorFile;



(****
 *
 * Module Instructor Edit defines the operations related to undo and redo. 
 * The following object definitions are taken from the Calander RSL specifictations:
 * Clipboard, TextSelection, StartPosition, EndPosition, Context, and State.
 *)

module InstructorEdit;

from InstructorInterface import Text, HighlightedText, InstructorWorkspace,length;
export Clipboard,State, PreviousState; 

object Clipboard is
	components: str:string and l:length;
	operations: CutText,CopyText,PasteText;
	description: (*
		Clipboard is a buffer that stores the TextSelection temporarily
	*);
 end Clipboard;

object State is boolean
	description: (*
		      * State is a flag indicating if a change has been made to a test displayed in the
		      * instructor interface.
	              *);
end State;

object PreviousState is State
	operations:UndoChange;
	description: (*
		PreviousState is a state of a test before the most recent change.
	*);
 end PreviousState;	

object PreviousText is Text
	operations:UndoChange;
	description: (*
		PreviousText is the original text before any recent change.
	*);
 end PreviousText;	
operation UndoChange is
	inputs: txt:PreviousText and ps:PreviousState;
	outputs: txt':Text;
	description: (*
		UndoChange reverts the most recent change made to the currently displayed Test
		in the student interface. The UndoChange operation can only undo changes made to
		the text answer of a question made by a student. The UndoChage operation can be
		used only one time.
	*);
	
 precondition:
	(*
	 * Some text must exist in the test and the text must have been changed at least once
	 * before the UndoChange operation can be used.
	 *)
	(txt'.ps);

 postcondition:
	(*
	 * The most recent change to the text on the test is reverted back to its original
	 * form before the most recent change was made.
	 *)
	(txt' = txt);

 end UndoChange;

operation CutText is
	inputs: htxt:HighlightedText and cp:Clipboard;
	outputs: ;
	description: (*
		CutText will remove a piece of highlighted text from the test currently displayed
		in student interface. The text will not be deleted, but will be temporarily saved
		on the Clipboard until he decides to put it back onto the test. 
	*);
 precondition:
	(*
	 * Some text must exist in the test and the student must manually highlight the text to
	 * be cut from the test.
	 *)
	true;
 
 postcondition:
	(*
	 * The highighted text is cut out from the test and saved as a temporary file on the 
	 * Clipboard.
	 *)
	(htxt.l = 0) and (cp.str = htxt.str);
 end CutText;

 operation CopyText is
	inputs: htxt:HighlightedText and cp:Clipboard;
	outputs: cptxt:Text;
	description: (*
		CopyText will copy a piece of highlighted text from the test currently displayed
		in the student interface. The copied text is saved on the Clipboard until the 
		student decides to put the copied text back onto the test.
	*);
 
 precondition:
	(*
	 * Some text must exist in the test and the student must manually highlight the text to
	 * be copied from the test.
	 *)
	true;

 postcondition:
	(*
	 * The highlighted text is copied from the test and saved as a temporary file on the
	 * Clipboard.
	 *)
	 (cp.str = htxt.str);

 end CopyText;

 operation PasteText is
	inputs: ctxt:Text and cptxt:Text and cb:Clipboard;
	outputs: Text;
	description: (*
		PasteText will place the string currently in the buffer to the current location of the 
		cursor in the active document*);
	
 precondition:
	(*
	 * The clipboard is not empty.
	 *)
	(cb.str != nil);

 postcondition:
	(*
	 * The text retrieved from the clipboard is placed to the current location of the cursor
	 *)
	true;

 end PasteText;


end InstructorEdit;



(****
 *
 * Module InstructorTests defines the objects and operations related to administering a test,   
 * grading tests, passing back tests, and exporting to the grader within the instructor 
 * interface. 
 *)

module InstructorTests;

from InstructorInterface import Test, TestFile, InstructorWorkspace,InstructorUserName,InstructorPassword,IsValid;
from QuestionModule import CorrectAnswer,QuestionText,Answer;
from TestAdminister import Status, QuestionView, CurrentQuestion, TeacherView, TestView,ClassTests;
from TestGrading import TestGradingView;
from InstructorFile import FilePermissions;
export Accessible;

object Accessible is boolean
	operations: GradeTest;
	description: (*
		Accessible is a flag indicating if a LocationAddress is accessible to the instructor from
		the instructor interface. 
	*);
 end Accessible;

object IsAvailable is boolean
	operations:PassBackTest;
	description:(* This is a flag to notify the system that the graded test is now available for the 
		students to view*);
end;

operation AdministerTest is
	inputs: iw:InstructorWorkspace;
	outputs: iw':InstructorWorkspace,tv:TeacherView;
        description: (*
                      * The teacher view of administering a test is displayed in the instructor workspace.
                      *);
        precondition: 
		(* The instructor can run this operation anytime he is ready to administer a test*)
		true;
	postcondition:
		(*
		 * The proctoring window is displayed in the intructor's interface
		 *)
		(iw'.tv = iw.tv);
end AdministerTest;

operation GradeTest is
	inputs: iw:InstructorWorkspace, a:Accessible, t:Test, ct:ClassTests;
	outputs: iw':InstructorWorkspace, tgv:TestGradingView;
	description: (*
		      * The instructor opens up the test that needs to be graded. This will open up the 
			Test Grading View.
		      *);
	precondition:
		(*
		 * A graded test file exsts and must be part of classtests.
		 *)
		exists (t:Test) t.aq != nil; 
	postcondition:		
		(* After the test file has been verified that it exists and is answered then, the workspace will have the test grading view 
		   displayed.*)	
		iw'.tgv = iw.tgv;
end GradeTest;

operation PassBackTest is
	inputs: iw:InstructorWorkspace,t:Test,ct:ClassTests, ia:IsAvailable;
	outputs: iw':InstructorWorkspace;
	description: (*
		      * The instructor makes the graded exam available for students who can then check their grades
		      *);
	precondition:
		(*
		 * The graded test exists 
		 *)
		exists (t:Test) t.gq != nil;
	postcondition:
		(*
		 * The graded test is now made available to students
		 *)
		t.ia;
end PassBackTest;

operation closeGradedTests is
	inputs: iw:InstructorWorkspace, t:Test;
	outputs: iw':InstructorWorkspace;
	description:(*After the gradedtest has been made available by the instructor, he may wish to close it 
		    so that no new student can access his test.This operation will make the graded tests unavailable*);
	precondition:
		(*The graded tests should be available*)
		t.ia;
	postcondition:
		(*The graded tests have now been made unavailable*)
		not(t.ia);
end closeGradedTests;

object ServerLocation is 
	components: str:string, valid:IsValid;
	operations: ExportToGrader;
	description:(*This is a pre determined location for the grader server.*);
end ServerLocation;

operation ExportToGrader is
	inputs: iw:InstructorWorkspace,t:Test,ct:ClassTests,un:InstructorUserName,ps:InstructorPassword, valid:IsValid, sl:ServerLocation;
	outputs: iw':InstructorWorkspace;
	description: (*
		      * The instructor takes all taken tests and export them to the grader tool
		      * for grading.
		      *);
	precondition:
		(*
		 * The test to be exported to the grader tool must be graded by the instructor. The loacation for the 
		 * grader server is a valid location. Also the instructor needs a valid user name and password to export a test
		 * file to the grader tool 
		 *)
		exists (at:AnsweredTest) t.gq != nil;
	postcondition:
		(*
		 * If the userName, Password and location is valid, then the chosen test will be exported to the 
		 * grader tool
		 *)
		if(un.valid and ps.valid) then
		Export(sl)
		else 
			iw' = iw;

end ExportToGrader;
function Export(sl:ServerLocation) -> (boolean) = sl.valid;
end InstructorTests;



(****
 *
 * Module InstructorQuestions defines the objects and operations related to setting up
 * local and shared question banks, connecting to local question banks, and connection to 
 * shared question banks within the instructor interface.
 *)

module InstructorQuestions;

from InstructorInterface import InstructorWorkspace,InstructorLogOnScreen,InstructorUserName,InstructorPassword,IsValid;
from InstructorTests import Accessible;
from QuestionBankModule import QuestionBank, LocalQuestionBank,SharedQuestionBank,QuestionBankSettings,
				LocalQuestionBankSettings,SharedQuestionBankSettings,LocalBankProfile,BankName,BankLocation,
				BankUserList,BankAdministrator,BankUR,Username,Password,SharedBankProfile;

operation OpenQuestionBankSetting is
	inputs: iw:InstructorWorkspace, qbs:QuestionBankSettings;
	outputs: iw':InstructorWorkspace;
	description: (*
		      * The instructor uses this option to setup his question bank setting. This will include
		      * local and shared question bank settings.
		      *);
	precondition:
		(*
		 *No other questionBank or QuestionBankSettings window should be open.
		 *)
		iw.qbs = nil and iw.lqb = nil and iw.sqb = nil;
	postcondition:
		(*
		 * The instructors workspace now contains the dialog to change question bank settings 
		 *)
		iw'.qbs = qbs;
end OpenQuestionBankSetting;

operation OpenLocalQuestionBank is
	inputs: iw:InstructorWorkspace, qbs:QuestionBankSettings;
	outputs: iw':InstructorWorkspace;
	description: (*
		      * The instructors can use this option to open up the local question bank, where he can edit questions.
		      *);
	precondition:
		(*
		 * The question bank exists within the instructor's local hard drive.
		 *)
		iw.lqb = nil and #(qbs.Lqbs.Lbp) > 0;
	postcondition:
		(*
		 * The question bank is opened up in the Instructor Interface.
		 *)
		iw'.lqb = qbs.Lqbs.Lbp[1].lqb;
end OpenLocalQuestionBank;

operation OpenSharedQuestionBank is
	inputs: iw: InstructorWorkspace, qbs:QuestionBankSettings;
	outputs: iw':InstructorWorkspace;
	description: (*
		      * The instructor enters his username and password in or to connect to the shared
		      * question bank. Once connected, the shared question bank opens within the 
		      * instructor's interface.
		      *);
	precondition: 
		(* 
		 * The log on screen appears and the username and password are authenticated by the system. If they are valid, then the shared 
		 * question bank will appear in the instructors interface.
		 *)
		 iw.sqb = nil and #(qbs.Sqbs.sbp) > 0 and exists(bur' in qbs.Sqbs.sbp[1].bul.bur) (qbs.Sqbs.sbp[1].un = bur'.un)
		and (qbs.Sqbs.sbp[1].pw = bur'.pw);

	postcondition:
		(*
		 * The shared question bank is displayed within the instructor's interface.
		 *)
		iw'.sqb = qbs.Sqbs.sbp[1].sqb;
end OpenSharedQuestionBank;

end InstructorQuestions;