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

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

Parent Directory Parent Directory | Revision Log Revision Log


Revision 2200 - (view) (download) (as text)
Original Path: trunk/webwork-modperl/lib/WeBWorK/PG.pm

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

aubreyja at gmail dot com
ViewVC Help
Powered by ViewVC 1.0.9