Diff of /trunk/webwork2/lib/WeBWorK/PG.pm

Revision 455		Revision 2217
1	################################################################################	1	################################################################################
2	# WeBWorK mod_perl (c) 1995-2002 WeBWorK Team, Univeristy of Rochester	2	# WeBWorK Online Homework Delivery System
3	# $Id$	3	# Copyright © 2000-2003 The WeBWorK Project, http://openwebwork.sf.net/
		4	# $CVSHeader: webwork-modperl/lib/WeBWorK/PG.pm,v 1.51 2004/05/24 02:01:25 dpvc 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.
4	################################################################################	15	################################################################################
5		16
6	package WeBWorK::PG;	17	package WeBWorK::PG;
7		18
8	=head1 NAME	19	=head1 NAME
9		20
10	WeBWorK::PG - Wrap the action of the PG Translator in an easy-to-use API	21	WeBWorK::PG - Invoke one of several PG rendering methods using an easy-to-use
		22	API.
11		23
12	=cut	24	=cut
13		25
14	use strict;	26	use strict;
15	use warnings;	27	use warnings;
16	use WeBWorK::DB::Classlist;
17	use WeBWorK::DB::WW;
18	use WeBWorK::PG::Translator;	28	use WeBWorK::PG::ImageGenerator;
19	use WeBWorK::Utils qw(readFile formatDateTime);	29	use WeBWorK::Utils qw(runtime_use formatDateTime makeTempDirectory);
20		30
21	sub new($$$$$$$$) {	31	use constant DISPLAY_MODES => {
22	my $invocant = shift;	32	# display name # mode name
23	my $class = ref($invocant) \|\| $invocant;	33	tex => "TeX",
		34	plainText => "HTML",
		35	formattedText => "HTML_tth",
		36	images => "HTML_dpng",
		37	jsMath => "HTML_jsMath",
		38	asciimath => "HTML_asciimath",
		39	};
		40
		41	use constant DISPLAY_MODE_FAILOVER => {
		42	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	# 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	sub new {
		56	shift; # throw away invocant -- we don't need it
		57	my ($ce, $user, $key, $set, $problem, $psvn, $formFields,
		58	$translationOptions) = @_;
		59
		60	my $renderer = $ce->{pg}->{renderer};
		61
		62	runtime_use $renderer;
		63
		64	return $renderer->new(@_);
		65	}
		66
		67	sub defineProblemEnvir {
24	my (	68	my (
25	$courseEnv,	69	$self,
26	$userName,
27	$key,	70	$ce,
28	$setName,
29	$problemNumber,
30	$translationOptions, # hashref containing options for the
31	# translator, such as whether to show
32	# hints and the display mode to use
33	$formFields, # in CGI::Vars format
34	) = @_;
35
36	# get database information
37	my $classlist = WeBWorK::DB::Classlist->new($courseEnv);
38	my $wwdb = WeBWorK::DB::WW->new($courseEnv);
39	my $user = $classlist->getUser($userName);
40	my $set = $wwdb->getSet($userName, $setName);
41	my $problem = $wwdb->getProblem($userName, $setName, $problemNumber);
42	my $psvn = $wwdb->getPSVN($userName, $setName);
43
44	# create a Translator
45	warn "PG: creating a Translator\n";
46	my $translator = WeBWorK::PG::Translator->new;
47
48	# set the directory hash
49	warn "PG: setting the directory hash\n";
50	$translator->rh_directories({
51	courseScriptsDirectory => $courseEnv->{webworkDirs}->{macros},
52	macroDirectory => $courseEnv->{courseDirs}->{macros},
53	templateDirectory => $courseEnv->{courseDirs}->{templates},
54	tempDirectory => $courseEnv->{courseDirs}->{html_temp},
55	});
56
57	# evaluate modules and "extra packages"
58	warn "PG: evaluating modules and \"extra packages\"\n";
59	my @modules = @{ $courseEnv->{pg}->{modules} };
60	foreach my $module_packages (@modules) {
61	# the first item in $module_packages is the main package
62	$translator->evaluate_modules(shift @$module_packages);
63	# the remaining items are "extra" packages
64	$translator->load_extra_packages(@$module_packages);
65	}
66
67	# set the environment (from defineProblemEnvir)
68	warn "PG: setting the environment (from defineProblemEnvir)\n";
69	$translator->environment(defineProblemEnvir(
70	$courseEnv, $user, $key, $set, $problem, $psvn, $formFields, $translationOptions));
71
72	# initialize the Translator
73	warn "PG: initializing the Translator\n";
74	$translator->initialize();
75
76	# load PG.pl and dangerousMacros.pl using unrestricted_load
77	# i'd like to change this at some point to have the same sort of interface to global.conf
78	# that the module loading does -- have a list of macros to load unrestrictedly.
79	warn "PG: loading PG.pl and dangerousMacros.pl using unrestricted_load\n";
80	my $pg_pl = $courseEnv->{webworkDirs}->{macros} . "/PG.pl";
81	my $dangerousMacros_pl = $courseEnv->{webworkDirs}->{macros} . "/dangerousMacros.pl";
82	my $err = $translator->unrestricted_load($pg_pl);
83	warn "Error while loading $pg_pl: $err" if $err;
84	$err = $translator->unrestricted_load($dangerousMacros_pl);
85	warn "Error while loading $dangerousMacros_pl: $err" if $err;
86
87	# set the opcode mask (using default values)
88	warn "PG: setting the opcode mask (using default values)\n";
89	$translator->set_mask();
90
91	# store the problem source
92	warn "PG: storing the problem source\n";
93	my $sourceFile = $courseEnv->{courseDirs}->{templates}."/".$problem->source_file;
94	$translator->source_string(readFile($sourceFile));
95
96	# install a safety filter (&safetyFilter)
97	warn "PG: installing a safety filter\n";
98	$translator->rf_safety_filter(\&safetyFilter);
99
100	# translate the PG source into text
101	warn "PG: translating the PG source into text\n";
102	$translator->translate();
103
104	# [in Problem.pm and processProblem8.pl, "install a grader" is here]
105
106	# process student answers
107	warn "PG: processing student answers\n";
108	$translator->process_answers($formFields);
109
110	# retrieve the problem state and give it to the translator
111	warn "PG: retrieving the problem state and giving it to the translator\n";
112	$translator->rh_problem_state({
113	recorded_score => $problem->status,
114	num_of_correct_ans => $problem->num_correct,
115	num_of_incorrect_ans => $problem->num_incorrect,
116	});
117
118	# determine an entry order -- the ANSWER_ENTRY_ORDER flag is built by
119	# the PG macro package (PG.pl)
120	warn "PG: determining an entry order\n";
121	my @answerOrder =
122	$translator->rh_flags->{ANSWER_ENTRY_ORDER}
123	? @{ $translator->rh_flags->{ANSWER_ENTRY_ORDER} }
124	: keys %{ $translator->rh_evaluated_answers };
125
126	# install a grader -- use the one specified in the problem,
127	# or fall back on the default from the course environment.
128	# (two magic strings are accepted, to avoid having to
129	# reference code when it would be difficult.)
130	warn "PG: installing a grader\n";
131	my $grader = $translator->rh_flags->{PROBLEM_GRADER_TO_USE}
132	\|\| $courseEnv->{pg}->{options}->{grader};
133	$grader = $translator->rf_std_problem_grader
134	if $grader eq "std_problem_grader";
135	$grader = $translator->rf_avg_problem_grader
136	if $grader eq "avg_problem_grader";
137	die "Problem grader $grader is not a CODE reference."
138	unless ref $grader eq "CODE";
139	$translator->rf_problem_grader($grader);
140
141	# grade the problem
142	warn "PG: grading the problem\n";
143	my ($result, $state) = $translator->grade_problem(
144	answers_submitted => $translationOptions->{processAnswers},
145	ANSWER_ENTRY_ORDER => \@answerOrder,
146	);
147
148	# return an object which contains the translator and the results of
149	# the translation process. this is DIFFERENT from the "format expected
150	# by Webwork.pm (and I believe processProblem8, but check.)"
151	return bless {
152	translator => $translator,
153	head_text => ${ $translator->r_header },
154	body_text => ${ $translator->r_text },
155	answers => $translator->rh_evaluated_answers,
156	result => $result,
157	state => $state,
158	errors => $translator->errors, # *** what is this doing?
159	warnings => undef, # *** gotta catch warnings eventually...
160	flags => $translator->rh_flags,
161	}, $class;
162	}
163
164	# -----
165
166	sub defineProblemEnvir($$$$$$$) {
167	my (
168	$courseEnv,
169	$user,	71	$user,
170	$key,	72	$key,
171	$set,	73	$set,
172	$problem,	74	$problem,
173	$psvn,	75	$psvn,
…		…
175	$options,	77	$options,
176	) = @_;	78	) = @_;
177		79
178	my %envir;	80	my %envir;
179		81
		82	# ----------------------------------------------------------------------
		83
180	# PG environment variables	84	# PG environment variables
181	# from docs/pglanguage/pgreference/environmentvariables as of 06/25/2002	85	# from docs/pglanguage/pgreference/environmentvariables as of 06/25/2002
182	# any changes are noted by "ADDED:" or "REMOVED:"	86	# any changes are noted by "ADDED:" or "REMOVED:"
183		87
184	# Vital state information	88	# Vital state information
185	# ADDED: displayHintsQ, displaySolutionsQ	89	# ADDED: displayModeFailover, displayHintsQ, displaySolutionsQ,
		90	# refreshMath2img, texDisposition
186		91
187	$envir{psvn} = $psvn;	92	$envir{psvn} = $set->psvn;
188	$envir{psvnNumber} = $envir{psvn};	93	$envir{psvnNumber} = $envir{psvn};
189	$envir{probNum} = $problem->id;	94	$envir{probNum} = $problem->problem_id;
190	$envir{questionNumber} = $envir{probNum};	95	$envir{questionNumber} = $envir{probNum};
191	$envir{fileName} = $problem->source_file;	96	$envir{fileName} = $problem->source_file;
192	$envir{probFileName} = $envir{fileName};	97	$envir{probFileName} = $envir{fileName};
193	$envir{problemSeed} = $problem->problem_seed;	98	$envir{problemSeed} = $problem->problem_seed;
194	$envir{displayMode} = translateDisplayModeNames($options->{displayMode});	99	$envir{displayMode} = translateDisplayModeNames($options->{displayMode});
195	$envir{languageMode} = $envir{displayMode};	100	$envir{languageMode} = $envir{displayMode};
196	$envir{outputMode} = $envir{displayMode};	101	$envir{outputMode} = $envir{displayMode};
		102	$envir{displayModeFailover} = DISPLAY_MODE_FAILOVER();
197	$envir{displayHintsQ} = $options->{hints};	103	$envir{displayHintsQ} = $options->{showHints};
198	$envir{displaySolutionsQ} = $options->{solutions};	104	$envir{displaySolutionsQ} = $options->{showSolutions};
199	$envir{refreshMath2img} = $options->{refreshMath2img};	105	$envir{texDisposition} = "pdf"; # in webwork2, we use pdflatex
200		106
201	# Problem Information	107	# Problem Information
202	# ADDED: courseName	108	# ADDED: courseName, formatedDueDate
203		109
204	$envir{openDate} = $set->open_date;	110	$envir{openDate} = $set->open_date;
205	$envir{formattedOpenDate} = formatDateTime($envir{openDate});	111	$envir{formattedOpenDate} = formatDateTime($envir{openDate});
206	$envir{dueDate} = $set->due_date;	112	$envir{dueDate} = $set->due_date;
207	$envir{formattedDueDate} = formatDateTime($envir{dueDate});	113	$envir{formattedDueDate} = formatDateTime($envir{dueDate});
		114	$envir{formatedDueDate} = $envir{formattedDueDate}; # typo in many header files
208	$envir{answerDate} = $set->answer_date;	115	$envir{answerDate} = $set->answer_date;
209	$envir{formattedAnswerDate} = formatDateTime($envir{answerDate});	116	$envir{formattedAnswerDate} = formatDateTime($envir{answerDate});
210	$envir{numOfAttempts} = $problem->num_correct + $problem->num_incorrect;	117	$envir{numOfAttempts} = ($problem->num_correct \|\| 0) + ($problem->num_incorrect \|\| 0);
211	$envir{problemValue} = $problem->value;	118	$envir{problemValue} = $problem->value;
212	$envir{sessionKey} = $key;	119	$envir{sessionKey} = $key;
213	$envir{courseName} = $courseEnv->{courseName};	120	$envir{courseName} = $ce->{courseName};
214		121
215	# Student Information	122	# Student Information
216	# ADDED: studentID	123	# ADDED: studentID
217		124
218	$envir{sectionName} = $user->section;	125	$envir{sectionName} = $user->section;
219	$envir{sectionNumber} = $envir{sectionName};	126	$envir{sectionNumber} = $envir{sectionName};
220	$envir{recitationName} = $user->recitation;	127	$envir{recitationName} = $user->recitation;
221	$envir{recitationNumber} = $envir{recitationName};	128	$envir{recitationNumber} = $envir{recitationName};
222	$envir{setNumber} = $set->id;	129	$envir{setNumber} = $set->set_id;
223	$envir{studentLogin} = $user->id;	130	$envir{studentLogin} = $user->user_id;
224	$envir{studentName} = $user->first_name . " " . $user->last_name;	131	$envir{studentName} = $user->first_name . " " . $user->last_name;
225	$envir{studentID} = $user->student_id;	132	$envir{studentID} = $user->student_id;
226		133
227	# Answer Information	134	# Answer Information
228	# REMOVED: refSubmittedAnswers	135	# REMOVED: refSubmittedAnswers
229		136
230	$envir{inputs_ref} = $formFields;	137	$envir{inputs_ref} = $formFields;
231		138
232	# External Programs	139	# External Programs
		140	# ADDED: externalLaTeXPath, externalDvipngPath,
		141	# externalGif2EpsPath, externalPng2EpsPath
233		142
234	$envir{externalTTHPath} = $courseEnv->{externalPrograms}->{tth};	143	$envir{externalTTHPath} = $ce->{externalPrograms}->{tth};
		144	$envir{externalLaTeXPath} = $ce->{externalPrograms}->{latex};
235	$envir{externalMath2imgPath} = $courseEnv->{externalPrograms}->{math2img};	145	$envir{externalDvipngPath} = $ce->{externalPrograms}->{dvipng};
		146	$envir{externalGif2EpsPath} = $ce->{externalPrograms}->{gif2eps};
		147	$envir{externalPng2EpsPath} = $ce->{externalPrograms}->{png2eps};
		148	$envir{externalGif2PngPath} = $ce->{externalPrograms}->{gif2png};
236		149
237	# Directories and URLs	150	# Directories and URLs
238	# REMOVED: courseName	151	# REMOVED: courseName
		152	# ADDED: dvipngTempDir
		153	# ADDED: jsMathURL
		154	# ADDED: asciimathURL
239		155
240	$envir{cgiDirectory} = undef;	156	$envir{cgiDirectory} = undef;
241	$envir{cgiURL} = undef;	157	$envir{cgiURL} = undef;
242	$envir{classDirectory} = undef;	158	$envir{classDirectory} = undef;
243	$envir{courseScriptsDirectory} = $courseEnv->{webworkDirs}->{macros}."/";	159	$envir{courseScriptsDirectory} = $ce->{pg}->{directories}->{macros}."/";
244	$envir{htmlDirectory} = $courseEnv->{courseDirs}->{html}."/";	160	$envir{htmlDirectory} = $ce->{courseDirs}->{html}."/";
245	$envir{htmlURL} = $courseEnv->{courseURLs}->{html};	161	$envir{htmlURL} = $ce->{courseURLs}->{html}."/";
246	$envir{macroDirectory} = $courseEnv->{courseDirs}->{macros}."/";	162	$envir{macroDirectory} = $ce->{courseDirs}->{macros}."/";
247	$envir{templateDirectory} = $courseEnv->{courseDirs}->{templates}."/";	163	$envir{templateDirectory} = $ce->{courseDirs}->{templates}."/";
248	$envir{tempDirectory} = $courseEnv->{courseDirs}->{html_temp}."/";	164	$envir{tempDirectory} = $ce->{courseDirs}->{html_temp}."/";
249	$envir{tempURL} = $courseEnv->{courseURLs}->{html_temp};	165	$envir{tempURL} = $ce->{courseURLs}->{html_temp}."/";
250	$envir{scriptDirectory} = undef;	166	$envir{scriptDirectory} = undef;
251	$envir{webworkDocsURL} = $courseEnv->{webworkURLs}->{docs};	167	$envir{webworkDocsURL} = $ce->{webworkURLs}->{docs}."/";
		168	$envir{localHelpURL} = $ce->{webworkURLs}->{local_help}."/";
		169	$envir{jsMathURL} = $ce->{webworkURLs}->{jsMath};
		170	$envir{asciimathURL} = $ce->{webworkURLs}->{asciimath};
		171
		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};
252		177
253	# Default values for evaluating answers	178	# Default values for evaluating answers
254		179
255	my $ansEvalDefaults = $courseEnv->{pg}->{ansEvalDefaults};	180	my $ansEvalDefaults = $ce->{pg}->{ansEvalDefaults};
256	$envir{$_} = $ansEvalDefaults->{$_} foreach (keys %$ansEvalDefaults);	181	$envir{$_} = $ansEvalDefaults->{$_} foreach (keys %$ansEvalDefaults);
257		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
258	# Other things...	199	# Other things...
259		200	$envir{QUIZ_PREFIX} = $options->{QUIZ_PREFIX}; # used by quizzes
260	$envir{PROBLEM_GRADER_TO_USE} = $courseEnv->{pg}->{options}->{grader};	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 and other things to be
		205	# seen in a pg file
		206	my $specialPGEnvironmentVarHash = $ce->{pg}->{specialPGEnvironmentVars};
		207	for my $SPGEV (keys %{$specialPGEnvironmentVarHash}) {
		208	$envir{$SPGEV} = $specialPGEnvironmentVarHash->{$SPGEV};
		209	}
261		210
262	return \%envir;	211	return \%envir;
263	}	212	}
264		213
265	sub translateDisplayModeNames($) {	214	sub translateDisplayModeNames($) {
266	my $name = shift;	215	my $name = shift;
267	return {	216	return DISPLAY_MODES()->{$name};
268	plainText => "HTML",
269	formattedText => "HTML_tth",
270	images => "HTML_img"
271	}->{$name};
272	}	217	}
273		218
274	sub safetyFilter {	219	sub oldSafetyFilter {
275	my $answer = shift; # accepts one answer and checks it	220	my $answer = shift; # accepts one answer and checks it
276	my $submittedAnswer = $answer;	221	my $submittedAnswer = $answer;
277	$answer = '' unless defined $answer;	222	$answer = '' unless defined $answer;
278	my ($errorno);	223	my ($errorno);
279	$answer =~ tr/\000-\037/ /;	224	$answer =~ tr/\000-\037/ /;
…		…
283	$errorno = 0; ## don't report blank answer as error	228	$errorno = 0; ## don't report blank answer as error
284	return ($answer,$errorno);	229	return ($answer,$errorno);
285	}	230	}
286	# replace ^ with ** (for exponentiation)	231	# replace ^ with ** (for exponentiation)
287	# $answer =~ s/\^/**/g;	232	# $answer =~ s/\^/**/g;
288	# Return if forbidden characters are found	233	# Return if forbidden characters are found
289	unless ($answer =~ /^[a-zA-Z0-9_\-\+ \t\/@%\*\.\n^]+$/ ) {	234	unless ($answer =~ /^[a-zA-Z0-9_\-\+ \t\/@%\*\.\n^\[\]\,\\|]+$/ ) {
290	$answer =~ tr/a-zA-Z0-9_\-\+ \t\/@%\*\.\n^/#/c;	235	$answer =~ tr/a-zA-Z0-9_\-\+ \t\/@%\*\.\n^/#/c;
291	$errorno = "<BR>There are forbidden characters in your answer: $submittedAnswer<BR>";	236	$errorno = "<BR>There are forbidden characters in your answer: $submittedAnswer<BR>";
292	return ($answer,$errorno);	237	return ($answer,$errorno);
293	}	238	}
294	$errorno = 0;	239	$errorno = 0;
295	return($answer, $errorno);	240	return($answer, $errorno);
296	}	241	}
297		242
		243	sub nullSafetyFilter {
		244	return shift, 0; # no errors
		245	}
		246
