PGstringevaluators.pl - Macros that generate string answer evaluators.

From WeBWorK

Jump to: navigation


NAME

PGstringevaluators.pl - Macros that generate string answer evaluators.

SYNOPSIS

        ANS(str_cmp("increasing"));
        
        ANS(unordered_str_cmp("A C E"));

DESCRIPTION

String answer evaluators compare a student string to the correct string.

MathObjects and answer evaluators

The MathObjects system provides a String->cmp() method that produce answer evaluators for string comparisons. It is recommended that you use the String object's cmp() method directly if possible.

String Filters

Different filters can be applied to allow various degrees of variation. Both the student and correct answers are subject to the same filters, to ensure that there are no unexpected matches or rejections.

remove_whitespace

Removes all whitespace from the string. It applies the following substitution to the string:

        $filteredAnswer =~ s/\s+//g;
compress_whitespace

Removes leading and trailing whitespace, and replaces all other blocks of whitespace by a single space. Applies the following substitutions:

        $filteredAnswer =~ s/^\s*//;
        $filteredAnswer =~ s/\s*$//;
        $filteredAnswer =~ s/\s+/ /g;
trim_whitespace

Removes leading and trailing whitespace. Applies the following substitutions:

        $filteredAnswer =~ s/^\s*//;
        $filteredAnswer =~ s/\s*$//;
nullify

Returns the null string.

ignore_case

Ignores the case of the string. More accurately, it converts the string to uppercase (by convention). Applies the following function:

        $filteredAnswer = uc($filteredAnswer);
ignore_order

Ignores the order of the letters in the string. This is used for problems of the form "Choose all that apply." Specifically, it removes all whitespace and lexically sorts the letters in ascending alphabetical order. Applies the following functions:

        $filteredAnswer = join("", lex_sort(split(/\s*/, $filteredAnswer)));

str_cmp

        ANS(str_cmp($answer_or_answer_array_ref, @filters));
        ANS(str_cmp($answer_or_answer_array_ref, %options));

Compares a string or a list of strings, using a named hash of options to set parameters. This can make for more readable code than using the "mode"_str_cmp() style, but some people find one or the other easier to remember.

$answer_or_answer_array_ref can be a scalar representing the correct answer or a reference to an array of string scalars. If multiple answers are given, str_cmp returns one answer evaluator for each answer.

num_cmp() differentiates %options from @filters by checking for the names of supported options in the list. Currently "filter", "filters", and "debug" are checked for. If these strings are found in the argument list, it is assumed that %options is present rather than @filters.

%options can contain the following items:

filters

A reference to an array of filter names, to be applied to both the correct answer and the student's answer before doing string comparison. Supported filters are listed above. filter is avaliable as a synonym for filters.

debug

If set to 1, extra debugging information will be output.

If %options is not detected, the rest of the argument list is assumed to be a list of filter names. Hence, the following two forms are equivalent:

        ANS(str_cmp($ans, 'remove_whitespace', 'ignore_order'));
        ANS(str_cmp($ans, filters=>['remove_whitespace', 'ignore_order']));

Examples

        # same as std_str_cmp() -- matches "Hello", "  hello", etc.
        str_cmp("Hello")
        # same as std_str_cmp_list()
        str_cmp(["Hello", "Goodbye"]);
        # matches "hello", " hello  ", etc.
        str_cmp(' hello ', 'trim_whitespace');
        # matches "ACB" and "A B C", but not "abc"
        str_cmp('ABC', filters=>'ignore_order');
        # matches "def" and "d e f" but not "fed"
        str_cmp('D E F', 'remove_whitespace', 'ignore_case');

"mode"_str_cmp functions

The functions of the the form "mode"_str_cmp() use different functions to specify which filters to apply. They take no options except the correct string. There are also versions which accept a list of strings.

standard
        std_str_cmp($correctString)
        std_str_cmp_list(@correctStringList)

Filters: compress_whitespace, ignore_case

standard, case sensitive
        std_cs_str_cmp($correctString)
        std_cs_str_cmp_list(@correctStringList)

Filters: compress_whitespace

strict
        strict_str_cmp($correctString)
        strict_str_cmp_list(@correctStringList)

Filters: trim_whitespace

unordered
        unordered_str_cmp( $correctString )
        unordered_str_cmp_list( @correctStringList )

Filters: ignore_order, ignore_case

unordered, case sensitive
        unordered_cs_str_cmp( $correctString )
        unordered_cs_str_cmp_list( @correctStringList )

Filters: ignore_order

ordered
        ordered_str_cmp( $correctString )
        ordered_str_cmp_list( @correctStringList )

Filters: remove_whitespace, ignore_case

ordered, case sensitive
        ordered_cs_str_cmp( $correctString )
        ordered_cs_str_cmp_list( @correctStringList )

Filters: remove_whitespace

Examples

        # Accepts "W. Mozart", "W. MOZarT", and so forth. Case insensitive. All
        # internal spaces treated as single spaces.
        ANS(std_str_cmp("W. Mozart"));
        # Rejects "mozart". Same as std_str_cmp() but case sensitive.
        ANS(std_cs_str_cmp("Mozart"));
        # Accepts only the exact string.
        ANS(strict_str_cmp("W. Mozart"));
        # Accepts "a c B", "CBA" and so forth. Unordered, case insensitive, spaces
        # ignored.
        ANS(unordered_str_cmp("ABC"));
        # Rejects "abc". Same as unordered_str_cmp() but case sensitive.
        ANS(unordered_cs_str_cmp("ABC"));
        # Accepts "a b C", "A B C" and so forth. Ordered, case insensitive, spaces
        # ignored.
        ANS(ordered_str_cmp("ABC"));
        # Rejects "abc", accepts "A BC" and so forth. Same as ordered_str_cmp() but
        # case sensitive.
        ANS(ordered_cs_str_cmp("ABC"));

SEE ALSO

the PGanswermacros.pl manpage, MathObjects.