diff --git a/lib/AnswerHash.pm b/lib/AnswerHash.pm index 9593820a89..8229f03000 100755 --- a/lib/AnswerHash.pm +++ b/lib/AnswerHash.pm @@ -6,37 +6,18 @@ =head1 NAME - AnswerHash.pm -- located in the courseScripts directory +AnswerHash.pm - a class to store student answers and the answer evaluator - This file contains the packages/classes: - AnswerHash and AnswerEvaluator +=head1 DESCRIPTION - AnswerHash -=head1 SYNPOSIS +This class stores information related to the student's answer. It is little more than a standard perl hash with +a special name, but it does have some access and manipulation methods. - AnswerHash -- this class stores information related to the student's - answer. It is little more than a standard perl hash with - a special name, but it does have some access and - manipulation methods. More of these may be added as it - becomes necessary. +Usage: - Usage: $rh_ans = new AnswerHash; + $rh_ans = AnswerHash->new(); - 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. - - Usage: $ans_eval = new AnswerEvaluator; - -=cut - -=head1 DESCRIPTION : AnswerHash +=head2 SYNOPSIS The answer hash class is guaranteed to contain the following instance variables: @@ -105,7 +86,7 @@ The answer hash class is guaranteed to contain the following instance variables: 'error_message' => '', -=head3 AnswerHash Methods: +=head2 METHODS =cut @@ -128,11 +109,13 @@ my %fields = ( ## Initializing constructor -=head4 new +=head3 AnswerHash->new - Useage $rh_anshash = new AnswerHash; +Usage - returns an object of type AnswerHash. + $rh_anshash = new AnswerHash; + +returns an object of type AnswerHash. =cut @@ -164,17 +147,19 @@ sub new { ## Checks to make sure that the keys are valid, ## then sets their value -=head4 setKeys +=head3 setKeys + +Usage: - $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. + $rh_ans->setKeys(score=>1, student_answer => "yes"); - To set a non-standard element in a hash use +Sets standard elements in the AnswerHash (the ones defined +above). Will give error if one attempts to set non-standard key +To set a non-standard element in a hash use - $rh_ans->{non-standard-key} = newValue; + $rh_ans->{non-standard-key} = newValue; - There are no safety checks when using this method. +There are no safety checks when using this method. =cut @@ -192,40 +177,45 @@ sub setKeys { # access methods -=head4 data +=head3 data + +Usage: + + $rh_ans->data('foo'); # set $rh_ans->{student_ans} = 'foo'; + $student_input = $rh_ans->data(); # retrieve value of $rh_ans->{student_ans} - Usage: $rh_ans->data('foo'); set $rh_ans->{student_ans} = 'foo'; - $student_input = $rh_ans->data(); retrieve value of $rh_ans->{student_ans} +synonym for C - synonym for input +=head3 input -=head4 input +Usage: - Usage: $rh_ans->input('foo') sets $rh_ans->{student_ans} = 'foo'; - $student_input = $rh_ans->input(); + $rh_ans->input('foo') # sets $rh_ans->{student_ans} = 'foo'; + $student_input = $rh_ans->input(); - synonym for data +synonym for C =cut -sub data { #$rh_ans->data('foo') is a synonym for $rh_ans->{student_ans}='foo' +sub data { my $self = shift; $self->input(@_); } -sub input { #$rh_ans->input('foo') is a synonym for $rh_ans->{student_ans}='foo' +sub input { my $self = shift; my $input = shift; $self->{student_ans} = $input if defined($input); $self->{student_ans}; } -=head4 input +=head3 score - Usage: $rh_ans->score(1) - $score = $rh_ans->score(); +Usage: + $rh_ans->score(1) + $score = $rh_ans->score(); - Retrieve or set $rh_ans->{score}, the student's score on the problem. +Retrieve or set $rh_ans->{score}, the student's score on the problem. =cut @@ -236,14 +226,14 @@ sub score { $self->{score}; } -=head4 stringify_hash +=head3 stringify_hash - Usage: $rh_ans->stringify_hash; +Usage: - Turns all values in the hash into strings (so they won't cause trouble outside - the safe compartment). + $rh_ans->stringify_hash; - Hashes and arrays are converted into a JSON string. +Turns all values in the hash into strings (so they won't cause trouble outside +the safe compartment). Hashes and arrays are converted into a JSON string. =cut @@ -263,46 +253,49 @@ sub stringify_hash { # error methods -=head4 throw_error +=head3 throw_error - Usage: $rh_ans->throw_error("FLAG", "message"); +Usage: - 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". + $rh_ans->throw_error("FLAG", "message"); - The catch_error and clear_error methods use - this entry. +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". - message is a descriptive message for the end user, defining what error occured. +The catch_error and clear_error methods use this entry. -=head4 catch_error +message is a descriptive message for the end user, defining what error occured. - Usage: $rh_ans->catch_error("FLAG2"); +=head3 catch_error - Returns true (1) if $rh_ans->{error_flag} equals "FLAG2", otherwise it returns - false (empty string). +Usage: + $rh_ans->catch_error("FLAG2"); +Returns true (1) if $rh_ans->{error_flag} equals "FLAG2", otherwise it returns +false (empty string). -=head4 clear_error +=head3 clear_error - Usage: $rh_ans->clear_error("FLAG2"); +Usage: - If $rh_ans->{error_flag} equals "FLAG2" then the {error_flag} entry is set to - the empty string as is the entry {error_message} + $rh_ans->clear_error("FLAG2"); -=head4 error_flag +If $rh_ans->{error_flag} equals "FLAG2" then the {error_flag} entry is set to +the empty string as is the entry {error_message} -=head4 error_message +=head3 error_flag, error_message - Usage: $flag = $rh_ans -> error_flag(); +Usage: - $message = $rh_ans -> error_message(); + $flag = $rh_ans -> error_flag(); - Retrieve or set the {error_flag} and {error_message} entries. + $message = $rh_ans -> error_message(); - Use catch_error and throw_error where possible. +Retrieve or set the {error_flag} and {error_message} entries. + +Use catch_error and throw_error where possible. =cut @@ -395,29 +388,27 @@ sub error_message { # action methods -=head4 OR - - Usage: $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. - +=head3 OR +Usage: -=head4 AND + $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. - Usage: $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. +=head3 AND +Usage: + $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. =cut @@ -456,29 +447,31 @@ sub AND { $out_hash; } -=head1 Description: AnswerEvaluator - - - - -=cut - package AnswerEvaluator; use Exporter; use PGUtil qw(not_null pretty_print); -=head3 AnswerEvaluator Methods +=head1 DESCRIPTION: 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. +Usage: + $ans_eval = new AnswerEvaluator; +=head2 METHODS +=head3 new +Create a new AnswerEvaluator -=cut - -=head4 new +Usage: + AnswerEvaluator->new(); =cut @@ -547,10 +540,11 @@ sub get_student_answer { $input; } -=head4 evaluate +=head3 evaluate - $answer_evaluator->evaluate($student_answer_string) +Usage: + $answer_evaluator->evaluate($student_answer_string) =cut @@ -671,14 +665,11 @@ sub print_result_if_debug { # $rh_ans; # } -=head4 install_pre_filter - -=head4 install_evaluator - - -=head4 install_post_filter +=head3 install_pre_filter +=head3 install_evaluator +=head3 install_post_filter =cut @@ -755,18 +746,20 @@ sub install_correct_answer_post_filter { @{ $self->{correct_answer_post_filters} }; # return array of all post_filters } -=head4 withPreFilter +=head3 withPreFilter + +Usage: $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., +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(...)); + ANS(Real(10)->cmp->withPreFilter(...)); - or +or - ANS(num_cmp(10)->withPreFilter(...)); + ANS(num_cmp(10)->withPreFilter(...)); =cut @@ -776,18 +769,20 @@ sub withPreFilter { return $self; } -=head4 withPostFilter +=head3 withPostFilter + +Usage: $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., +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(...)); + ANS(Real(10)->cmp->withPostFilter(...)); - or +or - ANS(num_cmp(10)->withPostFilter(...)); + ANS(num_cmp(10)->withPostFilter(...)); =cut @@ -811,12 +806,13 @@ sub rh_ans { $self->{rh_ans}; } -=head1 Description: Filters +=head1 DESCRIPTION - Filters A filter is a subroutine which takes one AnswerHash as an input, followed by a hash of options. - Usage: filter($ans_hash, option1 =>value1, option2=> value2 ); +Usage: + filter($ans_hash, option1 =>value1, option2=> value2 ); The filter performs some operations on the input AnswerHash and returns an @@ -840,12 +836,9 @@ Setting the flag C<$rh_ans->{done} = 1> will skip the AnswerHash past the remaining post_filters. -=head3 Built in filters +=head2 blank_prefilter -=head4 blank_prefilter - - -=head4 blank_postfilter +=head2 blank_postfilter =cut @@ -889,5 +882,3 @@ sub blank_postfilter { } 1; -#package AnswerEvaluatorMaker; - diff --git a/lib/AnswerIO.pm b/lib/AnswerIO.pm index f9df86a1ee..569767a56b 100644 --- a/lib/AnswerIO.pm +++ b/lib/AnswerIO.pm @@ -1,9 +1,9 @@ =head1 NAME - AnswerIO.pm +AnswerIO.pm -=head1 SYNPOSIS +=head1 SYNOPSIS This is not really an object, but it gives us a place to IO used by answer macros. diff --git a/lib/Applet.pm b/lib/Applet.pm index fd0fb96d45..78f7e9789b 100644 --- a/lib/Applet.pm +++ b/lib/Applet.pm @@ -3,7 +3,7 @@ Applet.pl - Provides code for inserting GeogebraWebApplets into webwork problems -=head1 SYNPOSIS +=head1 SYNOPSIS ################################### # Create the applet object diff --git a/lib/ChoiceList.pm b/lib/ChoiceList.pm index 156532fe49..5955142a67 100644 --- a/lib/ChoiceList.pm +++ b/lib/ChoiceList.pm @@ -6,7 +6,7 @@ =head1 NAME - ChoiceList.pm -- super-class for all ChoiceList structures +ChoiceList.pm - super-class for all ChoiceList structures =head1 SYNOPSIS diff --git a/lib/Circle.pm b/lib/Circle.pm index 49eba47d2c..d5f9ba0634 100644 --- a/lib/Circle.pm +++ b/lib/Circle.pm @@ -1,14 +1,14 @@ =head1 NAME - Circle +Circle -=head1 SYNPOSIS +=head1 SYNOPSIS use Carp; - use GD; - use WWPlot; - use Fun; + use GD; + use WWPlot; + use Fun; =head1 DESCRIPTION @@ -17,29 +17,28 @@ This module defines a circle which can be inserted as a stamp in a graph (WWPlot =head2 Command: - $circle_object = new Circle( $center_pos_x, $center_pos_y, $radius, $border_color, $fill_color); - + $circle_object = new Circle( $center_pos_x, $center_pos_y, $radius, $border_color, $fill_color); =head2 Examples: - Here is the code used to define the subroutines open_circle - and closed_circle in PGgraphmacros.pl +Here is the code used to define the subroutines open_circle +and closed_circle in PGgraphmacros.pl - sub open_circle { - my ($cx,$cy,$color) = @_; - new Circle ($cx, $cy, 4,$color,'nearwhite'); - } + sub open_circle { + my ($cx,$cy,$color) = @_; + new Circle ($cx, $cy, 4,$color,'nearwhite'); + } - sub closed_circle { - my ($cx,$cy, $color) = @_; - $color = 'black' unless defined $color; - new Circle ($cx, $cy, 4,$color, $color); - } + sub closed_circle { + my ($cx,$cy, $color) = @_; + $color = 'black' unless defined $color; + new Circle ($cx, $cy, 4,$color, $color); + } - $circle_object2 = closed_circle( $x_position, $y_position, $color ); + $circle_object2 = closed_circle( $x_position, $y_position, $color ); - @circle_objects = $graph -> stamps($circle_object2); - # puts a filled dot at ($x_position, $y_position) on the graph -- using real world coordinates. + @circle_objects = $graph -> stamps($circle_object2); + # puts a filled dot at ($x_position, $y_position) on the graph -- using real world coordinates. =cut diff --git a/lib/Fraction.pm b/lib/Fraction.pm index 2e7ffc5a8e..faf86e0268 100644 --- a/lib/Fraction.pm +++ b/lib/Fraction.pm @@ -7,47 +7,46 @@ # numerator/denominator. # VS 7/20/2000 -=head3 Fraction +=head1 NAME - This object is designed to ease the use of fractions +Fraction - This object is designed to ease the use of fractions -=head4 Variables and Methods +=head1 VARIABLES - Variables + numerator # numerator of fraction + denominator # denominator of fraction - numerator #numerator of fraction - denominator #denominator of fraction +=head1 METHODS - Arithmetic Methods #these will all accept a scalar value or - #another fraction as an argument +Arithmetic Methods #these will all accept a scalar value or + #another fraction as an argument - plus #returns the sum of the fraction and argument - minus #returns fraction minus argument - subtractFrom #returns argument minus fraction - divBy #returns fraction divided by argument - divInto #returns argument divided by fraction - times #returns fraction times argument - compare #returns <, =, or > for the relation of fraction to argument + plus #returns the sum of the fraction and argument + minus #returns fraction minus argument + subtractFrom #returns argument minus fraction + divBy #returns fraction divided by argument + divInto #returns argument divided by fraction + times #returns fraction times argument + compare #returns <, =, or > for the relation of fraction to argument - pow #returns fraction raised to argument, a given integer power + pow #returns fraction raised to argument, a given integer power - Other methods +Other methods - reduce #reduces to lowest terms, and makes sure denominator is positive - scalar #returns the scalar value numerator/denominator - print #prints the fraction - print_mixed #prints the fractionas a mixed number - print_inline #prints the fraction like this 2/3 + reduce #reduces to lowest terms, and makes sure denominator is positive + scalar #returns the scalar value numerator/denominator + print #prints the fraction + print_mixed #prints the fractionas a mixed number + print_inline #prints the fraction like this 2/3 -=head4 Synopsis +=head1 SYNOPSIS - The fraction object stores two variables, numerator and denominator. The basic +The fraction object stores two variables, numerator and denominator. The basic arithmatic methods listed above can be performed on a fraction, and it can return its own scalar value for use with functions expecting a scalar (ie, sqrt($frac->scalar) ). - =cut package Fraction; diff --git a/lib/Fun.pm b/lib/Fun.pm index 67cf094d03..85e1100c9c 100644 --- a/lib/Fun.pm +++ b/lib/Fun.pm @@ -31,9 +31,9 @@ =head1 NAME - Fun +Fun -=head1 SYNPOSIS +=head1 SYNOPSIS use Carp; use GD; diff --git a/lib/Hermite.pm b/lib/Hermite.pm index b429793446..837565c253 100644 --- a/lib/Hermite.pm +++ b/lib/Hermite.pm @@ -4,38 +4,31 @@ use Carp; =head1 NAME - Hermite.pm +Hermite.pm -=head1 SYNPOSIS - - Usage: - $obj = new Hermit(\@x_values, \y_valuses \@yp_values); - - #get and set methods - $ra_x_values = $obj -> ra_x(\@x_values); - $ra_y_values = $obj -> ra_y; - $ra_yp_values = $obj -> ra_yp; - - $obj -> initialize; # calculates the approximation - - #get methods - $rf_function = $obj -> rf_f; - $rf_function_derivative = $obj -> rf_fp; - $rf_function_2nd_derivative = $obj -> rf_fpp; - - $rh_critical_points =$obj -> rh_critical_points - $rh_inflection_points =$obj -> rh_inflection_points +=head1 SYNOPSIS +Usage: + $obj = new Hermit(\@x_values, \y_valuses \@yp_values); + #get and set methods + $ra_x_values = $obj -> ra_x(\@x_values); + $ra_y_values = $obj -> ra_y; + $ra_yp_values = $obj -> ra_yp; + $obj -> initialize; # calculates the approximation + #get methods + $rf_function = $obj -> rf_f; + $rf_function_derivative = $obj -> rf_fp; + $rf_function_2nd_derivative = $obj -> rf_fpp; + $rh_critical_points =$obj -> rh_critical_points + $rh_inflection_points =$obj -> rh_inflection_points =head1 DESCRIPTION This module defines an object containing a Hermite spline approximation to a function. - The approximation -consists of a piecewise cubic polynomial which agrees with the original -function and its first derivative at -the node points. +The approximation consists of a piecewise cubic polynomial which agrees with the original +function and its first derivative at the node points. This is useful for creating on the fly graphics. Care must be taken to use a small number of points spaced reasonably far apart, preferably diff --git a/lib/Label.pm b/lib/Label.pm index 52f9b77071..e987335aa0 100644 --- a/lib/Label.pm +++ b/lib/Label.pm @@ -1,10 +1,10 @@ =head1 NAME - Label +Label -=head1 SYNPOSIS +=head1 SYNOPSIS use Carp; use GD; @@ -19,8 +19,8 @@ This module defines labels for the graph objects (WWPlot). =head2 Usage - $label1 = new Label($x_value, $y_value, $label_string, $label_color, @options) - $options is an array with (*'d defaults) + $label1 = new Label($x_value, $y_value, $label_string, $label_color, @options) + $options is an array with (*'d defaults) - one of 'left'*, 'center', 'right' (horizontal alignment) - one of 'bottom', 'center', 'top'* (verical alignment) - one of 'horizontal'*, 'vertical' (orientation) diff --git a/lib/List.pm b/lib/List.pm index 4c49993466..e7059dc741 100644 --- a/lib/List.pm +++ b/lib/List.pm @@ -6,7 +6,7 @@ =head1 NAME - List.pm -- super-class for all list structures +List.pm - super-class for all list structures =head1 SYNOPSIS diff --git a/lib/Matrix.pm b/lib/Matrix.pm index 05b5afaa62..eec59c5984 100644 --- a/lib/Matrix.pm +++ b/lib/Matrix.pm @@ -11,14 +11,7 @@ subroutines in this file are still used behind the scenes by Value::Matrix to perform calculations, such as decompose_LR(). -=head1 DESCRIPTION - - - -=head1 SYNOPSIS - - -=head3 Matrix Methods: +=head1 METHODS =cut @@ -32,9 +25,9 @@ use Carp; $Matrix::DEFAULT_FORMAT = '% #-19.12E '; # allows specification of the format -=head4 Method $matrix->_stringify() +=head2 _stringify - -- overrides MatrixReal1 display mode +overrides MatrixReal1 display mode =cut @@ -69,10 +62,10 @@ sub _stringify { return ($s); } -=head3 Accessor functions +=head1 FUNCTIONS - (these are deprecated for direct use. Use the covering Methods - provided by MathObject Matrices instead.) +(these are deprecated for direct use. Use the covering Methods +provided by MathObject Matrices instead.) L($matrix) - return matrix L of the LR decomposition R($matrix) - return matrix R of the LR decomposition @@ -136,7 +129,7 @@ sub PR { # use this permuation on the right PL*L*R*PR =M } -=head4 Method $matrix->rh_options +=head2 rh_options Meant for internal use when dealing with MatrixReal1 @@ -149,12 +142,12 @@ sub rh_options { $self->[$MatrixReal1::OPTION_ENTRY]; # provides a reference to the options hash MEG } -=head4 Method $matrix->trace +=head2 trace - Returns: scalar which is the trace of the matrix. +Returns: scalar which is the trace of the matrix. - Used by MathObject Matrices for calculating the trace. - Deprecated for direct use in PG questions. +Used by MathObject Matrices for calculating the trace. +Deprecated for direct use in PG questions. =cut @@ -170,9 +163,13 @@ sub trace { $sum; } -=head4 Method $new_matrix = $matrix->new_from_array_ref ([[a,b,c],[d,e,f]]) +=head2 new_from_array_ref + +Usage: + + $new_matrix = $matrix->new_from_array_ref ([[a,b,c],[d,e,f]]) - Deprecated in favor of using creation tools for MathObject Matrices +Deprecated in favor of using creation tools for MathObject Matrices =cut @@ -186,7 +183,7 @@ sub new_from_array_ref { # this will build a matrix or a row vector from [a, $matrix; } -=head4 Method $matrix->array_ref +=head2 array_ref Converts Matrix from an ARRAY to an ARRAY reference. @@ -197,7 +194,7 @@ sub array_ref { $this->[0]; } -=head4 Method $matrix->list +=head2 list Converts a Matrix column vector to an ARRAY (list). @@ -214,9 +211,9 @@ sub list { # this is used only for column vectors @list; } -=head4 Method $matrix->new_row_matrix +=head2 new_row_matrix [DEPRECATED] - Deprecated -- there are better tools for MathObject Matrices. +Deprecated -- there are better tools for MathObject Matrices. Create a row 1 by n matrix from a list. This subroutine appears to be broken @@ -236,10 +233,10 @@ sub new_row_matrix { # this builds a row vector from an array $matrix; } -=head4 Method $matrix->proj +=head2 proj - Provides behind the scenes calculations for MathObject Matrix->proj - Deprecated for direct use in favor of methods of MathObject matrix +Provides behind the scenes calculations for MathObject Matrix->proj +Deprecated for direct use in favor of methods of MathObject matrix =cut @@ -249,10 +246,10 @@ sub proj { $self * $self->proj_coeff($vec); } -=head4 Method $matrix->proj_coeff +=head2 proj_coeff - Provides behind the scenes calculations for MathObject Matrix->proj_coeff - Deprecated for direct use in favor of methods of MathObject matrix +Provides behind the scenes calculations for MathObject Matrix->proj_coeff +Deprecated for direct use in favor of methods of MathObject matrix =cut @@ -271,9 +268,9 @@ sub proj_coeff { $x_vector; } -=head4 Method $matrix->new_column_matrix +=head2 new_column_matrix - Create column matrix from an ARRAY reference (list reference) +Create column matrix from an ARRAY reference (list reference) =cut @@ -290,13 +287,13 @@ sub new_column_matrix { $matrix; } -=head4 Method $matrix->new_from_col_vecs +=head2 new_from_col_vecs - This method takes an array of column vectors, or an array of arrays, - and converts them to a matrix where each column is one of the previous - vectors. +This method takes an array of column vectors, or an array of arrays, +and converts them to a matrix where each column is one of the previous +vectors. - Deprecated: The tools for creating MathObjects Matrices are simpler +Deprecated: The tools for creating MathObjects Matrices are simpler =cut @@ -334,13 +331,13 @@ sub new_from_col_vecs { # Modifications to MatrixReal.pm which allow use of complex entries ###################################################################### -=head3 Overrides of MatrixReal which allow use of complex entries +=head1 Overrides of MatrixReal which allow use of complex entries =cut -=head4 Function: cp() +=head2 cp - Provides ability to use complex numbers. +Provides ability to use complex numbers. =cut @@ -350,7 +347,7 @@ sub cp { # MEG makes new copies of complex number Complex1::cplx($z->Re, $z->Im); } -=head4 Method $matrix->copy +=head2 copy =cut @@ -389,7 +386,7 @@ sub copy { # MEG added 6/25/03 to accomodate complex entries -=head4 Method $matrix->conj +=head2 conj =cut @@ -399,7 +396,7 @@ sub conj { $elem; } -=head4 Method $matrix->transpose +=head2 transpose =cut @@ -439,10 +436,10 @@ sub transpose { $matrix1; } -=head4 Method $matrix->decompose_LR +=head2 decompose_LR - Used by MathObjects Matrix for LR decomposition - Deprecated for direct use in PG problems. +Used by MathObjects Matrix for LR decomposition +Deprecated for direct use in PG problems. =cut diff --git a/lib/PGloadfiles.pm b/lib/PGloadfiles.pm index af1c455512..65f4932d5b 100644 --- a/lib/PGloadfiles.pm +++ b/lib/PGloadfiles.pm @@ -1,7 +1,13 @@ -=head2 loadMacros +=head1 NAME - loadMacros(@macroFiles) +loadMacros - load macros within a PG problem. + +=head1 DESCRIPTION + +Usage: + + loadMacros(@macroFiles) loadMacros takes a list of file names and evaluates the contents of each file. This is used to load macros which define and augment the PG language. The macro @@ -17,7 +23,7 @@ if $macrosPath contains the path to a problem library macros directory which contains a PG.pl file, this file will be loaded and allowed to engage in privileged behavior. -=head3 Overloading macro files +=head2 Overloading macro files An individual course can modify the PG language, for that course only, by duplicating one of the macro files in the system-wide macros directory and @@ -28,7 +34,7 @@ system-wide macros directory. The new file in the course macros directory can by modified by adding macros or modifying existing macros. -=head3 Modifying existing macros +=head2 Modifying existing macros I diff --git a/lib/Parser/Legacy/PGcomplexmacros.pl b/lib/Parser/Legacy/PGcomplexmacros.pl index 696880e563..153be18195 100644 --- a/lib/Parser/Legacy/PGcomplexmacros.pl +++ b/lib/Parser/Legacy/PGcomplexmacros.pl @@ -10,7 +10,7 @@ =head1 NAME Macros for complex numbers for the PG language -=head1 SYNPOSIS +=head1 SYNOPSIS diff --git a/lib/Regression.pm b/lib/Regression.pm index 12c0a1ffa4..953a05c5a2 100644 --- a/lib/Regression.pm +++ b/lib/Regression.pm @@ -13,7 +13,7 @@ use constant DEBUGGING => 0; =head1 NAME - Regression.pm - weighted linear regression package (line+plane fitting) +Regression.pm - weighted linear regression package (line+plane fitting) =head1 DESCRIPTION diff --git a/lib/Select.pm b/lib/Select.pm index 14bd2ed542..51f23a6dbe 100644 --- a/lib/Select.pm +++ b/lib/Select.pm @@ -5,9 +5,9 @@ =head1 NAME - Select.pm -- sub-class of ChoiceList that implements a select list. +Select.pm - sub-class of ChoiceList that implements a select list. - All items accessed by $out = $sl -> item( $in ); +All items accessed by $out = $sl -> item( $in ); =head1 SYNOPSIS diff --git a/lib/Value.pm b/lib/Value.pm index 8c23f9ead0..72c00fcd7f 100644 --- a/lib/Value.pm +++ b/lib/Value.pm @@ -18,44 +18,40 @@ like equality are "fuzzy", meaning that two items are equal when they are "close =cut -=head3 Value context - - ############################################################# - # - # Initialize the context-- flags set - # - The following are list objects, meaning that they involve delimiters (parentheses) - of some type. They get overridden in lib/Parser/Context.pm - - lists => { - 'Point' => {open => '(', close => ')'}, - 'Vector' => {open => '<', close => '>'}, - 'Matrix' => {open => '[', close => ']'}, - 'List' => {open => '(', close => ')'}, - 'Set' => {open => '{', close => '}'}, - }, - - The following context flags are set: - - # For vectors: - # +=head1 Value context + +The following are list objects, meaning that they involve delimiters (parentheses) +of some type. They get overridden in lib/Parser/Context.pm + + lists => { + 'Point' => {open => '(', close => ')'}, + 'Vector' => {open => '<', close => '>'}, + 'Matrix' => {open => '[', close => ']'}, + 'List' => {open => '(', close => ')'}, + 'Set' => {open => '{', close => '}'}, + }; + +The following context flags are set: + +For vectors: + ijk => 0, # print vectors as <...> - # - # For strings: - # + +For strings: + allowEmptyStrings => 1, infiniteWord => 'infinity', - # - # For intervals and unions: - # + +For intervals and unions: + ignoreEndpointTypes => 0, reduceSets => 1, reduceSetsForComparison => 1, reduceUnions => 1, reduceUnionsForComparison => 1, - # - # For fuzzy reals: - # + + For fuzzy reals: + useFuzzyReals => 1, tolerance => 1E-4, tolType => 'relative', @@ -63,9 +59,9 @@ like equality are "fuzzy", meaning that two items are equal when they are "close zeroLevelTol => 1E-12, tolTruncation => 1, tolExtraDigits => 1, - # - # For Formulas: - # + +For Formulas: + limits => [-2,2], num_points => 5, granularity => 1000, @@ -73,8 +69,6 @@ like equality are "fuzzy", meaning that two items are equal when they are "close max_adapt => 1E8, checkUndefinedPoints => 0, max_undefined => undef, - }, - =cut @@ -135,27 +129,25 @@ BEGIN { } -=head3 Implemented MathObject types and their precedence - - # - # Precedence of the various types - # (They will be promoted upward automatically when needed) - # - - 'Number' => 0, - 'Real' => 1, - 'Infinity' => 2, - 'Complex' => 3, - 'Point' => 4, - 'Vector' => 5, - 'Matrix' => 6, - 'List' => 7, - 'Interval' => 8, - 'Set' => 9, - 'Union' => 10, - 'String' => 11, - 'Formula' => 12, - 'special' => 20, +=head1 MathObject types and their precedence + +Precedence of the various types +(They will be promoted upward automatically when needed) + + 'Number' => 0, + 'Real' => 1, + 'Infinity' => 2, + 'Complex' => 3, + 'Point' => 4, + 'Vector' => 5, + 'Matrix' => 6, + 'List' => 7, + 'Interval' => 8, + 'Set' => 9, + 'Union' => 10, + 'String' => 11, + 'Formula' => 12, + 'special' => 20, =cut @@ -176,9 +168,8 @@ $$context->{precedence} = { 'special' => 20, }; -# # Binding of perl operator to class method -# + $$context->{method} = { '+' => 'add', '-' => 'sub', @@ -198,9 +189,8 @@ $$context->{pattern}{-infinity} = '-inf(?:inity)?'; push(@{ $$context->{data}{values} }, 'method', 'precedence'); -# # Copy an item and its data -# + sub copy { my $self = shift; my $copy = { %{$self} }; @@ -209,18 +199,17 @@ sub copy { return bless $copy, ref($self); } -=head3 getFlag +=head2 getFlag -# -# Get the value of a flag from the object itself, or from the -# equation that created the object (if any), or from the AnswerHash -# for the object (if it is being used as the source for an answer -# checker), or from the object's context, or from the current -# context, or use the given default, whichever is found first. -# +Get the value of a flag from the object itself, or from the +equation that created the object (if any), or from the AnswerHash +for the object (if it is being used as the source for an answer +checker), or from the object's context, or from the current +context, or use the given default, whichever is found first. - Usage: $mathObj->getFlag("showTypeWarnings"); - $mathObj->getFlag("showTypeWarnings",1); # default is second parameter +Usage: + $mathObj->getFlag("showTypeWarnings"); + $mathObj->getFlag("showTypeWarnings",1); # default is second parameter =cut @@ -242,9 +231,8 @@ sub getFlag { return shift; } -# # Get or set the context of an object -# + sub context { my $self = shift; my $context = shift; @@ -260,18 +248,14 @@ sub context { return $$Value::context; } -# # Set context but return object -# -sub inContext { my $self = shift; $self->context(@_); $self } -############################################################# +sub inContext { my $self = shift; $self->context(@_); $self } -# # The address of a Value object (actually ANY perl value). # Use this to compare two objects to see of they are # the same object (avoids automatic stringification). -# + sub address { Scalar::Util::refaddr(shift) } sub isBlessed { (Scalar::Util::blessed(shift) // '') ne "" } @@ -290,9 +274,16 @@ sub isHash { } -# example: return Boolean: Value->subclassed($self,"classMatch") -# if $self has the method 'classMath' and 'Value' has the method 'classMatch' -# and the reference to these methods don't agree then the method 'classMatch' has been subclassed. +=head2 subclassed + +Usage: + Value->subclassed($self,"classMatch") + +if $self has the method 'classMath' and 'Value' has the method 'classMatch' +and the reference to these methods don't agree then the method 'classMatch' has been subclassed. + +=cut + sub subclassed { my $self = shift; my $obj = shift; @@ -354,14 +345,17 @@ sub canBeInUnion { && $close =~ m/^[\)\]]$/; } -###################################################################### +=head2 Package + +Usage: + + Value->Package(name[,noerror]]) + +Returns the package name for the specificied Value object class +(as specified by the context's {value} hash, or "Value::name"). + +=cut -# -# Value->Package(name[,noerror]]) -# -# Returns the package name for the specificied Value object class -# (as specified by the context's {value} hash, or "Value::name"). -# sub Package { (shift)->context->Package(@_) } # Check if the object class matches one of a list of classes @@ -386,14 +380,13 @@ sub classMatch { return 0; } -=head3 makeValue +=head2 makeValue - Usage: Value::makeValue(45); +Usage: - Will create a Real mathObject. - # - # Convert non-Value objects to Values, if possible - # + Value::makeValue(45); + +This will create a Real mathObject and convert non-Value objects to Values, if possible =cut @@ -425,16 +418,13 @@ sub makeValue { return $x; } -=head3 showClass +=head2 showClass - Usage: TEXT( $mathObj -> showClass() ); +Usage: - Will print the class of the MathObject + $mathObj->showClass(); - # - # Get a printable version of the class of an object - # (used primarily in error messages) - # +This returns a printable version of the class of an object (used primarily in error messages) =cut @@ -455,17 +445,15 @@ sub showClass { return 'a ' . $class; } -=head3 showType +=head2 showType - Usage: TEXT( $mathObj -> showType() ); +Usage: - Will print the class of the MathObject + $mathObj->showType(); - # - # Get a printable version of the type of an object - # (the class and type are not the same. For example - # a Formula-class object can be of type Number) - # +This will return a printable version of the type of an object +(the class and type are not the same. For example +a Formula-class object can be of type Number) =cut @@ -487,9 +475,12 @@ sub showType { return 'a ' . $type; } -# -# Return a string describing a value's type -# +=head2 getType + +Return a string describing a value's type + +=cut + sub getType { my $equation = shift; my $value = shift; @@ -522,10 +513,12 @@ sub getType { return 'unknown'; } -# -# Get a string describing a value's type, -# and convert the value to a Value object (if needed) -# +=head2 getValueType + +Get a string describing a value's type, and convert the value to a Value object (if needed) + +=cut + sub getValueType { my $equation = shift; my $value = shift; @@ -545,9 +538,12 @@ sub getValueType { return ($value, $type); } -# -# Convert a list of values to a list of formulas (called by Parser::Value) -# +=head2 toFormula + +Convert a list of values to a list of formulas (called by Parser::Value) + +=cut + sub toFormula { my $formula = shift; my $processed = 0; @@ -565,11 +561,14 @@ sub toFormula { return (@f); } -# -# Convert a list of values (and open and close parens) -# to a formula whose type is the list type associated with -# the parens. -# +=head2 formula + +Convert a list of values (and open and close parens) +to a formula whose type is the list type associated with +the parens. + +=cut + sub formula { my $self = shift; my $values = shift; @@ -587,11 +586,14 @@ sub formula { return $formula; } -# -# A shortcut for new() that creates an instance of the object, -# but doesn't do the error checking. We assume the data are already -# known to be good. -# +=head2 make + +A shortcut for C that creates an instance of the object, +but doesn't do the error checking. We assume the data are already +known to be good. + +=cut + sub make { my $self = shift; my $class = ref($self) || $self; @@ -599,19 +601,25 @@ sub make { bless { $self->hashNoInherit, data => [@_], context => $context }, $class; } -# -# Easy method for setting parameters of an object -# (returns a copy with the new values set, but the copy -# is not a deep copy.) -# +=head2 with + +Easy method for setting parameters of an object +(returns a copy with the new values set, but the copy +is not a deep copy.) + +=cut + sub with { my $self = shift; bless { %{$self}, @_ }, ref($self); } -# -# Return a copy with the specified fields removed -# +=head2 without + +Return a copy with the specified fields removed + +=cut + sub without { my $self = shift; $self = bless { %{$self} }, ref($self); @@ -619,11 +627,12 @@ sub without { return $self; } -###################################################################### +=head2 hash + +Return the hash data as an array of key=>value pairs + +=cut -# -# Return the hash data as an array of key=>value pairs -# sub hash { my $self = shift; return %$self if isHash($self); @@ -637,11 +646,14 @@ sub hashNoInherit { return %hash; } -# -# Copy attributes that are not already in the current object -# from the given objects. (Used by binary operators to make sure -# the result inherits the values from the two terms.) -# +=head2 inherit + +Copy attributes that are not already in the current object +from the given objects. (Used by binary operators to make sure +the result inherits the values from the two terms.) + +=cut + sub inherit { my $self = shift; my %copy = (map {%$_} @_, $self); # copy values from given objects @@ -650,22 +662,25 @@ sub inherit { return $self; } -# -# The list of fields NOT to inherit. -# Use the default list plus any specified explicitly in the object itself. -# Subclasses can override and return additional fields, if necessary. -# +=head2 noinherit + +The list of fields NOT to inherit. +Use the default list plus any specified explicitly in the object itself. +Subclasses can override and return additional fields, if necessary. + +=cut + sub noinherit { my $self = shift; ("correct_ans", "correct_ans_latex_string", "original_formula", "equation", @{ $self->{noinherit} || [] }); } -###################################################################### +=head2 Type + +Return a type structure for the item (includes name, length of vectors, and so on) + +=cut -# -# Return a type structure for the item -# (includes name, length of vectors, and so on) -# sub Type { my $name = shift; my $length = shift; @@ -723,9 +738,12 @@ sub class { return $class; } -# -# Get an element from a point, vector, matrix, or list -# +=head2 extract + +Get an element from a point, vector, matrix, or list + +=cut + sub extract { my $M = shift; my $i; @@ -745,8 +763,6 @@ sub extract { return $M; } -###################################################################### - use overload '+' => '_add', '-' => '_sub', @@ -770,9 +786,12 @@ use overload 'nomethod' => 'nomethod', '""' => 'stringify'; -# -# Promote an operand to the same precedence as the current object -# +=head2 promotePrecedence + +Promote an operand to the same precedence as the current object + +=cut + sub promotePrecedence { my $self = shift; my $other = shift; @@ -794,19 +813,24 @@ sub promote { return $self->new($context, $x, @_); } -# -# Return the operators in the correct order -# +=head2 checkOpOrder + +Return the operators in the correct order + +=cut + sub checkOpOrder { my ($l, $r, $flag) = @_; if ($flag) { return ($l, $r, $l, $r) } else { return ($l, $l, $r, $r) } } -# -# Return the operators in the correct order, and promote the -# other value, if needed. -# +=head2 checkOpOrderWithPromote + +Return the operators in the correct order, and promote the other value, if needed. + +=cut + sub checkOpOrderWithPromote { my ($l, $r, $flag) = @_; $r = $l->promote($r); @@ -814,10 +838,13 @@ sub checkOpOrderWithPromote { else { return ($l, $l, $r, $r) } } -# -# Handle a binary operator, promoting the object types -# as needed, and then calling the main method -# +=head2 binOp + +Handle a binary operator, promoting the object types +as needed, and then calling the main method + +=cut + sub binOp { my ($l, $r, $flag, $call) = @_; if ($l->promotePrecedence($r)) { return $r->$call($l, !$flag) } @@ -928,18 +955,25 @@ sub dot { # sub pdot { shift->stringify } -# -# Compare the values of the objects +=head2 compare + +Compare the values of the objects + +=cut + # (list classes should replace this) -# + sub compare { my ($self, $l, $r) = Value::checkOpOrder(@_); return $l->value <=> $r->value; } -# -# Compare the values as strings -# +=head2 compare_string + +Compare the values as strings + +=cut + sub compare_string { my ($l, $r, $flag) = @_; $l = $l->string; @@ -949,9 +983,12 @@ sub compare_string { return $l cmp $r; } -# -# Copy flags from the parent object to its children (recursively). -# +=head2 transferFlags + +Copy flags from the parent object to its children (recursively). + +=cut + sub transferFlags { my $self = shift; foreach my $flag (@_) { @@ -971,24 +1008,15 @@ sub transferTolerances { $other->transferFlags("tolerance", "tolType", "zeroLevel", "zeroLevelTol") if Value::isValue($other); } -=head3 output methods for MathObjects - - # - # Generate the various output formats - # (can be replaced by sub-classes) - # +=head1 MathObjects output methods -=cut +=head2 stringify -=head4 stringify +Usage: - Usage: TEXT($mathObj); or TEXT( $mathObj->stringify() ) ; + $mathObj->stringify(); - Produces text string or TeX output depending on context - Context()->texStrings; - Context()->normalStrings; - - called automatically when object is called in a string context. +Produces text string or TeX output depending on context. =cut @@ -998,12 +1026,13 @@ sub stringify { return $self->string; } -=head4 ->string +=head2 string + +Usage: - Usage: $mathObj->string() + $mathObj->string() - ---produce a string representation of the object - (as opposed to stringify, which can produce TeX or string versions) +produce a string representation of the object (as opposed to stringify, which can produce TeX or string versions) =cut @@ -1038,11 +1067,13 @@ sub TO_JSON { return shift->string; } -=head4 ->TeX +=head2 TeX + +Usage: - Usage: $mathObj->TeX() + $mathObj->TeX() - ---produce TeX prepresentation of the object +produce TeX prepresentation of the object =cut @@ -1118,16 +1149,19 @@ sub ijk { Value::Error("Can't use method 'ijk' with objects of type '%s'", (shift)->class); } -=head3 Error +=head2 Error + +Usage: + + Value->Error("We're sorry..."); - Usage: Value->Error("We're sorry..."); - or $mathObject->Error("We're still sorry..."); +OR - # - # Report an error and die. This can be used within custom answer checkers - # to report errors during the check, or when sub-classing a MathObject to - # report error conditions. - # + $mathObject->Error("We're still sorry..."); + +Report an error and die. This can be used within custom answer checkers +to report errors during the check, or when sub-classing a MathObject to +report error conditions. =cut @@ -1142,9 +1176,12 @@ sub Error { die $message . getCaller(); } -# -# Try to locate the line and file where the error occurred -# +=head2 getCaller + +Try to locate the line and file where the error occurred + +=cut + sub getCaller { my $frame = 2; while (my ($pkg, $file, $line, $subname) = caller($frame++)) { @@ -1188,10 +1225,6 @@ END { use Value::WeBWorK; # stuff specific to WeBWorK } -########################################################################### - our $installed = 1; -########################################################################### - 1; diff --git a/lib/Value/AnswerChecker.pm b/lib/Value/AnswerChecker.pm index ec6a6b9b13..fb4dacb06c 100644 --- a/lib/Value/AnswerChecker.pm +++ b/lib/Value/AnswerChecker.pm @@ -1,42 +1,45 @@ +=head1 NAME + +AnswerChecker - Implements the compare method for Value objects. + =head1 DESCRIPTION - ############################################################# - # - # Implements the ->cmp method for Value objects. - # Otherwise known as MathObjects. This produces - # an answer checker appropriate for the type of object. - # Additional options can be passed to the cmp method to - # modify its action. - # - # Usage: $num = Real(3.45); # Real can be replaced by any other MathObject - # ANS($num->cmp(compareOptionName => compareOptionValue, ... )) - # - # The individual Value packages are modified below to add the - # needed methods. - # - ############################################################# +Implements the ->cmp method for Value objects. +Otherwise known as MathObjects. This produces +an answer checker appropriate for the type of object. +Additional options can be passed to the cmp method to +modify its action. + +Usage: + + $num = Real(3.45); # Real can be replaced by any other MathObject + ANS($num->cmp(compareOptionName => compareOptionValue, ... )) + +The individual Value packages are modified below to add the +needed methods. + +=head1 METHODS =cut package Value; use PGcore; -# # Context can add default values to the answer checkers by class; -# + $Value::defaultContext->{cmpDefaults} = {}; -=head4 $mathObject->cmp_defaults() +=head2 cmp_defaults -# Internal use. -# Set default flags for the answer checker in this object -# showTypeWarnings => 1 -# showEqualErrors => 1 -# ignoreStrings => 1 -# studentsMustReduceUnions => 1 -# showUnionReduceWarnings => 1 -# +Internal use. +Set default flags for the answer checker in this object + + showTypeWarnings => 1 + showEqualErrors => 1 + ignoreStrings => 1 + studentsMustReduceUnions => 1 + showUnionReduceWarnings => 1 =cut @@ -48,9 +51,7 @@ sub cmp_defaults { ( showUnionReduceWarnings => 1, ) } -# # Special Context flags to be set for the student answer -# sub cmp_contextFlags { my $self = shift; @@ -80,9 +81,7 @@ sub cmp_contextFlags { ); } -# # Create an answer checker for the given type of object -# sub cmp { my $self = shift; @@ -116,17 +115,15 @@ sub correct_ans { preformat(shift->string) } sub correct_ans_latex { shift->TeX } sub cmp_diagnostics { } -# # Parse the student answer and compute its value, # produce the preview strings, and then compare the # student and professor's answers for equality. -# + sub cmp_parse { my $self = shift; my $ans = shift; - # + # Do some setup - # my $context = $ans->{correct_value}{context} || $current; Parser::Context->current(undef, $context); # change to correct answser's context my $flags = contextSet($context, $self->cmp_contextFlags($ans)); # save old context flags @@ -138,10 +135,8 @@ sub cmp_parse { $context->clearError(); $context->{answerHash} = $ans; # values here can override context flags - # # Parse and evaluate the student answer - # - $ans->score(0); # assume failure + $ans->score(0); # assume failure $context->flags->set( parseMathQuill => $context->flag("useMathQuill") && (!defined $context->{answerHash}{mathQuillOpts} || $context->{answerHash}{mathQuillOpts} !~ /^\s*disabled\s*$/i) @@ -151,19 +146,18 @@ sub cmp_parse { if defined($ans->{student_formula}) && $ans->{student_formula}->isConstant; $context->flags->set(parseMathQuill => 0); - # # If it parsed OK, save the output forms and check if it is correct # otherwise report an error - # + if (defined $ans->{student_value}) { $ans->{student_value} = $self->Package("Formula")->new($ans->{student_value}) unless Value::isValue($ans->{student_value}); $ans->{student_value}{isStudent} = 1; $ans->{preview_latex_string} = $ans->{student_formula}->TeX; $ans->{preview_text_string} = preformat($ans->{student_formula}->string); - # + # Get the string for the student answer - # + for ($self->getFlag('formatStudentAnswer')) { /evaluated/i and do { $ans->{student_ans} = preformat($ans->{student_value}->string); last }; /parsed/i and do { $ans->{student_ans} = $ans->{preview_text_string}; last }; @@ -191,10 +185,9 @@ sub cmp_parse { return $ans; } -# # Check if the object has an answer array and collect the results # Build the combined student answer and set the preview values -# + sub cmp_collect { my $self = shift; my $ans = shift; @@ -831,17 +824,22 @@ sub getPG { eval('package main; ' . shift); # faster } -############################################################# -############################################################# +=head2 Compare Details for Default MathObjects =head3 Value::Real - Usage ANS( Real(3.56)->cmp() ) - Compares response to a real value using 'fuzzy' comparison - compareOptions and default values: - showTypeWarnings => 1, - showEqualErrors => 1, - ignoreStrings => 1, +Options for C for C: + +Usage: + + ANS( Real(3.56)->cmp() ) + +Compares response to a real value using 'fuzzy' comparison +compareOptions and default values: + + showTypeWarnings => 1, + showEqualErrors => 1, + ignoreStrings => 1, =cut @@ -879,17 +877,23 @@ sub typeMatch { =head3 Value::String - Usage: $s = String("pole"); - ANS($s->cmp(typeMatch => Complex("4+i"))); - # compare to response 'pole', don't complain about complex number responses. +Options for C for C: + +Usage: - compareOptions and default values: - showTypeWarnings => 1, - showEqualErrors => 1, - ignoreStrings => 1, # don't complain about string-valued responses - typeMatch => 'Value::Real' + $s = String("pole"); + ANS($s->cmp(typeMatch => Complex("4+i"))); - Initial and final spaces are ignored when comparing strings. +compare to response 'pole', don't complain about complex number responses. + +compareOptions and default values: + + showTypeWarnings => 1, + showEqualErrors => 1, + ignoreStrings => 1, # don't complain about string-valued responses + typeMatch => 'Value::Real' + +Leading and trailing spaces are ignored when comparing strings. =cut @@ -959,17 +963,23 @@ sub cmp_preprocess { =head3 Value::Point - Usage: $pt = Point("(3,6)"); # preferred - or $pt = Point(3,6); - or $pt = Point([3,6]); - ANS($pt->cmp()); +Options for C for C: + +Usage: - compareOptions: - showTypeWarnings => 1, # warns if student response is of incorrect type - showEqualErrors => 1, - ignoreStrings => 1, - showDimensionHints => 1, # reports incorrect number of coordinates - showCoordinateHints =>1, # flags individual coordinates that are incorrect + $pt = Point("(3,6)"); # preferred + $pt = Point(3,6); + $pt = Point([3,6]); + + ANS($pt->cmp()); + +compareOptions and default values: + + showTypeWarnings => 1, # warns if student response is of incorrect type + showEqualErrors => 1, + ignoreStrings => 1, + showDimensionHints => 1, # reports incorrect number of coordinates + showCoordinateHints =>1, # flags individual coordinates that are incorrect =cut @@ -1034,26 +1044,29 @@ sub ans_array { my $self = shift; $self->ANS_MATRIX(0, '', @_) } sub named_ans_array { my $self = shift; $self->ANS_MATRIX(0, @_) } sub named_ans_array_extension { my $self = shift; $self->ANS_MATRIX(1, @_) } -############################################################# - =head3 Value::Vector - Usage: $vec = Vector("<3,6,7>"); - or $vec = Vector(3,6,7); - or $vec = Vector([3,6,7]); - ANS($vec->cmp()); +Options for C for C: - compareOptions: - showTypeWarnings => 1, # warns if student response is of incorrect type - showEqualErrors => 1, - ignoreStrings => 1, - showDimensionHints => 1, # reports incorrect number of coordinates - showCoordinateHints => 1, # flags individual coordinates which are incorrect - promotePoints => 0, # allow students to enter vectors as points (3,5,6) - parallel => 1, # response is correct if it is parallel to correct answer - sameDirection => 1, # response is correct if it has same orientation as correct answer - # (only has an effect when parallel => 1 is specified) +Usage: + $vec = Vector("<3,6,7>"); + $vec = Vector(3,6,7); + $vec = Vector([3,6,7]); + + ANS($vec->cmp()); + +compareOptions and default values: + + showTypeWarnings => 1, # warns if student response is of incorrect type + showEqualErrors => 1, + ignoreStrings => 1, + showDimensionHints => 1, # reports incorrect number of coordinates + showCoordinateHints => 1, # flags individual coordinates which are incorrect + promotePoints => 0, # allow students to enter vectors as points (3,5,6) + parallel => 1, # response is correct if it is parallel to correct answer + sameDirection => 1, # response is correct if it has same orientation as correct answer + # (only has an effect when parallel => 1 is specified) =cut @@ -1167,21 +1180,24 @@ sub ans_array { my $self = shift; $self->ANS_MATRIX(0, '', @_) } sub named_ans_array { my $self = shift; $self->ANS_MATRIX(0, @_) } sub named_ans_array_extension { my $self = shift; $self->ANS_MATRIX(1, @_) } -############################################################# - =head3 Value::Matrix - Usage $ma = Matrix([[3,6],[2,5]]) or $ma =Matrix([3,6],[2,5]) - ANS($ma->cmp()); +Options for C for C: + +Usage: + + $ma = Matrix([[3,6],[2,5]]) + $ma = Matrix([3,6],[2,5]) - compareOptions: + ANS($ma->cmp()); - showTypeWarnings => 1, # warns if student response is of incorrect type - showEqualErrors => 1, # reports messages that occur during element comparisons - ignoreStrings => 1, - showDimensionHints => 1, # reports incorrect number of coordinates - showCoordinateHints => 1, # flags individual coordinates which are incorrect +compareOptions and default values: + showTypeWarnings => 1, # warns if student response is of incorrect type + showEqualErrors => 1, # reports messages that occur during element comparisons + ignoreStrings => 1, + showDimensionHints => 1, # reports incorrect number of coordinates + showCoordinateHints => 1, # flags individual coordinates which are incorrect =cut @@ -1268,22 +1284,23 @@ sub ans_array { my $self = shift; $self->ANS_MATRIX(0, '', @_) } sub named_ans_array { my $self = shift; $self->ANS_MATRIX(0, @_) } sub named_ans_array_extension { my $self = shift; $self->ANS_MATRIX(1, @_) } -############################################################# - =head3 Value::Interval - Usage: $interval = Interval("(1,2]"); - or $interval = Interval('(',1,2,']'); - ANS($inteval->cmp); +Usage: - compareOptions and defaults: - showTypeWarnings => 1, - showEqualErrors => 1, - ignoreStrings => 1, - showEndpointHints => 1, # show hints about which end point values are correct - showEndTypeHints => 1, # show hints about endpoint types - requireParenMatch => 1, + $interval = Interval("(1,2]"); + $interval = Interval('(',1,2,']'); + ANS($inteval->cmp); + +compareOptions and default values: + + showTypeWarnings => 1, + showEqualErrors => 1, + ignoreStrings => 1, + showEndpointHints => 1, # show hints about which end point values are correct + showEndTypeHints => 1, # show hints about endpoint types + requireParenMatch => 1, =cut @@ -1339,18 +1356,22 @@ sub cmp_postprocess { $self->cmp_Error($ans, @errors); } -############################################################# - =head3 Value::Set - Usage: $set = Set(5,6,'a', 'b') - or $set = Set("{5, 6, a, b}") +Options for C for C: - The object is a finite set of real numbers. It can be used with Union and - Interval. +Usage: - Examples: Interval("(-inf,inf)") - Set(0) - Compute("R-{0}") # in Interval context: Context("Interval"); + $set = Set(5,6,'a', 'b') + $set = Set("{5, 6, a, b}") + +The object is a finite set of real numbers. It can be used with Union and +Interval. + +Examples: + + Interval("(-inf,inf)") - Set(0) + Compute("R-{0}") # in Interval context: Context("Interval"); =cut @@ -1403,14 +1424,13 @@ sub cmp_compare { $self->SUPER::cmp_compare($student, $ans, @_); } -############################################################# - =head3 Value::Union - Usage: $union = Union("[4,5] U [6,7]"); - or $union = Union(Interval("[4,5]",Interval("[6,7]")); - ANS($union->cmp()); +Usage: + $union = Union("[4,5] U [6,7]"); + $union = Union(Interval("[4,5]",Interval("[6,7]")); + ANS($union->cmp()); =cut @@ -1470,30 +1490,34 @@ sub cmp_compare { =head3 Value::List - Usage: $lst = List("1, x, <4,5,6>"); # list of a real, a formula and a vector. - or $lst = List(Real(1), Formula("x"), Vector(4,5,6)); - ANS($lst->cmp(showHints=>1)); - - compareOptions and defaults: - showTypeWarnings => 1, - showEqualErrors => 1, # show errors produced when checking equality of entries - ignoreStrings => 1, # don't show type warnings for strings - studentsMustReduceUnions => 1, - showUnionReduceWarnings => 1, - showHints => undef, # automatically set to 1 if $showPartialCorrectAnswers == 1 - showLengthHints => undef, # automatically set to 1 if $showPartialCorrectAnswers == 1 - showParenHints => undef, # automatically set to 1 if $showPartialCorrectAnswers == 1 - partialCredit => undef, # automatically set to 1 if $showPartialCorrectAnswers == 1 - ordered => 0, # 1 = must be in same order as correct answer - entry_type => undef, # determined from first entry - list_type => undef, # determined automatically - typeMatch => $element, # used for type checking the entries - firstElement => $element, - extra => undef, # used to check syntax of incorrect answers - requireParenMatch => 1, # student parens must match correct parens - removeParens => 1, # remove outermost parens, if any - implicitList => 1, # force single answers to be lists (even if they ARE lists) - +Options for C for C: + +Usage: + + $lst = List("1, x, <4,5,6>"); # list of a real, a formula and a vector. + $lst = List(Real(1), Formula("x"), Vector(4,5,6)); + ANS($lst->cmp(showHints=>1)); + +compareOptions and default values: + + showTypeWarnings => 1, + showEqualErrors => 1, # show errors produced when checking equality of entries + ignoreStrings => 1, # don't show type warnings for strings + studentsMustReduceUnions => 1, + showUnionReduceWarnings => 1, + showHints => undef, # automatically set to 1 if $showPartialCorrectAnswers == 1 + showLengthHints => undef, # automatically set to 1 if $showPartialCorrectAnswers == 1 + showParenHints => undef, # automatically set to 1 if $showPartialCorrectAnswers == 1 + partialCredit => undef, # automatically set to 1 if $showPartialCorrectAnswers == 1 + ordered => 0, # 1 = must be in same order as correct answer + entry_type => undef, # determined from first entry + list_type => undef, # determined automatically + typeMatch => $element, # used for type checking the entries + firstElement => $element, + extra => undef, # used to check syntax of incorrect answers + requireParenMatch => 1, # student parens must match correct parens + removeParens => 1, # remove outermost parens, if any + implicitList => 1, # force single answers to be lists (even if they ARE lists) =cut @@ -1826,16 +1850,15 @@ sub getOption { return $ans->{showPartialCorrectAnswers}; } -############################################################# - =head3 Value::Formula - Usage: $fun = Formula("x^2-x+1"); - $set = Formula("[-1, x) U (x, 2]"); +Usage: - A formula can have any of the other math object types as its range. - Union, List, Number (Complex or Real), + $fun = Formula("x^2-x+1"); + $set = Formula("[-1, x) U (x, 2]"); +A formula can have any of the other math object types as its range. +Union, List, Number (Complex or Real), =cut diff --git a/lib/VectorField.pm b/lib/VectorField.pm index 6d071229ce..fbec4e9de6 100644 --- a/lib/VectorField.pm +++ b/lib/VectorField.pm @@ -1,9 +1,9 @@ =head1 NAME - VectorField +VectorField - Produce a vector field plot. -=head1 SYNPOSIS +=head1 SYNOPSIS use Carp; use GD; diff --git a/lib/WWPlot.pm b/lib/WWPlot.pm index 6d5175c51a..c3c98a2197 100644 --- a/lib/WWPlot.pm +++ b/lib/WWPlot.pm @@ -8,9 +8,9 @@ =head1 NAME - WWPlot +WWPlot - methods to create plots. -=head1 SYNPOSIS +=head1 SYNOPSIS $graph = new WWPlot(400,400); # creates a graph 400 pixels by 400 pixels diff --git a/lib/WeBWorK/PG/ConvertToPGML.pm b/lib/WeBWorK/PG/ConvertToPGML.pm index 6d087ffc8e..04e4eeddba 100644 --- a/lib/WeBWorK/PG/ConvertToPGML.pm +++ b/lib/WeBWorK/PG/ConvertToPGML.pm @@ -1,7 +1,7 @@ =head1 NAME -WeBWorK::PG::ConvertToPGML +WeBWorK::PG::ConvertToPGML - convert a file in original PG format to PGML =head1 DESCRIPTION @@ -10,19 +10,44 @@ Converts a pg file to PGML format. This script does a number of conversions: =over -=item Update the loadMacros call to include PGML.pl, eliminate MathObject.pl (since it is loaded by PGML.pl) -and adds PGcourse.pl to the end of the list. -=item Coverts BEGIN_TEXT/END_TEXT (and older versions of this), BEGIN_SOLUTION/END_SOLUTION, BEGIN_HINT/END_HINT -to their newer BEGIN_PGML blocks. -=item Convert math mode in these blocks to PGML style math mode. -=item Convert other styling (bold, italics) to PGML style. -=item Convert variables to the interpolated [$var] PGML style. -=item Convert some of the answer rules to newer PGML style. -=item Remove some outdated code. -=item A few other minor things. + +=item * + +Update the loadMacros call to include C, eliminate C (since it is loaded by C) +and adds C to the end of the list. + +=item * + +Coverts C/C (and older versions of this), C/C, +C/C to their newer C blocks. + +=item * + +Convert math mode in these blocks to PGML style math mode. + +=item * + +Convert other styling (bold, italics) to PGML style. + +=item * + +Convert variables to the interpolated C<[$var]> PGML style. + +=item * + +Convert some of the answer rules to newer PGML style. + +=item * + +Remove some outdated code. + +=item * + +A few other minor things. + =back -=head1 OPTIONS +=head1 FUNCTIONS =cut @@ -34,15 +59,16 @@ use warnings; our @EXPORT = qw(convertToPGML); -# This subroutine converts the file that is passed in as a multi-line string and -# assumed to be an older-style PG file with BEGIN_TEXT/END_TEXT, BEGIN_SOLUTION/END_SOLUTION, -# and BEGIN_HINT/END_HINT blocks. +=head2 convertToPGML -# * parses the loadMacros line(s) to include PGML.pl (and eliminate MathObjects.pl, which) -# is imported by PGML.pl. This also adds PGcourse.pl to the end of the list. +This subroutine converts the file that is passed in as a multi-line string and +assumed to be an older-style PG file with BEGIN_TEXT/END_TEXT, BEGIN_SOLUTION/END_SOLUTION, +and BEGIN_HINT/END_HINT blocks. -# input is a string containing the source of the pg file to be converted. -# returns a string that is the converted input string. +The input is expected to be a string containing the source of the pg file to be converted. +This returns a string that is the converted input string. + +=cut # This stores the answers inside of ANS and related functions. my @ans_list; diff --git a/lib/WeBWorK/PG/EquationCache.pm b/lib/WeBWorK/PG/EquationCache.pm index cd41935008..ffc19f9eca 100644 --- a/lib/WeBWorK/PG/EquationCache.pm +++ b/lib/WeBWorK/PG/EquationCache.pm @@ -4,7 +4,7 @@ package WeBWorK::PG::EquationCache; WeBWorK::PG::EquationCache - create and cache images of TeX equations. -=head1 SYNPOSIS +=head1 SYNOPSIS my $cache = WeBWorK::PG::EquationCache->new(cacheDB => "/path/to/equationcache.db"); my $imageName = $cache->lookup('\[3x^2\]'); diff --git a/lib/WeBWorK/PG/ImageGenerator.pm b/lib/WeBWorK/PG/ImageGenerator.pm index 88915a6d94..a5d09c86b3 100644 --- a/lib/WeBWorK/PG/ImageGenerator.pm +++ b/lib/WeBWorK/PG/ImageGenerator.pm @@ -5,7 +5,7 @@ package WeBWorK::PG::ImageGenerator; WeBWorK::PG::ImageGenerator - create an object for holding bits of math for LaTeX, and then to process them all at once. -=head1 SYNPOSIS +=head1 SYNOPSIS my $image_generator = WeBWorK::PG::ImageGenerator->new( tempDir => $pg_envir->{directories}{tmp}, diff --git a/lib/WeBWorK/PG/RestrictedClosureClass.pm b/lib/WeBWorK/PG/RestrictedClosureClass.pm index 80d3302e5d..2345e75ce8 100644 --- a/lib/WeBWorK/PG/RestrictedClosureClass.pm +++ b/lib/WeBWorK/PG/RestrictedClosureClass.pm @@ -5,7 +5,7 @@ package WeBWorK::PG::RestrictedClosureClass; WeBWorK::PG::RestrictedClosureClass - Protect instance data and only allow calling of specified methods. -=head1 SYNPOSIS +=head1 SYNOPSIS package MyScaryClass; diff --git a/lib/WeBWorK/PG/Translator.pm b/lib/WeBWorK/PG/Translator.pm index cab91b7e89..f74566610b 100644 --- a/lib/WeBWorK/PG/Translator.pm +++ b/lib/WeBWorK/PG/Translator.pm @@ -4,7 +4,7 @@ package WeBWorK::PG::Translator; WeBWorK::PG::Translator - Evaluate PG code and evaluate answers safely -=head1 SYNPOSIS +=head1 SYNOPSIS my $pt = WeBWorK::PG::Translator->new; # create a translator $pt->environment(\%envir); # provide the environment variable for the problem