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-named 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 method.
Explicitly-named answers: Answers that have been explicitly assigned names with the NAMED_ANS method, or a macro that uses it. An explicitly- named 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.
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.
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.
POST_HEADER_TEXT("string1", "string2", "string3");POST_HEADER_TEXT() concatenates its arguments and appends them to the stored post_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 iimmediately after the HEAD of the page as the first item in the body, before the main problem form 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("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.
Associates answer names with answer evaluators. If the given answer name has a response group in the PG_ANSWERS_HASH, then the evaluator is added to that response group. Otherwise the name and evaluator are added to the hash of explicitly named answer evaluators. They will be paired with explicitly named answer rules by name. This allows pairing of answer evaluators and answer rules that may not have been entered in the same order.
An example of the usage is:
TEXT(NAMED_ANS_RULE("name1"), NAMED_ANS_RULE("name2"));
NAMED_ANS(name1 => answer_evaluator1, name2 => answer_evaluator2);Note that internally implicitly named evaluators are also associated with their names via this method.
Registers answer evaluators to be implicitly associated with answer names. If there is an answer name in the implicit answer name stack, then a given answer evaluator will be paired with the first name in the stack. Otherwise the evaluator will be pushed onto the implicit answer evaluator stack. This is the standard method for entering answers.
TEXT(ans_rule(), ans_rule(), ans_rule());
ANS($answer_evaluator1, $answer_evaluator2, $answer_evaluator3);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. Note that if the ANS call is made before the ans_rule calls, the same pairing would occur.
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();Resumes accumulating problem text and storing answer blanks and answer evaluators. Reverses the effect of STOP_RENDERING().
$str = decode_base64($coded_str);
$coded_str = encode_base64($str);# returns a path to the file containing the graph image.
$filePath = insertGraph($graphObject);insertGraph writes an image file to the images subdirectory of the current course's HTML temp directory. The file name is obtained from the graph object. Warnings are issued if errors occur while writing to the file.
Returns a string containing the full path to the temporary file containing the image. This is most often used in the construct
TEXT(alias(insertGraph($graph)));where alias converts the directory address to a URL when serving HTML pages and insures that an EPS file is generated when creating TeX code for downloading.
Note that a file is only actually written in the temporary directory if the file does not already exist, or the last modified time of the problem file is sooner than the last modified time of existing temporary file, or the set is an undefined set (for instance, the problem is loaded from the library browser), or $refreshCachedImages is true.
# Returns a unique file name for use in the problem
$name = getUniqueName('png');getUniqueName generates a unique file name for use in a problem. Its single argument is the file type. This is used internally by PGgraphmacros.pl and PGtikz.pl.
$path = surePathToTmpFile($path);Creates all of the intermediate directories between the tempDirectory
If $path begins with the tempDirectory path, then the path is treated as absolute. Otherwise, the path is treated as relative the the course temp directory.
includePGtext
read_whole_problem_file
fileFromPath
directoryFromPathThere are two message channels $PG->debug_message() or in PG: DEBUG_MESSAGE() $PG->warning_message() or in PG: WARN_MESSAGE()
They behave the same way, it is simply convention as to how they are used.
To report the messages use:
$PG->get_debug_messages
$PG->get_warning_messagesThese are used in Problem.pm for example to report any errors.
There is also
$PG->internal_debug_message()
$PG->get_internal_debug_message
$PG->clear_internal_debug_messages();There were times when things were buggy enough that only the internal_debug_message which are not saved inside the PGcore object would report.