Merge commit 'catalyst/MOODLE_19_STABLE' into mdl19-linuxchix
[moodle-linuxchix.git] / question / format / gift / format.php
blob506efa507656729a028c2f343d2a0161b6d0e785
1 <?php // $Id$
2 //
3 ///////////////////////////////////////////////////////////////
4 // The GIFT import filter was designed as an easy to use method
5 // for teachers writing questions as a text file. It supports most
6 // question types and the missing word format.
7 //
8 // Multiple Choice / Missing Word
9 // Who's buried in Grant's tomb?{~Grant ~Jefferson =no one}
10 // Grant is {~buried =entombed ~living} in Grant's tomb.
11 // True-False:
12 // Grant is buried in Grant's tomb.{FALSE}
13 // Short-Answer.
14 // Who's buried in Grant's tomb?{=no one =nobody}
15 // Numerical
16 // When was Ulysses S. Grant born?{#1822:5}
17 // Matching
18 // Match the following countries with their corresponding
19 // capitals.{=Canada->Ottawa =Italy->Rome =Japan->Tokyo}
21 // Comment lines start with a double backslash (//).
22 // Optional question names are enclosed in double colon(::).
23 // Answer feedback is indicated with hash mark (#).
24 // Percentage answer weights immediately follow the tilde (for
25 // multiple choice) or equal sign (for short answer and numerical),
26 // and are enclosed in percent signs (% %). See docs and examples.txt for more.
27 //
28 // This filter was written through the collaboration of numerous
29 // members of the Moodle community. It was originally based on
30 // the missingword format, which included code from Thomas Robb
31 // and others. Paul Tsuchido Shew wrote this filter in December 2003.
32 //////////////////////////////////////////////////////////////////////////
33 // Based on default.php, included by ../import.php
34 /**
35 * @package questionbank
36 * @subpackage importexport
38 class qformat_gift extends qformat_default {
40 function provide_import() {
41 return true;
44 function provide_export() {
45 return true;
48 function answerweightparser(&$answer) {
49 $answer = substr($answer, 1); // removes initial %
50 $end_position = strpos($answer, "%");
51 $answer_weight = substr($answer, 0, $end_position); // gets weight as integer
52 $answer_weight = $answer_weight/100; // converts to percent
53 $answer = substr($answer, $end_position+1); // removes comment from answer
54 return $answer_weight;
58 function commentparser(&$answer) {
59 if (strpos($answer,"#") > 0){
60 $hashpos = strpos($answer,"#");
61 $comment = substr($answer, $hashpos+1);
62 $comment = addslashes(trim($this->escapedchar_post($comment)));
63 $answer = substr($answer, 0, $hashpos);
64 } else {
65 $comment = " ";
67 return $comment;
70 function split_truefalse_comment($comment){
71 // splits up comment around # marks
72 // returns an array of true/false feedback
73 $bits = explode('#',$comment);
74 $feedback = array('wrong' => $bits[0]);
75 if (count($bits) >= 2) {
76 $feedback['right'] = $bits[1];
77 } else {
78 $feedback['right'] = '';
80 return $feedback;
83 function escapedchar_pre($string) {
84 //Replaces escaped control characters with a placeholder BEFORE processing
86 $escapedcharacters = array("\\:", "\\#", "\\=", "\\{", "\\}", "\\~", "\\n" ); //dlnsk
87 $placeholders = array("&&058;", "&&035;", "&&061;", "&&123;", "&&125;", "&&126;", "&&010" ); //dlnsk
89 $string = str_replace("\\\\", "&&092;", $string);
90 $string = str_replace($escapedcharacters, $placeholders, $string);
91 $string = str_replace("&&092;", "\\", $string);
92 return $string;
95 function escapedchar_post($string) {
96 //Replaces placeholders with corresponding character AFTER processing is done
97 $placeholders = array("&&058;", "&&035;", "&&061;", "&&123;", "&&125;", "&&126;", "&&010"); //dlnsk
98 $characters = array(":", "#", "=", "{", "}", "~", "\n" ); //dlnsk
99 $string = str_replace($placeholders, $characters, $string);
100 return $string;
103 function check_answer_count( $min, $answers, $text ) {
104 $countanswers = count($answers);
105 if ($countanswers < $min) {
106 $importminerror = get_string( 'importminerror', 'quiz' );
107 $this->error( $importminerror, $text );
108 return false;
111 return true;
115 function readquestion($lines) {
116 // Given an array of lines known to define a question in this format, this function
117 // converts it into a question object suitable for processing and insertion into Moodle.
119 $question = $this->defaultquestion();
120 $comment = NULL;
121 // define replaced by simple assignment, stop redefine notices
122 $gift_answerweight_regex = "^%\-*([0-9]{1,2})\.?([0-9]*)%";
124 // REMOVED COMMENTED LINES and IMPLODE
125 foreach ($lines as $key => $line) {
126 $line = trim($line);
127 if (substr($line, 0, 2) == "//") {
128 $lines[$key] = " ";
132 $text = trim(implode(" ", $lines));
134 if ($text == "") {
135 return false;
138 // Substitute escaped control characters with placeholders
139 $text = $this->escapedchar_pre($text);
141 // Look for category modifier
142 if (ereg( '^\$CATEGORY:', $text)) {
143 // $newcategory = $matches[1];
144 $newcategory = trim(substr( $text, 10 ));
146 // build fake question to contain category
147 $question->qtype = 'category';
148 $question->category = $newcategory;
149 return $question;
152 // QUESTION NAME parser
153 if (substr($text, 0, 2) == "::") {
154 $text = substr($text, 2);
156 $namefinish = strpos($text, "::");
157 if ($namefinish === false) {
158 $question->name = false;
159 // name will be assigned after processing question text below
160 } else {
161 $questionname = substr($text, 0, $namefinish);
162 $question->name = addslashes(trim($this->escapedchar_post($questionname)));
163 $text = trim(substr($text, $namefinish+2)); // Remove name from text
165 } else {
166 $question->name = false;
170 // FIND ANSWER section
171 // no answer means its a description
172 $answerstart = strpos($text, "{");
173 $answerfinish = strpos($text, "}");
175 $description = false;
176 if (($answerstart === false) and ($answerfinish === false)) {
177 $description = true;
178 $answertext = '';
179 $answerlength = 0;
181 elseif (!(($answerstart !== false) and ($answerfinish !== false))) {
182 $this->error( get_string( 'braceerror', 'quiz' ), $text );
183 return false;
185 else {
186 $answerlength = $answerfinish - $answerstart;
187 $answertext = trim(substr($text, $answerstart + 1, $answerlength - 1));
190 // Format QUESTION TEXT without answer, inserting "_____" as necessary
191 if ($description) {
192 $questiontext = $text;
194 elseif (substr($text, -1) == "}") {
195 // no blank line if answers follow question, outside of closing punctuation
196 $questiontext = substr_replace($text, "", $answerstart, $answerlength+1);
197 } else {
198 // inserts blank line for missing word format
199 $questiontext = substr_replace($text, "_____", $answerstart, $answerlength+1);
202 // get questiontext format from questiontext
203 $oldquestiontext = $questiontext;
204 $questiontextformat = 0;
205 if (substr($questiontext,0,1)=='[') {
206 $questiontext = substr( $questiontext,1 );
207 $rh_brace = strpos( $questiontext, ']' );
208 $qtformat= substr( $questiontext, 0, $rh_brace );
209 $questiontext = substr( $questiontext, $rh_brace+1 );
210 if (!$questiontextformat = text_format_name( $qtformat )) {
211 $questiontext = $oldquestiontext;
214 $question->questiontextformat = $questiontextformat;
215 $question->questiontext = addslashes(trim($this->escapedchar_post($questiontext)));
217 // set question name if not already set
218 if ($question->name === false) {
219 $question->name = $question->questiontext;
222 // ensure name is not longer than 250 characters
223 $question->name = shorten_text( $question->name, 200 );
224 $question->name = strip_tags(substr( $question->name, 0, 250 ));
226 // determine QUESTION TYPE
227 $question->qtype = NULL;
229 // give plugins first try
230 // plugins must promise not to intercept standard qtypes
231 // MDL-12346, this could be called from lesson mod which has its own base class =(
232 if (method_exists($this, 'try_importing_using_qtypes') && ($try_question = $this->try_importing_using_qtypes( $lines, $question, $answertext ))) {
233 return $try_question;
236 if ($description) {
237 $question->qtype = DESCRIPTION;
239 elseif ($answertext == '') {
240 $question->qtype = ESSAY;
242 elseif ($answertext{0} == "#"){
243 $question->qtype = NUMERICAL;
245 } elseif (strpos($answertext, "~") !== false) {
246 // only Multiplechoice questions contain tilde ~
247 $question->qtype = MULTICHOICE;
249 } elseif (strpos($answertext, "=") !== false
250 && strpos($answertext, "->") !== false) {
251 // only Matching contains both = and ->
252 $question->qtype = MATCH;
254 } else { // either TRUEFALSE or SHORTANSWER
256 // TRUEFALSE question check
257 $truefalse_check = $answertext;
258 if (strpos($answertext,"#") > 0){
259 // strip comments to check for TrueFalse question
260 $truefalse_check = trim(substr($answertext, 0, strpos($answertext,"#")));
263 $valid_tf_answers = array("T", "TRUE", "F", "FALSE");
264 if (in_array($truefalse_check, $valid_tf_answers)) {
265 $question->qtype = TRUEFALSE;
267 } else { // Must be SHORTANSWER
268 $question->qtype = SHORTANSWER;
272 if (!isset($question->qtype)) {
273 $giftqtypenotset = get_string('giftqtypenotset','quiz');
274 $this->error( $giftqtypenotset, $text );
275 return false;
278 switch ($question->qtype) {
279 case DESCRIPTION:
280 $question->defaultgrade = 0;
281 $question->length = 0;
282 return $question;
283 break;
284 case ESSAY:
285 $question->feedback = '';
286 $question->fraction = 0;
287 return $question;
288 break;
289 case MULTICHOICE:
290 if (strpos($answertext,"=") === false) {
291 $question->single = 0; // multiple answers are enabled if no single answer is 100% correct
292 } else {
293 $question->single = 1; // only one answer allowed (the default)
296 $answertext = str_replace("=", "~=", $answertext);
297 $answers = explode("~", $answertext);
298 if (isset($answers[0])) {
299 $answers[0] = trim($answers[0]);
301 if (empty($answers[0])) {
302 array_shift($answers);
305 $countanswers = count($answers);
307 if (!$this->check_answer_count( 2,$answers,$text )) {
308 return false;
309 break;
312 foreach ($answers as $key => $answer) {
313 $answer = trim($answer);
315 // determine answer weight
316 if ($answer[0] == "=") {
317 $answer_weight = 1;
318 $answer = substr($answer, 1);
320 } elseif (ereg($gift_answerweight_regex, $answer)) { // check for properly formatted answer weight
321 $answer_weight = $this->answerweightparser($answer);
323 } else { //default, i.e., wrong anwer
324 $answer_weight = 0;
326 $question->fraction[$key] = $answer_weight;
327 $question->feedback[$key] = $this->commentparser($answer); // commentparser also removes comment from $answer
328 $question->answer[$key] = addslashes($this->escapedchar_post($answer));
329 $question->correctfeedback = '';
330 $question->partiallycorrectfeedback = '';
331 $question->incorrectfeedback = '';
332 } // end foreach answer
334 //$question->defaultgrade = 1;
335 //$question->image = ""; // No images with this format
336 return $question;
337 break;
339 case MATCH:
340 $answers = explode("=", $answertext);
341 if (isset($answers[0])) {
342 $answers[0] = trim($answers[0]);
344 if (empty($answers[0])) {
345 array_shift($answers);
348 if (!$this->check_answer_count( 2,$answers,$text )) {
349 return false;
350 break;
353 foreach ($answers as $key => $answer) {
354 $answer = trim($answer);
355 if (strpos($answer, "->") === false) {
356 $giftmatchingformat = get_string('giftmatchingformat','quiz');
357 $this->error($giftmatchingformat, $answer );
358 return false;
359 break 2;
362 $marker = strpos($answer,"->");
363 $question->subquestions[$key] = addslashes(trim($this->escapedchar_post(substr($answer, 0, $marker))));
364 $question->subanswers[$key] = addslashes(trim($this->escapedchar_post(substr($answer, $marker+2))));
366 } // end foreach answer
368 return $question;
369 break;
371 case TRUEFALSE:
372 $answer = $answertext;
373 $comment = $this->commentparser($answer); // commentparser also removes comment from $answer
374 $feedback = $this->split_truefalse_comment($comment);
376 if ($answer == "T" OR $answer == "TRUE") {
377 $question->answer = 1;
378 $question->feedbacktrue = $feedback['right'];
379 $question->feedbackfalse = $feedback['wrong'];
380 } else {
381 $question->answer = 0;
382 $question->feedbackfalse = $feedback['right'];
383 $question->feedbacktrue = $feedback['wrong'];
386 $question->penalty = 1;
387 $question->correctanswer = $question->answer;
389 return $question;
390 break;
392 case SHORTANSWER:
393 // SHORTANSWER Question
394 $answers = explode("=", $answertext);
395 if (isset($answers[0])) {
396 $answers[0] = trim($answers[0]);
398 if (empty($answers[0])) {
399 array_shift($answers);
402 if (!$this->check_answer_count( 1,$answers,$text )) {
403 return false;
404 break;
407 foreach ($answers as $key => $answer) {
408 $answer = trim($answer);
410 // Answer Weight
411 if (ereg($gift_answerweight_regex, $answer)) { // check for properly formatted answer weight
412 $answer_weight = $this->answerweightparser($answer);
413 } else { //default, i.e., full-credit anwer
414 $answer_weight = 1;
416 $question->fraction[$key] = $answer_weight;
417 $question->feedback[$key] = $this->commentparser($answer); //commentparser also removes comment from $answer
418 $question->answer[$key] = addslashes($this->escapedchar_post($answer));
419 } // end foreach
421 //$question->usecase = 0; // Ignore case
422 //$question->defaultgrade = 1;
423 //$question->image = ""; // No images with this format
424 return $question;
425 break;
427 case NUMERICAL:
428 // Note similarities to ShortAnswer
429 $answertext = substr($answertext, 1); // remove leading "#"
431 // If there is feedback for a wrong answer, store it for now.
432 if (($pos = strpos($answertext, '~')) !== false) {
433 $wrongfeedback = substr($answertext, $pos);
434 $answertext = substr($answertext, 0, $pos);
435 } else {
436 $wrongfeedback = '';
439 $answers = explode("=", $answertext);
440 if (isset($answers[0])) {
441 $answers[0] = trim($answers[0]);
443 if (empty($answers[0])) {
444 array_shift($answers);
447 if (count($answers) == 0) {
448 // invalid question
449 $giftnonumericalanswers = get_string('giftnonumericalanswers','quiz');
450 $this->error( $giftnonumericalanswers, $text );
451 return false;
452 break;
455 foreach ($answers as $key => $answer) {
456 $answer = trim($answer);
458 // Answer weight
459 if (ereg($gift_answerweight_regex, $answer)) { // check for properly formatted answer weight
460 $answer_weight = $this->answerweightparser($answer);
461 } else { //default, i.e., full-credit anwer
462 $answer_weight = 1;
464 $question->fraction[$key] = $answer_weight;
465 $question->feedback[$key] = $this->commentparser($answer); //commentparser also removes comment from $answer
467 //Calculate Answer and Min/Max values
468 if (strpos($answer,"..") > 0) { // optional [min]..[max] format
469 $marker = strpos($answer,"..");
470 $max = trim(substr($answer, $marker+2));
471 $min = trim(substr($answer, 0, $marker));
472 $ans = ($max + $min)/2;
473 $tol = $max - $ans;
474 } elseif (strpos($answer,":") > 0){ // standard [answer]:[errormargin] format
475 $marker = strpos($answer,":");
476 $tol = trim(substr($answer, $marker+1));
477 $ans = trim(substr($answer, 0, $marker));
478 } else { // only one valid answer (zero errormargin)
479 $tol = 0;
480 $ans = trim($answer);
483 if (!(is_numeric($ans) || $ans = '*') || !is_numeric($tol)) {
484 $errornotnumbers = get_string( 'errornotnumbers' );
485 $this->error( $errornotnumbers, $text );
486 return false;
487 break;
490 // store results
491 $question->answer[$key] = $ans;
492 $question->tolerance[$key] = $tol;
493 } // end foreach
495 if ($wrongfeedback) {
496 $key += 1;
497 $question->fraction[$key] = 0;
498 $question->feedback[$key] = $this->commentparser($wrongfeedback);
499 $question->answer[$key] = '';
500 $question->tolerance[$key] = '';
503 return $question;
504 break;
506 default:
507 $giftnovalidquestion = get_string('giftnovalidquestion','quiz');
508 $this->error( $giftnovalidquestion, $text );
509 return false;
510 break;
512 } // end switch ($question->qtype)
514 } // end function readquestion($lines)
516 function repchar( $text, $format=0 ) {
517 // escapes 'reserved' characters # = ~ { ) : and removes new lines
518 // also pushes text through format routine
519 $reserved = array( '#', '=', '~', '{', '}', ':', "\n","\r");
520 $escaped = array( '\#','\=','\~','\{','\}','\:','\n','' ); //dlnsk
522 $newtext = str_replace( $reserved, $escaped, $text );
523 $format = 0; // turn this off for now
524 if ($format) {
525 $newtext = format_text( $format );
527 return $newtext;
530 function writequestion( $question ) {
531 // turns question into string
532 // question reflects database fields for general question and specific to type
534 // initial string;
535 $expout = "";
537 // add comment
538 $expout .= "// question: $question->id name: $question->name \n";
540 // get question text format
541 $textformat = $question->questiontextformat;
542 $tfname = "";
543 if ($textformat!=FORMAT_MOODLE) {
544 $tfname = text_format_name( (int)$textformat );
545 $tfname = "[$tfname]";
548 // output depends on question type
549 switch($question->qtype) {
550 case 'category':
551 // not a real question, used to insert category switch
552 $expout .= "\$CATEGORY: $question->category\n";
553 break;
554 case DESCRIPTION:
555 $expout .= '::'.$this->repchar($question->name).'::';
556 $expout .= $tfname;
557 $expout .= $this->repchar( $question->questiontext, $textformat);
558 break;
559 case ESSAY:
560 $expout .= '::'.$this->repchar($question->name).'::';
561 $expout .= $tfname;
562 $expout .= $this->repchar( $question->questiontext, $textformat);
563 $expout .= "{}\n";
564 break;
565 case TRUEFALSE:
566 $trueanswer = $question->options->answers[$question->options->trueanswer];
567 $falseanswer = $question->options->answers[$question->options->falseanswer];
568 if ($trueanswer->fraction == 1) {
569 $answertext = 'TRUE';
570 $right_feedback = $trueanswer->feedback;
571 $wrong_feedback = $falseanswer->feedback;
572 } else {
573 $answertext = 'FALSE';
574 $right_feedback = $falseanswer->feedback;
575 $wrong_feedback = $trueanswer->feedback;
578 $wrong_feedback = $this->repchar($wrong_feedback);
579 $right_feedback = $this->repchar($right_feedback);
580 $expout .= "::".$this->repchar($question->name)."::".$tfname.$this->repchar( $question->questiontext,$textformat )."{".$this->repchar( $answertext );
581 if ($wrong_feedback) {
582 $expout .= "#" . $wrong_feedback;
583 } else if ($right_feedback) {
584 $expout .= "#";
586 if ($right_feedback) {
587 $expout .= "#" . $right_feedback;
589 $expout .= "}\n";
590 break;
591 case MULTICHOICE:
592 $expout .= "::".$this->repchar($question->name)."::".$tfname.$this->repchar( $question->questiontext, $textformat )."{\n";
593 foreach($question->options->answers as $answer) {
594 if ($answer->fraction==1) {
595 $answertext = '=';
597 elseif ($answer->fraction==0) {
598 $answertext = '~';
600 else {
601 $export_weight = $answer->fraction*100;
602 $answertext = "~%$export_weight%";
604 $expout .= "\t".$answertext.$this->repchar( $answer->answer );
605 if ($answer->feedback!="") {
606 $expout .= "#".$this->repchar( $answer->feedback );
608 $expout .= "\n";
610 $expout .= "}\n";
611 break;
612 case SHORTANSWER:
613 $expout .= "::".$this->repchar($question->name)."::".$tfname.$this->repchar( $question->questiontext, $textformat )."{\n";
614 foreach($question->options->answers as $answer) {
615 $weight = 100 * $answer->fraction;
616 $expout .= "\t=%".$weight."%".$this->repchar( $answer->answer )."#".$this->repchar( $answer->feedback )."\n";
618 $expout .= "}\n";
619 break;
620 case NUMERICAL:
621 $expout .= "::".$this->repchar($question->name)."::".$tfname.$this->repchar( $question->questiontext, $textformat )."{#\n";
622 foreach ($question->options->answers as $answer) {
623 if ($answer->answer != '') {
624 $percentage = '';
625 if ($answer->fraction < 1) {
626 $pval = $answer->fraction * 100;
627 $percentage = "%$pval%";
629 $expout .= "\t=$percentage".$answer->answer.":".(float)$answer->tolerance."#".$this->repchar( $answer->feedback )."\n";
630 } else {
631 $expout .= "\t~#".$this->repchar( $answer->feedback )."\n";
634 $expout .= "}\n";
635 break;
636 case MATCH:
637 $expout .= "::".$this->repchar($question->name)."::".$tfname.$this->repchar( $question->questiontext, $textformat )."{\n";
638 foreach($question->options->subquestions as $subquestion) {
639 $expout .= "\t=".$this->repchar( $subquestion->questiontext )." -> ".$this->repchar( $subquestion->answertext )."\n";
641 $expout .= "}\n";
642 break;
643 case DESCRIPTION:
644 $expout .= "// DESCRIPTION type is not supported\n";
645 break;
646 case MULTIANSWER:
647 $expout .= "// CLOZE type is not supported\n";
648 break;
649 default:
650 // check for plugins
651 if ($out = $this->try_exporting_using_qtypes( $question->qtype, $question )) {
652 $expout .= $out;
654 else {
655 notify("No handler for qtype '$question->qtype' for GIFT export" );
658 // add empty line to delimit questions
659 $expout .= "\n";
660 return $expout;