[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 414 Revision 4091
1################################################################################
2# WeBWorK Online Homework Delivery System
3# Copyright © 2000-2006 The WeBWorK Project, http://openwebwork.sf.net/
4# $CVSHeader: webwork-modperl/lib/WeBWorK/PG.pm,v 1.63 2006/01/25 23:13:51 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.
15################################################################################
16
1package WeBWork::PG; 17package WeBWorK::PG;
2 18
3# hide PG::* from the not-yet-insane. 19=head1 NAME
20
21WeBWorK::PG - Invoke one of several PG rendering methods using an easy-to-use
22API.
23
24=cut
4 25
5use strict; 26use strict;
6use warnings; 27use warnings;
7use WeBWorK::Utils qw(readFile formatDateTime);
8use WeBWorK::DB::Classlist;
9use WeBWorK::DB::WW;
10use WeBWorK::PG::Translator; 28use WeBWorK::PG::ImageGenerator;
29use WeBWorK::Utils qw(runtime_use formatDateTime makeTempDirectory);
11 30
12use base qw(Exporter); 31use constant DISPLAY_MODES => {
13our @EXPORT = qw(init_translator); 32 # display name # mode name
14our @EXPORT_OK = qw(); 33 tex => "TeX",
34 plainText => "HTML",
35 formattedText => "HTML_tth",
36 images => "HTML_dpng",
37 jsMath => "HTML_jsMath",
38 asciimath => "HTML_asciimath",
39};
15 40
16sub init_translator($$$$$) { 41sub new {
17 my $courseEnv = shift; 42 shift; # throw away invocant -- we don't need it
18 my $userName = shift; 43 my ($ce, $user, $key, $set, $problem, $psvn, $formFields,
19 my $setName = shift; 44 $translationOptions) = @_;
20 my $problemNumber = shift;
21 my $formData = shift;
22 45
23 # get database information 46 my $renderer = $ce->{pg}->{renderer};
24 my $classlist = WeBWorK::DB::Classlist->new($courseEnv);
25 my $wwdb = WeBWorK::DB::WW->new($courseEnv);
26 my $user = $classlist->getUser($userName);
27 my $set = $wwdb->getSet($userName, $setName);
28 my $problem = $wwdb->getProblem($userName, $setName, $problemNumber);
29 my $psvn = $wwdb->getPSVN($userName, $setName);
30 47
31 # create a Translator 48 runtime_use $renderer;
32 my $translator = WeBWorK::PG::Translator->new;
33 49
34 # give it a directory hash 50 return $renderer->new(@_);
35 $translator->rh_directories({
36 courseScriptsDirectory => $courseEnv->{webworkDirs}->{macros},
37 macroDirectory => $courseEnv->{courseDirs}->{macros},
38 templateDirectory => $courseEnv->{courseDirs}->{templates},
39 tempDirectory => $courseEnv->{courseDirs}->{html_temp},
40 });
41
42 # give it modules to evaluate
43 # give it "extra packages" to load
44 my $modules = $courseEnv->{pg}->{modules};
45 foreach $module (keys %$modules) {
46 my $main_package_loaded = 0;
47 foreach $package (@{$modules->{$module}}) {
48 if ($package eq $module) {
49 # this is the main package
50 $translator->evaluate_modules($package);
51 $main_package_loaded = 1;
52 } else {
53 # this is an "extra" package
54 if ($main_package_loaded) {
55 $translator->load_extra_packages($package);
56 } else {
57 warn "Can't load extra package $package: module $module hasn't been evaluated.";
58 }
59
60 }
61 }
62 }
63
64 # give it an environment (from defineProblemEnvir)
65 $translator->environment(
66 defineProblemEnvir($courseEnv, $user, $set, $problem, $psvn, $formData)
67 );
68
69 # initialize it
70 $translator->initialize();
71
72 # have it "unrestricted load" PG.pl and dangerousMacros.pl
73 my $pg_pl = $courseEnv->{webworkDirs}->{macros} . "/PG.pl";
74 my $dangerousMacros_pl = $courseEnv->{webworkDirs}->{macros} . "/dangerousMacros.pl"
75 my $err = $translator->unrestricted_load($pg_pl);
76 warn "Error while loading $pg_pl: $err" if $err;
77 $err = $translator->unrestricted_load($dangerousMacros_pl);
78 warn "Error while loading $dangerousMacros_pl: $err" if $err;
79
80 # give it an opcode mask (using default values)
81 $translator->set_mask();
82
83 # give it the problem source
84 my $sourceFile = $courseEnv->{courseDirs}->{templates}."/".$problem->source_file;
85 $translator->source_string(readFile($sourceFile));
86
87 # install a safety filter (&safetyFilter)
88 $translator->rf_safety_filter(\&safetyFilter);
89
90 # return the translator
91 return $translator;
92} 51}
93 52
94# -----
95
96sub defineProblemEnvir($$$$$$) { 53sub defineProblemEnvir {
97 my $courseEnv = shift; 54 my (
98 my $user = shift; 55 $self,
99 my $set = shift; 56 $ce,
100 my $problem = shift; 57 $user,
101 my $psvn = shift; 58 $key,
102 my $form = shift; 59 $set,
60 $problem,
61 $psvn,
62 $formFields,
63 $options,
64 ) = @_;
103 65
104 my %envir; 66 my %envir;
67
68 # ----------------------------------------------------------------------
105 69
106 # PG environment variables 70 # PG environment variables
107 # from docs/pglanguage/pgreference/environmentvariables as of 06/25/2002 71 # from docs/pglanguage/pgreference/environmentvariables as of 06/25/2002
108 # any changes are noted by "ADDED:" or "REMOVED:" 72 # any changes are noted by "ADDED:" or "REMOVED:"
109 73
110 # Vital state information 74 # Vital state information
111 # ADDED: displayHintsQ, displaySolutionsQ, externalTTHPath 75 # ADDED: displayModeFailover, displayHintsQ, displaySolutionsQ,
76 # refreshMath2img, texDisposition
112 77
113 $envir{psvn} = $psvn; 78 $envir{psvn} = $set->psvn;
114 $envir{psvnNumber} = $envir{psvn}; 79 $envir{psvnNumber} = $envir{psvn};
115 $envir{probNum} = $problem->id; 80 $envir{probNum} = $problem->problem_id;
116 $envir{questionNumber} = $envir{probNum}; 81 $envir{questionNumber} = $envir{probNum};
117 $envir{fileName} = $problem->source_file; 82 $envir{fileName} = $problem->source_file;
118 $envir{probFileName} = $envir{fileName}; 83 $envir{probFileName} = $envir{fileName};
119 $envir{problemSeed} = $problem->problem_seed; 84 $envir{problemSeed} = $problem->problem_seed;
120 $envir{displayMode} = $form->param('Mode'); 85 $envir{displayMode} = translateDisplayModeNames($options->{displayMode});
121 $envir{languageMode} = $envir{displayMode}; 86 $envir{languageMode} = $envir{displayMode};
122 $envir{outputMode} = $envir{displayMode}; 87 $envir{outputMode} = $envir{displayMode};
123 $envir{displayHintsQ} = $form->param('ShowHint'); 88 $envir{displayHintsQ} = $options->{showHints};
124 $envir{displaySolutionsQ} = $form->param('ShowSol'); 89 $envir{displaySolutionsQ} = $options->{showSolutions};
125 $envir{externalTTHPath} = $courseEnv->{externalPrograms}->{tth}; 90 $envir{texDisposition} = "pdf"; # in webwork2, we use pdflatex
126 91
127 # Problem Information 92 # Problem Information
128 # ADDED: courseName 93 # ADDED: courseName, formatedDueDate
129 94
130 $envir{openDate} = $set->open_date; 95 $envir{openDate} = $set->open_date;
131 $envir{formattedOpenDate} = formatDateTime $envir{openDate}; 96 $envir{formattedOpenDate} = formatDateTime($envir{openDate}, $ce->{siteDefaults}{timezone});
132 $envir{dueDate} = $set->due_date; 97 $envir{dueDate} = $set->due_date;
133 $envir{formattedDueDate} = formatDateTime $envir{dueDate}; 98 $envir{formattedDueDate} = formatDateTime($envir{dueDate}, $ce->{siteDefaults}{timezone});
99 $envir{formatedDueDate} = $envir{formattedDueDate}; # typo in many header files
134 $envir{answerDate} = $set->answer_date; 100 $envir{answerDate} = $set->answer_date;
135 $envir{formattedAnswerDate} = formatDateTime $envir{answerDate}; 101 $envir{formattedAnswerDate} = formatDateTime($envir{answerDate}, $ce->{siteDefaults}{timezone});
136 $envir{numOfAttempts} = $problem->num_correct + $problem->num_incorrect; 102 $envir{numOfAttempts} = ($problem->num_correct || 0) + ($problem->num_incorrect || 0);
137 $envir{problemValue} = $problem->value; 103 $envir{problemValue} = $problem->value;
138 $envir{sessionKey} = $form->param('key'); 104 $envir{sessionKey} = $key;
139 $envir{courseName} = $courseEnv->{courseName}; 105 $envir{courseName} = $ce->{courseName};
140 106
141 # Student Information 107 # Student Information
142 # ADDED: studentID 108 # ADDED: studentID
143 109
144 $envir{sectionName} = $user->section; 110 $envir{sectionName} = $user->section;
145 $envir{sectionNumber} = $envir{sectionName}; 111 $envir{sectionNumber} = $envir{sectionName};
146 $envir{recitationName} = $user->recitation; 112 $envir{recitationName} = $user->recitation;
147 $envir{recitationNumber} = $envir{recitationName}; 113 $envir{recitationNumber} = $envir{recitationName};
148 $envir{setNumber} = $set->id; 114 $envir{setNumber} = $set->set_id;
149 $envir{studentLogin} = $user->id; 115 $envir{studentLogin} = $user->user_id;
150 $envir{studentName} = $user->first_name . " " . $user->last_name; 116 $envir{studentName} = $user->first_name . " " . $user->last_name;
151 $envir{studentID} = $user->student_id 117 $envir{studentID} = $user->student_id;
152 118
153 # Answer Information 119 # Answer Information
120 # REMOVED: refSubmittedAnswers
154 121
155 $envir{inputs_ref} = {}; # *** keys like "Answer1" 122 $envir{inputs_ref} = $formFields;
156 $envir{refSubmittedAnswers} = {}; # *** keys like "AnSwEr1"
157 123
158 # Default values for evaluating answers 124 # External Programs
125 # ADDED: externalLaTeXPath, externalDvipngPath,
126 # externalGif2EpsPath, externalPng2EpsPath
159 127
160 my $ansEvalDefaults = $courseEnv->{pg}->{ansEvalDefaults}; 128 $envir{externalTTHPath} = $ce->{externalPrograms}->{tth};
161 $envir{$_} = $ansEvalDefaults->{$_} foreach (keys %$ansEvalDefaults); 129 $envir{externalLaTeXPath} = $ce->{externalPrograms}->{latex};
130 $envir{externalDvipngPath} = $ce->{externalPrograms}->{dvipng};
131 $envir{externalGif2EpsPath} = $ce->{externalPrograms}->{gif2eps};
132 $envir{externalPng2EpsPath} = $ce->{externalPrograms}->{png2eps};
133 $envir{externalGif2PngPath} = $ce->{externalPrograms}->{gif2png};
162 134
163 # Directories and URLs 135 # Directories and URLs
164 # REMOVED: courseName 136 # REMOVED: courseName
137 # ADDED: dvipngTempDir
138 # ADDED: jsMathURL
139 # ADDED: asciimathURL
140 # ADDED: macrosPath
141 # REMOVED: macrosDirectory, courseScriptsDirectory
165 142
166 $envir{cgiDirectory} = undef; 143 $envir{cgiDirectory} = undef;
167 $envir{cgiURL} = undef; 144 $envir{cgiURL} = undef;
168 $envir{classDirectory} = undef; 145 $envir{classDirectory} = undef;
169 $envir{courseScriptsDirectory} = $courseEnv->{webworkDirs}->{macros}; 146 $envir{macrosPath} = $ce->{pg}->{directories}{macrosPath};
147 $envir{appletDirs} = $ce->{pg}->{directories}{appletDirs};
170 $envir{htmlDirectory} = $courseEnv->{courseDirs}->{html}; 148 $envir{htmlDirectory} = $ce->{courseDirs}->{html}."/";
171 $envir{htmlURL} = $courseEnv->{courseURLs}->{html}; 149 $envir{htmlURL} = $ce->{courseURLs}->{html}."/";
172 $envir{macroDirectory} = $courseEnv->{courseDirs}->{macros};
173 $envir{templateDirectory} = $courseEnv->{courseDirs}->{templates}; 150 $envir{templateDirectory} = $ce->{courseDirs}->{templates}."/";
174 $envir{tempDirectory} = $courseEnv->{courseDirs}->{html_temp}; 151 $envir{tempDirectory} = $ce->{courseDirs}->{html_temp}."/";
175 $envir{tempURL} = $courseEnv->{courseURLs}->{html_temp}; 152 $envir{tempURL} = $ce->{courseURLs}->{html_temp}."/";
176 $envir{scriptDirectory} = undef; 153 $envir{scriptDirectory} = undef;
177 $envir{webworkDocsURL} = $courseEnv->{webworkURLs}->{docs}; 154 $envir{webworkDocsURL} = $ce->{webworkURLs}->{docs}."/";
155 $envir{localHelpURL} = $ce->{webworkURLs}->{local_help}."/";
156 $envir{jsMathURL} = $ce->{webworkURLs}->{jsMath};
157 $envir{asciimathURL} = $ce->{webworkURLs}->{asciimath};
158
159 # Information for sending mail
160
161 $envir{mailSmtpServer} = $ce->{mail}->{smtpServer};
162 $envir{mailSmtpSender} = $ce->{mail}->{smtpSender};
163 $envir{ALLOW_MAIL_TO} = $ce->{mail}->{allowedRecipients};
164
165 # Default values for evaluating answers
166
167 my $ansEvalDefaults = $ce->{pg}->{ansEvalDefaults};
168 $envir{$_} = $ansEvalDefaults->{$_} foreach (keys %$ansEvalDefaults);
169
170 # ----------------------------------------------------------------------
171
172 my $basename = "equation-$envir{psvn}.$envir{probNum}";
173 $basename .= ".$envir{problemSeed}" if $envir{problemSeed};
174
175 # to make grabbing these options easier, we'll pull them out now...
176 my %imagesModeOptions = %{$ce->{pg}->{displayModeOptions}->{images}};
177
178 # Object for generating equation images
179 $envir{imagegen} = WeBWorK::PG::ImageGenerator->new(
180 tempDir => $ce->{webworkDirs}->{tmp}, # global temp dir
181 latex => $envir{externalLaTeXPath},
182 dvipng => $envir{externalDvipngPath},
183 useCache => 1,
184 cacheDir => $ce->{webworkDirs}->{equationCache},
185 cacheURL => $ce->{webworkURLs}->{equationCache},
186 cacheDB => $ce->{webworkFiles}->{equationCacheDB},
187 useMarkers => ($imagesModeOptions{dvipng_align} && $imagesModeOptions{dvipng_align} eq 'mysql'),
188 dvipng_align => $imagesModeOptions{dvipng_align},
189 dvipng_depth_db => $imagesModeOptions{dvipng_depth_db},
190 );
191
192 # ADDED: jsMath options
193 $envir{jsMath} = {%{$ce->{pg}{displayModeOptions}{jsMath}}};
194
195 # Other things...
196 $envir{QUIZ_PREFIX} = $options->{QUIZ_PREFIX}; # used by quizzes
197 $envir{PROBLEM_GRADER_TO_USE} = $ce->{pg}->{options}->{grader};
198 $envir{PRINT_FILE_NAMES_FOR} = $ce->{pg}->{specialPGEnvironmentVars}->{PRINT_FILE_NAMES_FOR};
199
200 # ADDED: __files__
201 # an array for mapping (eval nnn) to filenames in error messages
202 $envir{__files__} = {
203 root => $ce->{webworkDirs}{root}, # used to shorten filenames
204 pg => $ce->{pg}{directories}{root}, # ditto
205 tmpl => $ce->{courseDirs}{templates}, # ditto
206 };
207
208 # variables for interpreting capa problems and other things to be
209 # seen in a pg file
210 my $specialPGEnvironmentVarHash = $ce->{pg}->{specialPGEnvironmentVars};
211 for my $SPGEV (keys %{$specialPGEnvironmentVarHash}) {
212 $envir{$SPGEV} = $specialPGEnvironmentVarHash->{$SPGEV};
213 }
178 214
179 return \%envir; 215 return \%envir;
180} 216}
181 217
218sub translateDisplayModeNames($) {
219 my $name = shift;
220 return DISPLAY_MODES()->{$name};
221}
222
182sub safetyFilter { 223sub oldSafetyFilter {
183 my $answer = shift; # accepts one answer and checks it 224 my $answer = shift; # accepts one answer and checks it
184 my $submittedAnswer = $answer; 225 my $submittedAnswer = $answer;
185 $answer = '' unless defined $answer; 226 $answer = '' unless defined $answer;
186 my ($errorno); 227 my ($errorno);
187 $answer =~ tr/\000-\037/ /; 228 $answer =~ tr/\000-\037/ /;
188 # Return if answer field is empty 229 # Return if answer field is empty
… …
191 $errorno = 0; ## don't report blank answer as error 232 $errorno = 0; ## don't report blank answer as error
192 return ($answer,$errorno); 233 return ($answer,$errorno);
193 } 234 }
194 # replace ^ with ** (for exponentiation) 235 # replace ^ with ** (for exponentiation)
195 # $answer =~ s/\^/**/g; 236 # $answer =~ s/\^/**/g;
196 # Return if forbidden characters are found 237 # Return if forbidden characters are found
197 unless ($answer =~ /^[a-zA-Z0-9_\-\+ \t\/@%\*\.\n^\(\)]+$/ ) { 238 unless ($answer =~ /^[a-zA-Z0-9_\-\+ \t\/@%\*\.\n^\[\]\(\)\,\|]+$/ ) {
198 $answer =~ tr/a-zA-Z0-9_\-\+ \t\/@%\*\.\n^\(\)/#/c; 239 $answer =~ tr/a-zA-Z0-9_\-\+ \t\/@%\*\.\n^\(\)/#/c;
199 $errorno = "<BR>There are forbidden characters in your answer: $submittedAnswer<BR>"; 240 $errorno = "<BR>There are forbidden characters in your answer: $submittedAnswer<BR>";
200 return ($answer,$errorno); 241 return ($answer,$errorno);
201 } 242 }
202 $errorno = 0; 243 $errorno = 0;
203 return($answer, $errorno); 244 return($answer, $errorno);
204} 245}
205 246
247sub nullSafetyFilter {
248 return shift, 0; # no errors
249}
250
2061; 2511;
252
253__END__
254
255=head1 SYNOPSIS
256
257 $pg = WeBWorK::PG->new(
258 $ce, # a WeBWorK::CourseEnvironment object
259 $user, # a WeBWorK::DB::Record::User object
260 $sessionKey,
261 $set, # a WeBWorK::DB::Record::UserSet object
262 $problem, # a WeBWorK::DB::Record::UserProblem object
263 $psvn,
264 $formFields # in &WeBWorK::Form::Vars format
265 { # translation options
266 displayMode => "images", # (plainText|formattedText|images)
267 showHints => 1, # (0|1)
268 showSolutions => 0, # (0|1)
269 refreshMath2img => 0, # (0|1)
270 processAnswers => 1, # (0|1)
271 },
272 );
273
274 $translator = $pg->{translator}; # WeBWorK::PG::Translator
275 $body = $pg->{body_text}; # text string
276 $header = $pg->{head_text}; # text string
277 $answerHash = $pg->{answers}; # WeBWorK::PG::AnswerHash
278 $result = $pg->{result}; # hash reference
279 $state = $pg->{state}; # hash reference
280 $errors = $pg->{errors}; # text string
281 $warnings = $pg->{warnings}; # text string
282 $flags = $pg->{flags}; # hash reference
283
284=head1 DESCRIPTION
285
286WeBWorK::PG is a factory for modules which use the WeBWorK::PG API. Notable
287modules which use this API (and exist) are WeBWorK::PG::Local and
288WeBWorK::PG::Remote. The course environment key $pg{renderer} is consulted to
289determine which render to use.
290
291=head1 THE WEBWORK::PG API
292
293Modules which support this API must implement the following method:
294
295=over
296
297=item new ENVIRONMENT, USER, KEY, SET, PROBLEM, PSVN, FIELDS, OPTIONS
298
299The C<new> method creates a translator, initializes it using the parameters
300specified, translates a PG file, and processes answers. It returns a reference
301to a blessed hash containing the results of the translation process.
302
303=back
304
305=head2 Parameters
306
307=over
308
309=item ENVIRONMENT
310
311a WeBWorK::CourseEnvironment object
312
313=item USER
314
315a WeBWorK::User object
316
317=item KEY
318
319the session key of the current session
320
321=item SET
322
323a WeBWorK::Set object
324
325=item PROBLEM
326
327a WeBWorK::DB::Record::UserProblem object. The contents of the source_file
328field can specify a PG file either by absolute path or path relative to the
329"templates" directory. I<The caller should remove taint from this value before
330passing!>
331
332=item PSVN
333
334the problem set version number
335
336=item FIELDS
337
338a reference to a hash (as returned by &WeBWorK::Form::Vars) containing form
339fields submitted by a problem processor. The translator will look for fields
340like "AnSwEr[0-9]" containing submitted student answers.
341
342=item OPTIONS
343
344a reference to a hash containing the following data:
345
346=over
347
348=item displayMode
349
350one of "plainText", "formattedText", or "images"
351
352=item showHints
353
354boolean, render hints
355
356=item showSolutions
357
358boolean, render solutions
359
360=item refreshMath2img
361
362boolean, force images created by math2img (in "images" mode) to be recreated,
363even if the PG source has not been updated. FIXME: remove this option.
364
365=item processAnswers
366
367boolean, call answer evaluators and graders
368
369=back
370
371=back
372
373=head2 RETURN VALUE
374
375The C<new> method returns a blessed hash reference containing the following
376fields. More information can be found in the documentation for
377WeBWorK::PG::Translator.
378
379=over
380
381=item translator
382
383The WeBWorK::PG::Translator object used to render the problem.
384
385=item head_text
386
387HTML code for the E<lt>headE<gt> block of an resulting web page. Used for
388JavaScript features.
389
390=item body_text
391
392HTML code for the E<lt>bodyE<gt> block of an resulting web page.
393
394=item answers
395
396An C<AnswerHash> object containing submitted answers, and results of answer
397evaluation.
398
399=item result
400
401A hash containing the results of grading the problem.
402
403=item state
404
405A hash containing the new problem state.
406
407=item errors
408
409A string containing any errors encountered while rendering the problem.
410
411=item warnings
412
413A string containing any warnings encountered while rendering the problem.
414
415=item flags
416
417A hash containing PG_flags (see the Translator docs).
418
419=back
420
421=head1 METHODS PROVIDED BY THE BASE CLASS
422
423The following methods are provided for use by subclasses of WeBWorK::PG.
424
425=over
426
427=item defineProblemEnvir ENVIRONMENT, USER, KEY, SET, PROBLEM, PSVN, FIELDS, OPTIONS
428
429Generate a problem environment hash to pass to the renderer.
430
431=item translateDisplayModeNames NAME
432
433NAME contains
434
435=back
436
437=head1 AUTHOR
438
439Written by Sam Hathaway, sh002i (at) math.rochester.edu.
440
441=cut
Legend:
Removed from v.414  
changed lines
  Added in v.4091
aubreyja at gmail dot com
 ViewVC Help
Powered by ViewVC 1.0.9