298	1;	247	1;
299		248
300	__END__	249	__END__
301		250
302	=head1 SYNOPSIS	251	=head1 SYNOPSIS
303		252
304	$pg = WeBWorK::PG->new(	253	$pg = WeBWorK::PG->new(
305	$courseEnv, # a WeBWorK::CourseEnvironment object	254	$ce, # a WeBWorK::CourseEnvironment object
306	$userName,	255	$user, # a WeBWorK::DB::Record::User object
307	$sessionKey,	256	$sessionKey,
308	$setName,	257	$set, # a WeBWorK::DB::Record::UserSet object
309	$problemNumber,	258	$problem, # a WeBWorK::DB::Record::UserProblem object
		259	$psvn,
		260	$formFields # in &WeBWorK::Form::Vars format
310	{ # translation options	261	{ # translation options
311	displayMode => "images", # (plainText\|formattedText\|images)	262	displayMode => "images", # (plainText\|formattedText\|images)
312	showHints => 1, # (0\|1)	263	showHints => 1, # (0\|1)
313	showSolutions => 0, # (0\|1)	264	showSolutions => 0, # (0\|1)
314	refreshMath2img => 0, # (0\|1)	265	refreshMath2img => 0, # (0\|1)
315	processAnswers => 1, # (0\|1)	266	processAnswers => 1, # (0\|1)
316	},	267	},
317	$formFields # in WeBWorK::Form::Vars format
318	);	268	);
319		269
320	$translator = $pg->{translator}; # WeBWorK::PG::Translator	270	$translator = $pg->{translator}; # WeBWorK::PG::Translator
321	$body = $pg->{body_text}; # text string	271	$body = $pg->{body_text}; # text string
322	$header = $pg->{head_text}; # text string	272	$header = $pg->{head_text}; # text string
…		…
327	$warnings = $pg->{warnings}; # text string	277	$warnings = $pg->{warnings}; # text string
328	$flags = $pg->{flags}; # hash reference	278	$flags = $pg->{flags}; # hash reference
329		279
330	=head1 DESCRIPTION	280	=head1 DESCRIPTION
331		281
332	WeBWorK::PG encapsulates the PG translation process, making multiple calls to	282	WeBWorK::PG is a factory for modules which use the WeBWorK::PG API. Notable
333	WeBWorK::PG::Translator. Much of the flexibility of the Translator is hidden,	283	modules which use this API (and exist) are WeBWorK::PG::Local and
334	instead making choices that are appropriate for the webwork-modperl system.	284	WeBWorK::PG::Remote. The course environment key $pg{renderer} is consulted to
		285	determine which render to use.
