[system] / trunk / pg / macros / answerCustom.pl Repository:
ViewVC logotype

View of /trunk/pg/macros/answerCustom.pl

Parent Directory Parent Directory | Revision Log Revision Log


Revision 5551 - (download) (as text) (annotate)
Tue Oct 2 20:48:05 2007 UTC (12 years, 2 months ago) by sh002i
File size: 5978 byte(s)
improved formatting for docs -- these were in pod sections but were all
formatted as verbatim sections, and i moved them into normal paragraphs,
lists, etc. should make things more readable from the web.

    1 =head1 NAME
    2 
    3 answerCustom.pl - An easy method for creating answer checkers with a custom
    4 subroutine that performs the check for correctness.
    5 
    6 =cut
    7 
    8 loadMacros('MathObjects.pl');
    9 
   10 sub _answerCustom_init {}; # don't reload this file
   11 
   12 =head1 MACROS
   13 
   14 =head2 custom_cmp
   15 
   16  ANS(custom_cmp($correct_ans, $ans_checker, %options))
   17 
   18 This answer checker provides an easy method for creating an answer
   19 checker with a custom subroutine that performs the check for
   20 correctness.
   21 
   22 Pass the correct answer (either as a string or as a Parser object)
   23 as the first argument, and a reference to the checker subroutine
   24 as the second argument.  Additional parameters can follow.  These
   25 include any of the parameters for the usual answer checker of the
   26 of the type of the correct answer (e.g., showCoordinateHints), plus
   27 the following:
   28 
   29 =over
   30 
   31 =item S<C<< sameClass => 0 or 1 >>>
   32 
   33 If 1 (the default), only call the
   34 custom checker if the student answer
   35 is the same object class as the correct
   36 answer (e.g., both are points).
   37 If 0, the checker will be called
   38 whenever the student answer passes
   39 the typeMatch check for the correct
   40 answer.  For example, if the correct
   41 answer is a vector, and promotePoints
   42 has been set to 1, then the checker
   43 will be called when the student answer
   44 is a vector OR a point.
   45 
   46 =item S<C<< sameLength => 0 or 1 >>>
   47 
   48 If 1 (the default), only call the
   49 custom checker if the student answer
   50 has the same number of coordinates as
   51 the correct answer.
   52 
   53 =back
   54 
   55 If the correct answer is a list, the custom checker will be called
   56 on the individual entries of the list, not on the list as a whole.
   57 If the list is an unordered list, the routine may be called
   58 multiple times with various combinations of student and professor's
   59 answers in order to find a correct match.
   60 
   61 Note: If you want a correct answer whose class is a complex variable
   62 to check a real number entry you will have to set both sameClass and
   63 sameLength to 0 since a complex number has length 2 and a real number
   64 has length 1.
   65 
   66 The checker routine will be passed the correct answer, the
   67 student's answer, and the answer evaluator object, in that order.
   68 
   69 For example, the following checks if a student entered
   70 a unit vector (any unit vector in R^3 will do):
   71 
   72    ANS(custom_cmp("<1,0,0>",sub {
   73      my ($correct,$student,$ans) = @_;
   74      return norm($student) == 1;
   75    },showCoordinateHints => 0));
   76 
   77 The checker subroutine can call Value::Error(message) to generate
   78 an error message that will be reported in the table at the top of
   79 the page.  If the checker generates a fatal runtime error (e.g.,
   80 calls the "die" function), then the message is reported with the
   81 "pink screen of death", and includes a request for the student to
   82 inform the instructor.
   83 
   84 =cut
   85 
   86 sub custom_cmp {
   87   my $correct = shift; my $checker = shift;
   88   die "custom_cmp requires a correct answer" unless defined($correct);
   89   die "custom_cmp requires a checker subroutine" unless defined($checker);
   90   $correct = Value::makeValue($correct);
   91   $correct = Value->Package("Formula")->new($correct) unless Value::isValue($correct);
   92   $correct->cmp(
   93     checker => sub {
   94       my ($correct,$student,$ans) = @_;
   95       return 0 if $ans->{sameClass} && $correct->class ne $student->class;
   96       return 0 if $ans->{sameLength} && $correct->length != $student->length;
   97       return &{$ans->{custom_checker}}($correct,$student,$ans);
   98     },
   99     custom_checker => $checker,
  100     sameClass => 1,
  101     sameLength => 1,
  102     showEqualErrors => 1,  # make sure we see errors in list checker
  103     @custom_cmp_defaults,
  104     @_,
  105   );
  106 }
  107 
  108 #
  109 #  Set this to include any default parameters you want
  110 #  to include in the custom answer checkers
  111 #
  112 @custom_cmp_defaults = ();
  113 
  114 =head2 custom_list_cmp
  115 
  116  ANS(custom_list_cmp($correct_ans, $ans_checker, %options))
  117 
  118 This one installs a custom list-based answer checker (for the
  119 List and Union classes).  Basically it is just a shell that makes
  120 it a little easier to do, and provides an interface similar to
  121 custom_cmp.
  122 
  123 You pass the correct answer (as a string or as a List or Union
  124 object) as the first argument, and the custom list checker as
  125 the second argument.  You can pass any additional parameters
  126 that should be included in the answer checker following those
  127 two required ones.
  128 
  129 The checker will be passed a reference to the array of correct
  130 answers, a reference to the array of student answers, and
  131 the answer evaluator object.  Note that the correct and student
  132 answers are array references, not List structures (this is because
  133 a list of formulas becomes a formula returning a list, so in order
  134 to keep the formulas separate, they are passed in an array).
  135 
  136 The checker should return the number of list entries that were
  137 matched by the students answers.  (I.e., a number between 0
  138 and the length of the list.)
  139 
  140 For example, the following checks for any list of the same length
  141 as the instructor's list.  (A stupid checker, but just an example.)
  142 
  143     ANS(custom_list_cmp("1,2,3",sub {
  144         my ($correct,$student,$ans) = @_;
  145         (scalar(@{$correct}) == scalar(@{$student}) ? 3 : 0);
  146     }));
  147 
  148 The checker subroutine can call Value::Error(message) to generate
  149 an error message that will be reported in the table at the top of
  150 the page.  If the checker generates a fatal runtime error (e.g.,
  151 calls the "die" function), then the message is reported with the
  152 "pink screen of death", and includes a request for the student to
  153 inform the instructor.
  154 
  155 =cut
  156 
  157 sub custom_list_cmp {
  158   my $correct = shift; my $checker = shift;
  159   die "custom_list_cmp requires a correct answer" unless defined($correct);
  160   die "custom_list_cmp requires a checker subroutine" unless defined($checker);
  161   $correct = Value::makeValue($correct);
  162   $correct = Value->Package("Formula")->new($correct) unless Value::isValue($correct);
  163   $correct->cmp(
  164     list_checker => $checker,
  165     @custom_list_cmp_defaults,
  166     @_,
  167   );
  168 }
  169 
  170 #
  171 #  Set this to include any default parameters you want
  172 #  to include in the custom answer checkers
  173 #
  174 @custom_list_cmp_defaults = ();
  175 

aubreyja at gmail dot com
ViewVC Help
Powered by ViewVC 1.0.9