2 // This file is part of Moodle - http://moodle.org/
4 // Moodle is free software: you can redistribute it and/or modify
5 // it under the terms of the GNU General Public License as published by
6 // the Free Software Foundation, either version 3 of the License, or
7 // (at your option) any later version.
9 // Moodle is distributed in the hope that it will be useful,
10 // but WITHOUT ANY WARRANTY; without even the implied warranty of
11 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12 // GNU General Public License for more details.
14 // You should have received a copy of the GNU General Public License
15 // along with Moodle. If not, see <http://www.gnu.org/licenses/>.
18 * GIFT format question importer/exporter.
22 * @copyright 2003 Paul Tsuchido Shew
23 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
27 defined('MOODLE_INTERNAL') ||
die();
31 * The GIFT import filter was designed as an easy to use method
32 * for teachers writing questions as a text file. It supports most
33 * question types and the missing word format.
35 * Multiple Choice / Missing Word
36 * Who's buried in Grant's tomb?{~Grant ~Jefferson =no one}
37 * Grant is {~buried =entombed ~living} in Grant's tomb.
39 * Grant is buried in Grant's tomb.{FALSE}
41 * Who's buried in Grant's tomb?{=no one =nobody}
43 * When was Ulysses S. Grant born?{#1822:5}
45 * Match the following countries with their corresponding
46 * capitals.{=Canada->Ottawa =Italy->Rome =Japan->Tokyo}
48 * Comment lines start with a double backslash (//).
49 * Optional question names are enclosed in double colon(::).
50 * Answer feedback is indicated with hash mark (#).
51 * Percentage answer weights immediately follow the tilde (for
52 * multiple choice) or equal sign (for short answer and numerical),
53 * and are enclosed in percent signs (% %). See docs and examples.txt for more.
55 * This filter was written through the collaboration of numerous
56 * members of the Moodle community. It was originally based on
57 * the missingword format, which included code from Thomas Robb
58 * and others. Paul Tsuchido Shew wrote this filter in December 2003.
60 * @copyright 2003 Paul Tsuchido Shew
61 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
63 class qformat_gift
extends qformat_default
{
65 public function provide_import() {
69 public function provide_export() {
73 public function export_file_extension() {
77 protected function answerweightparser(&$answer) {
78 $answer = substr($answer, 1); // removes initial %
79 $end_position = strpos($answer, "%");
80 $answer_weight = substr($answer, 0, $end_position); // gets weight as integer
81 $answer_weight = $answer_weight/100; // converts to percent
82 $answer = substr($answer, $end_position+
1); // removes comment from answer
83 return $answer_weight;
86 protected function commentparser($answer, $defaultformat) {
87 $bits = explode('#', $answer, 2);
88 $ans = $this->parse_text_with_format(trim($bits[0]), $defaultformat);
89 if (count($bits) > 1) {
90 $feedback = $this->parse_text_with_format(trim($bits[1]), $defaultformat);
92 $feedback = array('text' => '', 'format' => $defaultformat, 'files' => array());
94 return array($ans, $feedback);
97 protected function split_truefalse_comment($answer, $defaultformat) {
98 $bits = explode('#', $answer, 3);
99 $ans = $this->parse_text_with_format(trim($bits[0]), $defaultformat);
100 if (count($bits) > 1) {
101 $wrongfeedback = $this->parse_text_with_format(trim($bits[1]), $defaultformat);
103 $wrongfeedback = array('text' => '', 'format' => $defaultformat, 'files' => array());
105 if (count($bits) > 2) {
106 $rightfeedback = $this->parse_text_with_format(trim($bits[2]), $defaultformat);
108 $rightfeedback = array('text' => '', 'format' => $defaultformat, 'files' => array());
110 return array($ans, $wrongfeedback, $rightfeedback);
113 protected function escapedchar_pre($string) {
114 //Replaces escaped control characters with a placeholder BEFORE processing
116 $escapedcharacters = array("\\:", "\\#", "\\=", "\\{", "\\}", "\\~", "\\n" ); //dlnsk
117 $placeholders = array("&&058;", "&&035;", "&&061;", "&&123;", "&&125;", "&&126;", "&&010"); //dlnsk
119 $string = str_replace("\\\\", "&&092;", $string);
120 $string = str_replace($escapedcharacters, $placeholders, $string);
121 $string = str_replace("&&092;", "\\", $string);
125 protected function escapedchar_post($string) {
126 //Replaces placeholders with corresponding character AFTER processing is done
127 $placeholders = array("&&058;", "&&035;", "&&061;", "&&123;", "&&125;", "&&126;", "&&010"); //dlnsk
128 $characters = array(":", "#", "=", "{", "}", "~", "\n" ); //dlnsk
129 $string = str_replace($placeholders, $characters, $string);
133 protected function check_answer_count($min, $answers, $text) {
134 $countanswers = count($answers);
135 if ($countanswers < $min) {
136 $this->error(get_string('importminerror', 'qformat_gift'), $text);
143 protected function parse_text_with_format($text, $defaultformat = FORMAT_MOODLE
) {
146 'format' => $defaultformat,
149 if (strpos($text, '[') === 0) {
150 $formatend = strpos($text, ']');
151 $result['format'] = $this->format_name_to_const(substr($text, 1, $formatend - 1));
152 if ($result['format'] == -1) {
153 $result['format'] = $defaultformat;
155 $result['text'] = substr($text, $formatend +
1);
158 $result['text'] = trim($this->escapedchar_post($result['text']));
162 public function readquestion($lines) {
163 // Given an array of lines known to define a question in this format, this function
164 // converts it into a question object suitable for processing and insertion into Moodle.
166 $question = $this->defaultquestion();
168 // define replaced by simple assignment, stop redefine notices
169 $gift_answerweight_regex = '/^%\-*([0-9]{1,2})\.?([0-9]*)%/';
171 // REMOVED COMMENTED LINES and IMPLODE
172 foreach ($lines as $key => $line) {
174 if (substr($line, 0, 2) == '//') {
179 $text = trim(implode(' ', $lines));
185 // Substitute escaped control characters with placeholders
186 $text = $this->escapedchar_pre($text);
188 // Look for category modifier
189 if (preg_match('~^\$CATEGORY:~', $text)) {
190 // $newcategory = $matches[1];
191 $newcategory = trim(substr($text, 10));
193 // build fake question to contain category
194 $question->qtype
= 'category';
195 $question->category
= $newcategory;
199 // QUESTION NAME parser
200 if (substr($text, 0, 2) == '::') {
201 $text = substr($text, 2);
203 $namefinish = strpos($text, '::');
204 if ($namefinish === false) {
205 $question->name
= false;
206 // name will be assigned after processing question text below
208 $questionname = substr($text, 0, $namefinish);
209 $question->name
= $this->clean_question_name($this->escapedchar_post($questionname));
210 $text = trim(substr($text, $namefinish+
2)); // Remove name from text
213 $question->name
= false;
216 // Find the answer section.
217 $answerstart = strpos($text, '{');
218 $answerfinish = strpos($text, '}');
220 $description = false;
221 if ($answerstart === false && $answerfinish === false) {
222 // No answer means it's a description.
227 } else if ($answerstart === false ||
$answerfinish === false) {
228 $this->error(get_string('braceerror', 'qformat_gift'), $text);
232 $answerlength = $answerfinish - $answerstart;
233 $answertext = trim(substr($text, $answerstart +
1, $answerlength - 1));
236 // Format the question text, without answer, inserting "_____" as necessary.
238 $questiontext = $text;
239 } else if (substr($text, -1) == "}") {
240 // No blank line if answers follow question, outside of closing punctuation.
241 $questiontext = substr_replace($text, "", $answerstart, $answerlength +
1);
243 // Inserts blank line for missing word format.
244 $questiontext = substr_replace($text, "_____", $answerstart, $answerlength +
1);
247 // Look to see if there is any general feedback.
248 $gfseparator = strrpos($answertext, '####');
249 if ($gfseparator === false) {
250 $generalfeedback = '';
252 $generalfeedback = substr($answertext, $gfseparator +
4);
253 $answertext = trim(substr($answertext, 0, $gfseparator));
256 // Get questiontext format from questiontext.
257 $text = $this->parse_text_with_format($questiontext);
258 $question->questiontextformat
= $text['format'];
259 $question->questiontext
= $text['text'];
261 // Get generalfeedback format from questiontext.
262 $text = $this->parse_text_with_format($generalfeedback, $question->questiontextformat
);
263 $question->generalfeedback
= $text['text'];
264 $question->generalfeedbackformat
= $text['format'];
266 // set question name if not already set
267 if ($question->name
=== false) {
268 $question->name
= $this->create_default_question_name($question->questiontext
, get_string('questionname', 'question'));
271 // determine QUESTION TYPE
272 $question->qtype
= NULL;
274 // give plugins first try
275 // plugins must promise not to intercept standard qtypes
276 // MDL-12346, this could be called from lesson mod which has its own base class =(
277 if (method_exists($this, 'try_importing_using_qtypes') && ($try_question = $this->try_importing_using_qtypes($lines, $question, $answertext))) {
278 return $try_question;
282 $question->qtype
= 'description';
284 } else if ($answertext == '') {
285 $question->qtype
= 'essay';
287 } else if ($answertext{0} == '#') {
288 $question->qtype
= 'numerical';
290 } else if (strpos($answertext, '~') !== false) {
291 // only Multiplechoice questions contain tilde ~
292 $question->qtype
= 'multichoice';
294 } else if (strpos($answertext, '=') !== false
295 && strpos($answertext, '->') !== false) {
296 // only Matching contains both = and ->
297 $question->qtype
= 'match';
299 } else { // either truefalse or shortanswer
301 // truefalse question check
302 $truefalse_check = $answertext;
303 if (strpos($answertext, '#') > 0) {
304 // strip comments to check for TrueFalse question
305 $truefalse_check = trim(substr($answertext, 0, strpos($answertext,"#")));
308 $valid_tf_answers = array('T', 'TRUE', 'F', 'FALSE');
309 if (in_array($truefalse_check, $valid_tf_answers)) {
310 $question->qtype
= 'truefalse';
312 } else { // Must be shortanswer
313 $question->qtype
= 'shortanswer';
317 if (!isset($question->qtype
)) {
318 $giftqtypenotset = get_string('giftqtypenotset', 'qformat_gift');
319 $this->error($giftqtypenotset, $text);
323 switch ($question->qtype
) {
325 $question->defaultmark
= 0;
326 $question->length
= 0;
330 $question->responseformat
= 'editor';
331 $question->responsefieldlines
= 15;
332 $question->attachments
= 0;
333 $question->graderinfo
= array(
334 'text' => '', 'format' => FORMAT_HTML
, 'files' => array());
338 if (strpos($answertext,"=") === false) {
339 $question->single
= 0; // multiple answers are enabled if no single answer is 100% correct
341 $question->single
= 1; // only one answer allowed (the default)
343 $question = $this->add_blank_combined_feedback($question);
345 $answertext = str_replace("=", "~=", $answertext);
346 $answers = explode("~", $answertext);
347 if (isset($answers[0])) {
348 $answers[0] = trim($answers[0]);
350 if (empty($answers[0])) {
351 array_shift($answers);
354 $countanswers = count($answers);
356 if (!$this->check_answer_count(2, $answers, $text)) {
360 foreach ($answers as $key => $answer) {
361 $answer = trim($answer);
363 // determine answer weight
364 if ($answer[0] == '=') {
366 $answer = substr($answer, 1);
368 } else if (preg_match($gift_answerweight_regex, $answer)) { // check for properly formatted answer weight
369 $answer_weight = $this->answerweightparser($answer);
371 } else { //default, i.e., wrong anwer
374 list($question->answer
[$key], $question->feedback
[$key]) =
375 $this->commentparser($answer, $question->questiontextformat
);
376 $question->fraction
[$key] = $answer_weight;
377 } // end foreach answer
382 $question = $this->add_blank_combined_feedback($question);
384 $answers = explode('=', $answertext);
385 if (isset($answers[0])) {
386 $answers[0] = trim($answers[0]);
388 if (empty($answers[0])) {
389 array_shift($answers);
392 if (!$this->check_answer_count(2,$answers,$text)) {
396 foreach ($answers as $key => $answer) {
397 $answer = trim($answer);
398 if (strpos($answer, "->") === false) {
399 $this->error(get_string('giftmatchingformat','qformat_gift'), $answer);
403 $marker = strpos($answer, '->');
404 $question->subquestions
[$key] = $this->parse_text_with_format(
405 substr($answer, 0, $marker), $question->questiontextformat
);
406 $question->subanswers
[$key] = trim($this->escapedchar_post(
407 substr($answer, $marker +
2)));
413 list($answer, $wrongfeedback, $rightfeedback) =
414 $this->split_truefalse_comment($answertext, $question->questiontextformat
);
416 if ($answer['text'] == "T" OR $answer['text'] == "TRUE") {
417 $question->correctanswer
= 1;
418 $question->feedbacktrue
= $rightfeedback;
419 $question->feedbackfalse
= $wrongfeedback;
421 $question->correctanswer
= 0;
422 $question->feedbacktrue
= $wrongfeedback;
423 $question->feedbackfalse
= $rightfeedback;
426 $question->penalty
= 1;
431 // Shortanswer question.
432 $answers = explode("=", $answertext);
433 if (isset($answers[0])) {
434 $answers[0] = trim($answers[0]);
436 if (empty($answers[0])) {
437 array_shift($answers);
440 if (!$this->check_answer_count(1, $answers, $text)) {
444 foreach ($answers as $key => $answer) {
445 $answer = trim($answer);
448 if (preg_match($gift_answerweight_regex, $answer)) { // check for properly formatted answer weight
449 $answer_weight = $this->answerweightparser($answer);
450 } else { //default, i.e., full-credit anwer
454 list($answer, $question->feedback
[$key]) = $this->commentparser(
455 $answer, $question->questiontextformat
);
457 $question->answer
[$key] = $answer['text'];
458 $question->fraction
[$key] = $answer_weight;
464 // Note similarities to ShortAnswer
465 $answertext = substr($answertext, 1); // remove leading "#"
467 // If there is feedback for a wrong answer, store it for now.
468 if (($pos = strpos($answertext, '~')) !== false) {
469 $wrongfeedback = substr($answertext, $pos);
470 $answertext = substr($answertext, 0, $pos);
475 $answers = explode("=", $answertext);
476 if (isset($answers[0])) {
477 $answers[0] = trim($answers[0]);
479 if (empty($answers[0])) {
480 array_shift($answers);
483 if (count($answers) == 0) {
485 $giftnonumericalanswers = get_string('giftnonumericalanswers','qformat_gift');
486 $this->error($giftnonumericalanswers, $text);
490 foreach ($answers as $key => $answer) {
491 $answer = trim($answer);
494 if (preg_match($gift_answerweight_regex, $answer)) { // check for properly formatted answer weight
495 $answer_weight = $this->answerweightparser($answer);
496 } else { //default, i.e., full-credit anwer
500 list($answer, $question->feedback
[$key]) = $this->commentparser(
501 $answer, $question->questiontextformat
);
502 $question->fraction
[$key] = $answer_weight;
503 $answer = $answer['text'];
505 //Calculate Answer and Min/Max values
506 if (strpos($answer,"..") > 0) { // optional [min]..[max] format
507 $marker = strpos($answer,"..");
508 $max = trim(substr($answer, $marker+
2));
509 $min = trim(substr($answer, 0, $marker));
510 $ans = ($max +
$min)/2;
512 } else if (strpos($answer, ':') > 0) { // standard [answer]:[errormargin] format
513 $marker = strpos($answer, ':');
514 $tol = trim(substr($answer, $marker+
1));
515 $ans = trim(substr($answer, 0, $marker));
516 } else { // only one valid answer (zero errormargin)
518 $ans = trim($answer);
521 if (!(is_numeric($ans) ||
$ans = '*') ||
!is_numeric($tol)) {
522 $errornotnumbers = get_string('errornotnumbers');
523 $this->error($errornotnumbers, $text);
528 $question->answer
[$key] = $ans;
529 $question->tolerance
[$key] = $tol;
532 if ($wrongfeedback) {
534 $question->fraction
[$key] = 0;
535 list($notused, $question->feedback
[$key]) = $this->commentparser(
536 $wrongfeedback, $question->questiontextformat
);
537 $question->answer
[$key] = '*';
538 $question->tolerance
[$key] = '';
544 $this->error(get_string('giftnovalidquestion', 'qformat_gift'), $text);
550 protected function repchar($text, $notused = 0) {
551 // Escapes 'reserved' characters # = ~ {) :
553 $reserved = array( '\\', '#', '=', '~', '{', '}', ':', "\n", "\r");
554 $escaped = array('\\\\', '\#','\=','\~','\{','\}','\:', '\n', '' );
556 $newtext = str_replace($reserved, $escaped, $text);
561 * @param int $format one of the FORMAT_ constants.
562 * @return string the corresponding name.
564 protected function format_const_to_name($format) {
565 if ($format == FORMAT_MOODLE
) {
567 } else if ($format == FORMAT_HTML
) {
569 } else if ($format == FORMAT_PLAIN
) {
571 } else if ($format == FORMAT_MARKDOWN
) {
579 * @param int $format one of the FORMAT_ constants.
580 * @return string the corresponding name.
582 protected function format_name_to_const($format) {
583 if ($format == 'moodle') {
584 return FORMAT_MOODLE
;
585 } else if ($format == 'html') {
587 } else if ($format == 'plain') {
589 } else if ($format == 'markdown') {
590 return FORMAT_MARKDOWN
;
596 public function write_name($name) {
597 return '::' . $this->repchar($name) . '::';
600 public function write_questiontext($text, $format, $defaultformat = FORMAT_MOODLE
) {
602 if ($text != '' && $format != $defaultformat) {
603 $output .= '[' . $this->format_const_to_name($format) . ']';
605 $output .= $this->repchar($text, $format);
610 * Outputs the general feedback for the question, if any. This needs to be the
611 * last thing before the }.
612 * @param object $question the question data.
613 * @param string $indent to put before the general feedback. Defaults to a tab.
614 * If this is not blank, a newline is added after the line.
616 public function write_general_feedback($question, $indent = "\t") {
617 $generalfeedback = $this->write_questiontext($question->generalfeedback
,
618 $question->generalfeedbackformat
, $question->questiontextformat
);
620 if ($generalfeedback) {
621 $generalfeedback = '####' . $generalfeedback;
623 $generalfeedback = $indent . $generalfeedback . "\n";
627 return $generalfeedback;
630 public function writequestion($question) {
633 // Start with a comment
634 $expout = "// question: $question->id name: $question->name\n";
636 // output depends on question type
637 switch($question->qtype
) {
640 // not a real question, used to insert category switch
641 $expout .= "\$CATEGORY: $question->category\n";
645 $expout .= $this->write_name($question->name
);
646 $expout .= $this->write_questiontext($question->questiontext
, $question->questiontextformat
);
650 $expout .= $this->write_name($question->name
);
651 $expout .= $this->write_questiontext($question->questiontext
, $question->questiontextformat
);
653 $expout .= $this->write_general_feedback($question, '');
658 $trueanswer = $question->options
->answers
[$question->options
->trueanswer
];
659 $falseanswer = $question->options
->answers
[$question->options
->falseanswer
];
660 if ($trueanswer->fraction
== 1) {
661 $answertext = 'TRUE';
662 $rightfeedback = $this->write_questiontext($trueanswer->feedback
,
663 $trueanswer->feedbackformat
, $question->questiontextformat
);
664 $wrongfeedback = $this->write_questiontext($falseanswer->feedback
,
665 $falseanswer->feedbackformat
, $question->questiontextformat
);
667 $answertext = 'FALSE';
668 $rightfeedback = $this->write_questiontext($falseanswer->feedback
,
669 $falseanswer->feedbackformat
, $question->questiontextformat
);
670 $wrongfeedback = $this->write_questiontext($trueanswer->feedback
,
671 $trueanswer->feedbackformat
, $question->questiontextformat
);
674 $expout .= $this->write_name($question->name
);
675 $expout .= $this->write_questiontext($question->questiontext
, $question->questiontextformat
);
676 $expout .= '{' . $this->repchar($answertext);
677 if ($wrongfeedback) {
678 $expout .= '#' . $wrongfeedback;
679 } else if ($rightfeedback) {
682 if ($rightfeedback) {
683 $expout .= '#' . $rightfeedback;
685 $expout .= $this->write_general_feedback($question, '');
690 $expout .= $this->write_name($question->name
);
691 $expout .= $this->write_questiontext($question->questiontext
, $question->questiontextformat
);
693 foreach($question->options
->answers
as $answer) {
694 if ($answer->fraction
== 1) {
696 } else if ($answer->fraction
== 0) {
699 $weight = $answer->fraction
* 100;
700 $answertext = '~%' . $weight . '%';
702 $expout .= "\t" . $answertext . $this->write_questiontext($answer->answer
,
703 $answer->answerformat
, $question->questiontextformat
);
704 if ($answer->feedback
!= '') {
705 $expout .= '#' . $this->write_questiontext($answer->feedback
,
706 $answer->feedbackformat
, $question->questiontextformat
);
710 $expout .= $this->write_general_feedback($question);
715 $expout .= $this->write_name($question->name
);
716 $expout .= $this->write_questiontext($question->questiontext
, $question->questiontextformat
);
718 foreach($question->options
->answers
as $answer) {
719 $weight = 100 * $answer->fraction
;
720 $expout .= "\t=%" . $weight . '%' . $this->repchar($answer->answer
) .
721 '#' . $this->write_questiontext($answer->feedback
,
722 $answer->feedbackformat
, $question->questiontextformat
) . "\n";
724 $expout .= $this->write_general_feedback($question);
729 $expout .= $this->write_name($question->name
);
730 $expout .= $this->write_questiontext($question->questiontext
, $question->questiontextformat
);
732 foreach ($question->options
->answers
as $answer) {
733 if ($answer->answer
!= '' && $answer->answer
!= '*') {
734 $weight = 100 * $answer->fraction
;
735 $expout .= "\t=%" . $weight . '%' . $answer->answer
. ':' .
736 (float)$answer->tolerance
. '#' . $this->write_questiontext($answer->feedback
,
737 $answer->feedbackformat
, $question->questiontextformat
) . "\n";
739 $expout .= "\t~#" . $this->write_questiontext($answer->feedback
,
740 $answer->feedbackformat
, $question->questiontextformat
) . "\n";
743 $expout .= $this->write_general_feedback($question);
748 $expout .= $this->write_name($question->name
);
749 $expout .= $this->write_questiontext($question->questiontext
, $question->questiontextformat
);
751 foreach($question->options
->subquestions
as $subquestion) {
752 $expout .= "\t=" . $this->write_questiontext($subquestion->questiontext
,
753 $subquestion->questiontextformat
, $question->questiontextformat
) .
754 ' -> ' . $this->repchar($subquestion->answertext
) . "\n";
756 $expout .= $this->write_general_feedback($question);
762 if ($out = $this->try_exporting_using_qtypes($question->qtype
, $question)) {
765 $expout .= "Question type $question->qtype is not supported\n";
766 echo $OUTPUT->notification(get_string('nohandler', 'qformat_gift',
767 question_bank
::get_qtype_name($question->qtype
)));
771 // Add empty line to delimit questions