--- trunk/webwork2/lib/WeBWorK/PG.pm 2002/10/25 20:56:49 607 +++ trunk/webwork2/lib/WeBWorK/PG.pm 2006/05/21 00:52:20 4091 @@ -1,221 +1,59 @@ ################################################################################ -# WeBWorK mod_perl (c) 2000-2002 WeBWorK Project -# $Id$ +# WeBWorK Online Homework Delivery System +# Copyright © 2000-2006 The WeBWorK Project, http://openwebwork.sf.net/ +# $CVSHeader: webwork-modperl/lib/WeBWorK/PG.pm,v 1.63 2006/01/25 23:13:51 sh002i Exp $ +# +# This program is free software; you can redistribute it and/or modify it under +# the terms of either: (a) the GNU General Public License as published by the +# Free Software Foundation; either version 2, or (at your option) any later +# version, or (b) the "Artistic License" which comes with this package. +# +# This program is distributed in the hope that it will be useful, but WITHOUT +# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS +# FOR A PARTICULAR PURPOSE. See either the GNU General Public License or the +# Artistic License for more details. ################################################################################ package WeBWorK::PG; =head1 NAME -WeBWorK::PG - Wrap the action of the PG Translator in an easy-to-use API. +WeBWorK::PG - Invoke one of several PG rendering methods using an easy-to-use +API. =cut use strict; use warnings; -use File::Path qw(rmtree); -use File::Temp qw(tempdir); -use WeBWorK::DB::Classlist; -use WeBWorK::DB::WW; -use WeBWorK::PG::Translator; -use WeBWorK::Problem; -use WeBWorK::Utils qw(readFile formatDateTime writeTimingLogEntry); - -sub new($$$$$$$$) { - my $invocant = shift; - my $class = ref($invocant) || $invocant; - my ( - $courseEnv, - $user, - $key, - $set, - $problem, - $psvn, - $formFields, # in CGI::Vars format - $translationOptions, # hashref containing options for the - # translator, such as whether to show - # hints and the display mode to use - ) = @_; - - # write timing log entry - writeTimingLogEntry($courseEnv, "WeBWorK::PG::new", - "user=".$user->id.",problem=".$courseEnv->{courseName}."/".$set->id."/".$problem->id.",mode=".$translationOptions->{displayMode}, - "begin"); - - # install a local warn handler to collect warnings - my $warnings = ""; - local $SIG{__WARN__} = sub { $warnings .= shift }; - - # create a Translator - #warn "PG: creating a Translator\n"; - my $translator = WeBWorK::PG::Translator->new; - - # set the directory hash - #warn "PG: setting the directory hash\n"; - $translator->rh_directories({ - courseScriptsDirectory => $courseEnv->{webworkDirs}->{macros}, - macroDirectory => $courseEnv->{courseDirs}->{macros}, - templateDirectory => $courseEnv->{courseDirs}->{templates}, - tempDirectory => $courseEnv->{courseDirs}->{html_temp}, - }); - - # evaluate modules and "extra packages" - #warn "PG: evaluating modules and \"extra packages\"\n"; - my @modules = @{ $courseEnv->{pg}->{modules} }; - foreach my $module_packages_ref (@modules) { - my ($module, @extra_packages) = @$module_packages_ref; - # the first item is the main package - $translator->evaluate_modules($module); - # the remaining items are "extra" packages - $translator->load_extra_packages(@extra_packages); - } - - # set the environment (from defineProblemEnvir) - #warn "PG: setting the environment (from defineProblemEnvir)\n"; - my $envir = defineProblemEnvir( - $courseEnv, - $user, - $key, - $set, - $problem, - $psvn, - $formFields, - $translationOptions, - ); - $translator->environment($envir); - - # initialize the Translator - #warn "PG: initializing the Translator\n"; - $translator->initialize(); - - # load PG.pl and dangerousMacros.pl using unrestricted_load - # i'd like to change this at some point to have the same sort of interface to global.conf - # that the module loading does -- have a list of macros to load unrestrictedly. - #warn "PG: loading PG.pl and dangerousMacros.pl using unrestricted_load\n"; - my $pg_pl = $courseEnv->{webworkDirs}->{macros} . "/PG.pl"; - my $dangerousMacros_pl = $courseEnv->{webworkDirs}->{macros} . "/dangerousMacros.pl"; - my $io_pl = $courseEnv->{webworkDirs}->{macros} . "/IO.pl"; - my $err = $translator->unrestricted_load($pg_pl); - warn "Error while loading $pg_pl: $err" if $err; - $err = $translator->unrestricted_load($dangerousMacros_pl); - warn "Error while loading $dangerousMacros_pl: $err" if $err; - $err = $translator->unrestricted_load($io_pl); - warn "Error while loading $io_pl: $err" if $err; - - # set the opcode mask (using default values) - #warn "PG: setting the opcode mask (using default values)\n"; - $translator->set_mask(); - - # store the problem source - #warn "PG: storing the problem source\n"; - my $sourceFile = $problem->source_file; - $sourceFile = $courseEnv->{courseDirs}->{templates}."/".$sourceFile - unless ($sourceFile =~ /^\//); - eval { $translator->source_string(readFile($sourceFile)) }; - if ($@) { - # well, we couldn't get the problem source, for some reason. - return bless { - translator => $translator, - head_text => "", - body_text => < {}, - result => {}, - state => {}, - errors => "Failed to read the problem source file.", - warnings => $warnings, - flags => {error_flag => 1}, - }, $class; - } - - # install a safety filter (&safetyFilter) - #warn "PG: installing a safety filter\n"; - $translator->rf_safety_filter(\&safetyFilter); - - # translate the PG source into text - #warn "PG: translating the PG source into text\n"; - $translator->translate(); - - # after we're done translating, we may have to clean up after the translator. - # for example, 'images' mode uses a tempdir for dvipng's temp files. We have - # to remove it. - if ($translationOptions->{displayMode} eq 'images' && $envir->{dvipngTempDir}) { - rmtree($envir->{dvipngTempDir}, 0, 0); - } +use WeBWorK::PG::ImageGenerator; +use WeBWorK::Utils qw(runtime_use formatDateTime makeTempDirectory); + +use constant DISPLAY_MODES => { + # display name # mode name + tex => "TeX", + plainText => "HTML", + formattedText => "HTML_tth", + images => "HTML_dpng", + jsMath => "HTML_jsMath", + asciimath => "HTML_asciimath", +}; + +sub new { + shift; # throw away invocant -- we don't need it + my ($ce, $user, $key, $set, $problem, $psvn, $formFields, + $translationOptions) = @_; - my ($result, $state); # we'll need these on the other side of the if block! - if ($translationOptions->{processAnswers}) { - - # process student answers - #warn "PG: processing student answers\n"; - $translator->process_answers($formFields); - - # retrieve the problem state and give it to the translator - #warn "PG: retrieving the problem state and giving it to the translator\n"; - $translator->rh_problem_state({ - recorded_score => $problem->status, - num_of_correct_ans => $problem->num_correct, - num_of_incorrect_ans => $problem->num_incorrect, - }); - - # determine an entry order -- the ANSWER_ENTRY_ORDER flag is built by - # the PG macro package (PG.pl) - #warn "PG: determining an entry order\n"; - my @answerOrder = - $translator->rh_flags->{ANSWER_ENTRY_ORDER} - ? @{ $translator->rh_flags->{ANSWER_ENTRY_ORDER} } - : keys %{ $translator->rh_evaluated_answers }; - - # install a grader -- use the one specified in the problem, - # or fall back on the default from the course environment. - # (two magic strings are accepted, to avoid having to - # reference code when it would be difficult.) - #warn "PG: installing a grader\n"; - my $grader = $translator->rh_flags->{PROBLEM_GRADER_TO_USE} - || $courseEnv->{pg}->{options}->{grader}; - $grader = $translator->rf_std_problem_grader - if $grader eq "std_problem_grader"; - $grader = $translator->rf_avg_problem_grader - if $grader eq "avg_problem_grader"; - die "Problem grader $grader is not a CODE reference." - unless ref $grader eq "CODE"; - $translator->rf_problem_grader($grader); - - # grade the problem - #warn "PG: grading the problem\n"; - ($result, $state) = $translator->grade_problem( - answers_submitted => $translationOptions->{processAnswers}, - ANSWER_ENTRY_ORDER => \@answerOrder, - ); - - } + my $renderer = $ce->{pg}->{renderer}; - # write timing log entry - writeTimingLogEntry($courseEnv, "WeBWorK::PG::new", "", "end"); + runtime_use $renderer; - # return an object which contains the translator and the results of - # the translation process. this is DIFFERENT from the "format expected - # by Webwork.pm (and I believe processProblem8, but check.)" - return bless { - translator => $translator, - head_text => ${ $translator->r_header }, - body_text => ${ $translator->r_text }, - answers => $translator->rh_evaluated_answers, - result => $result, - state => $state, - errors => $translator->errors, - warnings => $warnings, - flags => $translator->rh_flags, - }, $class; + return $renderer->new(@_); } -# ----- - -sub defineProblemEnvir($$$$$$$) { +sub defineProblemEnvir { my ( - $courseEnv, + $self, + $ce, $user, $key, $set, @@ -227,40 +65,44 @@ my %envir; + # ---------------------------------------------------------------------- + # PG environment variables # from docs/pglanguage/pgreference/environmentvariables as of 06/25/2002 # any changes are noted by "ADDED:" or "REMOVED:" # Vital state information - # ADDED: displayHintsQ, displaySolutionsQ, refreshMath2img + # ADDED: displayModeFailover, displayHintsQ, displaySolutionsQ, + # refreshMath2img, texDisposition - $envir{psvn} = $psvn; - $envir{psvnNumber} = $envir{psvn}; - $envir{probNum} = $problem->id; - $envir{questionNumber} = $envir{probNum}; - $envir{fileName} = $problem->source_file; - $envir{probFileName} = $envir{fileName}; - $envir{problemSeed} = $problem->problem_seed; - $envir{displayMode} = translateDisplayModeNames($options->{displayMode}); - $envir{languageMode} = $envir{displayMode}; - $envir{outputMode} = $envir{displayMode}; - $envir{displayHintsQ} = $options->{hints}; - $envir{displaySolutionsQ} = $options->{solutions}; - $envir{refreshMath2img} = $options->{refreshMath2img}; + $envir{psvn} = $set->psvn; + $envir{psvnNumber} = $envir{psvn}; + $envir{probNum} = $problem->problem_id; + $envir{questionNumber} = $envir{probNum}; + $envir{fileName} = $problem->source_file; + $envir{probFileName} = $envir{fileName}; + $envir{problemSeed} = $problem->problem_seed; + $envir{displayMode} = translateDisplayModeNames($options->{displayMode}); + $envir{languageMode} = $envir{displayMode}; + $envir{outputMode} = $envir{displayMode}; + $envir{displayHintsQ} = $options->{showHints}; + $envir{displaySolutionsQ} = $options->{showSolutions}; + $envir{texDisposition} = "pdf"; # in webwork2, we use pdflatex # Problem Information - # ADDED: courseName + # ADDED: courseName, formatedDueDate $envir{openDate} = $set->open_date; - $envir{formattedOpenDate} = formatDateTime($envir{openDate}); + $envir{formattedOpenDate} = formatDateTime($envir{openDate}, $ce->{siteDefaults}{timezone}); $envir{dueDate} = $set->due_date; - $envir{formattedDueDate} = formatDateTime($envir{dueDate}); + $envir{formattedDueDate} = formatDateTime($envir{dueDate}, $ce->{siteDefaults}{timezone}); + $envir{formatedDueDate} = $envir{formattedDueDate}; # typo in many header files $envir{answerDate} = $set->answer_date; - $envir{formattedAnswerDate} = formatDateTime($envir{answerDate}); + $envir{formattedAnswerDate} = formatDateTime($envir{answerDate}, $ce->{siteDefaults}{timezone}); $envir{numOfAttempts} = ($problem->num_correct || 0) + ($problem->num_incorrect || 0); $envir{problemValue} = $problem->value; $envir{sessionKey} = $key; - $envir{courseName} = $courseEnv->{courseName}; + $envir{courseName} = $ce->{courseName}; # Student Information # ADDED: studentID @@ -269,8 +111,8 @@ $envir{sectionNumber} = $envir{sectionName}; $envir{recitationName} = $user->recitation; $envir{recitationNumber} = $envir{recitationName}; - $envir{setNumber} = $set->id; - $envir{studentLogin} = $user->id; + $envir{setNumber} = $set->set_id; + $envir{studentLogin} = $user->user_id; $envir{studentName} = $user->first_name . " " . $user->last_name; $envir{studentID} = $user->student_id; @@ -283,56 +125,102 @@ # ADDED: externalLaTeXPath, externalDvipngPath, # externalGif2EpsPath, externalPng2EpsPath - $envir{externalTTHPath} = $courseEnv->{externalPrograms}->{tth}; - $envir{externalLaTeXPath} = $courseEnv->{externalPrograms}->{latex}; - $envir{externalDvipngPath} = $courseEnv->{externalPrograms}->{dvipng}; - $envir{externalGif2EpsPath} = $courseEnv->{externalPrograms}->{gif2eps}; - $envir{externalPng2EpsPath} = $courseEnv->{externalPrograms}->{png2eps}; + $envir{externalTTHPath} = $ce->{externalPrograms}->{tth}; + $envir{externalLaTeXPath} = $ce->{externalPrograms}->{latex}; + $envir{externalDvipngPath} = $ce->{externalPrograms}->{dvipng}; + $envir{externalGif2EpsPath} = $ce->{externalPrograms}->{gif2eps}; + $envir{externalPng2EpsPath} = $ce->{externalPrograms}->{png2eps}; + $envir{externalGif2PngPath} = $ce->{externalPrograms}->{gif2png}; # Directories and URLs # REMOVED: courseName # ADDED: dvipngTempDir - + # ADDED: jsMathURL + # ADDED: asciimathURL + # ADDED: macrosPath + # REMOVED: macrosDirectory, courseScriptsDirectory $envir{cgiDirectory} = undef; $envir{cgiURL} = undef; $envir{classDirectory} = undef; - $envir{courseScriptsDirectory} = $courseEnv->{webworkDirs}->{macros}."/"; - $envir{htmlDirectory} = $courseEnv->{courseDirs}->{html}."/"; - $envir{htmlURL} = $courseEnv->{courseURLs}->{html}."/"; - $envir{macroDirectory} = $courseEnv->{courseDirs}->{macros}."/"; - $envir{templateDirectory} = $courseEnv->{courseDirs}->{templates}."/"; - $envir{tempDirectory} = $courseEnv->{courseDirs}->{html_temp}."/"; - $envir{tempURL} = $courseEnv->{courseURLs}->{html_temp}."/"; + $envir{macrosPath} = $ce->{pg}->{directories}{macrosPath}; + $envir{appletDirs} = $ce->{pg}->{directories}{appletDirs}; + $envir{htmlDirectory} = $ce->{courseDirs}->{html}."/"; + $envir{htmlURL} = $ce->{courseURLs}->{html}."/"; + $envir{templateDirectory} = $ce->{courseDirs}->{templates}."/"; + $envir{tempDirectory} = $ce->{courseDirs}->{html_temp}."/"; + $envir{tempURL} = $ce->{courseURLs}->{html_temp}."/"; $envir{scriptDirectory} = undef; - $envir{webworkDocsURL} = $courseEnv->{webworkURLs}->{docs}."/"; - $envir{dvipngTempDir} = $options->{displayMode} eq 'images' - ? tempdir("webwork-dvipng-XXXXXXXX", DIR => $envir{tempDirectory}) - : undef; + $envir{webworkDocsURL} = $ce->{webworkURLs}->{docs}."/"; + $envir{localHelpURL} = $ce->{webworkURLs}->{local_help}."/"; + $envir{jsMathURL} = $ce->{webworkURLs}->{jsMath}; + $envir{asciimathURL} = $ce->{webworkURLs}->{asciimath}; + + # Information for sending mail + + $envir{mailSmtpServer} = $ce->{mail}->{smtpServer}; + $envir{mailSmtpSender} = $ce->{mail}->{smtpSender}; + $envir{ALLOW_MAIL_TO} = $ce->{mail}->{allowedRecipients}; # Default values for evaluating answers - my $ansEvalDefaults = $courseEnv->{pg}->{ansEvalDefaults}; + my $ansEvalDefaults = $ce->{pg}->{ansEvalDefaults}; $envir{$_} = $ansEvalDefaults->{$_} foreach (keys %$ansEvalDefaults); - # Other things... + # ---------------------------------------------------------------------- + + my $basename = "equation-$envir{psvn}.$envir{probNum}"; + $basename .= ".$envir{problemSeed}" if $envir{problemSeed}; + + # to make grabbing these options easier, we'll pull them out now... + my %imagesModeOptions = %{$ce->{pg}->{displayModeOptions}->{images}}; - $envir{PROBLEM_GRADER_TO_USE} = $courseEnv->{pg}->{options}->{grader}; + # Object for generating equation images + $envir{imagegen} = WeBWorK::PG::ImageGenerator->new( + tempDir => $ce->{webworkDirs}->{tmp}, # global temp dir + latex => $envir{externalLaTeXPath}, + dvipng => $envir{externalDvipngPath}, + useCache => 1, + cacheDir => $ce->{webworkDirs}->{equationCache}, + cacheURL => $ce->{webworkURLs}->{equationCache}, + cacheDB => $ce->{webworkFiles}->{equationCacheDB}, + useMarkers => ($imagesModeOptions{dvipng_align} && $imagesModeOptions{dvipng_align} eq 'mysql'), + dvipng_align => $imagesModeOptions{dvipng_align}, + dvipng_depth_db => $imagesModeOptions{dvipng_depth_db}, + ); + + # ADDED: jsMath options + $envir{jsMath} = {%{$ce->{pg}{displayModeOptions}{jsMath}}}; + + # Other things... + $envir{QUIZ_PREFIX} = $options->{QUIZ_PREFIX}; # used by quizzes + $envir{PROBLEM_GRADER_TO_USE} = $ce->{pg}->{options}->{grader}; + $envir{PRINT_FILE_NAMES_FOR} = $ce->{pg}->{specialPGEnvironmentVars}->{PRINT_FILE_NAMES_FOR}; + + # ADDED: __files__ + # an array for mapping (eval nnn) to filenames in error messages + $envir{__files__} = { + root => $ce->{webworkDirs}{root}, # used to shorten filenames + pg => $ce->{pg}{directories}{root}, # ditto + tmpl => $ce->{courseDirs}{templates}, # ditto + }; + + # variables for interpreting capa problems and other things to be + # seen in a pg file + my $specialPGEnvironmentVarHash = $ce->{pg}->{specialPGEnvironmentVars}; + for my $SPGEV (keys %{$specialPGEnvironmentVarHash}) { + $envir{$SPGEV} = $specialPGEnvironmentVarHash->{$SPGEV}; + } return \%envir; } sub translateDisplayModeNames($) { my $name = shift; - return { - tex => "TeX", - plainText => "HTML", - formattedText => "HTML_tth", - images => "HTML_img" - }->{$name}; + return DISPLAY_MODES()->{$name}; } -sub safetyFilter { +sub oldSafetyFilter { my $answer = shift; # accepts one answer and checks it my $submittedAnswer = $answer; $answer = '' unless defined $answer; @@ -346,8 +234,8 @@ } # replace ^ with ** (for exponentiation) # $answer =~ s/\^/**/g; - # Return if forbidden characters are found - unless ($answer =~ /^[a-zA-Z0-9_\-\+ \t\/@%\*\.\n^\(\)]+$/ ) { + # Return if forbidden characters are found + unless ($answer =~ /^[a-zA-Z0-9_\-\+ \t\/@%\*\.\n^\[\]\(\)\,\|]+$/ ) { $answer =~ tr/a-zA-Z0-9_\-\+ \t\/@%\*\.\n^\(\)/#/c; $errorno = "
There are forbidden characters in your answer: $submittedAnswer
"; return ($answer,$errorno); @@ -356,6 +244,10 @@ return($answer, $errorno); } +sub nullSafetyFilter { + return shift, 0; # no errors +} + 1; __END__ @@ -363,11 +255,11 @@ =head1 SYNOPSIS $pg = WeBWorK::PG->new( - $courseEnv, # a WeBWorK::CourseEnvironment object - $user, # a WeBWorK::User object + $ce, # a WeBWorK::CourseEnvironment object + $user, # a WeBWorK::DB::Record::User object $sessionKey, - $set, # a WeBWorK::Set object - $problem, # a WeBWorK::Problem object + $set, # a WeBWorK::DB::Record::UserSet object + $problem, # a WeBWorK::DB::Record::UserProblem object $psvn, $formFields # in &WeBWorK::Form::Vars format { # translation options @@ -391,15 +283,18 @@ =head1 DESCRIPTION -WeBWorK::PG encapsulates the PG translation process, making multiple calls to -WeBWorK::PG::Translator. Much of the flexibility of the Translator is hidden, -instead making choices that are appropriate for the webwork-modperl system. +WeBWorK::PG is a factory for modules which use the WeBWorK::PG API. Notable +modules which use this API (and exist) are WeBWorK::PG::Local and +WeBWorK::PG::Remote. The course environment key $pg{renderer} is consulted to +determine which render to use. + +=head1 THE WEBWORK::PG API -=head1 CONSTRUCTION +Modules which support this API must implement the following method: =over -=item new (ENVIRONMENT, USER, KEY, SET, PROBLEM, PSVN, FIELDS, OPTIONS) +=item new ENVIRONMENT, USER, KEY, SET, PROBLEM, PSVN, FIELDS, OPTIONS The C method creates a translator, initializes it using the parameters specified, translates a PG file, and processes answers. It returns a reference @@ -429,9 +324,10 @@ =item PROBLEM -a WeBWorK::Problem object. The contents of the source_file field can specify a -PG file either by absolute path or path relative to the "templates" directory. -I +a WeBWorK::DB::Record::UserProblem object. The contents of the source_file +field can specify a PG file either by absolute path or path relative to the +"templates" directory. I =item PSVN @@ -464,7 +360,7 @@ =item refreshMath2img boolean, force images created by math2img (in "images" mode) to be recreated, -even if the PG source has not been updated. +even if the PG source has not been updated. FIXME: remove this option. =item processAnswers @@ -522,84 +418,19 @@ =back -=head1 OPERATION +=head1 METHODS PROVIDED BY THE BASE CLASS -WeBWorK::PG goes through the following operations when constructed: +The following methods are provided for use by subclasses of WeBWorK::PG. =over -=item Get database information - -Retrieve information about the current user, set, and problem from the -database. - -=item Create a translator - -Instantiate a WeBWorK::PG::Translator object. - -=item Set the directory hash - -Set the translator's directory hash (courseScripts, macros, templates, and temp -directories) from the course environment. - -=item Evaluate PG modules - -Using the module list from the course environment (pg->modules), perform a -"use"-like operation to evaluate modules at runtime. - -=item Set the problem environment - -Use data from the user, set, and problem, as well as the course environemnt and -translation options, to set the problem environment. - -=item Initialize the translator - -Call &WeBWorK::PG::Translator::initialize. What more do you want? - -=item Load PG.pl and dangerousMacros.pl - -These macros must be loaded without opcode masking, so they are loaded here. - -=item Set the opcode mask - -Set the opcode mask to the default specified by WeBWorK::PG::Translator. - -=item Load the problem source - -Give the problem source to the translator. - -=item Install a safety filter - -The safety filter is used to preprocess student input before evaluation. The -default safety filter, &WeBWorK::PG::safetyFilter, is used. - -=item Translate the problem source - -Call &WeBWorK::PG::Translator::translate to render the problem source into the -format given by the display mode. - -=item Process student answers - -Use form field inputs to evaluate student answers. - -=item Load the problem state - -Use values from the database to initialize the problem state, so that the -grader will have a point of reference. - -=item Determine an entry order - -Use the ANSWER_ENTRY_ORDER flag to determine the order of answers in the -problem. This is important for problems with dependancies among parts. - -=item Install a grader +=item defineProblemEnvir ENVIRONMENT, USER, KEY, SET, PROBLEM, PSVN, FIELDS, OPTIONS -Use the PROBLEM_GRADER_TO_USE flag, or a default from the course environment, -to install a grader. +Generate a problem environment hash to pass to the renderer. -=item Grade the problem +=item translateDisplayModeNames NAME -Use the selected grader to grade the problem. +NAME contains =back