[system] / trunk / webwork2 / lib / WeBWorK / PG.pm Repository:
ViewVC logotype

Diff of /trunk/webwork2/lib/WeBWorK/PG.pm

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

Revision 1154 Revision 1703
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.46 2003/12/09 01:12:30 sh002i 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);
20 30
21sub new($$$$$$$$) { 31sub new {
22 my $invocant = shift; 32 shift; # throw away invocant -- we don't need it
23 my $class = ref($invocant) || $invocant; 33 my ($ce, $user, $key, $set, $problem, $psvn, $formFields,
34 $translationOptions) = @_;
35
36 my $renderer = $ce->{pg}->{renderer};
37
38 runtime_use $renderer;
39
40 return $renderer->new(@_);
41}
42
43sub defineProblemEnvir {
24 my ( 44 my (
25 $courseEnv,
26 $user,
27 $key,
28 $set, 45 $self,
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, 46 $ce,
77 $set,
78 $problem,
79 $psvn,
80 $formFields,
81 $translationOptions,
82 );
83 $translator->environment($envir);
84
85 # initialize the Translator
86 #warn "PG: initializing the Translator\n";
87 $translator->initialize();
88
89 # load IO.pl, PG.pl, and dangerousMacros.pl using unrestricted_load
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
99 # set the opcode mask (using default values)
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 = ( defined($translationOptions->{override_problem_source}) ) ?
106 $translationOptions->{override_problem_source} :
107 $problem->source_file;
108 $sourceFile = $courseEnv->{courseDirs}->{templates}."/".$sourceFile
109 unless ($sourceFile =~ /^\//);
110 eval { $translator->source_string(readFile($sourceFile)) };
111 if ($@) {
112 # well, we couldn't get the problem source, for some reason.
113 return bless {
114 translator => $translator,
115 head_text => "",
116 body_text => <<EOF,
117WeBWorK::Utils::readFile($sourceFile) says:
118$@
119EOF
120 answers => {},
121 result => {},
122 state => {},
123 errors => "Failed to read the problem source file.",
124 warnings => $warnings,
125 flags => {error_flag => 1},
126 }, $class;
127 }
128
129 # install a safety filter (&safetyFilter)
130 #warn "PG: installing a safety filter\n";
131 $translator->rf_safety_filter(\&safetyFilter);
132
133 # write timing log entry -- the translator is now all set up
134 writeTimingLogEntry($courseEnv, "WeBWorK::PG::new",
135 "initialized",
136 "intermediate");
137
138 # translate the PG source into text
139 #warn "PG: translating the PG source into text\n";
140 $translator->translate();
141
142 # after we're done translating, we may have to clean up after the
143 # translator:
144
145 # for example, HTML_img mode uses a tempdir for dvipng's temp files.\
146 # We have to remove it.
147 if ($envir->{dvipngTempDir}) {
148 rmtree($envir->{dvipngTempDir}, 0, 0);
149 }
150
151 # HTML_dpng, on the other hand, uses an ImageGenerator. We have to
152 # render the queued equations.
153 if ($envir->{imagegen}) {
154 my $sourceFile = $courseEnv->{courseDirs}->{templates} . "/" . $problem->source_file;
155 my %mtimeOption = -e $sourceFile
156 ? (mtime => (stat $sourceFile)[9])
157 : ();
158
159 $envir->{imagegen}->render(
160 refresh => $translationOptions->{refreshMath2img},
161 %mtimeOption,
162 );
163 }
164
165 my ($result, $state); # we'll need these on the other side of the if block!
166 if ($translationOptions->{processAnswers}) {
167
168 # process student answers
169 #warn "PG: processing student answers\n";
170 $translator->process_answers($formFields);
171
172 # retrieve the problem state and give it to the translator
173 #warn "PG: retrieving the problem state and giving it to the translator\n";
174 $translator->rh_problem_state({
175 recorded_score => $problem->status,
176 num_of_correct_ans => $problem->num_correct,
177 num_of_incorrect_ans => $problem->num_incorrect,
178 });
179
180 # determine an entry order -- the ANSWER_ENTRY_ORDER flag is built by
181 # the PG macro package (PG.pl)
182 #warn "PG: determining an entry order\n";
183 my @answerOrder =
184 $translator->rh_flags->{ANSWER_ENTRY_ORDER}
185 ? @{ $translator->rh_flags->{ANSWER_ENTRY_ORDER} }
186 : keys %{ $translator->rh_evaluated_answers };
187
188 # install a grader -- use the one specified in the problem,
189 # or fall back on the default from the course environment.
190 # (two magic strings are accepted, to avoid having to
191 # reference code when it would be difficult.)
192 #warn "PG: installing a grader\n";
193 my $grader = $translator->rh_flags->{PROBLEM_GRADER_TO_USE}
194 || $courseEnv->{pg}->{options}->{grader};
195 $grader = $translator->rf_std_problem_grader
196 if $grader eq "std_problem_grader";
197 $grader = $translator->rf_avg_problem_grader
198 if $grader eq "avg_problem_grader";
199 die "Problem grader $grader is not a CODE reference."
200 unless ref $grader eq "CODE";
201 $translator->rf_problem_grader($grader);
202
203 # grade the problem
204 #warn "PG: grading the problem\n";
205 ($result, $state) = $translator->grade_problem(
206 answers_submitted => $translationOptions->{processAnswers},
207 ANSWER_ENTRY_ORDER => \@answerOrder,
208 );
209
210 }
211
212 # write timing log entry
213 writeTimingLogEntry($courseEnv, "WeBWorK::PG::new", "", "end");
214
215 # return an object which contains the translator and the results of
216 # the translation process. this is DIFFERENT from the "format expected
217 # by Webwork.pm (and I believe processProblem8, but check.)"
218 return bless {
219 translator => $translator,
220 head_text => ${ $translator->r_header },
221 body_text => ${ $translator->r_text },
222 answers => $translator->rh_evaluated_answers,
223 result => $result,
224 state => $state,
225 errors => $translator->errors,
226 warnings => $warnings,
227 flags => $translator->rh_flags,
228 }, $class;
229}
230
231# -----
232
233sub defineProblemEnvir($$$$$$$) {
234 my (
235 $courseEnv,
236 $user, 47 $user,
237 $key, 48 $key,
238 $set, 49 $set,
239 $problem, 50 $problem,
240 $psvn, 51 $psvn,
… …
252 63
253 # Vital state information 64 # Vital state information
254 # ADDED: displayHintsQ, displaySolutionsQ, refreshMath2img, 65 # ADDED: displayHintsQ, displaySolutionsQ, refreshMath2img,
255 # texDisposition 66 # texDisposition
256 67
257 $envir{psvn} = $psvn; 68 $envir{psvn} = $set->psvn;
258 $envir{psvnNumber} = $envir{psvn}; 69 $envir{psvnNumber} = $envir{psvn};
259 $envir{probNum} = $problem->problem_id; 70 $envir{probNum} = $problem->problem_id;
260 $envir{questionNumber} = $envir{probNum}; 71 $envir{questionNumber} = $envir{probNum};
261 $envir{fileName} = $problem->source_file; 72 $envir{fileName} = $problem->source_file;
262 $envir{probFileName} = $envir{fileName}; 73 $envir{probFileName} = $envir{fileName};
263 $envir{problemSeed} = (defined($options->{override_seed}) ) ? $options->{override_seed} :$problem->problem_seed; 74 $envir{problemSeed} = $problem->problem_seed;
264 $envir{displayMode} = translateDisplayModeNames($options->{displayMode}); 75 $envir{displayMode} = translateDisplayModeNames($options->{displayMode});
265 $envir{languageMode} = $envir{displayMode}; 76 $envir{languageMode} = $envir{displayMode};
266 $envir{outputMode} = $envir{displayMode}; 77 $envir{outputMode} = $envir{displayMode};
267 $envir{displayHintsQ} = $options->{showHints}; 78 $envir{displayHintsQ} = $options->{showHints};
268 $envir{displaySolutionsQ} = $options->{showSolutions}; 79 $envir{displaySolutionsQ} = $options->{showSolutions};
269 # FIXME: this is HTML_img specific
270 #$envir{refreshMath2img} = $options->{refreshMath2img};
271 $envir{texDisposition} = "pdf"; # in webwork-modperl, we use pdflatex 80 $envir{texDisposition} = "pdf"; # in webwork2, we use pdflatex
272 81
273 # Problem Information 82 # Problem Information
274 # ADDED: courseName, formatedDueDate 83 # ADDED: courseName, formatedDueDate
275 84
276 $envir{openDate} = $set->open_date; 85 $envir{openDate} = $set->open_date;
… …
281 $envir{answerDate} = $set->answer_date; 90 $envir{answerDate} = $set->answer_date;
282 $envir{formattedAnswerDate} = formatDateTime($envir{answerDate}); 91 $envir{formattedAnswerDate} = formatDateTime($envir{answerDate});
283 $envir{numOfAttempts} = ($problem->num_correct || 0) + ($problem->num_incorrect || 0); 92 $envir{numOfAttempts} = ($problem->num_correct || 0) + ($problem->num_incorrect || 0);
284 $envir{problemValue} = $problem->value; 93 $envir{problemValue} = $problem->value;
285 $envir{sessionKey} = $key; 94 $envir{sessionKey} = $key;
286 $envir{courseName} = $courseEnv->{courseName}; 95 $envir{courseName} = $ce->{courseName};
287 96
288 # Student Information 97 # Student Information
289 # ADDED: studentID 98 # ADDED: studentID
290 99
291 $envir{sectionName} = $user->section; 100 $envir{sectionName} = $user->section;
… …
304 113
305 # External Programs 114 # External Programs
306 # ADDED: externalLaTeXPath, externalDvipngPath, 115 # ADDED: externalLaTeXPath, externalDvipngPath,
307 # externalGif2EpsPath, externalPng2EpsPath 116 # externalGif2EpsPath, externalPng2EpsPath
308 117
309 $envir{externalTTHPath} = $courseEnv->{externalPrograms}->{tth}; 118 $envir{externalTTHPath} = $ce->{externalPrograms}->{tth};
310 $envir{externalLaTeXPath} = $courseEnv->{externalPrograms}->{latex}; 119 $envir{externalLaTeXPath} = $ce->{externalPrograms}->{latex};
311 $envir{externalDvipngPath} = $courseEnv->{externalPrograms}->{dvipng}; 120 $envir{externalDvipngPath} = $ce->{externalPrograms}->{dvipng};
312 $envir{externalGif2EpsPath} = $courseEnv->{externalPrograms}->{gif2eps}; 121 $envir{externalGif2EpsPath} = $ce->{externalPrograms}->{gif2eps};
313 $envir{externalPng2EpsPath} = $courseEnv->{externalPrograms}->{png2eps}; 122 $envir{externalPng2EpsPath} = $ce->{externalPrograms}->{png2eps};
314 $envir{externalGif2PngPath} = $courseEnv->{externalPrograms}->{gif2png}; 123 $envir{externalGif2PngPath} = $ce->{externalPrograms}->{gif2png};
315 124
316 # Directories and URLs 125 # Directories and URLs
317 # REMOVED: courseName 126 # REMOVED: courseName
318 # ADDED: dvipngTempDir 127 # ADDED: dvipngTempDir
319 128
320 $envir{cgiDirectory} = undef; 129 $envir{cgiDirectory} = undef;
321 $envir{cgiURL} = undef; 130 $envir{cgiURL} = undef;
322 $envir{classDirectory} = undef; 131 $envir{classDirectory} = undef;
323 $envir{courseScriptsDirectory} = $courseEnv->{webworkDirs}->{macros}."/"; 132 $envir{courseScriptsDirectory} = $ce->{pg}->{directories}->{macros}."/";
324 $envir{htmlDirectory} = $courseEnv->{courseDirs}->{html}."/"; 133 $envir{htmlDirectory} = $ce->{courseDirs}->{html}."/";
325 $envir{htmlURL} = $courseEnv->{courseURLs}->{html}."/"; 134 $envir{htmlURL} = $ce->{courseURLs}->{html}."/";
326 $envir{macroDirectory} = $courseEnv->{courseDirs}->{macros}."/"; 135 $envir{macroDirectory} = $ce->{courseDirs}->{macros}."/";
327 $envir{templateDirectory} = $courseEnv->{courseDirs}->{templates}."/"; 136 $envir{templateDirectory} = $ce->{courseDirs}->{templates}."/";
328 $envir{tempDirectory} = $courseEnv->{courseDirs}->{html_temp}."/"; 137 $envir{tempDirectory} = $ce->{courseDirs}->{html_temp}."/";
329 $envir{tempURL} = $courseEnv->{courseURLs}->{html_temp}."/"; 138 $envir{tempURL} = $ce->{courseURLs}->{html_temp}."/";
330 $envir{scriptDirectory} = undef; 139 $envir{scriptDirectory} = undef;
331 $envir{webworkDocsURL} = $courseEnv->{webworkURLs}->{docs}."/"; 140 $envir{webworkDocsURL} = $ce->{webworkURLs}->{docs}."/";
332 # FIXME: this is HTML_img mode-specific
333 #$envir{dvipngTempDir} = $options->{displayMode} eq 'images'
334 # ? makeTempDirectory($envir{tempDirectory}, "webwork-dvipng")
335 # : undef;
336 141
337 # Information for sending mail 142 # Information for sending mail
338 143
339 $envir{mailSmtpServer} = $courseEnv->{mail}->{smtpServer}; 144 $envir{mailSmtpServer} = $ce->{mail}->{smtpServer};
340 $envir{mailSmtpSender} = $courseEnv->{mail}->{smtpSender}; 145 $envir{mailSmtpSender} = $ce->{mail}->{smtpSender};
341 $envir{ALLOW_MAIL_TO} = $courseEnv->{mail}->{allowedRecipients}; 146 $envir{ALLOW_MAIL_TO} = $ce->{mail}->{allowedRecipients};
342 147
343 # Default values for evaluating answers 148 # Default values for evaluating answers
344 149
345 my $ansEvalDefaults = $courseEnv->{pg}->{ansEvalDefaults}; 150 my $ansEvalDefaults = $ce->{pg}->{ansEvalDefaults};
346 $envir{$_} = $ansEvalDefaults->{$_} foreach (keys %$ansEvalDefaults); 151 $envir{$_} = $ansEvalDefaults->{$_} foreach (keys %$ansEvalDefaults);
347 152
348 # ---------------------------------------------------------------------- 153 # ----------------------------------------------------------------------
349 154
155 my $basename = "equation-$envir{psvn}.$envir{probNum}";
156 $basename .= ".$envir{problemSeed}" if $envir{problemSeed};
157
350 # Object for generating equation images 158 # Object for generating equation images
351 $envir{imagegen} = WeBWorK::PG::ImageGenerator->new( 159 $envir{imagegen} = WeBWorK::PG::ImageGenerator->new(
352 tempDir => $courseEnv->{webworkDirs}->{tmp}, # global temp dir 160 tempDir => $ce->{webworkDirs}->{tmp}, # global temp dir
353 dir => $envir{tempDirectory},
354 url => $envir{tempURL},
355 #basename => "$envir{studentLogin}.$envir{setNumber}.$envir{probNum}",
356 basename => "equation-$envir{psvn}.$envir{probNum}.$envir{problemSeed}",
357 latex => $envir{externalLaTeXPath}, 161 latex => $envir{externalLaTeXPath},
358 dvipng => $envir{externalDvipngPath}, 162 dvipng => $envir{externalDvipngPath},
163 useCache => 1,
164 cacheDir => $ce->{webworkDirs}->{equationCache},
165 cacheURL => $ce->{webworkURLs}->{equationCache},
166 cacheDB => $ce->{webworkFiles}->{equationCacheDB},
359 ); 167 );
360 168
361 # Other things... 169 # Other things...
362 $envir{QUIZ_PREFIX} = $options->{QUIZ_PREFIX}; # used by quizzes 170 $envir{QUIZ_PREFIX} = $options->{QUIZ_PREFIX}; # used by quizzes
363 $envir{PROBLEM_GRADER_TO_USE} = $courseEnv->{pg}->{options}->{grader}; 171 $envir{PROBLEM_GRADER_TO_USE} = $ce->{pg}->{options}->{grader};
364 $envir{PRINT_FILE_NAMES_FOR} = $courseEnv->{pg}->{specialPGEnvironmentVars}->{PRINT_FILE_NAMES_FOR}; 172 $envir{PRINT_FILE_NAMES_FOR} = $ce->{pg}->{specialPGEnvironmentVars}->{PRINT_FILE_NAMES_FOR};
365 173
366 # variables for interpreting capa problems. 174 # variables for interpreting capa problems.
367 $envir{CAPA_Tools} = $courseEnv->{pg}->{specialPGEnvironmentVars}->{CAPA_Tools}; 175 $envir{CAPA_Tools} = $ce->{pg}->{specialPGEnvironmentVars}->{CAPA_Tools};
368 $envir{CAPA_MCTools} = $courseEnv->{pg}->{specialPGEnvironmentVars}->{CAPA_MCTools}; 176 $envir{CAPA_MCTools} = $ce->{pg}->{specialPGEnvironmentVars}->{CAPA_MCTools};
369 $envir{CAPA_Graphics_URL} = $courseEnv->{pg}->{specialPGEnvironmentVars}->{CAPA_Graphics_URL}; 177 $envir{CAPA_Graphics_URL} = $ce->{pg}->{specialPGEnvironmentVars}->{CAPA_Graphics_URL};
370 $envir{CAPA_GraphicsDirectory} = $courseEnv->{pg}->{specialPGEnvironmentVars}->{CAPA_GraphicsDirectory}; 178 $envir{CAPA_GraphicsDirectory} = $ce->{pg}->{specialPGEnvironmentVars}->{CAPA_GraphicsDirectory};
371 179
372 return \%envir; 180 return \%envir;
373} 181}
374 182
375sub translateDisplayModeNames($) { 183sub translateDisplayModeNames($) {
… …
380 formattedText => "HTML_tth", 188 formattedText => "HTML_tth",
381 images => "HTML_dpng", # "HTML_img", 189 images => "HTML_dpng", # "HTML_img",
382 }->{$name}; 190 }->{$name};
383} 191}
384 192
385sub safetyFilter { 193sub oldSafetyFilter {
386 my $answer = shift; # accepts one answer and checks it 194 my $answer = shift; # accepts one answer and checks it
387 my $submittedAnswer = $answer; 195 my $submittedAnswer = $answer;
388 $answer = '' unless defined $answer; 196 $answer = '' unless defined $answer;
389 my ($errorno); 197 my ($errorno);
390 $answer =~ tr/\000-\037/ /; 198 $answer =~ tr/\000-\037/ /;
… …
404 } 212 }
405 $errorno = 0; 213 $errorno = 0;
406 return($answer, $errorno); 214 return($answer, $errorno);
407} 215}
408 216
217sub nullSafetyFilter {
218 return shift, 0; # no errors
219}
220
4091; 2211;
410 222
411__END__ 223__END__
412 224
413=head1 SYNOPSIS 225=head1 SYNOPSIS
414 226
415 $pg = WeBWorK::PG->new( 227 $pg = WeBWorK::PG->new(
416 $courseEnv, # a WeBWorK::CourseEnvironment object 228 $ce, # a WeBWorK::CourseEnvironment object
417 $user, # a WeBWorK::DB::Record::User object 229 $user, # a WeBWorK::DB::Record::User object
418 $sessionKey, 230 $sessionKey,
419 $set, # a WeBWorK::DB::Record::UserSet object 231 $set, # a WeBWorK::DB::Record::UserSet object
420 $problem, # a WeBWorK::DB::Record::UserProblem object 232 $problem, # a WeBWorK::DB::Record::UserProblem object
421 $psvn, 233 $psvn,
… …
439 $warnings = $pg->{warnings}; # text string 251 $warnings = $pg->{warnings}; # text string
440 $flags = $pg->{flags}; # hash reference 252 $flags = $pg->{flags}; # hash reference
441 253
442=head1 DESCRIPTION 254=head1 DESCRIPTION
443 255
444WeBWorK::PG encapsulates the PG translation process, making multiple calls to 256WeBWorK::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, 257modules which use this API (and exist) are WeBWorK::PG::Local and
446instead making choices that are appropriate for the webwork-modperl system. 258WeBWorK::PG::Remote. The course environment key $pg{renderer} is consulted to
259determine which render to use.
447 260
448=head1 CONSTRUCTION 261=head1 THE WEBWORK::PG API
262
263Modules which support this API must implement the following method:
449 264
450=over 265=over
451 266
452=item new (ENVIRONMENT, USER, KEY, SET, PROBLEM, PSVN, FIELDS, OPTIONS) 267=item new ENVIRONMENT, USER, KEY, SET, PROBLEM, PSVN, FIELDS, OPTIONS
453 268
454The C<new> method creates a translator, initializes it using the parameters 269The C<new> method creates a translator, initializes it using the parameters
455specified, translates a PG file, and processes answers. It returns a reference 270specified, translates a PG file, and processes answers. It returns a reference
456to a blessed hash containing the results of the translation process. 271to a blessed hash containing the results of the translation process.
457 272
… …
513boolean, render solutions 328boolean, render solutions
514 329
515=item refreshMath2img 330=item refreshMath2img
516 331
517boolean, force images created by math2img (in "images" mode) to be recreated, 332boolean, 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 333even if the PG source has not been updated. FIXME: remove this option.
519option to "refreshEquations" and update the docs accordingly.
520 334
521=item processAnswers 335=item processAnswers
522 336
523boolean, call answer evaluators and graders 337boolean, call answer evaluators and graders
524 338
… …
572 386
573A hash containing PG_flags (see the Translator docs). 387A hash containing PG_flags (see the Translator docs).
574 388
575=back 389=back
576 390
577=head1 OPERATION 391=head1 METHODS PROVIDED BY THE BASE CLASS
578 392
579WeBWorK::PG goes through the following operations when constructed: 393The following methods are provided for use by subclasses of WeBWorK::PG.
580 394
581=over 395=over
582 396
583=item Get database information 397=item defineProblemEnvir ENVIRONMENT, USER, KEY, SET, PROBLEM, PSVN, FIELDS, OPTIONS
584 398
585Retrieve information about the current user, set, and problem from the 399Generate a problem environment hash to pass to the renderer.
586database.
587 400
588=item Create a translator 401=item translateDisplayModeNames NAME
589 402
590Instantiate a WeBWorK::PG::Translator object. 403NAME 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 404
656=back 405=back
657 406
658=head1 AUTHOR 407=head1 AUTHOR
659 408
Legend:
Removed from v.1154  
changed lines
  Added in v.1703
aubreyja at gmail dot com
 ViewVC Help
Powered by ViewVC 1.0.9