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.
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.
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.
Old name for LABELED_ANS(). DEPRECATED.
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.
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);There are three 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.
# 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.
includePGtext
read_whole_problem_file
convertPath
fileFromPath
directoryFromPath
createDirectory$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.