[system] / branches / rel-2-4-patches / webwork2 / lib / WeBWorK / PG.pm Repository:
ViewVC logotype

Diff of /branches/rel-2-4-patches/webwork2/lib/WeBWorK/PG.pm

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

Revision 434 Revision 620
1################################################################################
2# WeBWorK mod_perl (c) 2000-2002 WeBWorK Project
3# $Id$
4################################################################################
5
1package WeBWorK::PG; 6package WeBWorK::PG;
2 7
3# hide PG::* from the not-yet-insane. 8=head1 NAME
4# "PG Render" or something 9
10WeBWorK::PG - Wrap the action of the PG Translator in an easy-to-use API.
11
12=cut
5 13
6use strict; 14use strict;
7use warnings; 15use warnings;
8use WeBWorK::Utils qw(readFile formatDateTime); 16use File::Path qw(rmtree);
17use File::Temp qw(tempdir);
9use WeBWorK::DB::Classlist; 18use WeBWorK::DB::Classlist;
10use WeBWorK::DB::WW; 19use WeBWorK::DB::WW;
11use WeBWorK::PG::Translator; 20use WeBWorK::PG::Translator;
21use WeBWorK::Problem;
22use WeBWorK::Utils qw(readFile formatDateTime writeTimingLogEntry);
12 23
13sub new($$$$$$$$) { 24sub new($$$$$$$$) {
14 my $invocant = shift; 25 my $invocant = shift;
15 my $class = ref($invocant) || $invocant; 26 my $class = ref($invocant) || $invocant;
16 my ( 27 my (
17 $courseEnv, 28 $courseEnv,
18 $userName, 29 $user,
19 $key, 30 $key,
20 $setName, 31 $set,
21 $problemNumber, 32 $problem,
33 $psvn,
34 $formFields, # in CGI::Vars format
22 $translationOptions, # hashref containing options for the 35 $translationOptions, # hashref containing options for the
23 # translator, such as whether to show 36 # translator, such as whether to show
24 # hints and the display mode to use 37 # hints and the display mode to use
25 $formFields, # in CGI::Vars format
26 ) = @_; 38 ) = @_;
27 39
28 # get database information 40 # write timing log entry
29 my $classlist = WeBWorK::DB::Classlist->new($courseEnv); 41 writeTimingLogEntry($courseEnv, "WeBWorK::PG::new",
30 my $wwdb = WeBWorK::DB::WW->new($courseEnv); 42 "user=".$user->id.",problem=".$courseEnv->{courseName}."/".$set->id."/".$problem->id.",mode=".$translationOptions->{displayMode},
31 my $user = $classlist->getUser($userName); 43 "begin");
32 my $set = $wwdb->getSet($userName, $setName); 44
33 my $problem = $wwdb->getProblem($userName, $setName, $problemNumber); 45 # install a local warn handler to collect warnings
34 my $psvn = $wwdb->getPSVN($userName, $setName); 46 my $warnings = "";
47 if ($courseEnv->{pg}->{options}->{catchWarnings}) {
48 local $SIG{__WARN__} = sub { $warnings .= shift };
49 }
35 50
36 # create a Translator 51 # create a Translator
37 warn "PG: creating a Translator\n"; 52 #warn "PG: creating a Translator\n";
38 my $translator = WeBWorK::PG::Translator->new; 53 my $translator = WeBWorK::PG::Translator->new;
39 54
40 # set the directory hash 55 # set the directory hash
41 warn "PG: setting the directory hash\n"; 56 #warn "PG: setting the directory hash\n";
42 $translator->rh_directories({ 57 $translator->rh_directories({
43 courseScriptsDirectory => $courseEnv->{webworkDirs}->{macros}, 58 courseScriptsDirectory => $courseEnv->{webworkDirs}->{macros},
44 macroDirectory => $courseEnv->{courseDirs}->{macros}, 59 macroDirectory => $courseEnv->{courseDirs}->{macros},
45 templateDirectory => $courseEnv->{courseDirs}->{templates}, 60 templateDirectory => $courseEnv->{courseDirs}->{templates},
46 tempDirectory => $courseEnv->{courseDirs}->{html_temp}, 61 tempDirectory => $courseEnv->{courseDirs}->{html_temp},
47 }); 62 });
48 63
49 # evaluate modules and "extra packages" 64 # evaluate modules and "extra packages"
50 warn "PG: evaluating modules and \"extra packages\"\n"; 65 #warn "PG: evaluating modules and \"extra packages\"\n";
51 my @modules = @{ $courseEnv->{pg}->{modules} }; 66 my @modules = @{ $courseEnv->{pg}->{modules} };
52 foreach my $module_packages (@modules) { 67 foreach my $module_packages_ref (@modules) {
53 # the first item in $module_packages is the main package 68 my ($module, @extra_packages) = @$module_packages_ref;
69 # the first item is the main package
54 $translator->evaluate_modules(shift @$module_packages); 70 $translator->evaluate_modules($module);
55 # the remaining items are "extra" packages 71 # the remaining items are "extra" packages
56 $translator->load_extra_packages(@$module_packages); 72 $translator->load_extra_packages(@extra_packages);
57 } 73 }
58 74
59 # set the environment (from defineProblemEnvir) 75 # set the environment (from defineProblemEnvir)
60 warn "PG: setting the environment (from defineProblemEnvir)\n"; 76 #warn "PG: setting the environment (from defineProblemEnvir)\n";
77 my $envir = defineProblemEnvir(
78 $courseEnv,
79 $user,
80 $key,
81 $set,
82 $problem,
83 $psvn,
84 $formFields,
85 $translationOptions,
86 );
61 $translator->environment(defineProblemEnvir( 87 $translator->environment($envir);
62 $courseEnv, $user, $key, $set, $problem, $psvn, $formFields, $translationOptions));
63 88
64 # initialize the Translator 89 # initialize the Translator
65 warn "PG: initializing the Translator\n"; 90 #warn "PG: initializing the Translator\n";
66 $translator->initialize(); 91 $translator->initialize();
67 92
68 # load PG.pl and dangerousMacros.pl using unrestricted_load 93 # load IO.pl, PG.pl, and dangerousMacros.pl using unrestricted_load
69 # i'd like to change this at some point to have the same sort of interface to global.conf 94 # i'd like to change this at some point to have the same sort of interface to global.conf
70 # that the module loading does -- have a list of macros to load unrestrictedly. 95 # that the module loading does -- have a list of macros to load unrestrictedly.
71 warn "PG: loading PG.pl and dangerousMacros.pl using unrestricted_load\n"; 96 #warn "PG: loading IO.pl, PG.pl, and dangerousMacros.pl using unrestricted_load\n";
97 foreach (qw(IO.pl PG.pl dangerousMacros.pl)) {
98 my $macroPath = $courseEnv->{webworkDirs}->{macros} . "/$_";
99 my $err = $translator->unrestricted_load($macroPath);
100 warn "Error while loading $macroPath: $err" if $err;
101 }
72 my $pg_pl = $courseEnv->{webworkDirs}->{macros} . "/PG.pl"; 102 #my $pg_pl = $courseEnv->{webworkDirs}->{macros} . "/PG.pl";
73 my $dangerousMacros_pl = $courseEnv->{webworkDirs}->{macros} . "/dangerousMacros.pl"; 103 #my $dangerousMacros_pl = $courseEnv->{webworkDirs}->{macros} . "/dangerousMacros.pl";
104 #my $io_pl = $courseEnv->{webworkDirs}->{macros} . "/IO.pl";
74 my $err = $translator->unrestricted_load($pg_pl); 105 #my $err = $translator->unrestricted_load($pg_pl);
75 warn "Error while loading $pg_pl: $err" if $err; 106 #warn "Error while loading $pg_pl: $err" if $err;
76 $err = $translator->unrestricted_load($dangerousMacros_pl); 107 #$err = $translator->unrestricted_load($dangerousMacros_pl);
77 warn "Error while loading $dangerousMacros_pl: $err" if $err; 108 #warn "Error while loading $dangerousMacros_pl: $err" if $err;
109 #$err = $translator->unrestricted_load($io_pl);
110 #warn "Error while loading $io_pl: $err" if $err;
78 111
79 # set the opcode mask (using default values) 112 # set the opcode mask (using default values)
80 warn "PG: setting the opcode mask (using default values)\n"; 113 #warn "PG: setting the opcode mask (using default values)\n";
81 $translator->set_mask(); 114 $translator->set_mask();
82 115
83 # store the problem source 116 # store the problem source
84 warn "PG: storing the problem source\n"; 117 #warn "PG: storing the problem source\n";
118 my $sourceFile = $problem->source_file;
85 my $sourceFile = $courseEnv->{courseDirs}->{templates}."/".$problem->source_file; 119 $sourceFile = $courseEnv->{courseDirs}->{templates}."/".$sourceFile
120 unless ($sourceFile =~ /^\//);
86 $translator->source_string(readFile($sourceFile)); 121 eval { $translator->source_string(readFile($sourceFile)) };
122 if ($@) {
123 # well, we couldn't get the problem source, for some reason.
124 return bless {
125 translator => $translator,
126 head_text => "",
127 body_text => <<EOF,
128WeBWorK::Utils::readFile($sourceFile) says:
129$@
130EOF
131 answers => {},
132 result => {},
133 state => {},
134 errors => "Failed to read the problem source file.",
135 warnings => $warnings,
136 flags => {error_flag => 1},
137 }, $class;
138 }
87 139
88 # install a safety filter (&safetyFilter) 140 # install a safety filter (&safetyFilter)
89 warn "PG: installing a safety filter\n"; 141 #warn "PG: installing a safety filter\n";
90 $translator->rf_safety_filter(\&safetyFilter); 142 $translator->rf_safety_filter(\&safetyFilter);
91 143
92 # translate the PG source into text 144 # translate the PG source into text
93 warn "PG: translating the PG source into text\n"; 145 #warn "PG: translating the PG source into text\n";
94 $translator->translate(); 146 $translator->translate();
95 147
96 # [in Problem.pm and processProblem8.pl, "install a grader" is here] 148 # after we're done translating, we may have to clean up after the translator.
149 # for example, 'images' mode uses a tempdir for dvipng's temp files. We have
150 # to remove it.
151 if ($translationOptions->{displayMode} eq 'images' && $envir->{dvipngTempDir}) {
152 rmtree($envir->{dvipngTempDir}, 0, 0);
153 }
97 154
155 my ($result, $state); # we'll need these on the other side of the if block!
156 if ($translationOptions->{processAnswers}) {
157
98 # process student answers 158 # process student answers
99 warn "PG: processing student answers\n"; 159 #warn "PG: processing student answers\n";
100 $translator->process_answers($formFields); 160 $translator->process_answers($formFields);
101 161
102 # retrieve the problem state and give it to the translator 162 # retrieve the problem state and give it to the translator
103 warn "PG: retrieving the problem state and giving it to the translator\n"; 163 #warn "PG: retrieving the problem state and giving it to the translator\n";
104 $translator->rh_problem_state({ 164 $translator->rh_problem_state({
105 recorded_score => $problem->status, 165 recorded_score => $problem->status,
106 num_of_correct_ans => $problem->num_correct, 166 num_of_correct_ans => $problem->num_correct,
107 num_of_incorrect_ans => $problem->num_incorrect, 167 num_of_incorrect_ans => $problem->num_incorrect,
108 }); 168 });
109 169
110 # determine an entry order -- the ANSWER_ENTRY_ORDER flag is built by 170 # determine an entry order -- the ANSWER_ENTRY_ORDER flag is built by
111 # the PG macro package (PG.pl) 171 # the PG macro package (PG.pl)
112 warn "PG: determining an entry order\n"; 172 #warn "PG: determining an entry order\n";
113 my @answerOrder = 173 my @answerOrder =
114 $translator->rh_flags->{ANSWER_ENTRY_ORDER} 174 $translator->rh_flags->{ANSWER_ENTRY_ORDER}
115 ? @{ $translator->rh_flags->{ANSWER_ENTRY_ORDER} } 175 ? @{ $translator->rh_flags->{ANSWER_ENTRY_ORDER} }
116 : keys %{ $translator->rh_evaluated_answers }; 176 : keys %{ $translator->rh_evaluated_answers };
117 177
118 # install a grader -- use the one specified in the problem, 178 # install a grader -- use the one specified in the problem,
119 # or fall back on the default from the course environment. 179 # or fall back on the default from the course environment.
120 # (two magic strings are accepted, to avoid having to 180 # (two magic strings are accepted, to avoid having to
121 # reference code when it would be difficult.) 181 # reference code when it would be difficult.)
122 warn "PG: installing a grader\n"; 182 #warn "PG: installing a grader\n";
123 my $grader = $translator->rh_flags->{PROBLEM_GRADER_TO_USE} 183 my $grader = $translator->rh_flags->{PROBLEM_GRADER_TO_USE}
124 || $courseEnv->{pg}->{options}->{grader}; 184 || $courseEnv->{pg}->{options}->{grader};
125 $grader = $translator->rf_std_problem_grader 185 $grader = $translator->rf_std_problem_grader
126 if $grader eq "std_problem_grader"; 186 if $grader eq "std_problem_grader";
127 $grader = $translator->rf_avg_problem_grader 187 $grader = $translator->rf_avg_problem_grader
128 if $grader eq "avg_problem_grader"; 188 if $grader eq "avg_problem_grader";
129 die "Problem grader $grader is not a CODE reference." 189 die "Problem grader $grader is not a CODE reference."
130 unless ref $grader eq "CODE"; 190 unless ref $grader eq "CODE";
131 $translator->rf_problem_grader($grader); 191 $translator->rf_problem_grader($grader);
132 192
133 # grading the problem 193 # grade the problem
134 warn "PG: grade the problem\n"; 194 #warn "PG: grading the problem\n";
135 my ($result, $state) = $translator->grade_problem( 195 ($result, $state) = $translator->grade_problem(
136 answers_submitted => $translationOptions->{processAnswers}, 196 answers_submitted => $translationOptions->{processAnswers},
137 ANSWER_ENTRY_ORDER => \@answerOrder, 197 ANSWER_ENTRY_ORDER => \@answerOrder,
138 ); 198 );
199
200 }
201
202 # write timing log entry
203 writeTimingLogEntry($courseEnv, "WeBWorK::PG::new", "", "end");
139 204
140 # return an object which contains the translator and the results of 205 # return an object which contains the translator and the results of
141 # the translation process. this is DIFFERENT from the "format expected 206 # the translation process. this is DIFFERENT from the "format expected
142 # by Webwork.pm (and I believe processProblem8, but check.)" 207 # by Webwork.pm (and I believe processProblem8, but check.)"
143 return bless { 208 return bless {
… …
145 head_text => ${ $translator->r_header }, 210 head_text => ${ $translator->r_header },
146 body_text => ${ $translator->r_text }, 211 body_text => ${ $translator->r_text },
147 answers => $translator->rh_evaluated_answers, 212 answers => $translator->rh_evaluated_answers,
148 result => $result, 213 result => $result,
149 state => $state, 214 state => $state,
150 errors => $translator->errors, # *** what is this doing? 215 errors => $translator->errors,
151 warnings => undef, # *** gotta catch warnings eventually... 216 warnings => $warnings,
152 flags => $translator->rh_flags, 217 flags => $translator->rh_flags,
153 }, $class; 218 }, $class;
154} 219}
155 220
156# ----- 221# -----
… …
172 # PG environment variables 237 # PG environment variables
173 # from docs/pglanguage/pgreference/environmentvariables as of 06/25/2002 238 # from docs/pglanguage/pgreference/environmentvariables as of 06/25/2002
174 # any changes are noted by "ADDED:" or "REMOVED:" 239 # any changes are noted by "ADDED:" or "REMOVED:"
175 240
176 # Vital state information 241 # Vital state information
177 # ADDED: displayHintsQ, displaySolutionsQ 242 # ADDED: displayHintsQ, displaySolutionsQ, refreshMath2img,
243 # texDisposition
178 244
179 $envir{psvn} = $psvn; 245 $envir{psvn} = $psvn;
180 $envir{psvnNumber} = $envir{psvn}; 246 $envir{psvnNumber} = $envir{psvn};
181 $envir{probNum} = $problem->id; 247 $envir{probNum} = $problem->id;
182 $envir{questionNumber} = $envir{probNum}; 248 $envir{questionNumber} = $envir{probNum};
… …
187 $envir{languageMode} = $envir{displayMode}; 253 $envir{languageMode} = $envir{displayMode};
188 $envir{outputMode} = $envir{displayMode}; 254 $envir{outputMode} = $envir{displayMode};
189 $envir{displayHintsQ} = $options->{hints}; 255 $envir{displayHintsQ} = $options->{hints};
190 $envir{displaySolutionsQ} = $options->{solutions}; 256 $envir{displaySolutionsQ} = $options->{solutions};
191 $envir{refreshMath2img} = $options->{refreshMath2img}; 257 $envir{refreshMath2img} = $options->{refreshMath2img};
258 $envir{texDisposition} = "pdf"; # in webwork-modperl, we use pdflatex
192 259
193 # Problem Information 260 # Problem Information
194 # ADDED: courseName 261 # ADDED: courseName
195 262
196 $envir{openDate} = $set->open_date; 263 $envir{openDate} = $set->open_date;
197 $envir{formattedOpenDate} = formatDateTime($envir{openDate}); 264 $envir{formattedOpenDate} = formatDateTime($envir{openDate});
198 $envir{dueDate} = $set->due_date; 265 $envir{dueDate} = $set->due_date;
199 $envir{formattedDueDate} = formatDateTime($envir{dueDate}); 266 $envir{formattedDueDate} = formatDateTime($envir{dueDate});
200 $envir{answerDate} = $set->answer_date; 267 $envir{answerDate} = $set->answer_date;
201 $envir{formattedAnswerDate} = formatDateTime($envir{answerDate}); 268 $envir{formattedAnswerDate} = formatDateTime($envir{answerDate});
202 $envir{numOfAttempts} = $problem->num_correct + $problem->num_incorrect; 269 $envir{numOfAttempts} = ($problem->num_correct || 0) + ($problem->num_incorrect || 0);
203 $envir{problemValue} = $problem->value; 270 $envir{problemValue} = $problem->value;
204 $envir{sessionKey} = $key; 271 $envir{sessionKey} = $key;
205 $envir{courseName} = $courseEnv->{courseName}; 272 $envir{courseName} = $courseEnv->{courseName};
206 273
207 # Student Information 274 # Student Information
… …
220 # REMOVED: refSubmittedAnswers 287 # REMOVED: refSubmittedAnswers
221 288
222 $envir{inputs_ref} = $formFields; 289 $envir{inputs_ref} = $formFields;
223 290
224 # External Programs 291 # External Programs
292 # ADDED: externalLaTeXPath, externalDvipngPath,
293 # externalGif2EpsPath, externalPng2EpsPath
225 294
226 $envir{externalTTHPath} = $courseEnv->{externalPrograms}->{tth}; 295 $envir{externalTTHPath} = $courseEnv->{externalPrograms}->{tth};
296 $envir{externalLaTeXPath} = $courseEnv->{externalPrograms}->{latex};
227 $envir{externalMath2imgPath} = $courseEnv->{externalPrograms}->{math2img}; 297 $envir{externalDvipngPath} = $courseEnv->{externalPrograms}->{dvipng};
298 $envir{externalGif2EpsPath} = $courseEnv->{externalPrograms}->{gif2eps};
299 $envir{externalPng2EpsPath} = $courseEnv->{externalPrograms}->{png2eps};
300 $envir{externalGif2PngPath} = $courseEnv->{externalPrograms}->{gif2png};
228 301
229 # Directories and URLs 302 # Directories and URLs
230 # REMOVED: courseName 303 # REMOVED: courseName
304 # ADDED: dvipngTempDir
231 305
232 $envir{cgiDirectory} = undef; 306 $envir{cgiDirectory} = undef;
233 $envir{cgiURL} = undef; 307 $envir{cgiURL} = undef;
234 $envir{classDirectory} = undef; 308 $envir{classDirectory} = undef;
235 $envir{courseScriptsDirectory} = $courseEnv->{webworkDirs}->{macros}."/"; 309 $envir{courseScriptsDirectory} = $courseEnv->{webworkDirs}->{macros}."/";
236 $envir{htmlDirectory} = $courseEnv->{courseDirs}->{html}."/"; 310 $envir{htmlDirectory} = $courseEnv->{courseDirs}->{html}."/";
237 $envir{htmlURL} = $courseEnv->{courseURLs}->{html}; 311 $envir{htmlURL} = $courseEnv->{courseURLs}->{html}."/";
238 $envir{macroDirectory} = $courseEnv->{courseDirs}->{macros}."/"; 312 $envir{macroDirectory} = $courseEnv->{courseDirs}->{macros}."/";
239 $envir{templateDirectory} = $courseEnv->{courseDirs}->{templates}."/"; 313 $envir{templateDirectory} = $courseEnv->{courseDirs}->{templates}."/";
240 $envir{tempDirectory} = $courseEnv->{courseDirs}->{html_temp}."/"; 314 $envir{tempDirectory} = $courseEnv->{courseDirs}->{html_temp}."/";
241 $envir{tempURL} = $courseEnv->{courseURLs}->{html_temp}; 315 $envir{tempURL} = $courseEnv->{courseURLs}->{html_temp}."/";
242 $envir{scriptDirectory} = undef; 316 $envir{scriptDirectory} = undef;
243 $envir{webworkDocsURL} = $courseEnv->{webworkURLs}->{docs}; 317 $envir{webworkDocsURL} = $courseEnv->{webworkURLs}->{docs}."/";
318 $envir{dvipngTempDir} = $options->{displayMode} eq 'images'
319 ? tempdir("webwork-dvipng-XXXXXXXX", DIR => $envir{tempDirectory})
320 : undef;
244 321
245 # Default values for evaluating answers 322 # Default values for evaluating answers
246 323
247 my $ansEvalDefaults = $courseEnv->{pg}->{ansEvalDefaults}; 324 my $ansEvalDefaults = $courseEnv->{pg}->{ansEvalDefaults};
248 $envir{$_} = $ansEvalDefaults->{$_} foreach (keys %$ansEvalDefaults); 325 $envir{$_} = $ansEvalDefaults->{$_} foreach (keys %$ansEvalDefaults);
… …
255} 332}
256 333
257sub translateDisplayModeNames($) { 334sub translateDisplayModeNames($) {
258 my $name = shift; 335 my $name = shift;
259 return { 336 return {
337 tex => "TeX",
260 plainText => "HTML", 338 plainText => "HTML",
261 formattedText => "HTML_tth", 339 formattedText => "HTML_tth",
262 images => "HTML_img" 340 images => "HTML_img"
263 }->{$name}; 341 }->{$name};
264} 342}
… …
286 $errorno = 0; 364 $errorno = 0;
287 return($answer, $errorno); 365 return($answer, $errorno);
288} 366}
289 367
2901; 3681;
369
370__END__
371
372=head1 SYNOPSIS
373
374 $pg = WeBWorK::PG->new(
375 $courseEnv, # a WeBWorK::CourseEnvironment object
376 $user, # a WeBWorK::User object
377 $sessionKey,
378 $set, # a WeBWorK::Set object
379 $problem, # a WeBWorK::Problem object
380 $psvn,
381 $formFields # in &WeBWorK::Form::Vars format
382 { # translation options
383 displayMode => "images", # (plainText|formattedText|images)
384 showHints => 1, # (0|1)
385 showSolutions => 0, # (0|1)
386 refreshMath2img => 0, # (0|1)
387 processAnswers => 1, # (0|1)
388 },
389 );
390
391 $translator = $pg->{translator}; # WeBWorK::PG::Translator
392 $body = $pg->{body_text}; # text string
393 $header = $pg->{head_text}; # text string
394 $answerHash = $pg->{answers}; # WeBWorK::PG::AnswerHash
395 $result = $pg->{result}; # hash reference
396 $state = $pg->{state}; # hash reference
397 $errors = $pg->{errors}; # text string
398 $warnings = $pg->{warnings}; # text string
399 $flags = $pg->{flags}; # hash reference
400
401=head1 DESCRIPTION
402
403WeBWorK::PG encapsulates the PG translation process, making multiple calls to
404WeBWorK::PG::Translator. Much of the flexibility of the Translator is hidden,
405instead making choices that are appropriate for the webwork-modperl system.
406
407=head1 CONSTRUCTION
408
409=over
410
411=item new (ENVIRONMENT, USER, KEY, SET, PROBLEM, PSVN, FIELDS, OPTIONS)
412
413The C<new> method creates a translator, initializes it using the parameters
414specified, translates a PG file, and processes answers. It returns a reference
415to a blessed hash containing the results of the translation process.
416
417=back
418
419=head2 Parameters
420
421=over
422
423=item ENVIRONMENT
424
425a WeBWorK::CourseEnvironment object
426
427=item USER
428
429a WeBWorK::User object
430
431=item KEY
432
433the session key of the current session
434
435=item SET
436
437a WeBWorK::Set object
438
439=item PROBLEM
440
441a WeBWorK::Problem object. The contents of the source_file field can specify a
442PG file either by absolute path or path relative to the "templates" directory.
443I<The caller should remove taint from this value before passing!>
444
445=item PSVN
446
447the problem set version number
448
449=item FIELDS
450
451a reference to a hash (as returned by &WeBWorK::Form::Vars) containing form
452fields submitted by a problem processor. The translator will look for fields
453like "AnSwEr[0-9]" containing submitted student answers.
454
455=item OPTIONS
456
457a reference to a hash containing the following data:
458
459=over
460
461=item displayMode
462
463one of "plainText", "formattedText", or "images"
464
465=item showHints
466
467boolean, render hints
468
469=item showSolutions
470
471boolean, render solutions
472
473=item refreshMath2img
474
475boolean, force images created by math2img (in "images" mode) to be recreated,
476even if the PG source has not been updated.
477
478=item processAnswers
479
480boolean, call answer evaluators and graders
481
482=back
483
484=back
485
486=head2 RETURN VALUE
487
488The C<new> method returns a blessed hash reference containing the following
489fields. More information can be found in the documentation for
490WeBWorK::PG::Translator.
491
492=over
493
494=item translator
495
496The WeBWorK::PG::Translator object used to render the problem.
497
498=item head_text
499
500HTML code for the E<lt>headE<gt> block of an resulting web page. Used for
501JavaScript features.
502
503=item body_text
504
505HTML code for the E<lt>bodyE<gt> block of an resulting web page.
506
507=item answers
508
509An C<AnswerHash> object containing submitted answers, and results of answer
510evaluation.
511
512=item result
513
514A hash containing the results of grading the problem.
515
516=item state
517
518A hash containing the new problem state.
519
520=item errors
521
522A string containing any errors encountered while rendering the problem.
523
524=item warnings
525
526A string containing any warnings encountered while rendering the problem.
527
528=item flags
529
530A hash containing PG_flags (see the Translator docs).
531
532=back
533
534=head1 OPERATION
535
536WeBWorK::PG goes through the following operations when constructed:
537
538=over
539
540=item Get database information
541
542Retrieve information about the current user, set, and problem from the
543database.
544
545=item Create a translator
546
547Instantiate a WeBWorK::PG::Translator object.
548
549=item Set the directory hash
550
551Set the translator's directory hash (courseScripts, macros, templates, and temp
552directories) from the course environment.
553
554=item Evaluate PG modules
555
556Using the module list from the course environment (pg->modules), perform a
557"use"-like operation to evaluate modules at runtime.
558
559=item Set the problem environment
560
561Use data from the user, set, and problem, as well as the course environemnt and
562translation options, to set the problem environment.
563
564=item Initialize the translator
565
566Call &WeBWorK::PG::Translator::initialize. What more do you want?
567
568=item Load PG.pl and dangerousMacros.pl
569
570These macros must be loaded without opcode masking, so they are loaded here.
571
572=item Set the opcode mask
573
574Set the opcode mask to the default specified by WeBWorK::PG::Translator.
575
576=item Load the problem source
577
578Give the problem source to the translator.
579
580=item Install a safety filter
581
582The safety filter is used to preprocess student input before evaluation. The
583default safety filter, &WeBWorK::PG::safetyFilter, is used.
584
585=item Translate the problem source
586
587Call &WeBWorK::PG::Translator::translate to render the problem source into the
588format given by the display mode.
589
590=item Process student answers
591
592Use form field inputs to evaluate student answers.
593
594=item Load the problem state
595
596Use values from the database to initialize the problem state, so that the
597grader will have a point of reference.
598
599=item Determine an entry order
600
601Use the ANSWER_ENTRY_ORDER flag to determine the order of answers in the
602problem. This is important for problems with dependancies among parts.
603
604=item Install a grader
605
606Use the PROBLEM_GRADER_TO_USE flag, or a default from the course environment,
607to install a grader.
608
609=item Grade the problem
610
611Use the selected grader to grade the problem.
612
613=back
614
615=head1 AUTHOR
616
617Written by Sam Hathaway, sh002i (at) math.rochester.edu.
618
619=cut
Legend:
Removed from v.434  
changed lines
  Added in v.620
aubreyja at gmail dot com
 ViewVC Help
Powered by ViewVC 1.0.9