PGcore

Jump to: Site Navigation

DESCRIPTION

This file provides the fundamental macros that define the PG language. It maintains a problem's text, header text, and answers:

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.

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.

POST_HEADER_TEXT()
 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()
 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.

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.

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.

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().

Message channels

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_messages

These 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.

insertGraph

        # returns a path to the file containing the graph image.
        $filePath = insertGraph($graphObject);

insertGraph writes a GIF or PNG 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.

getUniqueName

        # 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.

Macros from IO.pm

                includePGtext
                read_whole_problem_file
                convertPath
                getDirDelim
                fileFromPath
                directoryFromPath
                createDirectory

surePathToTmpFile

        $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.


Site Navigation