335		286
336	=head1 CONSTRUCTION	287	=head1 THE WEBWORK::PG API
		288
		289	Modules which support this API must implement the following method:
337		290
338	=over	291	=over
339		292
340	=item new (ENVIRONMENT, USER, KEY, SET, PROBLEM, OPTIONS, FIELDS)	293	=item new ENVIRONMENT, USER, KEY, SET, PROBLEM, PSVN, FIELDS, OPTIONS
341		294
342	The C<new> method creates a translator, initializes it using the parameters	295	The C<new> method creates a translator, initializes it using the parameters
343	specified, translates a PG file, and processes answers. It returns a reference	296	specified, translates a PG file, and processes answers. It returns a reference
344	to a blessed hash containing the results of the translation process.	297	to a blessed hash containing the results of the translation process.
345		298
…		…
353		306
354	a WeBWorK::CourseEnvironment object	307	a WeBWorK::CourseEnvironment object
355		308
356	=item USER	309	=item USER
357		310
358	the name of the user for whom to render	311	a WeBWorK::User object
359		312
360	=item KEY	313	=item KEY
361		314
362	the session key of the current session	315	the session key of the current session
363		316
364	=item SET	317	=item SET
365		318
366	the name of the problem set from which to get the problem	319	a WeBWorK::Set object
367		320
368	=item PROBLEM	321	=item PROBLEM
369		322
370	the number of the problem to render	323	a WeBWorK::DB::Record::UserProblem object. The contents of the source_file
		324	field can specify a PG file either by absolute path or path relative to the
		325	"templates" directory. I<The caller should remove taint from this value before
		326	passing!>
