[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 5556 - (download) (as text) (annotate)
Thu Oct 4 16:40:49 2007 UTC (12 years, 3 months ago) by sh002i
File size: 6909 byte(s)
added standard copyright/license header

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

aubreyja at gmail dot com
ViewVC Help
Powered by ViewVC 1.0.9