PGchoicemacros.pl - Macros for multiple choice, matching, and true/false questions.

From WeBWorK

Jump to: navigation


NAME

PGchoicemacros.pl - Macros for multiple choice, matching, and true/false questions.

SYNOPSIS

Matching example:

 loadMacros("PGchoicemacros.pl");
 
 # create a new match list
 $ml = new_match_list();
 
 # enter three questions and their answers
 $ml->qa(
        "What color is a rose?",
        "Red",
        "What color is the sky?",
        "Blue",
        "What color is the sea?",
        "Green",
 );
 
 # choose two of these questions, ordered at random,
 # which will be printed in the problem.
 $ml->choose(2);
 
 # print the question and answer choices
 BEGIN_TEXT
 Match the answers below with these questions: $BR
 \{ $ml->print_q \} $BR
 Answers:
 \{ $ml->print_a \}
 END_TEXT
 
 # register the correct answer
 ANS($ml->ra_correct_ans);

DESCRIPTION

There are two types of choice macros. The older versions are simple subroutines. The newer versions involve the List class and its sub-classes and the use of objects based on these classes. The list sub-classes are:

  • Match, which aids in setting up matching question and answer lists,

  • Select, which aids in selecting and presenting a subset of questions with short answers (e.g. true/false questions) from a larger question set, and

  • Multiple, which aids in setting up a standard one-question-many-answers multiple choice question.

MACROS

Match lists

new_match_list
 $ml = new_match_list();

new_match_list() creates a new Match object and initializes it with sensible defaults. It is equivalent to:

 $ml = new Match(random(1,2000,1), ~~&std_print_q, ~~&std_print_a);

The first argument is the seed for the match list (choosen at random between 1 and 2000 in the example above). The next two arguments are references to the print subroutines used to print the questions and the answers. Other printing methods can be used instead of the standard ones. An example of how to do this is demonstrated with pop_up_list_print_q() below.

Select lists

new_select_list
 $sl = new_select_list();

new_select_list() creates a new Select object and initializes it with sensible defaults. It is equivalent to:

 $sl = new Select(random(1,2000,1), ~~&std_print_q, ~~&std_print_a);

The parameters to the Select constructor are the same as those for the Match constrcutor described above under new_match_list().

See the documentation for the Select class to see how to use this object to create a true/false question.

std_print_a is only intended to be used for debugging with select lists, as there is rarely a reason to print out the answers to a select list.

new_pop_up_select_list()
 $sl = new_pop_up_select_list();

new_popup_select_list() creates a new Select object and initializes it such that it will render as a popup list. It is equivalent to:

 $selectlist = new Select(random(1,2000,1), ~~&pop_up_list_print_q, ~~&std_print_a);

Multiple choice quesitons

new_multiple_choice()
 $mc = new_multiple_choice();

new_multiple_choice() creates a new Multiple object that presents a question and a number possible answers, only one of which can be chosen. It is equivalent to:

 $mc = new Multiple(random(1,2000,1), ~~&std_print_q, ~~&radio_print_a);

The parameters to the Multiple constructor are the same as those for the Match constrcutor described above under new_match_list().

new_checkbox_multiple_choice()
 $mc = new_checkbox_multiple_choice();

new_checkbox_multiple_choice() creates a new Multiple object that presents a question and a number possible answers, any number of which can be chosen. It is equivalent to:

 $mc = new Multiple(random(1,2000,1), ~~&std_print_q, ~~&checkbox_print_a);

Question printing subroutines

std_print_q()
 # $list can be a matching list, a select list, or a multiple choice list
 $list->rf_print_q(~~&std_print_q);
 TEXT($list->print_q);

This formatting routine is the default method for formatting the way questions are printed for each of the three List sub-classes. It lists the questions vertically, numbering them sequentially and providing an answer blank before each question. std_print_q() checks which mode the user is trying to print the questions from and returns the appropriately formatted string.

pop_up_list_print_q()
 $sl->rf_print_q(~~&pop_up_list_print_q);
 $sl->ra_pop_up_list([T => 'True', F => 'False']);
 TEXT($sl->print_q);

Alternate method for print questions with pop up lists.

This printing routine is used to print the questions for a true/false or other select list with a preceding pop up list of possible answers. A list of values and labels need to be given to the pop_up_list so that the intended answer is returned when a student selects an answer form the list. Note the use of => in the example above to associate the values on the left with the labels on the right, this means that, for instance, the student will see the word True in the pop_up_list but the answer that is returned to the grader is T, so that it corresponds with what the professor typed in as the answer when using $sl->qa('blah blah', 'T');

quest_first_pop_up_list_print_q()
 $sl->rf_print_q(~~&quest_first_pop_up_list_print_q);
 $sl->ra_pop_up_list([T => 'True', F => 'False']);
 TEXT($sl->print_q);

Similar to pop_up_list_print_q(), but places the popup list after the question text in the output.

ans_in_middle_pop_up_list_print_q()
 $sl->rf_print_q(~~&ans_in_middle_pop_up_list_print_q);
 $sl->ra_pop_up_list([T => 'True', F => 'False']);
 TEXT($sl->print_q);

Similar to quest_first_pop_up_list_print_q(), except that no linebreaks are printed between questions, allowing for the popup list to be placed in the middle of the text of a problem.

units_list_print_q

A simple popup question printer. No question text is printed, instead the pop_up_list contents only are printed as a popup menu.

Answer printing subroutines

std_print_a
 # $list can be a matching list, a select list, or a multiple choice list
 $list->rf_print_a(~~&std_print_a);
 TEXT($list->print_a);

This simple formatting routine is the default method for formatting the answers for matching lists. It lists the answers vertically lettered sequentially.

radio_print_a()
 # $list can be a matching list, a select list, or a multiple choice list
 $list->rf_print_q(~~&radio_print_q);
 TEXT($list->print_q);

This simple printing routine is used to print the answers to multiple choice questions in a bulleted style with radio buttons preceding each possible answer. When a multiple choice object is created, a reference to radio_print_a is passed to that object so that it can be used from within the object later.

radio_print_a checks which mode the user is trying to print the answers from and returns the appropriately formatted string.

checkbox_print_a()
 # $list can be a matching list, a select list, or a multiple choice list
 $list->rf_print_q(~~&radio_print_q);
 TEXT($list->print_q);

This simple printing routine is used to print the answers to multiple choice questions in a bulleted style with checkboxes preceding each possible answer. When a multiple choice object is created, a reference to checkbox_print_a is passed to that object so that it can be used from within the object later.

checkbox_print_a checks which mode the user is trying to print the answers from and returns the appropriately formatted string.

Legacy macros

These are maintained for backward compatibility. They can still be useful in constructing non-standard lists that don't fit the various list objects. In general the using the list objects is likely to give better results and is preferred.

[DEPRECATED] qa()
 qa($questions, $answers, @new_qa);

$questions and $answers are references to arrays, and @new_qa is a list of questions and answers to add to the $questions and $answers arrays.

[DEPRECATED] invert()
 @b = invert(@a);

Inverts an arrays values and indexes. For example, invert(1,2,4,8) returns undef,0,1,undef,2,undef,undef,undef,4.

[DEPRECATED] NchooseK()
 @b = NchooseK($N, $K);

Selects $K random nonrepeating elements in the range 0 to $N-1.

[DEPRECATED] shuffle()
 @b = shuffle($i);

Returns the integers from 0 to $i-1 in random order.

[DEPRECATED] match_questions_list()
[DEPRECATED] match_questions_list_varbox()