Difference between revisions of "Modifying Contexts (advanced)"
(→Adding New Functions: fix typo, was using ":" instead of "::") 

Line 232:  Line 232:  
=== Adding New Functions === 
=== Adding New Functions === 

−  The [[Introduction to Contexts#FunctionsIntroduction to Contexts]] includes some information about adding new functions that can be used in student Answers. One approach is given in <code>[http://webwork.maa.org/pod/ 
+  The [[Introduction to Contexts#FunctionsIntroduction to Contexts]] includes some information about adding new functions that can be used in student Answers. One approach is given in <code>[http://webwork.maa.org/pod/pg/macros/parserFunction.html pg/macros/parserFunctions.pl]</code>, which implements an easy way to add functions to a Context using Formula objects. But if your function doesn't just compute the result of a Formula, then you would have to implement a Perlbased function. That process is described here. 
To make a new function, you must create a subclass of the <code>Parser::Function</code> class or one of its subclasses. It is easiest to do the latter, if possible, since these already handle most of the details. The subclasses are the following: 
To make a new function, you must create a subclass of the <code>Parser::Function</code> class or one of its subclasses. It is easiest to do the latter, if possible, since these already handle most of the details. The subclasses are the following: 
Latest revision as of 17:00, 7 April 2021
Contents
Advanced Context Modifications
The Introduction to Contexts describes how to make basic modifications to a Context's variables, constants, strings, flags, functions, operators, and reduction rules. Here we will describe more advanced modifications and techniques involving the Context.
Number Formats
Real numbers are stored using a format that retains about 16 or 17 significant digits, making computations very accurate in most situations. When a number is displayed, you probably don't want to see all 17 digits (that would make a vector in threespace take up around 35 characters, for example). To make answers easier to read, MathObjects usually display only 6 significant digits. You can change the format used, however, to suit your needs. The format is determined by the Context()>{format}{number}
, which is a printf
style string indicating how real numbers should be formatted for display.
The format always should begin with %
and end with one of f
, e
, or g
, possibly followed by #
. Here, f
means fixedpoint notation (e.g. 452.116
), e
means exponential notation (e.g, 3.578E5
), and g
means use the form most appropriate for the magnitude of the number. Between the %
and the letter you can (optionally) include .n
where n
is the number of decimal digits to use for the number. If the format ends in #
, then trailing zeros are removed after the number is formatted. (More sophisticated formats are possible, but this describes the basics.)
Context()>{format}{number} = "%.2f"; # format numbers using 2place decimals (e.g., for currency values). Context()>{format}{number} = "%.4f#"; # format numbers using 4place decimals, but remove trailing zeros, if any.
The default format is "%g"
.
The Context also includes information about what should count as a number when an answer is parsed. There are two patterns for this, a signed number and an unsigned number. The latter is what is used in parsing numbers (and the sign is treated as unary minus); former is used in the Value::matchNumber()
function. These are stored in the Context()>{pattern}
hash; the default values are:
Context()>{pattern}{number} = '(?:\d+(?:\.\d*)?\.\d+)(?:E[+]?\d+)?'; Context()>{pattern}{signedNumber} = '[+]?(?:\d+(?:\.\d*)?\.\d+)(?:E[+]?\d+)?';
These are fairly complicated regular expressions that match the usual fixepoint and exponential notation for numbers in WeBWorK. It is possible to change these patterns to handle things like commas instead of decimals for European usage, or to allow commas every three digits. Note, however, that you would need to include a NumberCheck
routine that would translate the special format into the required internal format. For example, this allows you to enter numbers as hexadecimal values:
# # Numbers in hexadecimal # Context()>{pattern}{number} = '[09AF]+'; Context()>{pattern}{signedNumber = '[+]?[09AF]+'; Context()>flags>set(NumberCheck => sub { my $self = shift; # the Number object $self>{value} = hex($self>{value_string}); # convert hex to decimal via perl hex() function $self>{isOne} = ($self>{value} == 1); # set marker indicating if the value is 1 $self>{isZero} = ($self>{value} == 0); # set marker indicating if the value is 0 }); Context()>update;
Note that after changing the pattern
you must call Context()>update
to remake the tokenization patterns used by the Context.
Here is an example that lets you use commas in your numbers:
# # Allow commas every three digits in numbers # Context()>{pattern}{number} = '(?:(?:\d{1,3}(?:\,\d{3})+\d+)(?:\.\d*)?\.\d+)(?:E[+]?\d+)?'; Context()>{pattern}{signedNumber} = '[+]?(?:(?:\d{1,3}(?:\,\d{3})+\d+)(?:\.\d*)?\.\d+)(?:E[+]?\d+)?'; Context()>flags>set(NumberCheck => sub { my $self = shift; # the Number object my $value = $self>{value_string}; # the original string $value =~ s/,//g; # remove commas $self>{value} = $value + 0; # make sure it is converted to a number $self>{isOne} = ($self>{value} == 1); # set marker indicating if the value is 1 $self>{isZero} = ($self>{value} == 0); # set marker indicating if the value is 0 }); Context()>update;
If you want to make the numbers display with commas, then you will need to subclass the Value::Real
object and override the string()
and TeX()
methods to insert the commas again, and then tie your new class into the Context()>{value}{Real}
value. For example, in addition to the changes above, you might do
# # Subclass the Value::Real class and override its string() and TeX() # methods to insert commas back into the output # package my::Real; our @ISA = ('Value::Real'); # subclass of this Value::Real sub string { my $self = shift; my $x = $self>SUPER::string(@_); # get the original string output my ($n,@rest) = split(/([.E])/,$x,1); # break it into the integer part and the rest while ($n =~ m/[09]{4}(,$)/) # add commas as needed {$n =~ s/([09])([09]{3})(,$)/$1,$2$3/} return join("",$n,@rest); # return the final string } sub TeX { my $self = shift; my $n = $self>SUPER::TeX(@_); # original TeX uses string(), so commas are already there $n =~ s/,/{,}/g; # just make sure they have the correct spacing return $n; } package main; # end of package my::Real; Context()>{value}{Real} = "my::Real"; # make the Context use my::Real rather then Value::Real Context()>{format}{number} = "%f#"; # format using "f" rather than "g", so no exponential notation
This could be put into a separate macro file that you could load into your problems whenever it is needed. See Creating Custom Contexts for details.
Lists and Delimiters
The Context object contains two more collections of data that were not mentioned in the Introduction to Contexts: the lists
and parens
objects. These are closely related, and determine what types of objects are created from various delimiters like braces and brackets. For example, in some contexts parentheses form Points, while in others they form Intervals or Lists. This is controlled by the settings in these two objects.
The lists
object contains the definitions for the various types of listlike objects such as Points, Vectors, and Intervals. Each of the types of list has an entry that tells the parser what class implements the list, and specifies the open and close delimiters and the separators that will be used by default to display an instance of the class. A special case is AbsoluteValue
, which is treated as a list since it has open and close delimiters, even though the list can only contain one element.
List  Open  Close  Separator 

Point

(

)

,

Vector

<

>

,

Matrix

[

]

,

List



,

Interval

(

)

,

Set

{

}

,

Union



U

AbsoluteValue






The delimiters listed in this table are used when the object doesn't specify the delimiters explicitly via its {open}
and {close}
properties. This is usually the case when objects are created via the class constructors rather than parsing a string. For example, Vector(4,0,1)
would not have its {open}
and {close}
properties set, so would use the defaults in the lists
object. Note that the Interval object has parentheses as its default delimiters, but the Interval()
constructor will set the open and close properties automatically so that you can form open and closed intervals easily:
$I1 = Interval(1,2); # an open interval $I2 = Interval([1,2]); # a closed interval $I3 = Interval("(",1,2,"]"); # a halfopen interval
It is also possible to put the delimiters at the end of the interval (which is how the Interval's value()
method returns them): Interval(0,1,"(","]")
.
On the other hand, instances of these objects created by parsing a string usually save the open and closing delimiters in the object's {open}
and {close}
properties, so the default will not be used in those cases. E.g., $v = Compute("<4,0,1>")
would produce a Vector object with the $v>{open} = "<"
and $v>{close} = ">"
.
To change the list
settings, use the set()
method, as usual:
Context()>lists>set(Vector => {open => "(", close => ")"});
Note that this only affects the case where the Vector object doesn't specify the open and close delimiters explicitly. It also doesn't change the delimiters that the parser uses to identify a vector, since the list
values are only for output.
To change what delimiter to use for a given object type, you need to change the parens
object. This associates each open delimiter to one of the list
types given above, and also gives the close delimiter that is needed to match it, and some other data about how it can be used. So to complete the change for Vectors, we would need to use
Context()>parens>set("(" => {type => "Vector", close => ")"});
The other possible data for a paren
object includes:
Name  Description 

type => "name"

Specifies the list type that this open delimiter will genarate. 
close => "c"

The closing delimiter for this opening one. 
removable => 1 or 0

Do/don't remove delimiters when used around a single element. When 1 , don't create a list, just return the element.

formInterval => "c"

When present, this indicates that an Interval should be formed when the list is closed by the character c rather than the usual close character.

formList => 1 or 0

Do/don't allow this delimiter to form a List when the entries don't work for its type , otherwise produce an error.

formMatrix => 1 or 0

Do/don't allow this delimiter to form a Matrix when the entries are appropriate for that. 
emptyOK => 1 or 0

Do/don't allow empty delimiters. When 0 there must be at least one element between the open and close delimiters.

function => 1 or 0

Do/don't allow this delimiter to form a function call when preceded by a function name. 
More about Variables
The Introduction to Contexts shows how to add variables to a Context. One thing to keep in mind is that most Contexts come with some variables predefined, and when you add new ones, the originals are still available. If you wish to have only the variables that you define, then use are()
rather than add()
to add the variables. For example,
Context("Numeric"); Context()>variables>add(t => "Real");
would add a new real variable [math]t[/math], which would be in addition to the [math]x[/math] that is already in the Numeric
context, while
Context("Numeric"); Context()>variables>are(t => "Real");
would remove any predefined variables and leave you with only one variable, [math]t[/math].
More about Constants
The Introduction to Contexts shows how to add constants to a Context. Usually, the output for a constant is its name, but you might want to specify a different value, particular for its [math]\rm\TeX[/math] output. You can set the constant's TeX
, string
, and perl
values to control the output in those formats. For example,
Context("Complex"); Context()>constants>set(i => {TeX=>'\boldsymbol{i}', perl=>'i'});
would indicate that [math]\rm\TeX[/math] output should be [math]\boldsymbol{i}[/math], while its Perl form should be just i
. Similarly,
Context("Interval"); Context()>constants>set(R => {TeX=>'\mathbb{R}'});
would set the R
constant to produce [math]\mathbb{R}[/math] rather than [math]{\bf R}[/math] in [math]\rm\TeX[/math] output.
Adding New Functions
The Introduction to Contexts includes some information about adding new functions that can be used in student Answers. One approach is given in pg/macros/parserFunctions.pl
, which implements an easy way to add functions to a Context using Formula objects. But if your function doesn't just compute the result of a Formula, then you would have to implement a Perlbased function. That process is described here.
To make a new function, you must create a subclass of the Parser::Function
class or one of its subclasses. It is easiest to do the latter, if possible, since these already handle most of the details. The subclasses are the following:
Subclass  Description 

Parser::Function::numeric

Functions with one real input producing a real result, or one complex input producing a complex result. Output type is determined by input type. Setting nocomplex=>1 means complex input not allowed.

Parser::Function::numeric2

Functions with two real input returning a real result. 
Parser::Function::complex

Functions with one complex (or real) input returning a real or complex result. Result is real unless complex=>1 is set.

Parser::Function::vector

Functions with one vector input producing a real or vector result. The result is real unless vector=>1 is set. Should always set vectorInput=>1 .

To implement your function, make a package that is a subclass of one of these, and give it a subroutine that computes the function you are interested in. Note that the number and type of inputs will already be checked, so there is not need to check that in your subroutine. Give your subroutine the same name as the function. E.g.,
package my::Function::numeric; our @ISA = ('Parser::Function::numeric'); # subclass of Parser::Function::numeric my $log2 = CORE::log(2); # cached value of log(2) sub log2 { # the routine for computing log base 2 shift; my $x = shift; return CORE::log($x)/$log2; } package main; # end my::Function::numeric
Now we have to hook the new function into the Context:
Context("Numeric"); Context()>functions>add( log2 => {class => 'my::Function::numeric', TeX => '\log_2', nocomplex => 1}, );
This sets the name of the function to log2
in the student answer, and uses my::Function::numeric
to implement it. The [math]\rm\TeX[/math] output is given as [math]\log_2[/math], and we are not allowing complex inputs. Once this is done, you can use things like
$r = Compute("(1/3)*log2(5)"); ... ANS($r>cmp);
and students can use log2(5)
in their answers.
If you want to be able to use log2()
directly in your Perl code, then you should also define
sub log2 {Parser::Function>call("log2",@_)}
in the main
package. Then you can do
$r = (1/3)*log2(5);
directly (i.e., without Compute()
).
It would be possible to put the required definitions into a macro file that you can load into a problem file whenever it is needed; see Creating Custom Contexts for details.
If your function isn't one that can be obtained by subclassing one of the classes listed above, then you will have to subclass Parser::Function
directly. In this case, you will have to create _check
, _eval
and _call
methods in your class in addition to the subroutine implementing your function. You can model these after the ones in any of the subclasses listed above (which are in the pg/lib/Parser/Function
directory). Note that the checkNumeric()
and other service routines are in pg/lib/Parser/Function.pm
.
Adding New Operators
The Introduction to Contexts gives information about controlling the operators that are part of the Context. To add a new operator you need to make a subclass of Parser::BOP
or Parser::UOP
depending on wether the new operator is a binary or unary operator. This should implement the _check()
and _eval()
methods to check that its operands are correct and to compute its value. It might also need to implement other methods like TeX()
or string()
or perl()
. There are a number of examples in the pg/lib/Parser/BOP
and pg/lib/Parser/UOP
directories.
The example given below implements a binary operator that performs "[math]n[/math] choose [math]r[/math]" so that n # r
means [math]n \choose r[/math].
# # A package for computing n choose r # package my::BOP::choose; our @ISA = ('Parser::BOP'); # subclass of Binary OPerator # # Check that the operand types are numbers. # sub _check { my $self = shift; my $name = $self>{bop}; return if $self>checkNumbers(); # method inherited from Parser::BOP $self>Error("Operands of '%s' must be Numbers",$name); } # # Compute the value of n choose r. # sub _eval { shift; my ($n,$r) = @_; my $C = 1; $r = $n$r if ($r > $n$r); # find the smaller of the two for (1..$r) {$C = $C*($n$_+1)/$_} return $C } # # Nonstandard TeX output # sub TeX { my $self = shift; return '{'.$self>{lop}>TeX.' \choose '.$self>{rop}>TeX.'}'; } # # Nonstandard perl output # sub perl { my $self = shift; return '(my::BOP::choose>_eval('.$self>{lop}>perl.','.$self>{rop}>perl.'))'; } package main;
This defines the new operator, but now we need to add it into the Context.
Context("Numeric"); $prec = Context()>operators>get('+')>{precedence}  .25; Context()>operators>add( '#' => { class => 'my::BOP::choose', precedence => $prec, # just below addition associativity => 'left', # computed left to right type => 'bin', # binary operator string => ' # ', # output string for it (default is the operator name with no spaces) TeX => '\mathbin{\#}', # TeX version (overridden above, but just an example) } );
Now you can do things like
$p = Compute("5 # 3");
and students can use #
to perform the same operation in their answers.
You can combine all of this into a macro file for inclusion into any problem that needs it. See Creating Custom Contexts for more information.
See also