Home
Current UR courses
Visitor page
Intro to WeBWorK
WeBWorK 2 Twiki
WW Community
Grant Support & awards
Discussion group
Problem library
Write/modify problems
Create & manage course
Tutorial on running a course
HowTos
FAQ
WeBWorK2 FAQ
Software Download
How to Install WW server
Feedback
Site Map
Change preferences
Change password
| Prev | Next | pod |
NAME
WeBWorK::PG::Translator - Evaluate PG code and evaluate answers safely
SYNPOSIS
my $pt = new WeBWorK::PG::Translator; # create a translator;
$pt->environment(\%envir); # provide the environment variable for the problem
$pt->initialize(); # initialize the translator
$pt-> set_mask(); # set the operation mask for the translator safe compartment
$pt->source_string($source); # provide the source string for the problem
$pt -> unrestricted_load("${courseScriptsDirectory}PG.pl");
$pt -> unrestricted_load("${courseScriptsDirectory}dangerousMacros.pl");
# load the unprotected macro files
# these files are evaluated with the Safe compartment wide open
# other macros are loaded from within the problem using loadMacros
$pt ->translate(); # translate the problem (the out following 4 pieces of
information are created)
$PG_PROBLEM_TEXT_ARRAY_REF = $pt->ra_text(); # output text for the body
of the HTML file (in array
form)
$PG_PROBLEM_TEXT_REF = $pt->r_text(); # output text for the body of
the HTML file
$PG_HEADER_TEXT_REF = $pt->r_header;#\$PG_HEADER_TEXT; # text for the header
of the HTML file
$PG_ANSWER_HASH_REF = $pt->rh_correct_answers; # a hash of answer evaluators
$PG_FLAGS_REF = $pt ->rh_flags; # misc. status flags.
$pt -> process_answers(\%inputs); # evaluates all of the answers using submitted
answers from %input
my $rh_answer_results = $pt->rh_evaluated_answers; # provides a hash of the
results of evaluating the
answers.
my $rh_problem_result = $pt->grade_problem; # grades the problem using the
default problem grading method.
DESCRIPTION
This module defines an object which will translate a problem written in the Problem Generating (PG) language
be_strict
This creates a substitute for use strict; which cannot be used in PG problem
sets or PG macro files. Use this way to imitate the behavior of use strict;
BEGIN {
be_strict(); # an alias for use strict.
# This means that all global variable
# must contain main:: as a prefix.
}
evaluate_modules
Usage: $obj -> evaluate_modules('WWPlot', 'Fun', 'Circle');
$obj -> evaluate_modules('reset');
Adds the modules WWPlot.pm, Fun.pm and Circle.pm in the courseScripts directory to the list of modules which can be used by the PG problems. The keyword 'reset' or 'erase' erases the list of modules already loaded
new Creates the translator object.
(b) The following routines defined within the PG module are shared:
&be_strict
&read_whole_problem_file
&convertPath
&surePathToTmpFile
&fileFromPath
&directoryFromPath
&createFile
&includePGtext
&PG_answer_eval
&PG_restricted_eval
&send_mail_to
&PGsort
In addition the environment hash %envir is shared. This variable is unpacked
when PG.pl is run and provides most of the environment variables for each problem
template.
<A href =
"${Global::webworkDocsURL}techdescription/pglanguage/PGenvironment.html"> environment
variables</A>
(c) Sharing macros:
The macros shared with the safe compartment are
'&read_whole_problem_file'
'&convertPath'
'&surePathToTmpFile'
'&fileFromPath'
'&directoryFromPath'
'&createFile'
'&PG_answer_eval'
'&PG_restricted_eval'
'&be_strict'
'&send_mail_to'
'&PGsort'
'&dumpvar'
'&includePGtext'
Safe compartment pass through macros
set_mask
(e) Now we close the safe compartment. Only the certain operations can be used within PG problems and the PG macro files. These include the subroutines shared with the safe compartment as defined above and most Perl commands which do not involve file access, access to the system or evaluation.
Specifically the following are allowed
time()
# gives the current Unix time
# used to determine whether solutions are visible.
atan, sin cos exp log sqrt
# arithemetic commands -- more are defined in PGauxiliaryFunctions.pl
The following are specifically not allowed:
eval()
unlink, symlink, system, exec
print require
PG_errorMessage
This routine processes error messages by fixing file names and adding
traceback information. It loops through the function calls via
caller() in order to give more information about where the error
occurred. Since the loadMacros() files and the .pg file itself are
handled via various kinds of eval calls, the caller() information does
not contain the file names. So we have saved them in the
$main::__files__ hash, which we look up here and use to replace the
(eval nnn) file names that are in the caller stack. We shorten the
filenames by removing the templates or root directories when possible,
so they are easier to read.
We skip any nested calls to Parser:: or Value:: so that these act more like perl built-in functions.
We stop when we find a routine in the WeBWorK:: package, or an __ANON__ routine, in order to avoid reporting the PG translator calls that surround the pg file. Finally, there is usually one more eval before that, so we remove it as well.
File names are shortened, when possible, by replacing the templates directory with [TMPL], the WeBWorK root directory by [WW] and the PG root directory by [PG].
=cut
sub PG_errorMessage {
my $return = shift; my $frame = 2;
my $message = join("\n",@_); $message =~ s/\.?\s+$//;
my $files = eval ('$main::__files__'); $files = {} unless $files;
my $tmpl = $files->{tmpl} || '$';
my $root = $files->{root} || '$';
my $pg = $files->{pg} || '$';
#
# Fix initial message file names
#
$message =~ s! $tmpl! [TMPL]!g; $message =~ s! $root! [WW]!g; $message =~ s!
$pg! [PG]!g;
$message =~ s/(\(eval \d+\)) (line (\d+))/$2 of $1/;
while ($message =~ m/of (?:file )?(\(eval \d+\))/ && defined($files->{$1})) {
my $name = $files->{$1};
$name =~ s!^$tmpl![TMPL]!; $name =~ s!^$root![WW]!; $name =~ s!^$pg![PG]!;
$message =~ s/\(eval \d+\)/$name/g;
}
#
# Return just the message if that's all we want, or
# if the message already includes a stack trace
#
return $message."\n" if $return eq 'message' || $message =~ m/\n Died within/;
#
# Look through caller stack for traceback information
#
my @trace = ($message);
my $skipParser = (caller(3))[3] =~ m/^(Parser|Value)::/;
while (my ($pkg,$file,$line,$subname) = caller($frame++)) {
last if ($subname =~ m/^(Safe::reval|main::__ANON__)/);
next if $skipParser && $subname =~ m/^(Parser|Value)::/; # skip Parser and
Value calls
next if $subname =~ m/__ANON__/;
$file = $files->{$file} || $file;
$file =~ s!^$tmpl![TMPL]!; $file =~ s!^$root![WW]!; $file =~ s!^$pg![PG]!;
$message = " from within $subname called at line $line of $file";
push @trace, $message; $skipParser = 0;
}
splice(@trace,1,1) while $trace[1] && $trace[1] =~ m/within \(eval\)/;
pop @trace while $trace[-1] && $trace[-1] =~ m/within \(eval\)/;
$trace[1] =~ s/ from/ Died/ if $trace[1];
#
# report the full traceback
#
return join("\n",@trace,");
}
############################################################################
Translate
(3) Preprocess the problem text
The input text is subjected to two global replacements. First every incidence of
BEGIN_TEXT
problem text
END_TEXT
is replaced by
TEXT( EV3( <<'END_TEXT' ) );
problem text
END_TEXT
The first construction is syntactic sugar for the second. This is explained
in PGbasicmacros.pl.
Second every incidence of \ (backslash) is replaced by \\ (double backslash). Third each incidence of ~~ is replaced by a single backslash.
This is done to alleviate a basic incompatibility between TeX and Perl. TeX uses backslashes constantly to denote a command word (as opposed to text which is to be entered literally). Perl uses backslash to escape the following symbol. This escape mechanism takes place immediately when a Perl script is compiled and takes place throughout the code and within every quoted string (both double and single quoted strings) with the single exception of single quoted "here" documents. That is backlashes which appear in
TEXT(<<'EOF');
... text including \{ \} for example
EOF
are the only ones not immediately evaluated. This behavior makes it very difficult to use TeX notation for defining mathematics within text.
The initial global replacement, before compiling a PG problem, allows one to use backslashes within text without doubling them. (The anomolous behavior inside single quoted "here" documents is compensated for by the behavior of the evaluation macro EV3.) This makes typing TeX easy, but introduces one difficulty in entering normal Perl code.
The second global replacement provides a work around for this -- use ~~ when you would ordinarily use a backslash in Perl code. In order to define a carriage return use ~~n rather than \n; in order to define a reference to a variable you must use ~~@array rather than \@array. This is annoying and a source of simple compiler errors, but must be lived with.
The problems are not evaluated in strict mode, so global variables can be used without warnings.
(4) Evaluate the problem text
Evaluate the text within the safe compartment. Save the errors. The safe compartment is a new one unless the $safeCompartment was set to zero in which case the previously defined safe compartment is used. (See item 1.)
(5) Process errors
The error provided by Perl is truncated slightly and returned. In the text string which would normally contain the rendered problem.
The original text string is given line numbers and concatenated to the errors.
(6) Prepare return values
Returns:
$PG_PROBLEM_TEXT_ARRAY_REF -- Reference to a string containing the rendered
text.
$PG_HEADER_TEXT_REF -- Reference to a string containing material to placed
in the header (for use by JavaScript)
$PG_ANSWER_HASH_REF -- Reference to an array containing the answer evaluators.
$PG_FLAGS_REF -- Reference to a hash containing flags and other references:
'error_flag' is set to 1 if there were errors in rendering
Answer evaluation methods
access methods
$obj->rh_student_answers
process_answers
$obj->process_answers()
grade_problem
$obj->rh_problem_state(%problem_state); # sets the current problem state
$obj->grade_problem(%form_options);
PGsort
Because of the way sort is optimized in Perl, the symbols $a and $b have special significance.
sort {$a<=$b} @list>
sort {$a cmp $b} @list
sorts the list numerically and lexically respectively.
If my $a; is used in a problem, before the sort routine is defined in a macro, then
things get badly confused. To correct this the macro PGsort is defined below. It
is
evaluated before the problem template is read. In PGbasicmacros.pl, the two subroutines
PGsort sub { $_[0] < $_[1] }, @list;
PGsort sub { $_[0] lt $_[1] }, @list;
(called num_sort and lex_sort) provide slightly slower, but safer, routines for the PG language. (The subroutines for ordering are required. Note the commas!)
includePGtext
includePGtext($string_ref, $envir_ref)
Calls createPGtext recursively with the $safeCompartment variable set to 0
so that the rendering continues in the current safe compartment. The output
is the same as the output from createPGtext. This is used in processing
some of the sample CAPA files.
PG_restricted_eval
PG_restricted_eval($string)
Evaluated in package 'main'. Result of last statement is returned. When called from within a safe compartment the safe compartment package is 'main'.
File path = /ww/webwork/pg/lib/WeBWorK/PG/Translator.pm
| Prev | Next | pod |