Difference between revisions of "Common MathObject Methods"

From WeBWorK_wiki
Jump to navigation Jump to search
m (Remove header)
(Reformat as a table (to match usage in individual class files))
Line 1: Line 1:
 
There are a number of methods that are common to all MathObjects, which are described below. Some classes have additional methods, and many of these are listed in the documentation for the individual [[:Category:MathObject_Classes|MathObject Classes]]. You call a method on a MathObject as you would a method for any Perl object, using the <code>-></code> operator with the MathObject on the left and the method name and its arguments (if any) on the right. E.g.,
 
There are a number of methods that are common to all MathObjects, which are described below. Some classes have additional methods, and many of these are listed in the documentation for the individual [[:Category:MathObject_Classes|MathObject Classes]]. You call a method on a MathObject as you would a method for any Perl object, using the <code>-></code> operator with the MathObject on the left and the method name and its arguments (if any) on the right. E.g.,
   
$mathObject->method; # when there are no arguments
+
$mo->method; # when there are no arguments
$mathObject->method($arg); # for one argument
+
$mo->method($arg); # for one argument
$mathObject->method($arg1,$arg2); # for two arguments
+
$mo->method($arg1,$arg2); # for two arguments
 
# and so on
 
# and so on
   
 
The common methods include:
 
The common methods include:
   
