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