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

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

Parent Directory Parent Directory | Revision Log Revision Log


Revision 5734 - (view) (download) (as text)

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

aubreyja at gmail dot com
ViewVC Help
Powered by ViewVC 1.0.9