* <code>cmp</code> or <code>cmp(options)</code>
 
  +
{| class="wikitable"
: Returns an answer checker for the MathObject. The <code>cmp</code> method can accept a number of settings that control the tolerances for the comparison, special options of the comparison (e.g., parallel vectors rather than equal vectors), the types of error messages produced (e.g., messages about individual coordinates that are wrong), and other features of the check. These are described in the [http://webwork.maa.org/pod/pg_TRUNK/doc/MathObjects/MathObjectsAnswerCheckers.html MathObjects Answer Checkers] POD documentation. All of the answer checkers are defined in the file <code>pg/lib/Value/AnswerChecker.pm</code>.
 
  +
! Method !! Description
   
* <code>value</code>
 
  +
|- style="vertical-align: top"
: Returns an array containing the data that represents the object. For a Real, it is just the perl real number that corresponds to it; for a Complex number, it is the real and imaginary parts (as Reals). For an Infinity, it is the string needed to obtain the Infinity. For a Point or Vector, it is the coordinates of the Point or Vector (as MathObjects). For a Matrix, it is an array of rows of the Matrix, where the rows are references to arrays of MathObjects. For an Interval, it is the two endpoints (as Reals) followed by strings that are the open and close parentheses or brackets for the Interval. For a Set, it is an array of the elements of the set (as Reals). For a Union, it is an array of the Sets and Intervals that make up the Union. For a String, it is a perl string representing the value of the string.
 
  +
| style="padding: 5px; white-space: nowrap" | <code>$mc->cmp</code><br><code>$mo->cmp(options)</code>
  +
| style="padding: 5px" | Returns an answer checker for the MathObject. The <code>cmp</code> method can accept a number of settings that control the tolerances for the comparison, special options of the comparison (e.g., parallel vectors rather than equal vectors), the types of error messages produced (e.g., messages about individual coordinates that are wrong), and other features of the check. These are described in the [http://webwork.maa.org/pod/pg_TRUNK/doc/MathObjects/MathObjectsAnswerCheckers.html MathObjects Answer Checkers] POD documentation. All of the answer checkers are defined in the file <code>pg/lib/Value/AnswerChecker.pm</code>.
   
: For a Formula, it is a little more complicated. If the Formula is an explicit Point, Vector, Matrix, Interval, etc. (e.g., <code>Formula("<x,x+1>")</code>), then the value is an array of Formulas that are the coordinates. If the Formula is an expression (e.g., <code>Formula("<x,1> + <2x,-x>")</code> or <code>Formula("norm(<x,x+1>)"</code>) then the value is just the original Formula.
 
  +
|- style="vertical-align: top"
  +
| style="padding: 5px; white-space: nowrap" | <code>$mo->value</code>
  +
| style="padding: 5px" | Returns an array containing the data that represents the object. For a Real, it is just the perl real number that corresponds to it; for a Complex number, it is the real and imaginary parts (as Reals). For an Infinity, it is the string needed to obtain the Infinity. For a Point or Vector, it is the coordinates of the Point or Vector (as MathObjects). For a Matrix, it is an array of rows of the Matrix, where the rows are references to arrays of MathObjects. For an Interval, it is the two endpoints (as Reals) followed by strings that are the open and close parentheses or brackets for the Interval. For a Set, it is an array of the elements of the set (as Reals). For a Union, it is an array of the Sets and Intervals that make up the Union. For a String, it is a perl string representing the value of the string.
   
* <code>getFlag("flag-name")</code> or <code>getFlag("flag-name",default)</code>
 
  +
For a Formula, it is a little more complicated. If the Formula is an explicit Point, Vector, Matrix, Interval, etc. (e.g., <code>Formula("<x,x+1>")</code>), then the value is an array of Formulas that are the coordinates. If the Formula is an expression (e.g., <code>Formula("<x,1> + <2x,-x>")</code> or <code>Formula("norm(<x,x+1>)"</code>) then the value is just the original Formula.
: Returns the object's value for a given context flag. The value can come from a variety of locations, which are searched in the following order (the first that has a property with the given flag name will have that propery's value returned): the object itself, the Formula that created it (if it was the result of an <code>eval()</code> call, for example), the AnswerHash associated with the object (if it was the source for an answer checker; this gives access to the flags passed to the <code>cmp</code> method), the Context in which the object was created, the currently active Context, or the default value (if given as the second argument), otherwise the return value is <code>undef</code>. This is useful in custom answer checkers for finding out the settings of things like the tolerances, the flags passed to the answer checker, and so on.
 
   
* <code>with(name => value)</code>
 
  +
|- style="vertical-align: top"
: This copies the object, and sets its property with the given name to the given value. You can supply multiple name/value pairs separated by commas. This gives you the ability to initialize the object when you create it, or to make a copy with specific settings. E.g.
 
  +
| style="padding: 5px; white-space: nowrap" | <code>$mo->getFlag("name")</code><br><code>$mo->getFlag("name",default)</code>
  +
| style="padding: 5px" | Returns the object's value for a given context flag. The value can come from a variety of locations, which are searched in the following order (the first that has a property with the given flag name will have that propery's value returned): the object itself, the Formula that created it (if it was the result of an <code>eval()</code> call, for example), the AnswerHash associated with the object (if it was the source for an answer checker; this gives access to the flags passed to the <code>cmp</code> method), the Context in which the object was created, the currently active Context, or the default value (if given as the second argument), otherwise the return value is <code>undef</code>. This is useful in custom answer checkers for finding out the settings of things like the tolerances, the flags passed to the answer checker, and so on.
  +
  +
|- style="vertical-align: top"
  +
| style="padding: 5px; white-space: nowrap" | <code>$mo->with(name => value)</code>
  +
| style="padding: 5px" | This copies the object, and sets its property with the given name to the given value. You can supply multiple name/value pairs separated by commas. This gives you the ability to initialize the object when you create it, or to make a copy with specific settings. E.g.
   
 
$f = Formula("sqrt(x-10)")->with(limits => [10,12]);
 
$f = Formula("sqrt(x-10)")->with(limits => [10,12]);
 
$a = Real(pi/2)->with(period => 2*pi);
 
$a = Real(pi/2)->with(period => 2*pi);
   
* <code>typeMatch($object)</code>
 
  +
|- style="vertical-align: top"
: This determines if the <code>$object</code> is "compatible" with the given MathObject for equality or inequality comparisons. For example, a Real will allow equality comparison to an Infinity, and a Complex will allow comparison to a Real. It is best to use <code>typeMatch</code> in your own custom answer checkers if you need to check if a student's answer is of the correct type rather than using something like <code>ref()</code> to check if the two are the same type of object (which is too restrictive, in general).
 
  +
| style="padding: 5px; white-space: nowrap" | <code>$mo->typeMatch($object)</code>
  +
| style="padding: 5px" | This determines if the <code>$object</code> is "compatible" with the given MathObject for equality or inequality comparisons. For example, a Real will allow equality comparison to an Infinity, and a Complex will allow comparison to a Real. It is best to use <code>typeMatch</code> in your own custom answer checkers if you need to check if a student's answer is of the correct type rather than using something like <code>ref()</code> to check if the two are the same type of object (which is too restrictive, in general).
   
* <code>class</code> and <code>type</code>
 
  +
|- style="vertical-align: top"
: These are two methods that help you determine what kind of MathObject you are working with. They can be useful in custom answer checkers if you want to know more about what kind of object a student answer is. The <code>class</code> method tells you the class of object (like Real, Complex, Point, Formula, etc.), while the <code>type</code> method tells you what kind of return value a Formula has (non-Formulas are considered constant-valued Formulas when computing the <code>type</code>). The <code>class</code> is essentially the package name from the Value package of the MathObject, while the <code>type</code> is the package name from the Parser package name for the result of the Formula.
 
  +
| style="padding: 5px; white-space: nowrap" | <code>$mo->class</code><br><code>$mo->type</code>
  +
| style="padding: 5px" | These are two methods that help you determine what kind of MathObject you are working with. They can be useful in custom answer checkers if you want to know more about what kind of object a student answer is. The <code>class</code> method tells you the class of object (like Real, Complex, Point, Formula, etc.), while the <code>type</code> method tells you what kind of return value a Formula has (non-Formulas are considered constant-valued Formulas when computing the <code>type</code>). The <code>class</code> is essentially the package name from the Value package of the MathObject, while the <code>type</code> is the package name from the Parser package name for the result of the Formula.
   
 
Real(5)->class; # produces "Real"
 
Real(5)->class; # produces "Real"
Line 39: Line 48:
 
Formula("3x+1")->type; # produces "Number"
 
Formula("3x+1")->type; # produces "Number"
   
* <code>TeX</code>
 
  +
|- style="vertical-align: top"
: Returns a string which represents the object in TeX format. For example
 
  +
| style="padding: 5px; white-space: nowrap" | <code>$mo->TeX</code>
  +
| style="padding: 5px" | Returns a string which represents the object in TeX format. For example
   
 
$f = Formula("(x+1)/(x-1)");
 
$f = Formula("(x+1)/(x-1)");
Line 47: Line 57:
 
END_TEXT
 
END_TEXT
   
: Since it is common to need the TeX expression in the problem's text, there is a special Context setting that tells MathObjects to output their TeX format whenever they are substituted into a string. That is enabled via the <code>Context()->texStrings</code> command, and turned off by <code>Context()->normalStrings</code>, as in the following example:
+
Since it is common to need the <math>\rm\TeX</math> expression in the problem's text, there is a special Context setting that tells MathObjects to output their <math>\rm\TeX</math> format whenever they are substituted into a string. That is enabled via the <code>Context()->texStrings</code> command, and turned off by <code>Context()->normalStrings</code>, as in the following example:
   
 
$f = Formula("(x+1)/(x-1)");
 
$f = Formula("(x+1)/(x-1)");
Line 56: Line 66:
 
Context()->normalStrings;
 
Context()->normalStrings;
   
: This avoids having to call the <code>TeX</code> method, and prevents the need for using <code>\{...\}</code> to get the TeX format.
+
This avoids having to call the <code>TeX()</code> method, and prevents the need for using <code>\{...\}</code> to get the <math>\rm\TeX</math> format.
   
* <code>string</code>
 
  +
|- style="vertical-align: top"
: Returns a string similar to that used to create the object, in the form that a student would use to enter the object in an answer blank, or that could be used in <code>Compute()</code> to create the object. The string may have more parentheses than the original string used to create the object, and may include explicit multiplication rather than implicit multiplication, and other normalization of the original format.
 
  +
| style="padding: 5px; white-space: nowrap" | <code>$mo->string</code>
  +
| style="padding: 5px" | Returns a string similar to that used to create the object, in the form that a student would use to enter the object in an answer blank, or that could be used in <code>Compute()</code> to create the object. The string may have more parentheses than the original string used to create the object, and may include explicit multiplication rather than implicit multiplication, and other normalization of the original format.
   
* <code>perl</code>
 
  +
|- style="vertical-align: top"
: Returns a string which represents the object as Perl source code. This is used internally, and would rarely be needed in a PG problem.
 
  +
| style="padding: 5px; white-space: nowrap" | <code>$mo->perl</code>
  +
| style="padding: 5px" | Returns a string which represents the object as Perl source code. This is used internally, and would rarely be needed in a PG problem.
   
  +
|}
   
 
'''(Still need to add answer checker methods, like ans_rule and ans_array. Also, look at Value.pm for more, like isOne, isZero, etc.)'''
 
'''(Still need to add answer checker methods, like ans_rule and ans_array. Also, look at Value.pm for more, like isOne, isZero, etc.)'''
 
'''(Reformat list as table?)'''
 
   
 
<br>
 
<br>

Revision as of 11:36, 6 August 2012

There are a number of methods that are common to all MathObjects, which are described below. Some classes have additional methods, and many of these are listed in the documentation for the individual MathObject Classes. You call a method on a MathObject as you would a method for any Perl object, using the -> operator with the MathObject on the left and the method name and its arguments (if any) on the right. E.g.,

   $mo->method;              # when there are no arguments
   $mo->method($arg);        # for one argument
   $mo->method($arg1,$arg2); # for two arguments
   # and so on

The common methods include:

Method Description
$mc->cmp
$mo->cmp(options)
Returns an answer checker for the MathObject. The cmp method can accept a number of settings that control the tolerances for the comparison, special options of the comparison (e.g., parallel vectors rather than equal vectors), the types of error messages produced (e.g., messages about individual coordinates that are wrong), and other features of the check. These are described in the MathObjects Answer Checkers POD documentation. All of the answer checkers are defined in the file pg/lib/Value/AnswerChecker.pm.
$mo->value Returns an array containing the data that represents the object. For a Real, it is just the perl real number that corresponds to it; for a Complex number, it is the real and imaginary parts (as Reals). For an Infinity, it is the string needed to obtain the Infinity. For a Point or Vector, it is the coordinates of the Point or Vector (as MathObjects). For a Matrix, it is an array of rows of the Matrix, where the rows are references to arrays of MathObjects. For an Interval, it is the two endpoints (as Reals) followed by strings that are the open and close parentheses or brackets for the Interval. For a Set, it is an array of the elements of the set (as Reals). For a Union, it is an array of the Sets and Intervals that make up the Union. For a String, it is a perl string representing the value of the string.

For a Formula, it is a little more complicated. If the Formula is an explicit Point, Vector, Matrix, Interval, etc. (e.g., Formula("<x,x+1>")), then the value is an array of Formulas that are the coordinates. If the Formula is an expression (e.g., Formula("<x,1> + <2x,-x>") or Formula("norm(<x,x+1>)") then the value is just the original Formula.

$mo->getFlag("name")
$mo->getFlag("name",default)
Returns the object's value for a given context flag. The value can come from a variety of locations, which are searched in the following order (the first that has a property with the given flag name will have that propery's value returned): the object itself, the Formula that created it (if it was the result of an eval() call, for example), the AnswerHash associated with the object (if it was the source for an answer checker; this gives access to the flags passed to the cmp method), the Context in which the object was created, the currently active Context, or the default value (if given as the second argument), otherwise the return value is undef. This is useful in custom answer checkers for finding out the settings of things like the tolerances, the flags passed to the answer checker, and so on.
$mo->with(name => value) This copies the object, and sets its property with the given name to the given value. You can supply multiple name/value pairs separated by commas. This gives you the ability to initialize the object when you create it, or to make a copy with specific settings. E.g.
   $f = Formula("sqrt(x-10)")->with(limits => [10,12]);
   $a = Real(pi/2)->with(period => 2*pi);
$mo->typeMatch($object) This determines if the $object is "compatible" with the given MathObject for equality or inequality comparisons. For example, a Real will allow equality comparison to an Infinity, and a Complex will allow comparison to a Real. It is best to use typeMatch in your own custom answer checkers if you need to check if a student's answer is of the correct type rather than using something like ref() to check if the two are the same type of object (which is too restrictive, in general).
$mo->class
$mo->type
These are two methods that help you determine what kind of MathObject you are working with. They can be useful in custom answer checkers if you want to know more about what kind of object a student answer is. The class method tells you the class of object (like Real, Complex, Point, Formula, etc.), while the type method tells you what kind of return value a Formula has (non-Formulas are considered constant-valued Formulas when computing the type). The class is essentially the package name from the Value package of the MathObject, while the type is the package name from the Parser package name for the result of the Formula.
   Real(5)->class;          # produces "Real"
   Real(5)->type;           # produces "Number"
   Point(1,2)->class;       # produces "Point"
   Point(1,2)->type;        # produces "Point"
   
   Formula("3x+1")->class;  # produces "Formula"
   Formula("3x+1")->type;   # produces "Number"
$mo->TeX Returns a string which represents the object in TeX format. For example
   $f = Formula("(x+1)/(x-1)");
   BEGIN_TEXT
   The formula is \(f(x) = \{$f->TeX\}\).
   END_TEXT

Since it is common to need the [math]\rm\TeX[/math] expression in the problem's text, there is a special Context setting that tells MathObjects to output their [math]\rm\TeX[/math] format whenever they are substituted into a string. That is enabled via the Context()->texStrings command, and turned off by Context()->normalStrings, as in the following example:

   $f = Formula("(x+1)/(x-1)");
   Context()->texStrings;
   BEGIN_TEXT
   The formula is \(f(x) = $f\)
   END_TEXT
   Context()->normalStrings;

This avoids having to call the TeX() method, and prevents the need for using \{...\} to get the [math]\rm\TeX[/math] format.

$mo->string Returns a string similar to that used to create the object, in the form that a student would use to enter the object in an answer blank, or that could be used in Compute() to create the object. The string may have more parentheses than the original string used to create the object, and may include explicit multiplication rather than implicit multiplication, and other normalization of the original format.
$mo->perl Returns a string which represents the object as Perl source code. This is used internally, and would rarely be needed in a PG problem.

(Still need to add answer checker methods, like ans_rule and ans_array. Also, look at Value.pm for more, like isOne, isZero, etc.)