371		327
372	=item OPTIONS	328	=item PSVN
373		329
374	a reference to a hash containing the following data:	330	the problem set version number
375
376	=over
377
378	=item displayMode
379
380	one of "plainText", "formattedText", or "images"
381
382	=item showHints
383
384	boolean, render hints
385
386	=item showSolutions
387
388	boolean, render solutions
389
390	=item refreshMath2img
391
392	boolean, force images created by math2img (in "images" mode) to be recreated,
393	even if the PG source has not been updated.
394
395	=item processAnswers
396
397	boolean, call answer evaluators and graders
398
399	=back
400		331
401	=item FIELDS	332	=item FIELDS
402		333
403	a reference to a hash (as returned by &WeBWorK::Form::Vars) containing form	334	a reference to a hash (as returned by &WeBWorK::Form::Vars) containing form
404	fields submitted by a problem processor. The translator will look for fields	335	fields submitted by a problem processor. The translator will look for fields
405	like "AnSwEr[0-9]" containing submitted student answers.	336	like "AnSwEr[0-9]" containing submitted student answers.
406		337
		338	=item OPTIONS
		339
		340	a reference to a hash containing the following data:
		341
		342	=over
		343
		344	=item displayMode
		345
		346	one of "plainText", "formattedText", or "images"
		347
		348	=item showHints
		349
		350	boolean, render hints
		351
		352	=item showSolutions
		353
		354	boolean, render solutions
		355
		356	=item refreshMath2img
		357
		358	boolean, force images created by math2img (in "images" mode) to be recreated,
		359	even if the PG source has not been updated. FIXME: remove this option.
		360
		361	=item processAnswers
		362
		363	boolean, call answer evaluators and graders
		364
		365	=back
		366
