WeBWorKdocs
Home Current UR courses Visitor page Intro to WeBWorK WeBWorK 2 Twiki WW Community Grant Support & awards Discussion group Problem library Write/modify problems Create & manage course Tutorial on running a course HowTos FAQ WeBWorK2 FAQ Software Download How to Install WW server Feedback Site Map Change preferences Change password	Prev | Next | pod NAME SYNPOSIS DESCRIPTION USAGE MACROS PRIVATE MACROS SEE ALSO NAME PG.pl - Provides core Program Generation Language functionality. SYNPOSIS In a PG problem: 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. TEXT( # insert text of problems "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 DESCRIPTION This file provides the fundamental macros that define the PG language. It maintains a problem's text, header text, and answers: Problem text: The text to appear in the body of the problem. See TEXT() below. Header text: When a problem is processed in an HTML-based display mode, this variable can contain text that the caller should place in the HEAD of the resulting HTML page. See HEADER_TEXT() below. Implicitly-labeled answers: Answers that have not been explicitly assigned names, and are associated with their answer blanks by the order in which they appear in the problem. These types of answers are designated using the ANS() macro. Explicitly-labeled answers: Answers that have been explicitly assigned names with the LABELED_ANS() macro, or a macro that uses it. An explicitly- labeled answer is associated with its answer blank by name. "Extra" answers: Names of answer blanks that do not have a 1-to-1 correspondance to an answer evaluator. For example, in matrix problems, there will be several input fields that correspond to the same answer evaluator. USAGE This file is automatically loaded into the namespace of every PG problem. The macros within can then be called to define the structure of the problem. DOCUMENT() should be the first executable statement in any problem. It initializes vriables and defines the problem environment. ENDDOCUMENT() must be the last executable statement in any problem. It packs up the results of problem processing for delivery back to WeBWorK. The HEADER_TEXT(), TEXT(), and ANS() macros add to the header text string, body text string, and answer evaluator queue, respectively. MACROS These macros may be used from PG problem files. DOCUMENT() DOCUMENT() should be the first statement in each problem template. It can only be used once in each problem. DOCUMENT() initializes some empty variables and unpacks the variables in the %envir hash which is implicitly passed from WeBWorK to the problem. It must be the first statement in any problem. 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. HEADER_TEXT() HEADER_TEXT("string1", "string2", "string3"); HEADER_TEXT() concatenates its arguments and appends them to the stored header text string. It can be used more than once in a file. The macro is used for material which is destined to be placed in the HEAD of the page when in HTML mode, such as JavaScript code. Spaces are placed between the arguments during concatenation, but no spaces are introduced between the existing content of the header text string and the new content being appended. TEXT() TEXT("string1", "string2", "string3"); TEXT() concatenates its arguments and appends them to the stored problem text string. It is used to define the text which will appear in the body of the problem. It can be used more than once in a file. This macro has no effect if rendering has been stopped with the STOP_RENDERING() macro. This macro defines text which will appear in the problem. All text must be passed to this macro, passed to another macro that calls this macro, or included in a BEGIN_TEXT/END_TEXT block, which uses this macro internally. No other statements in a PG file will directly appear in the output. Think of this as the "print" function for the PG language. Spaces are placed between the arguments during concatenation, but no spaces are introduced between the existing content of the header text string and the new content being appended. ANS() TEXT(ans_rule(), ans_rule(), ans_rule()); ANS($answer_evaluator1, $answer_evaluator2, $answer_evaluator3); Adds the answer evaluators listed to the list of unlabeled answer evaluators. They will be paired with unlabeled answer rules (a.k.a. answer blanks) in the order entered. This is the standard method for entering answers. In the above example, answer_evaluator1 will be associated with the first answer rule, answer_evaluator2 with the second, and answer_evaluator3 with the third. In practice, the arguments to ANS() will usually be calls to an answer evaluator generator such as the cmp() method of MathObjects or the num_cmp() macro in PGanswermacros.pl. LABELED_ANS() TEXT(labeled_ans_rule("name1"), labeled_ans_rule("name2")); LABELED_ANS(name1 => answer_evaluator1, name2 => answer_evaluator2); Adds the answer evaluators listed to the list of labeled answer evaluators. They will be paired with labeled answer rules (a.k.a. answer blanks) in the order entered. This allows pairing of answer evaluators and answer rules that may not have been entered in the same order. NAMED_ANS() Old name for LABELED_ANS(). DEPRECATED. STOP_RENDERING() STOP_RENDERING() unless all_answers_are_correct(); Temporarily suspends accumulation of problem text and storing of answer blanks and answer evaluators until RESUME_RENDERING() is called. RESUME_RENDERING() RESUME_RENDERING(); Resumes accumulating problem text and storing answer blanks and answer evaluators. Reverses the effect of STOP_RENDERING(). ENDDOCUMENT() ENDDOCUMENT(); When PG problems are evaluated, the result of evaluating the entire problem is interpreted as the return value of ENDDOCUMENT(). Therefore, ENDDOCUMENT() must be the last executable statement of every problem. It can only appear once. It returns a list 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 HEAD block when in and HTML-based mode (e.g. for JavaScript). A reference to the hash mapping answer labels to answer evaluators. A reference to a hash containing various flags: showPartialCorrectAnswers: determines whether students are told which of their answers in a problem are wrong. recordSubmittedAnswers: determines whether students submitted answers are saved. 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). solutionExits: indicates the existence of a solution. hintExits: indicates the existence of a hint. comment: contents of COMMENT commands if any. showHintLimit: determines the number of attempts after which hint(s) will be shown PROBLEM_GRADER_TO_USE: a reference to the chosen problem grader. ENDDOCUMENT chooses the problem grader as follows: If a problem grader has been chosen in the problem by calling install_problem_grader(\&grader), it is used. Otherwise, if the PROBLEM_GRADER_TO_USE PG environment variable contains a reference to a subroutine, it is used. Otherwise, if the PROBLEM_GRADER_TO_USE PG environment variable contains the string std_problem_grader or the string avg_problem_grader, &std_problem_grader or &avg_problem_grader are used. These graders are defined in PGanswermacros.pl. Otherwise, the PROBLEM_GRADER_TO_USE flag will contain an empty value and the PG translator should select &std_problem_grader. PRIVATE MACROS These macros should only be used by other macro files. In practice, they are used exclusively by PGbasicmacros.pl. inc_ans_rule_count() NEW_ANS_NAME(inc_ans_rule_count()); Increments the internal count of the number of answer blanks that have been defined ($ans_rule_count) and returns the new count. This should only be used when one is about to define a new answer blank, for example with NEW_ANS_NAME(). RECORD_ANS_NAME() RECORD_ANS_NAME("label"); Records the label for an answer blank. Used internally by PGbasicmacros.pl to record the order of explicitly-labelled answer blanks. NEW_ANS_NAME() NEW_ANS_NAME($num); Generates an answer label from the supplied answer number. The label is added to the list of implicity-labeled answers. Used internally by PGbasicmacros.pl to generate labels for unlabeled answer blanks. ANS_NUM_TO_NAME() ANS_NUM_TO_NAME($num); Generates an answer label from the supplied answer number, but does not add it to the list of inplicitly-labeled answers. Used internally by PGbasicmacros.pl in generating answers blanks that use radio buttons or check boxes. (This type of answer blank uses multiple HTML INPUT elements with the same label, but the label should only be added to the list of implicitly- labeled answers once.) RECORD_FROM_LABEL() RECORD_FORM_LABEL("label"); Stores the label of a form field in the "extra" answers list. This is used to keep track of answer blanks that are not associated with an answer evaluator. NEW_ANS_ARRAY_NAME() NEW_ANS_ARRAY_NAME($num, $row, $col); Generates a new answer label for an array (vector) element and adds it to the list of implicitly-labeled answers. NEW_ANS_ARRAY_NAME_EXTENSION() NEW_ANS_ARRAY_NAME_EXTENSION($num, $row, $col); Generate an additional answer label for an existing array (vector) element and add it to the list of "extra" answers. get_PG_ANSWERS_HASH() get_PG_ANSWERS_HASH(); get_PG_ANSWERS_HASH($key); includePGproblem($filePath) includePGproblem($filePath); Essentially runs the pg problem specified by $filePath, which is a path relative to the top of the templates directory. The output of that problem appears in the given problem. SEE ALSO PGbasicmacros.pl, PGanswermacros.pl. File path = /ww/webwork/pg/macros/PG.pl <| Post or View Comments |> Prev | Next | pod
Last update: Sunday, January 28, 2001 at 5:45:02 PM. This site maintained using Manila and Frontier software.