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

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

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

Revision 1196 Revision 2371
1################################################################################ 1################################################################################
2# WeBWorK mod_perl (c) 2000-2002 WeBWorK Project 2# WeBWorK Online Homework Delivery System
3# $Id$ 3# Copyright © 2000-2003 The WeBWorK Project, http://openwebwork.sf.net/
4# $CVSHeader: webwork-modperl/lib/WeBWorK/PG.pm,v 1.53 2004/06/21 19:07:08 gage Exp $
5#
6# This program is free software; you can redistribute it and/or modify it under
7# the terms of either: (a) the GNU General Public License as published by the
8# Free Software Foundation; either version 2, or (at your option) any later
9# version, or (b) the "Artistic License" which comes with this package.
10#
11# This program is distributed in the hope that it will be useful, but WITHOUT
12# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
13# FOR A PARTICULAR PURPOSE. See either the GNU General Public License or the
14# Artistic License for more details.
4################################################################################ 15################################################################################
5 16
6package WeBWorK::PG; 17package WeBWorK::PG;
7 18
8=head1 NAME 19=head1 NAME
9 20
10WeBWorK::PG - Wrap the action of the PG Translator in an easy-to-use API. 21WeBWorK::PG - Invoke one of several PG rendering methods using an easy-to-use
22API.
11 23
12=cut 24=cut
13 25
14use strict; 26use strict;
15use warnings; 27use warnings;
16use File::Path qw(rmtree);
17use WeBWorK::PG::ImageGenerator; 28use WeBWorK::PG::ImageGenerator;
18use WeBWorK::PG::Translator;
19use WeBWorK::Utils qw(readFile formatDateTime writeTimingLogEntry makeTempDirectory); 29use WeBWorK::Utils qw(runtime_use formatDateTime makeTempDirectory);
30
31use constant DISPLAY_MODES => {
32 # display name # mode name
33 tex => "TeX",
34 plainText => "HTML",
35 formattedText => "HTML_tth",
36 images => "HTML_dpng",
37 jsMath => "HTML_jsMath",
38 asciimath => "HTML_asciimath",
39};
20 40
21sub new { 41sub new {
22 my $invocant = shift; 42 shift; # throw away invocant -- we don't need it
23 my $class = ref($invocant) || $invocant; 43 my ($ce, $user, $key, $set, $problem, $psvn, $formFields,
24 my (
25 $courseEnv,
26 $user,
27 $key,
28 $set,
29 $problem,
30 $psvn,
31 $formFields, # in CGI::Vars format
32 $translationOptions, # hashref containing options for the
33 # translator, such as whether to show
34 # hints and the display mode to use
35 ) = @_;
36
37 # write timing log entry
38 writeTimingLogEntry($courseEnv, "WeBWorK::PG::new",
39 "user=".$user->user_id.",problem=".$courseEnv->{courseName}."/".$set->set_id."/".$problem->problem_id.",mode=".$translationOptions->{displayMode},
40 "begin");
41
42 # install a local warn handler to collect warnings
43 my $warnings = "";
44 local $SIG{__WARN__} = sub { $warnings .= shift }
45 if $courseEnv->{pg}->{options}->{catchWarnings};
46
47 # create a Translator
48 #warn "PG: creating a Translator\n";
49 my $translator = WeBWorK::PG::Translator->new;
50
51 # set the directory hash
52 #warn "PG: setting the directory hash\n";
53 $translator->rh_directories({
54 courseScriptsDirectory => $courseEnv->{webworkDirs}->{macros},
55 macroDirectory => $courseEnv->{courseDirs}->{macros},
56 templateDirectory => $courseEnv->{courseDirs}->{templates},
57 tempDirectory => $courseEnv->{courseDirs}->{html_temp},
58 });
59
60 # evaluate modules and "extra packages"
61 #warn "PG: evaluating modules and \"extra packages\"\n";
62 my @modules = @{ $courseEnv->{pg}->{modules} };
63 foreach my $module_packages_ref (@modules) {
64 my ($module, @extra_packages) = @$module_packages_ref;
65 # the first item is the main package
66 $translator->evaluate_modules($module);
67 # the remaining items are "extra" packages
68 $translator->load_extra_packages(@extra_packages);
69 }
70
71 # set the environment (from defineProblemEnvir)
72 #warn "PG: setting the environment (from defineProblemEnvir)\n";
73 my $envir = defineProblemEnvir(
74 $courseEnv,
75 $user,
76 $key,
77 $set,
78 $problem,
79 $psvn,
80 $formFields,
81 $translationOptions, 44 $translationOptions) = @_;
82 );
83 $translator->environment($envir);
84 45
85 # initialize the Translator 46 my $renderer = $ce->{pg}->{renderer};
86 #warn "PG: initializing the Translator\n";
87 $translator->initialize();
88 47
89 # load IO.pl, PG.pl, and dangerousMacros.pl using unrestricted_load 48 runtime_use $renderer;
90 # i'd like to change this at some point to have the same sort of interface to global.conf
91 # that the module loading does -- have a list of macros to load unrestrictedly.
92 #warn "PG: loading IO.pl, PG.pl, and dangerousMacros.pl using unrestricted_load\n";
93 foreach (qw(IO.pl PG.pl dangerousMacros.pl)) {
94 my $macroPath = $courseEnv->{webworkDirs}->{macros} . "/$_";
95 my $err = $translator->unrestricted_load($macroPath);
96 warn "Error while loading $macroPath: $err" if $err;
97 }
98 49
99 # set the opcode mask (using default values) 50 return $renderer->new(@_);
100 #warn "PG: setting the opcode mask (using default values)\n";
101 $translator->set_mask();
102
103 # store the problem source
104 #warn "PG: storing the problem source\n";
105 my $sourceFile = $problem->source_file;
106 $sourceFile = $courseEnv->{courseDirs}->{templates}."/".$sourceFile
107 unless ($sourceFile =~ /^\//);
108 eval { $translator->source_string(readFile($sourceFile)) };
109 if ($@) {
110 # well, we couldn't get the problem source, for some reason.
111 return bless {
112 translator => $translator,
113 head_text => "",
114 body_text => <<EOF,
115WeBWorK::Utils::readFile($sourceFile) says:
116$@
117EOF
118 answers => {},
119 result => {},
120 state => {},
121 errors => "Failed to read the problem source file.",
122 warnings => $warnings,
123 flags => {error_flag => 1},
124 }, $class;
125 }
126
127 # install a safety filter (&safetyFilter)
128 #warn "PG: installing a safety filter\n";
129 $translator->rf_safety_filter(\&safetyFilter);
130
131 # write timing log entry -- the translator is now all set up
132 writeTimingLogEntry($courseEnv, "WeBWorK::PG::new",
133 "initialized",
134 "intermediate");
135
136 # translate the PG source into text
137 #warn "PG: translating the PG source into text\n";
138 $translator->translate();
139
140 # after we're done translating, we may have to clean up after the
141 # translator:
142
143 # for example, HTML_img mode uses a tempdir for dvipng's temp files.\
144 # We have to remove it.
145 if ($envir->{dvipngTempDir}) {
146 rmtree($envir->{dvipngTempDir}, 0, 0);
147 }
148
149 # HTML_dpng, on the other hand, uses an ImageGenerator. We have to
150 # render the queued equations.
151 if ($envir->{imagegen}) {
152 my $sourceFile = $courseEnv->{courseDirs}->{templates} . "/" . $problem->source_file;
153 my %mtimeOption = -e $sourceFile
154 ? (mtime => (stat $sourceFile)[9])
155 : ();
156
157 $envir->{imagegen}->render(
158 refresh => $translationOptions->{refreshMath2img},
159 %mtimeOption,
160 );
161 }
162
163 my ($result, $state); # we'll need these on the other side of the if block!
164 if ($translationOptions->{processAnswers}) {
165
166 # process student answers
167 #warn "PG: processing student answers\n";
168 $translator->process_answers($formFields);
169
170 # retrieve the problem state and give it to the translator
171 #warn "PG: retrieving the problem state and giving it to the translator\n";
172 $translator->rh_problem_state({
173 recorded_score => $problem->status,
174 num_of_correct_ans => $problem->num_correct,
175 num_of_incorrect_ans => $problem->num_incorrect,
176 });
177
178 # determine an entry order -- the ANSWER_ENTRY_ORDER flag is built by
179 # the PG macro package (PG.pl)
180 #warn "PG: determining an entry order\n";
181 my @answerOrder =
182 $translator->rh_flags->{ANSWER_ENTRY_ORDER}
183 ? @{ $translator->rh_flags->{ANSWER_ENTRY_ORDER} }
184 : keys %{ $translator->rh_evaluated_answers };
185
186 # install a grader -- use the one specified in the problem,
187 # or fall back on the default from the course environment.
188 # (two magic strings are accepted, to avoid having to
189 # reference code when it would be difficult.)
190 #warn "PG: installing a grader\n";
191 my $grader = $translator->rh_flags->{PROBLEM_GRADER_TO_USE}
192 || $courseEnv->{pg}->{options}->{grader};
193 $grader = $translator->rf_std_problem_grader
194 if $grader eq "std_problem_grader";
195 $grader = $translator->rf_avg_problem_grader
196 if $grader eq "avg_problem_grader";
197 die "Problem grader $grader is not a CODE reference."
198 unless ref $grader eq "CODE";
199 $translator->rf_problem_grader($grader);
200
201 # grade the problem
202 #warn "PG: grading the problem\n";
203 ($result, $state) = $translator->grade_problem(
204 answers_submitted => $translationOptions->{processAnswers},
205 ANSWER_ENTRY_ORDER => \@answerOrder,
206 );
207
208 }
209
210 # write timing log entry
211 writeTimingLogEntry($courseEnv, "WeBWorK::PG::new", "", "end");
212
213 # return an object which contains the translator and the results of
214 # the translation process. this is DIFFERENT from the "format expected
215 # by Webwork.pm (and I believe processProblem8, but check.)"
216 return bless {
217 translator => $translator,
218 head_text => ${ $translator->r_header },
219 body_text => ${ $translator->r_text },
220 answers => $translator->rh_evaluated_answers,
221 result => $result,
222 state => $state,
223 errors => $translator->errors,
224 warnings => $warnings,
225 flags => $translator->rh_flags,
226 }, $class;
227} 51}
228
229# -----
230 52
231sub defineProblemEnvir { 53sub defineProblemEnvir {
232 my ( 54 my (
233 $courseEnv, 55 $self,
56 $ce,
234 $user, 57 $user,
235 $key, 58 $key,
236 $set, 59 $set,
237 $problem, 60 $problem,
238 $psvn, 61 $psvn,
… …
247 # PG environment variables 70 # PG environment variables
248 # from docs/pglanguage/pgreference/environmentvariables as of 06/25/2002 71 # from docs/pglanguage/pgreference/environmentvariables as of 06/25/2002
249 # any changes are noted by "ADDED:" or "REMOVED:" 72 # any changes are noted by "ADDED:" or "REMOVED:"
250 73
251 # Vital state information 74 # Vital state information
252 # ADDED: displayHintsQ, displaySolutionsQ, refreshMath2img, 75 # ADDED: displayModeFailover, displayHintsQ, displaySolutionsQ,
253 # texDisposition 76 # refreshMath2img, texDisposition
254 77
255 $envir{psvn} = $set->psvn; 78 $envir{psvn} = $set->psvn;
256 $envir{psvnNumber} = $envir{psvn}; 79 $envir{psvnNumber} = $envir{psvn};
257 $envir{probNum} = $problem->problem_id; 80 $envir{probNum} = $problem->problem_id;
258 $envir{questionNumber} = $envir{probNum}; 81 $envir{questionNumber} = $envir{probNum};
259 $envir{fileName} = $problem->source_file; 82 $envir{fileName} = $problem->source_file;
260 $envir{probFileName} = $envir{fileName}; 83 $envir{probFileName} = $envir{fileName};
261 $envir{problemSeed} = $problem->problem_seed; 84 $envir{problemSeed} = $problem->problem_seed;
262 $envir{displayMode} = translateDisplayModeNames($options->{displayMode}); 85 $envir{displayMode} = translateDisplayModeNames($options->{displayMode});
263 $envir{languageMode} = $envir{displayMode}; 86 $envir{languageMode} = $envir{displayMode};
264 $envir{outputMode} = $envir{displayMode}; 87 $envir{outputMode} = $envir{displayMode};
265 $envir{displayHintsQ} = $options->{showHints}; 88 $envir{displayHintsQ} = $options->{showHints};
266 $envir{displaySolutionsQ} = $options->{showSolutions}; 89 $envir{displaySolutionsQ} = $options->{showSolutions};
267 # FIXME: this is HTML_img specific
268 #$envir{refreshMath2img} = $options->{refreshMath2img};
269 $envir{texDisposition} = "pdf"; # in webwork-modperl, we use pdflatex 90 $envir{texDisposition} = "pdf"; # in webwork2, we use pdflatex
270 91
271 # Problem Information 92 # Problem Information
272 # ADDED: courseName, formatedDueDate 93 # ADDED: courseName, formatedDueDate
273 94
274 $envir{openDate} = $set->open_date; 95 $envir{openDate} = $set->open_date;
… …
279 $envir{answerDate} = $set->answer_date; 100 $envir{answerDate} = $set->answer_date;
280 $envir{formattedAnswerDate} = formatDateTime($envir{answerDate}); 101 $envir{formattedAnswerDate} = formatDateTime($envir{answerDate});
281 $envir{numOfAttempts} = ($problem->num_correct || 0) + ($problem->num_incorrect || 0); 102 $envir{numOfAttempts} = ($problem->num_correct || 0) + ($problem->num_incorrect || 0);
282 $envir{problemValue} = $problem->value; 103 $envir{problemValue} = $problem->value;
283 $envir{sessionKey} = $key; 104 $envir{sessionKey} = $key;
284 $envir{courseName} = $courseEnv->{courseName}; 105 $envir{courseName} = $ce->{courseName};
285 106
286 # Student Information 107 # Student Information
287 # ADDED: studentID 108 # ADDED: studentID
288 109
289 $envir{sectionName} = $user->section; 110 $envir{sectionName} = $user->section;
… …
302 123
303 # External Programs 124 # External Programs
304 # ADDED: externalLaTeXPath, externalDvipngPath, 125 # ADDED: externalLaTeXPath, externalDvipngPath,
305 # externalGif2EpsPath, externalPng2EpsPath 126 # externalGif2EpsPath, externalPng2EpsPath
306 127
307 $envir{externalTTHPath} = $courseEnv->{externalPrograms}->{tth}; 128 $envir{externalTTHPath} = $ce->{externalPrograms}->{tth};
308 $envir{externalLaTeXPath} = $courseEnv->{externalPrograms}->{latex}; 129 $envir{externalLaTeXPath} = $ce->{externalPrograms}->{latex};
309 $envir{externalDvipngPath} = $courseEnv->{externalPrograms}->{dvipng}; 130 $envir{externalDvipngPath} = $ce->{externalPrograms}->{dvipng};
310 $envir{externalGif2EpsPath} = $courseEnv->{externalPrograms}->{gif2eps}; 131 $envir{externalGif2EpsPath} = $ce->{externalPrograms}->{gif2eps};
311 $envir{externalPng2EpsPath} = $courseEnv->{externalPrograms}->{png2eps}; 132 $envir{externalPng2EpsPath} = $ce->{externalPrograms}->{png2eps};
312 $envir{externalGif2PngPath} = $courseEnv->{externalPrograms}->{gif2png}; 133 $envir{externalGif2PngPath} = $ce->{externalPrograms}->{gif2png};
313 134
314 # Directories and URLs 135 # Directories and URLs
315 # REMOVED: courseName 136 # REMOVED: courseName
316 # ADDED: dvipngTempDir 137 # ADDED: dvipngTempDir
138 # ADDED: jsMathURL
139 # ADDED: asciimathURL
317 140
318 $envir{cgiDirectory} = undef; 141 $envir{cgiDirectory} = undef;
319 $envir{cgiURL} = undef; 142 $envir{cgiURL} = undef;
320 $envir{classDirectory} = undef; 143 $envir{classDirectory} = undef;
321 $envir{courseScriptsDirectory} = $courseEnv->{webworkDirs}->{macros}."/"; 144 $envir{courseScriptsDirectory} = $ce->{pg}->{directories}->{macros}."/";
322 $envir{htmlDirectory} = $courseEnv->{courseDirs}->{html}."/"; 145 $envir{htmlDirectory} = $ce->{courseDirs}->{html}."/";
323 $envir{htmlURL} = $courseEnv->{courseURLs}->{html}."/"; 146 $envir{htmlURL} = $ce->{courseURLs}->{html}."/";
324 $envir{macroDirectory} = $courseEnv->{courseDirs}->{macros}."/"; 147 $envir{macroDirectory} = $ce->{courseDirs}->{macros}."/";
325 $envir{templateDirectory} = $courseEnv->{courseDirs}->{templates}."/"; 148 $envir{templateDirectory} = $ce->{courseDirs}->{templates}."/";
326 $envir{tempDirectory} = $courseEnv->{courseDirs}->{html_temp}."/"; 149 $envir{tempDirectory} = $ce->{courseDirs}->{html_temp}."/";
327 $envir{tempURL} = $courseEnv->{courseURLs}->{html_temp}."/"; 150 $envir{tempURL} = $ce->{courseURLs}->{html_temp}."/";
328 $envir{scriptDirectory} = undef; 151 $envir{scriptDirectory} = undef;
329 $envir{webworkDocsURL} = $courseEnv->{webworkURLs}->{docs}."/"; 152 $envir{webworkDocsURL} = $ce->{webworkURLs}->{docs}."/";
330 # FIXME: this is HTML_img mode-specific 153 $envir{localHelpURL} = $ce->{webworkURLs}->{local_help}."/";
331 #$envir{dvipngTempDir} = $options->{displayMode} eq 'images' 154 $envir{jsMathURL} = $ce->{webworkURLs}->{jsMath};
332 # ? makeTempDirectory($envir{tempDirectory}, "webwork-dvipng") 155 $envir{asciimathURL} = $ce->{webworkURLs}->{asciimath};
333 # : undef;
334 156
335 # Information for sending mail 157 # Information for sending mail
336 158
337 $envir{mailSmtpServer} = $courseEnv->{mail}->{smtpServer}; 159 $envir{mailSmtpServer} = $ce->{mail}->{smtpServer};
338 $envir{mailSmtpSender} = $courseEnv->{mail}->{smtpSender}; 160 $envir{mailSmtpSender} = $ce->{mail}->{smtpSender};
339 $envir{ALLOW_MAIL_TO} = $courseEnv->{mail}->{allowedRecipients}; 161 $envir{ALLOW_MAIL_TO} = $ce->{mail}->{allowedRecipients};
340 162
341 # Default values for evaluating answers 163 # Default values for evaluating answers
342 164
343 my $ansEvalDefaults = $courseEnv->{pg}->{ansEvalDefaults}; 165 my $ansEvalDefaults = $ce->{pg}->{ansEvalDefaults};
344 $envir{$_} = $ansEvalDefaults->{$_} foreach (keys %$ansEvalDefaults); 166 $envir{$_} = $ansEvalDefaults->{$_} foreach (keys %$ansEvalDefaults);
345 167
346 # ---------------------------------------------------------------------- 168 # ----------------------------------------------------------------------
347 169
348 my $basename = "equation-$envir{psvn}.$envir{probNum}"; 170 my $basename = "equation-$envir{psvn}.$envir{probNum}";
349 $basename .= ".$envir{problemSeed}" if $envir{problemSeed}; 171 $basename .= ".$envir{problemSeed}" if $envir{problemSeed};
350 172
351 # Object for generating equation images 173 # Object for generating equation images
352 $envir{imagegen} = WeBWorK::PG::ImageGenerator->new( 174 $envir{imagegen} = WeBWorK::PG::ImageGenerator->new(
353 tempDir => $courseEnv->{webworkDirs}->{tmp}, # global temp dir 175 tempDir => $ce->{webworkDirs}->{tmp}, # global temp dir
354 dir => $envir{tempDirectory},
355 url => $envir{tempURL},
356 basename => $basename,
357 latex => $envir{externalLaTeXPath}, 176 latex => $envir{externalLaTeXPath},
358 dvipng => $envir{externalDvipngPath}, 177 dvipng => $envir{externalDvipngPath},
178 useCache => 1,
179 cacheDir => $ce->{webworkDirs}->{equationCache},
180 cacheURL => $ce->{webworkURLs}->{equationCache},
181 cacheDB => $ce->{webworkFiles}->{equationCacheDB},
359 ); 182 );
360 183
361 # Other things... 184 # Other things...
362 $envir{QUIZ_PREFIX} = $options->{QUIZ_PREFIX}; # used by quizzes 185 $envir{QUIZ_PREFIX} = $options->{QUIZ_PREFIX}; # used by quizzes
363 $envir{PROBLEM_GRADER_TO_USE} = $courseEnv->{pg}->{options}->{grader}; 186 $envir{PROBLEM_GRADER_TO_USE} = $ce->{pg}->{options}->{grader};
364 $envir{PRINT_FILE_NAMES_FOR} = $courseEnv->{pg}->{specialPGEnvironmentVars}->{PRINT_FILE_NAMES_FOR}; 187 $envir{PRINT_FILE_NAMES_FOR} = $ce->{pg}->{specialPGEnvironmentVars}->{PRINT_FILE_NAMES_FOR};
365 188
366 # variables for interpreting capa problems. 189 # variables for interpreting capa problems and other things to be
367 $envir{CAPA_Tools} = $courseEnv->{pg}->{specialPGEnvironmentVars}->{CAPA_Tools}; 190 # seen in a pg file
368 $envir{CAPA_MCTools} = $courseEnv->{pg}->{specialPGEnvironmentVars}->{CAPA_MCTools}; 191 my $specialPGEnvironmentVarHash = $ce->{pg}->{specialPGEnvironmentVars};
369 $envir{CAPA_Graphics_URL} = $courseEnv->{pg}->{specialPGEnvironmentVars}->{CAPA_Graphics_URL}; 192 for my $SPGEV (keys %{$specialPGEnvironmentVarHash}) {
370 $envir{CAPA_GraphicsDirectory} = $courseEnv->{pg}->{specialPGEnvironmentVars}->{CAPA_GraphicsDirectory}; 193 $envir{$SPGEV} = $specialPGEnvironmentVarHash->{$SPGEV};
194 }
371 195
372 return \%envir; 196 return \%envir;
373} 197}
374 198
375sub translateDisplayModeNames($) { 199sub translateDisplayModeNames($) {
376 my $name = shift; 200 my $name = shift;
377 return { 201 return DISPLAY_MODES()->{$name};
378 tex => "TeX",
379 plainText => "HTML",
380 formattedText => "HTML_tth",
381 images => "HTML_dpng", # "HTML_img",
382 }->{$name};
383} 202}
384 203
385sub safetyFilter { 204sub oldSafetyFilter {
386 my $answer = shift; # accepts one answer and checks it 205 my $answer = shift; # accepts one answer and checks it
387 my $submittedAnswer = $answer; 206 my $submittedAnswer = $answer;
388 $answer = '' unless defined $answer; 207 $answer = '' unless defined $answer;
389 my ($errorno); 208 my ($errorno);
390 $answer =~ tr/\000-\037/ /; 209 $answer =~ tr/\000-\037/ /;
… …
404 } 223 }
405 $errorno = 0; 224 $errorno = 0;
406 return($answer, $errorno); 225 return($answer, $errorno);
407} 226}
408 227
228sub nullSafetyFilter {
229 return shift, 0; # no errors
230}
231
4091; 2321;
410 233
411__END__ 234__END__
412 235
413=head1 SYNOPSIS 236=head1 SYNOPSIS
414 237
415 $pg = WeBWorK::PG->new( 238 $pg = WeBWorK::PG->new(
416 $courseEnv, # a WeBWorK::CourseEnvironment object 239 $ce, # a WeBWorK::CourseEnvironment object
417 $user, # a WeBWorK::DB::Record::User object 240 $user, # a WeBWorK::DB::Record::User object
418 $sessionKey, 241 $sessionKey,
419 $set, # a WeBWorK::DB::Record::UserSet object 242 $set, # a WeBWorK::DB::Record::UserSet object
420 $problem, # a WeBWorK::DB::Record::UserProblem object 243 $problem, # a WeBWorK::DB::Record::UserProblem object
421 $psvn, 244 $psvn,
… …
439 $warnings = $pg->{warnings}; # text string 262 $warnings = $pg->{warnings}; # text string
440 $flags = $pg->{flags}; # hash reference 263 $flags = $pg->{flags}; # hash reference
441 264
442=head1 DESCRIPTION 265=head1 DESCRIPTION
443 266
444WeBWorK::PG encapsulates the PG translation process, making multiple calls to 267WeBWorK::PG is a factory for modules which use the WeBWorK::PG API. Notable
445WeBWorK::PG::Translator. Much of the flexibility of the Translator is hidden, 268modules which use this API (and exist) are WeBWorK::PG::Local and
446instead making choices that are appropriate for the webwork-modperl system. 269WeBWorK::PG::Remote. The course environment key $pg{renderer} is consulted to
270determine which render to use.
447 271
448=head1 CONSTRUCTION 272=head1 THE WEBWORK::PG API
273
274Modules which support this API must implement the following method:
449 275
450=over 276=over
451 277
452=item new (ENVIRONMENT, USER, KEY, SET, PROBLEM, PSVN, FIELDS, OPTIONS) 278=item new ENVIRONMENT, USER, KEY, SET, PROBLEM, PSVN, FIELDS, OPTIONS
453 279
454The C<new> method creates a translator, initializes it using the parameters 280The C<new> method creates a translator, initializes it using the parameters
455specified, translates a PG file, and processes answers. It returns a reference 281specified, translates a PG file, and processes answers. It returns a reference
456to a blessed hash containing the results of the translation process. 282to a blessed hash containing the results of the translation process.
457 283
… …
513boolean, render solutions 339boolean, render solutions
514 340
515=item refreshMath2img 341=item refreshMath2img
516 342
517boolean, force images created by math2img (in "images" mode) to be recreated, 343boolean, force images created by math2img (in "images" mode) to be recreated,
518even if the PG source has not been updated. FIXME: change the name of this 344even if the PG source has not been updated. FIXME: remove this option.
519option to "refreshEquations" and update the docs accordingly.
520 345
521=item processAnswers 346=item processAnswers
522 347
523boolean, call answer evaluators and graders 348boolean, call answer evaluators and graders
524 349
… …
572 397
573A hash containing PG_flags (see the Translator docs). 398A hash containing PG_flags (see the Translator docs).
574 399
575=back 400=back
576 401
577=head1 OPERATION 402=head1 METHODS PROVIDED BY THE BASE CLASS
578 403
579WeBWorK::PG goes through the following operations when constructed: 404The following methods are provided for use by subclasses of WeBWorK::PG.
580 405
581=over 406=over
582 407
583=item Get database information 408=item defineProblemEnvir ENVIRONMENT, USER, KEY, SET, PROBLEM, PSVN, FIELDS, OPTIONS
584 409
585Retrieve information about the current user, set, and problem from the 410Generate a problem environment hash to pass to the renderer.
586database.
587 411
588=item Create a translator 412=item translateDisplayModeNames NAME
589 413
590Instantiate a WeBWorK::PG::Translator object. 414NAME contains
591
592=item Set the directory hash
593
594Set the translator's directory hash (courseScripts, macros, templates, and temp
595directories) from the course environment.
596
597=item Evaluate PG modules
598
599Using the module list from the course environment (pg->modules), perform a
600"use"-like operation to evaluate modules at runtime.
601
602=item Set the problem environment
603
604Use data from the user, set, and problem, as well as the course environemnt and
605translation options, to set the problem environment.
606
607=item Initialize the translator
608
609Call &WeBWorK::PG::Translator::initialize. What more do you want?
610
611=item Load PG.pl and dangerousMacros.pl
612
613These macros must be loaded without opcode masking, so they are loaded here.
614
615=item Set the opcode mask
616
617Set the opcode mask to the default specified by WeBWorK::PG::Translator.
618
619=item Load the problem source
620
621Give the problem source to the translator.
622
623=item Install a safety filter
624
625The safety filter is used to preprocess student input before evaluation. The
626default safety filter, &WeBWorK::PG::safetyFilter, is used.
627
628=item Translate the problem source
629
630Call &WeBWorK::PG::Translator::translate to render the problem source into the
631format given by the display mode.
632
633=item Process student answers
634
635Use form field inputs to evaluate student answers.
636
637=item Load the problem state
638
639Use values from the database to initialize the problem state, so that the
640grader will have a point of reference.
641
642=item Determine an entry order
643
644Use the ANSWER_ENTRY_ORDER flag to determine the order of answers in the
645problem. This is important for problems with dependancies among parts.
646
647=item Install a grader
648
649Use the PROBLEM_GRADER_TO_USE flag, or a default from the course environment,
650to install a grader.
651
652=item Grade the problem
653
654Use the selected grader to grade the problem.
655 415
656=back 416=back
657 417
658=head1 AUTHOR 418=head1 AUTHOR
659 419
Legend:
Removed from v.1196  
changed lines
  Added in v.2371
aubreyja at gmail dot com
 ViewVC Help
Powered by ViewVC 1.0.9