407	=back	367	=back
408		368
409	=head2 RETURN VALUE	369	=head2 RETURN VALUE
410		370
411	The C<new> method returns a blessed hash reference containing the following	371	The C<new> method returns a blessed hash reference containing the following
…		…
452		412
453	A hash containing PG_flags (see the Translator docs).	413	A hash containing PG_flags (see the Translator docs).
454		414
455	=back	415	=back
456		416
457	=head1 OPERATION	417	=head1 METHODS PROVIDED BY THE BASE CLASS
458		418
459	WeBWorK::PG goes through the following operations when constructed:	419	The following methods are provided for use by subclasses of WeBWorK::PG.
460		420
461	=over	421	=over
462		422
463	=item Get database information	423	=item defineProblemEnvir ENVIRONMENT, USER, KEY, SET, PROBLEM, PSVN, FIELDS, OPTIONS
464		424
465	Retrieve information about the current user, set, and problem from the	425	Generate a problem environment hash to pass to the renderer.
466	database.
467		426
468	=item Create a translator	427	=item translateDisplayModeNames NAME
469		428
470	Instantiate a WeBWorK::PG::Translator object.	429	NAME contains
471
472	=item Set the directory hash
473
474	Set the translator's directory hash (courseScripts, macros, templates, and temp
475	directories) from the course environment.
476
477	=item Evaluate PG modules
478
479	Using the module list from the course environment (pg->modules), perform a
480	"use"-like operation to evaluate modules at runtime.
481
482	=item Set the problem environment
483
484	Use data from the user, set, and problem, as well as the course environemnt and
485	translation options, to set the problem environment.
486
487	=item Initialize the translator
488
489	Call &WeBWorK::PG::Translator::initialize. What more do you want?
490
491	=item Load PG.pl and dangerousMacros.pl
492
493	These macros must be loaded without opcode masking, so they are loaded here.
494
495	=item Set the opcode mask
496
497	Set the opcode mask to the default specified by WeBWorK::PG::Translator.
498
499	=item Load the problem source
500
501	Give the problem source to the translator.
502
503	=item Install a safety filter
504
505	The safety filter is used to preprocess student input before evaluation. The
506	default safety filter, &WeBWorK::PG::safetyFilter, is used.
507
508	=item Translate the problem source
509
510	Call &WeBWorK::PG::Translator::translate to render the problem source into the
511	format given by the display mode.
512
513	=item Process student answers
514
515	Use form field inputs to evaluate student answers.
516
517	=item Load the problem state
518
519	Use values from the database to initialize the problem state, so that the
520	grader will have a point of reference.
521
522	=item Determine an entry order
523
524	Use the ANSWER_ENTRY_ORDER flag to determine the order of answers in the
525	problem. This is important for problems with dependancies among parts.
526
527	=item Install a grader
528
529	Use the PROBLEM_GRADER_TO_USE flag, or a default from the course environment,
530	to install a grader.
531
532	=item Grade the problem
533
534	Use the selected grader to grade the problem.
535		430
536	=back	431	=back
537		432
538	=head1 AUTHOR	433	=head1 AUTHOR
539		434

 Legend:



Removed from v.455
 


changed lines


 
Added in v.2217
 Legend:



Removed from v.455
 


changed lines


 
Added in v.2217
-Removed from v.455
+Added in v.2217

aubreyja at gmail dot com	ViewVC Help
Powered by ViewVC 1.0.9