Modifying Contexts (advanced)

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 three-space 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 fixed-point notation (e.g. 452.116), e means exponential notation (e.g, 3.578E-5), 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 2-place decimals (e.g., for currency values).
   Context()->{format}{number} = "%.4f#";   # format numbers using 4-place 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 fixe-point 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} = '[0-9A-F]+'; 
   Context()->{pattern}{signedNumber = '[-+]?[0-9A-F]+';
   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/[0-9]{4}(,|$)/)                       # add commas as needed
       {$n =~ s/([0-9])([0-9]{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 list-like 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 half-open 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 pre-defined, 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 pre-defined 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 Perl-based 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
   }
   
   #
   #  Non-standard TeX output
   #
   sub TeX {
     my $self = shift;
     return '{'.$self->{lop}->TeX.' \choose '.$self->{rop}->TeX.'}';
   }
   
   #
   #  Non-standard 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

• Introduction to Contexts
• Creating Custom Contexts
• Course-Wide Customizations

• Context flags
• Reduction rules for MathObject Formulas
• Context Operator Table
• Common Contexts