[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 425 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
9
10WeBWorK::PG - Wrap the action of the PG Translator in an easy-to-use API.
11
12=cut
4 13
5use strict; 14use strict;
6use warnings; 15use warnings;
7use WeBWorK::Utils qw(readFile formatDateTime); 16use File::Path qw(rmtree);
17use File::Temp qw(tempdir);
8use WeBWorK::DB::Classlist; 18use WeBWorK::DB::Classlist;
9use WeBWorK::DB::WW; 19use WeBWorK::DB::WW;
10use WeBWorK::PG::Translator; 20use WeBWorK::PG::Translator;
21use WeBWorK::Problem;
22use WeBWorK::Utils qw(readFile formatDateTime writeTimingLogEntry);
11 23
12sub new($$$$$$$$) { 24sub new($$$$$$$$) {
13 my $invocant = shift; 25 my $invocant = shift;
14 my $class = ref($invocant) || $invocant; 26 my $class = ref($invocant) || $invocant;
15 my ( 27 my (
16 $courseEnv, 28 $courseEnv,
17 $userName, 29 $user,
18 $key, 30 $key,
19 $setName, 31 $set,
20 $problemNumber, 32 $problem,
33 $psvn,
34 $formFields, # in CGI::Vars format
21 $translationOptions, # hashref containing options for the 35 $translationOptions, # hashref containing options for the
22 # translator, such as whether to show 36 # translator, such as whether to show
23 # hints and the display mode to use 37 # hints and the display mode to use
24 $formFields, # in CGI::Vars format
25 ) = @_; 38 ) = @_;
26 39
27 # get database information 40 # write timing log entry
28 my $classlist = WeBWorK::DB::Classlist->new($courseEnv); 41 writeTimingLogEntry($courseEnv, "WeBWorK::PG::new",
29 my $wwdb = WeBWorK::DB::WW->new($courseEnv); 42 "user=".$user->id.",problem=".$courseEnv->{courseName}."/".$set->id."/".$problem->id.",mode=".$translationOptions->{displayMode},
30 my $user = $classlist->getUser($userName); 43 "begin");
31 my $set = $wwdb->getSet($userName, $setName); 44
32 my $problem = $wwdb->getProblem($userName, $setName, $problemNumber); 45 # install a local warn handler to collect warnings
33 my $psvn = $wwdb->getPSVN($userName, $setName); 46 my $warnings = "";
47 if ($courseEnv->{pg}->{options}->{catchWarnings}) {
48 local $SIG{__WARN__} = sub { $warnings .= shift };
49 }
34 50
35 # create a Translator 51 # create a Translator
36 warn "PG: creating a Translator\n"; 52 #warn "PG: creating a Translator\n";
37 my $translator = WeBWorK::PG::Translator->new; 53 my $translator = WeBWorK::PG::Translator->new;
38 54
39 # set the directory hash 55 # set the directory hash
40 warn "PG: setting the directory hash\n"; 56 #warn "PG: setting the directory hash\n";
41 $translator->rh_directories({ 57 $translator->rh_directories({
42 courseScriptsDirectory => $courseEnv->{webworkDirs}->{macros}, 58 courseScriptsDirectory => $courseEnv->{webworkDirs}->{macros},
43 macroDirectory => $courseEnv->{courseDirs}->{macros}, 59 macroDirectory => $courseEnv->{courseDirs}->{macros},
44 templateDirectory => $courseEnv->{courseDirs}->{templates}, 60 templateDirectory => $courseEnv->{courseDirs}->{templates},
45 tempDirectory => $courseEnv->{courseDirs}->{html_temp}, 61 tempDirectory => $courseEnv->{courseDirs}->{html_temp},
46 }); 62 });
47 63
48 # evaluate modules and "extra packages" 64 # evaluate modules and "extra packages"
49 warn "PG: evaluating modules and \"extra packages\"\n"; 65 #warn "PG: evaluating modules and \"extra packages\"\n";
50 my @modules = @{ $courseEnv->{pg}->{modules} }; 66 my @modules = @{ $courseEnv->{pg}->{modules} };
51 foreach my $module_packages (@modules) { 67 foreach my $module_packages_ref (@modules) {
52 # 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
53 $translator->evaluate_modules(shift @$module_packages); 70 $translator->evaluate_modules($module);
54 # the remaining items are "extra" packages 71 # the remaining items are "extra" packages
55 $translator->load_extra_packages(@$module_packages); 72 $translator->load_extra_packages(@extra_packages);
56 } 73 }
57 74
58 # set the environment (from defineProblemEnvir) 75 # set the environment (from defineProblemEnvir)
59 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 );
60 $translator->environment(defineProblemEnvir( 87 $translator->environment($envir);
61 $courseEnv, $user, $key, $set, $problem, $psvn, $formFields, $translationOptions));
62 88
63 # initialize the Translator 89 # initialize the Translator
64 warn "PG: initializing the Translator\n"; 90 #warn "PG: initializing the Translator\n";
65 $translator->initialize(); 91 $translator->initialize();
66 92
67 # load PG.pl and dangerousMacros.pl using unrestricted_load 93 # load IO.pl, PG.pl, and dangerousMacros.pl using unrestricted_load
68 # 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
69 # 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.
70 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 }
71 my $pg_pl = $courseEnv->{webworkDirs}->{macros} . "/PG.pl"; 102 #my $pg_pl = $courseEnv->{webworkDirs}->{macros} . "/PG.pl";
72 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";
73 my $err = $translator->unrestricted_load($pg_pl); 105 #my $err = $translator->unrestricted_load($pg_pl);
74 warn "Error while loading $pg_pl: $err" if $err; 106 #warn "Error while loading $pg_pl: $err" if $err;
75 $err = $translator->unrestricted_load($dangerousMacros_pl); 107 #$err = $translator->unrestricted_load($dangerousMacros_pl);
76 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;
77 111
78 # set the opcode mask (using default values) 112 # set the opcode mask (using default values)
79 warn "PG: setting the opcode mask (using default values)\n"; 113 #warn "PG: setting the opcode mask (using default values)\n";
80 $translator->set_mask(); 114 $translator->set_mask();
81 115
82 # store the problem source 116 # store the problem source
83 warn "PG: storing the problem source\n"; 117 #warn "PG: storing the problem source\n";
118 my $sourceFile = $problem->source_file;
84 my $sourceFile = $courseEnv->{courseDirs}->{templates}."/".$problem->source_file; 119 $sourceFile = $courseEnv->{courseDirs}->{templates}."/".$sourceFile
120 unless ($sourceFile =~ /^\//);
85 $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 }
86 139
87 # install a safety filter (&safetyFilter) 140 # install a safety filter (&safetyFilter)
88 warn "PG: installing a safety filter\n"; 141 #warn "PG: installing a safety filter\n";
89 $translator->rf_safety_filter(\&safetyFilter); 142 $translator->rf_safety_filter(\&safetyFilter);
90 143
91 # translate the PG source into text 144 # translate the PG source into text
92 warn "PG: translating the PG source into text\n"; 145 #warn "PG: translating the PG source into text\n";
93 $translator->translate(); 146 $translator->translate();
94 147
95 # [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 }
96 154
155 my ($result, $state); # we'll need these on the other side of the if block!
156 if ($translationOptions->{processAnswers}) {
157
97 # process student answers 158 # process student answers
98 warn "PG: processing student answers\n"; 159 #warn "PG: processing student answers\n";
99 $translator->process_answers($formFields); 160 $translator->process_answers($formFields);
100 161
101 # retrieve the problem state and give it to the translator 162 # retrieve the problem state and give it to the translator
102 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";
103 $translator->rh_problem_state({ 164 $translator->rh_problem_state({
104 recorded_score => $problem->status, 165 recorded_score => $problem->status,
105 num_of_correct_ans => $problem->num_correct, 166 num_of_correct_ans => $problem->num_correct,
106 num_of_incorrect_ans => $problem->num_incorrect, 167 num_of_incorrect_ans => $problem->num_incorrect,
107 }); 168 });
108 169
109 # 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
110 # the PG macro package (PG.pl) 171 # the PG macro package (PG.pl)
111 warn "PG: determining an entry order\n"; 172 #warn "PG: determining an entry order\n";
112 my @answerOrder = 173 my @answerOrder =
113 $translator->rh_flags->{ANSWER_ENTRY_ORDER} 174 $translator->rh_flags->{ANSWER_ENTRY_ORDER}
114 ? @{ $translator->rh_flags->{ANSWER_ENTRY_ORDER} } 175 ? @{ $translator->rh_flags->{ANSWER_ENTRY_ORDER} }
115 : keys %{ $translator->rh_evaluated_answers }; 176 : keys %{ $translator->rh_evaluated_answers };
116 177
117 # install a grader -- use the one specified in the problem, 178 # install a grader -- use the one specified in the problem,
118 # or fall back on the default from the course environment. 179 # or fall back on the default from the course environment.
119 # (two magic strings are accepted, to avoid having to 180 # (two magic strings are accepted, to avoid having to
120 # reference code when it would be difficult.) 181 # reference code when it would be difficult.)
121 warn "PG: installing a grader\n"; 182 #warn "PG: installing a grader\n";
122 my $grader = $translator->rh_flags->{PROBLEM_GRADER_TO_USE} 183 my $grader = $translator->rh_flags->{PROBLEM_GRADER_TO_USE}
123 || $courseEnv->{pg}->{options}->{grader}; 184 || $courseEnv->{pg}->{options}->{grader};
124 $grader = $translator->rf_std_problem_grader 185 $grader = $translator->rf_std_problem_grader
125 if $grader eq "std_problem_grader"; 186 if $grader eq "std_problem_grader";
126 $grader = $translator->rf_avg_problem_grader 187 $grader = $translator->rf_avg_problem_grader
127 if $grader eq "avg_problem_grader"; 188 if $grader eq "avg_problem_grader";
128 die "Problem grader $grader is not a CODE reference." 189 die "Problem grader $grader is not a CODE reference."
129 unless ref $grader eq "CODE"; 190 unless ref $grader eq "CODE";
130 $translator->rf_problem_grader($grader); 191 $translator->rf_problem_grader($grader);
131 192
132 # grading the problem 193 # grade the problem
133 warn "PG: grade the problem\n"; 194 #warn "PG: grading the problem\n";
134 my ($result, $state) = $translator->grade_problem( 195 ($result, $state) = $translator->grade_problem(
135 answers_submitted => $translationOptions->{processAnswers}, 196 answers_submitted => $translationOptions->{processAnswers},
136 ANSWER_ENTRY_ORDER => \@answerOrder, 197 ANSWER_ENTRY_ORDER => \@answerOrder,
137 ); 198 );
199
200 }
201
202 # write timing log entry
203 writeTimingLogEntry($courseEnv, "WeBWorK::PG::new", "", "end");
138 204
139 # return an object which contains the translator and the results of 205 # return an object which contains the translator and the results of
140 # the translation process. this is DIFFERENT from the "format expected 206 # the translation process. this is DIFFERENT from the "format expected
141 # by Webwork.pm (and I believe processProblem8, but check.)" 207 # by Webwork.pm (and I believe processProblem8, but check.)"
142 return bless { 208 return bless {
… …
144 head_text => ${ $translator->r_header }, 210 head_text => ${ $translator->r_header },
145 body_text => ${ $translator->r_text }, 211 body_text => ${ $translator->r_text },
146 answers => $translator->rh_evaluated_answers, 212 answers => $translator->rh_evaluated_answers,
147 result => $result, 213 result => $result,
148 state => $state, 214 state => $state,
149 errors => $translator->errors, # *** what is this doing? 215 errors => $translator->errors,
150 warnings => undef, # *** gotta catch warnings eventually... 216 warnings => $warnings,
151 flags => $translator->rh_flags, 217 flags => $translator->rh_flags,
152 }, $class; 218 }, $class;
153} 219}
154 220
155# ----- 221# -----
… …
171 # PG environment variables 237 # PG environment variables
172 # from docs/pglanguage/pgreference/environmentvariables as of 06/25/2002 238 # from docs/pglanguage/pgreference/environmentvariables as of 06/25/2002
173 # any changes are noted by "ADDED:" or "REMOVED:" 239 # any changes are noted by "ADDED:" or "REMOVED:"
174 240
175 # Vital state information 241 # Vital state information
176 # ADDED: displayHintsQ, displaySolutionsQ, externalTTHPath 242 # ADDED: displayHintsQ, displaySolutionsQ, refreshMath2img,
243 # texDisposition
177 244
178 $envir{psvn} = $psvn; 245 $envir{psvn} = $psvn;
179 $envir{psvnNumber} = $envir{psvn}; 246 $envir{psvnNumber} = $envir{psvn};
180 $envir{probNum} = $problem->id; 247 $envir{probNum} = $problem->id;
181 $envir{questionNumber} = $envir{probNum}; 248 $envir{questionNumber} = $envir{probNum};
… …
185 $envir{displayMode} = translateDisplayModeNames($options->{displayMode}); 252 $envir{displayMode} = translateDisplayModeNames($options->{displayMode});
186 $envir{languageMode} = $envir{displayMode}; 253 $envir{languageMode} = $envir{displayMode};
187 $envir{outputMode} = $envir{displayMode}; 254 $envir{outputMode} = $envir{displayMode};
188 $envir{displayHintsQ} = $options->{hints}; 255 $envir{displayHintsQ} = $options->{hints};
189 $envir{displaySolutionsQ} = $options->{solutions}; 256 $envir{displaySolutionsQ} = $options->{solutions};
190 $envir{externalTTHPath} = $courseEnv->{externalPrograms}->{tth}; 257 $envir{refreshMath2img} = $options->{refreshMath2img};
258 $envir{texDisposition} = "pdf"; # in webwork-modperl, we use pdflatex
191 259
192 # Problem Information 260 # Problem Information
193 # ADDED: courseName 261 # ADDED: courseName
194 262
195 $envir{openDate} = $set->open_date; 263 $envir{openDate} = $set->open_date;
196 $envir{formattedOpenDate} = formatDateTime($envir{openDate}); 264 $envir{formattedOpenDate} = formatDateTime($envir{openDate});
197 $envir{dueDate} = $set->due_date; 265 $envir{dueDate} = $set->due_date;
198 $envir{formattedDueDate} = formatDateTime($envir{dueDate}); 266 $envir{formattedDueDate} = formatDateTime($envir{dueDate});
199 $envir{answerDate} = $set->answer_date; 267 $envir{answerDate} = $set->answer_date;
200 $envir{formattedAnswerDate} = formatDateTime($envir{answerDate}); 268 $envir{formattedAnswerDate} = formatDateTime($envir{answerDate});
201 $envir{numOfAttempts} = $problem->num_correct + $problem->num_incorrect; 269 $envir{numOfAttempts} = ($problem->num_correct || 0) + ($problem->num_incorrect || 0);
202 $envir{problemValue} = $problem->value; 270 $envir{problemValue} = $problem->value;
203 $envir{sessionKey} = $key; 271 $envir{sessionKey} = $key;
204 $envir{courseName} = $courseEnv->{courseName}; 272 $envir{courseName} = $courseEnv->{courseName};
205 273
206 # Student Information 274 # Student Information
… …
214 $envir{studentLogin} = $user->id; 282 $envir{studentLogin} = $user->id;
215 $envir{studentName} = $user->first_name . " " . $user->last_name; 283 $envir{studentName} = $user->first_name . " " . $user->last_name;
216 $envir{studentID} = $user->student_id; 284 $envir{studentID} = $user->student_id;
217 285
218 # Answer Information 286 # Answer Information
219 # REMOVED: refSubmittedAnswers (alledgedly unused, causes errors) 287 # REMOVED: refSubmittedAnswers
220 288
221 $envir{inputs_ref} = $formFields; 289 $envir{inputs_ref} = $formFields;
222 290
223 # Default values for evaluating answers 291 # External Programs
292 # ADDED: externalLaTeXPath, externalDvipngPath,
293 # externalGif2EpsPath, externalPng2EpsPath
224 294
225 my $ansEvalDefaults = $courseEnv->{pg}->{ansEvalDefaults}; 295 $envir{externalTTHPath} = $courseEnv->{externalPrograms}->{tth};
226 $envir{$_} = $ansEvalDefaults->{$_} foreach (keys %$ansEvalDefaults); 296 $envir{externalLaTeXPath} = $courseEnv->{externalPrograms}->{latex};
297 $envir{externalDvipngPath} = $courseEnv->{externalPrograms}->{dvipng};
298 $envir{externalGif2EpsPath} = $courseEnv->{externalPrograms}->{gif2eps};
299 $envir{externalPng2EpsPath} = $courseEnv->{externalPrograms}->{png2eps};
300 $envir{externalGif2PngPath} = $courseEnv->{externalPrograms}->{gif2png};
227 301
228 # Directories and URLs 302 # Directories and URLs
229 # REMOVED: courseName 303 # REMOVED: courseName
304 # ADDED: dvipngTempDir
230 305
231 $envir{cgiDirectory} = undef; 306 $envir{cgiDirectory} = undef;
232 $envir{cgiURL} = undef; 307 $envir{cgiURL} = undef;
233 $envir{classDirectory} = undef; 308 $envir{classDirectory} = undef;
234 $envir{courseScriptsDirectory} = $courseEnv->{webworkDirs}->{macros}."/"; 309 $envir{courseScriptsDirectory} = $courseEnv->{webworkDirs}->{macros}."/";
235 $envir{htmlDirectory} = $courseEnv->{courseDirs}->{html}."/"; 310 $envir{htmlDirectory} = $courseEnv->{courseDirs}->{html}."/";
236 $envir{htmlURL} = $courseEnv->{courseURLs}->{html}; 311 $envir{htmlURL} = $courseEnv->{courseURLs}->{html}."/";
237 $envir{macroDirectory} = $courseEnv->{courseDirs}->{macros}."/"; 312 $envir{macroDirectory} = $courseEnv->{courseDirs}->{macros}."/";
238 $envir{templateDirectory} = $courseEnv->{courseDirs}->{templates}."/"; 313 $envir{templateDirectory} = $courseEnv->{courseDirs}->{templates}."/";
239 $envir{tempDirectory} = $courseEnv->{courseDirs}->{html_temp}."/"; 314 $envir{tempDirectory} = $courseEnv->{courseDirs}->{html_temp}."/";
240 $envir{tempURL} = $courseEnv->{courseURLs}->{html_temp}; 315 $envir{tempURL} = $courseEnv->{courseURLs}->{html_temp}."/";
241 $envir{scriptDirectory} = undef; 316 $envir{scriptDirectory} = undef;
242 $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;
243 321
244 # Other things... (where's your brain?!?!) 322 # Default values for evaluating answers
323
324 my $ansEvalDefaults = $courseEnv->{pg}->{ansEvalDefaults};
325 $envir{$_} = $ansEvalDefaults->{$_} foreach (keys %$ansEvalDefaults);
326
327 # Other things...
245 328
246 $envir{PROBLEM_GRADER_TO_USE} = $courseEnv->{pg}->{options}->{grader}; 329 $envir{PROBLEM_GRADER_TO_USE} = $courseEnv->{pg}->{options}->{grader};
247 330
248 return \%envir; 331 return \%envir;
249} 332}
250 333
251sub translateDisplayModeNames($) { 334sub translateDisplayModeNames($) {
252 my $name = shift; 335 my $name = shift;
253 return { 336 return {
337 tex => "TeX",
254 plainText => "HTML", 338 plainText => "HTML",
255 formattedText => "HTML_tth", 339 formattedText => "HTML_tth",
256 images => "Latex2HTML" 340 images => "HTML_img"
257 }->{$name}; 341 }->{$name};
258} 342}
259 343
260sub safetyFilter { 344sub safetyFilter {
261 my $answer = shift; # accepts one answer and checks it 345 my $answer = shift; # accepts one answer and checks it
… …
280 $errorno = 0; 364 $errorno = 0;
281 return($answer, $errorno); 365 return($answer, $errorno);
282} 366}
283 367
2841; 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.425  
changed lines
  Added in v.620
aubreyja at gmail dot com
 ViewVC Help
Powered by ViewVC 1.0.9