## Forum archive 2000-2006

### Michael Gage - PG.pl

by Arnold Pizer -
Number of replies: 0
 PG.pl topic started 5/22/2000; 9:29:39 PMlast post 5/22/2000; 9:29:39 PM
Michael Gage - PG.pl
5/22/2000; 9:29:39 PM (reads: 2978, responses: 0)

# NAME

    PG.pl --- located in the courseScripts directory.    Defines the Program Generating language at the most basic level.

# SYNPOSIS

    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

# DESCRIPTION

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

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

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

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

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

    RESUME_RENDERING();

## ANS()

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

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

## INITIALIZE_PG()

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