From WeBWorK

Jump to: navigation


NAME

        AnswerHash.pm -- located in the courseScripts directory
        
        This file contains the packages/classes:
        AnswerHash   and AnswerEvaluator

SYNPOSIS

        AnswerHash  -- this class stores information related to the student's
                       answer.  It is little more than a standard perl hash with
                       a special name, butit does have some access and 
                       manipulation methods.  More of these may be added as it
                       becomes necessary.
                       
        Useage:    $rh_ans = new AnswerHash;
                       
        AnswerEvaluator -- this class organizes the construction of
                           answer evaluator subroutines which check the 
                           student's answer.  By plugging filters into the
                           answer evaluator class you can customize the way the
                           student's answer is normalized and checked.  Our hope
                           is that with properly designed filters, it will be
                           possible to reuse the filters in different
                           combinations to obtain different answer evaluators,
                           thus greatly reducing the programming and maintenance
                           required for constructing answer evaluators.
                           
        Useage:         $ans_eval  = new AnswerEvaluator;

DESCRIPTION : AnswerHash

The answer hash class is guaranteed to contain the following instance variables:

        score                   =>      $correctQ,
        correct_ans             =>      $originalCorrEqn,
        student_ans             =>      $modified_student_ans
        original_student_ans    =>      $original_student_answer,
        ans_message             =>      $PGanswerMessage,
        type                    =>      'typeString',
        preview_text_string     =>      $preview_text_string,
        preview_latex_string    =>      $preview_latex_string
        $ans_hash->{score}              --      a number between 0 and 1 indicating
                                                whether the answer is correct. Fractions
                                                allow the implementation of partial
                                                credit for incorrect answers.
        $ans_hash->{correct_ans}                --      The correct answer, as supplied by the
                                                instructor and then formatted. This can
                                                be viewed by the student after the answer date.
        $ans_hash->{student_ans}                --      This is the student answer, after reformatting;
                                                for example the answer might be forced
                                                to capital letters for comparison with
                                                the instructors answer. For a numerical
                                                answer, it gives the evaluated answer.
                                                This is displayed in the section reporting
                                                the results of checking the student answers.
        $ans_hash->{original_student_ans}       --      This is the original student answer. 
                                                 This is displayed on the preview page and may be used for
                                                 sticky answers.
        $ans_hash->{ans_message}                --      Any error message, or hint provided by 
                                                the answer evaluator.
                                                This is also displayed in the section reporting
                                                the results of checking the student answers.
        $ans_hash->{type}                       --      A string indicating the type of answer evaluator. 
                                                This helps in preprocessing the student answer for errors.
                                                Some examples:
                                                        'number_with_units'
                                                        'function'
                                                        'frac_number'
                                                        'arith_number'
        $ans_hash->{preview_text_string}        --
                                                This typically shows how the student answer was parsed. It is
                                                displayed on the preview page. For a student answer of 2sin(3x)
                                                this would be 2*sin(3*x). For string answers it is typically the
                                                same as $ans_hash{student_ans}.
        $ans_hash->{preview_latex_string}       --      
                                                THIS IS OPTIONAL. This is latex version of the student answer
                                                which is used to show a typeset view on the answer on the preview
                                                page. For a student answer of 2/3, this would be \frac{2}{3}.
                                                'ans_message'                   =>      '', # null string
                                                                                        
                                                'preview_text_string'   =>      undef,
                                                'preview_latex_string'  =>  undef,
                                                'error_flag'                    =>  undef,
                                                'error_message'             =>  '',

AnswerHash Methods:

new

        Useage          $rh_anshash = new AnswerHash;
        
        returns an object of type AnswerHash.
        
=cut

sub new {
my $class = shift @_;


        my $self  = {   'score'                                 =>      0,
                                        'correct_ans'                   =>      'No correct answer specified',
                                        'student_ans'                   =>      undef,
                                        'ans_message'                   =>      '',
                                        'ans_label'            =>   undef,
                                        'type'                                  =>      'Undefined answer evaluator type',
                                        'preview_text_string'   =>      undef,
                                        'preview_latex_string'  =>      undef,
                                        'original_student_ans'  =>      undef,
                                        'error_flag'                    =>  undef,
                                        'error_message'             =>  '',
        };      # return a reference to a hash.
        
        bless $self, $class;
        $self -> setKeys(@_);
        
        return $self;
}

## IN: a hash ## Checks to make sure that the keys are valid, ## then sets their value

