|
PG.pl --- located in the courseScripts directory.
Defines the Program Generating language at the most basic level.
The basic PG problem structure:
DOCUMENT(); # should be the first statment in the problem
loadMacros(.....); # (optional) load other macro files if needed.
# (loadMacros is defined in F<dangerousMacros.pl>)
HEADER_TEXT(...); # (optional) used only for inserting javaScript into problems.
# # insert text of problems
TEXT("Problem text to be",
"displayed. Enter 1 in this blank:",
ANS_RULE(1,30) # ANS_RULE() defines an answer blank 30 characters long.
# It is defined in F<PGbasicmacros.pl>
);
ANS( answer_evalutors); # see F<PGanswermacros.pl> for examples of answer evaluatiors.
ENDDOCUMENT() # must be the last statement in the problem
As described in the synopsis, this file and the macros DOCUMENT() and ENDDOCUMENT()
determine
the interface between problems written in the PG language and the rest of WeBWorK,
in particular
the subroutine createPGtext(() in the file translate.pl.
DOCUMENT() must be the first statement in each problem template.
It initializes variables,
in particular all of the contents of the
environment variable become defined in the problem enviroment.
(See
webwork_system_html/docs/techdescription/pglanguage/PGenvironment.html)
ENDDOCUMENT() must the last executable statement in any problem template. It returns
the rendered problem, answer evaluators and other flags to the rest of WeBWorK, specificially
to the routine createPGtext() defined in translate.pl
The HEADER_TEXT(), TEXT(), and ANS() functions load the
header text string, the problem text string.
and the answer evaulator queue respectively.
DOCUMENT() must be the first statement in each problem template. It can
only be used once in each problem.
DOCUMENT() initializes some empty variables and via INITIALIZE_PG() unpacks the
variables in the %envir variable which is implicitly passed to the problem. It must
be the first statement in any problem template. It
also unpacks any answers submitted and places them in the @submittedAnswer list,
saves the problem seed in $PG_original_problemSeed in case you need it later, and
initializes the pseudo random number generator object in $PG_random_generator.
You can reset the standard number generator using the command:
$PG_random_generator->srand($new_seed_value);
(See also SRAND in the PGbasicmacros.pl file.)
The
environment variable contents is defined in
webwork_system_html/docs/techdescription/pglanguage/PGenvironment.html
HEADER_TEXT("string1", "string2", "string3");
The HEADER_TEXT()
function concatenates its arguments and places them in the output
header text string. It is used for material which is destined to be placed in
the header of the html problem -- such as javaScript code.
It can be used more than once in a file.
TEXT("string1", "string2", "string3");
The TEXT() function concatenates its arguments and places them in the output
text string. TEXT() is the function which defines text which will appear in the problem.
All text must be an argument to this function. Any other statements
are calculations (done in perl) which will not directly appear in the
output. Think of this as the "print" function for the .pg language.
It can be used more than once in a file.
STOP_RENDERING() unless all_answers_are_correct;
No text is printed and no answer blanks or answer evaluators are stored or processed
until
RESUME_RENDERING() is executed.
RESUME_RENDERING();
Resumes processing of text, answer blanks, and
answer evaluators.
ANS(answer_evaluator1, answer_evaluator2, answer_evaluator3,...)
Places the answer evaluators in the unlabeled answer_evaluator queue. They will
be paired
with unlabeled answer rules (answer entry blanks) in the order entered. This is the
standard
method for entering answers.
LABELED_ANS(answer_evaluater_name1, answer_evaluator1, answer_evaluater_name2,answer_evaluator2,...)
Places the answer evaluators in the labeled answer_evaluator hash. This allows pairing
of
labeled answer evaluators and labeled answer rules which may not have been entered
in the same
order.
ENDDOCUMENT() must the last executable statement in any problem template. It can
only appear once. It returns
an array consisting of
A reference to a string containing the rendered text of the problem.
A reference to a string containing text to be placed in the header
(for javaScript)
A reference to the array containing the answer evaluators.
(May be changed to a hash soon.)
A reference to an associative array (hash) containing various flags.
The following flags are set by ENDDOCUMENT:
(1) showPartialCorrectAnswers -- determines whether students are told which
of their answers in a problem are wrong.
(2) recordSubmittedAnswers -- determines whether students submitted answers
are saved.
(3) refreshCachedImages -- determines whether the cached image of the problem
in typeset mode is always refreshed (i.e. setting this to 1 means cached
images are not used).
(4) solutionExits -- indicates the existence of a solution.
(5) hintExits -- indicates the existence of a hint.
(6) comment -- contents of COMMENT commands if any.
(7) showHintLimit -- determines the number of attempts after which hint(s) will
be shown
(8) PROBLEM_GRADER_TO_USE -- chooses the problem grader to be used in this order
(a) A problem grader specified by the problem using:
install_problem_grader(\&grader);
(b) One of the standard problem graders defined in PGanswermacros.pl when
set to
'std_problem_grader' or 'avg_problem_grader' by the environment variable
$PG_environment{PROBLEM_GRADER_TO_USE}
(c) A subroutine referenced by $PG_environment{PROBLEM_GRADER_TO_USE}
(d) The default &std_problem_grader defined in PGanswermacros.pl
This is executed each DOCUMENT() is called. For backward compatibility
loadMacros also checks whether the macroDirectory has been defined
and if not, it runs INITIALIZE_PG() and issues a warning.
File path = /ww/webwork/pg/macros/PG.pl
<| Post or View Comments |> |