setKeys


                        $rh_ans->setKeys(score=>1, student_answer => "yes");  
                        Sets standard elements in the AnswerHash (the ones defined
                        above). Will give error if one attempts to set non-standard keys.

                        To set a non-standard element in a hash use

                        $rh_ans->{non-standard-key} = newValue;

                        There are no safety checks when using this method.

data

        Useage:     $rh_ans->data('foo');               set $rh_ans->{student_ans} = 'foo';
                    $student_input = $rh_ans->data();   retrieve value of $rh_ans->{student_ans}
        
        synonym for input

input

        Useage:     $rh_ans->input('foo')    sets $rh_ans->{student_ans} = 'foo';
                                $student_input = $rh_ans->input();
        
        synonym for data

input

        Useage:     $rh_ans->score(1)    
                                $score = $rh_ans->score();
        
        Retrieve or set $rh_ans->{score}, the student's score on the problem.

stringify_hash

        Usage:      $rh_ans->stringify_hash;
        Turns all values in the hash into strings (so they won't cause trouble outside
        the safe compartment).

throw_error

        Useage: $rh_ans->throw_error("FLAG", "message");
        
        FLAG is a distinctive word that describes the type of error.  
        Examples are EVAL for an evaluation error or "SYNTAX" for a syntax error.
        The entry $rh_ans->{error_flag} is set to "FLAG".
        
        The catch_error and clear_error methods use
        this entry.
        
        message is a descriptive message for the end user, defining what error occured.

catch_error

        Useage: $rh_ans->catch_error("FLAG2");
        
        Returns true (1) if  $rh_ans->{error_flag} equals "FLAG2", otherwise it returns
        false (empty string).

clear_error

        Useage:  $rh_ans->clear_error("FLAG2");
        
        If $rh_ans->{error_flag} equals "FLAG2" then the {error_flag} entry is set to 
        the empty string as is the entry {error_message}

error_flag

error_message

        Useage:   $flag = $rh_ans -> error_flag();
                        
                          $message = $rh_ans -> error_message();
        Retrieve or set the {error_flag} and {error_message} entries. 
        
        Use catch_error and throw_error where possible.

OR

        Useage:    $rh_ans->OR($rh_ans2);
        
        Returns a new AnswerHash whose score is the maximum of the scores in $rh_ans and $rh_ans2.
        The correct answers for the two hashes are combined with "OR".  
        The types are concatenated with "OR" as well.
        Currently nothing is done with the error flags and messages.

AND

        Useage:    $rh_ans->AND($rh_ans2);
        
        Returns a new AnswerHash whose score is the minimum of the scores in $rh_ans and $rh_ans2.
        The correct answers for the two hashes are combined with "AND". 
        The types are concatenated with "AND" as well.
         Currently nothing is done with the error flags and messages.

Description: AnswerEvaluator

AnswerEvaluator Methods

new

evaluate

        $answer_evaluator->evaluate($student_answer_string)

install_pre_filter

install_evaluator

install_post_filter

withPreFilter

    $answerHash->withPreFilter(filter[,options]);
    Installs a prefilter (possibly with options), and returns the AnswerHash. This is so that you
    can add a filter to a checker without having to save the checker in a variable, e.g.,
        ANS(Real(10)->cmp->withPreFilter(...));
    or
        ANS(num_cmp(10)->withPreFilter(...));

withPostFilter

    $answerHash->withPostFilter(filter[,options]);
    Installs a postfilter (possibly with options), and returns the AnswerHash. This is so that you
    can add a filter to a checker without having to save the checker in a variable, e.g.,
        ANS(Real(10)->cmp->withPostFilter(...));
    or
        ANS(num_cmp(10)->withPostFilter(...));

Description: Filters

A filter is a subroutine which takes one AnswerHash as an input, followed by a hash of options.

                Useage:  filter($ans_hash, option1 =>value1, option2=> value2 );
                

The filter performs some operations on the input AnswerHash and returns an AnswerHash as output.

Many AnswerEvaluator objects are merely a sequence of filters placed into three queues:

        pre_filters:    these normalize student input, prepare text and so forth
        evaluators:     these decide whether or not an answer is correct
        post_filters:   typically these clean up error messages or process errors 
                                        and generate error messages.

If a filter detects an error it can throw an error message using the $rh_ans-throw_error()> method. This skips the AnswerHash by all remaining pre_filter $rh_ans-catch_error>, decides how ( or whether) it is supposed to handle the error and then passes the result on to the next post_filter.

Setting the flag $rh_ans-{done} = 1> will skip the AnswerHash past the remaining post_filters.

Built in filters

blank_prefilter

blank_postfilter