[system] / trunk / pg / macros / PG.pl Repository:
ViewVC logotype

View of /trunk/pg/macros/PG.pl

Parent Directory Parent Directory | Revision Log Revision Log


Revision 1140 - (download) (as text) (annotate)
Thu Jun 12 19:14:38 2003 UTC (16 years, 7 months ago) by gage
File size: 13881 byte(s)
Answer labels are now prefixed by a Quiz prefix which allows more
than one problem to appear on the same page.
-- Mike

    1 #!/usr/local/bin/webwork-perl
    2 
    3 # This file provided the fundamental macros for the pg language
    4 # These macros define the interface between the problems written by
    5 # the professor and the processing which occurs in the script
    6 # processProblem.pl
    7 
    8 
    9 BEGIN {
   10   be_strict();
   11 }
   12 
   13 sub _PG_init{
   14 
   15 }
   16 
   17 #package PG;
   18 
   19 
   20 =head1 NAME
   21 
   22   PG.pl --- located in the courseScripts directory.
   23   Defines the Program Generating language at the most basic level.
   24 
   25 =head1 SYNPOSIS
   26 
   27   The basic PG problem structure:
   28 
   29   DOCUMENT();          # should be the first statment in the problem
   30   loadMacros(.....);   # (optional) load other macro files if needed.
   31                        # (loadMacros is defined in F<dangerousMacros.pl>)
   32 
   33   HEADER_TEXT(...);    # (optional) used only for inserting javaScript into problems.
   34 
   35   #            #  insert text of problems
   36   TEXT("Problem text to be",
   37        "displayed. Enter 1 in this blank:",
   38        ANS_RULE(1,30)  #  ANS_RULE() defines an answer blank 30 characters long.
   39                        #  It is defined in F<PGbasicmacros.pl>
   40        );
   41 
   42 
   43   ANS( answer_evalutors);  # see F<PGanswermacros.pl> for examples of answer evaluatiors.
   44 
   45   ENDDOCUMENT()        # must be the last statement in the problem
   46 
   47 
   48 
   49 =head1 DESCRIPTION
   50 
   51 As described in the synopsis, this file and the macros C<DOCUMENT()> and C<ENDDOCUMENT()> determine
   52 the interface between problems written in the PG language and the rest of B<WeBWorK>, in particular
   53 the subroutine C<createPGtext(()> in the file F<translate.pl>.
   54 
   55 C<DOCUMENT()> must be the first statement in each problem template.
   56 It  initializes variables,
   57 in particular all of the contents of the
   58 environment variable  become defined in the problem enviroment.
   59 (See
   60 L</webwork_system_html/docs/techdescription/pglanguage/PGenvironment.html>)
   61 
   62 ENDDOCUMENT() must the last executable statement in any problem template.  It returns
   63 the rendered problem, answer evaluators and other flags to the rest of B<WeBWorK>, specificially
   64 to the routine C<createPGtext()> defined in F<translate.pl>
   65 
   66 
   67 The C<HEADER_TEXT()>, C<TEXT()>, and C<ANS()> functions load the
   68 header text string, the problem text string.
   69 and the answer evaulator queue respectively.
   70 
   71 
   72 =cut
   73 
   74 
   75 #  Private variables for the PG.pl file.
   76 
   77 my ($STRINGforOUTPUT, $STRINGforHEADER_TEXT, @PG_ANSWERS, @PG_UNLABELED_ANSWERS);
   78 my %PG_ANSWERS_HASH ;
   79 
   80 #   DOCUMENT must come early in every .pg file, before any answers or text are
   81 # defined.  It initializes the variables.
   82 # It can appear only once.
   83 
   84 =head2 DOCUMENT()
   85 
   86 C<DOCUMENT()> must be the first statement in each problem template.  It can
   87 only be used once in each problem.
   88 
   89 C<DOCUMENT()> initializes some empty variables and via C<INITIALIZE_PG()> unpacks the
   90 variables in the C<%envir> variable which is implicitly passed to the problem. It must
   91 be the first statement in any problem template. It
   92 also unpacks any answers submitted and places them in the C<@submittedAnswer> list,
   93 saves the problem seed in C<$PG_original_problemSeed> in case you need it later, and
   94 initializes the pseudo random number generator object in C<$PG_random_generator>.
   95 
   96 You can reset the standard number generator using the command:
   97 
   98   $PG_random_generator->srand($new_seed_value);
   99 
  100 (See also C<SRAND> in the L<PGbasicmacros.pl> file.)
  101 
  102 The
  103 environment variable contents is defined in
  104 L</webwork_system_html/docs/techdescription/pglanguage/PGenvironment.html>
  105 
  106 
  107 =cut
  108 
  109 sub DOCUMENT {
  110   $STRINGforOUTPUT ="";
  111     $STRINGforHEADER_TEXT ="";
  112   @PG_ANSWERS=();
  113   @main::PG_ANSWER_ENTRY_ORDER = ();
  114   @PG_UNLABELED_ANSWERS = ();
  115   %PG_ANSWERS_HASH = ();
  116   $main::ANSWER_PREFIX = 'AnSwEr';
  117   %main::PG_FLAGS=();  #global flags
  118   $main::showPartialCorrectAnswers = 0 unless defined($main::showPartialCorrectAnswers );
  119   $main::showHint = 1 unless defined($main::showHint);
  120   $main::solutionExists =0;
  121   $main::hintExists =0;
  122   %main::gifs_created = ();
  123 
  124   die "The environment variable envir has not been defined" unless defined(%main::envir);
  125 
  126     foreach my $var ( keys %main::envir ) {
  127        eval("\$main::$var =\$main::envir{'$var'}");
  128        warn "Problem defining ", q{\$main::$var}, " while inititializing the PG problem: $@" if $@;
  129     }
  130 
  131   @main::submittedAnswers = @{$main::refSubmittedAnswers} if defined($main::refSubmittedAnswers);
  132   $main::PG_original_problemSeed = $main::problemSeed;
  133   $main::PG_random_generator = new PGrandom($main::problemSeed) || die "Can't create random number generator.";
  134   $main::ans_rule_count = 0;  # counts questions
  135 
  136     # end unpacking of environment variables.
  137     $main::QUIZ_PREFIX = '' unless defined($main::QUIZ_PREFIX)
  138 }
  139 
  140 # HEADER_TEXT is for material which is destined to be placed in the header of the html problem -- such
  141 #   as javaScript code.
  142 
  143 =head2 HEADER_TEXT()
  144 
  145 
  146   HEADER_TEXT("string1", "string2", "string3");
  147 
  148 The C<HEADER_TEXT()>
  149 function concatenates its arguments and places them in the output
  150 header text string.  It is used for material which is destined to be placed in
  151 the header of the html problem -- such as javaScript code.
  152  It can be used more than once in a file.
  153 
  154 
  155 =cut
  156 
  157 sub HEADER_TEXT {
  158   my @in = @_;
  159   $STRINGforHEADER_TEXT .= join(" ",@in);
  160   }
  161 
  162 # TEXT is the function which defines text which will appear in the problem.
  163 # All text must be an argument to this function.  Any other statements
  164 #   are calculations (done in perl) which will not directly appear in the
  165 # output.  Think of this as the "print" function for the .pg language.
  166 # It can be used more than once in a file.
  167 
  168 =head2 TEXT()
  169 
  170   TEXT("string1", "string2", "string3");
  171 
  172 The C<TEXT()> function concatenates its arguments and places them in the output
  173 text string. C<TEXT()> is the function which defines text which will appear in the problem.
  174 All text must be an argument to this function.  Any other statements
  175 are calculations (done in perl) which will not directly appear in the
  176 output.  Think of this as the "print" function for the .pg language.
  177 It can be used more than once in a file.
  178 
  179 =cut
  180 
  181 sub TEXT {
  182   my @in = @_;
  183   $STRINGforOUTPUT .= join(" ",@in);
  184   }
  185 
  186 
  187 
  188 =head2 ANS()
  189 
  190   ANS(answer_evaluator1, answer_evaluator2, answer_evaluator3,...)
  191 
  192 Places the answer evaluators in the unlabeled answer_evaluator queue.  They will be paired
  193 with unlabeled answer rules (answer entry blanks) in the order entered.  This is the standard
  194 method for entering answers.
  195 
  196   LABELED_ANS(answer_evaluater_name1, answer_evaluator1, answer_evaluater_name2,answer_evaluator2,...)
  197 
  198 Places the answer evaluators in the labeled answer_evaluator hash.  This allows pairing of
  199 labeled answer evaluators and labeled answer rules which may not have been entered in the same
  200 order.
  201 
  202 =cut
  203 
  204 sub ANS{             # store answer evaluators which have not been explicitly labeled
  205   my @in = @_;
  206   while (@in ) {
  207          warn("<BR><B>Error in ANS:$in[0]</B> -- inputs must be references to
  208                       subroutines<BR>")
  209       unless ref($in[0]);
  210       push(@PG_ANSWERS, shift @in );
  211       }
  212 }
  213 sub LABELED_ANS {  #a better alias for NAMED_ANS
  214   &NAMED_ANS;
  215 }
  216 
  217 sub NAMED_ANS{     # store answer evaluators which have been explicitly labeled (submitted in a hash)
  218   my @in = @_;
  219   while (@in ) {
  220     my $label = shift @in;
  221     $label = $main::QUIZ_PREFIX.$label;
  222     my $ans_eval = shift @in;
  223     TEXT("<BR><B>Error in NAMED_ANS:$in[0]</B>
  224           -- inputs must be references to subroutines<BR>")
  225       unless ref($ans_eval);
  226     $PG_ANSWERS_HASH{$label}= $ans_eval;
  227   }
  228 }
  229 sub RECORD_ANS_NAME {     # this maintains the order in which the answer rules are printed.
  230   my $label = shift;
  231   push(@main::PG_ANSWER_ENTRY_ORDER, $label);
  232   $label;
  233 }
  234 
  235 sub NEW_ANS_NAME {        # this keeps track of the answers which are entered implicitly,
  236                           # rather than with a specific label
  237     my $number=shift;
  238     my $label = "$main::QUIZ_PREFIX$main::ANSWER_PREFIX$number";
  239     push(@PG_UNLABELED_ANSWERS,$label);
  240     $label;
  241 }
  242 sub ANS_NUM_TO_NAME {     # This converts a number to an answer label for use in
  243                           # radio button and check box answers. No new answer
  244                           # name is recorded.
  245     my $number=shift;
  246     my $label = "$main::QUIZ_PREFIX$main::ANSWER_PREFIX$number";
  247     $label;
  248 }
  249 
  250 my $vecnum;
  251 
  252 sub NEW_ANS_ARRAY_NAME {        # this keeps track of the answers which are entered implicitly,
  253                           # rather than with a specific label
  254     my $number=shift;
  255     $vecnum = 0;
  256     my $row = shift;
  257     my $col = shift;
  258     my $label = "ArRaY"."$number"."["."$vecnum".","."$row".","."$col"."]";
  259     push(@PG_UNLABELED_ANSWERS,$label);
  260     $label;
  261 }
  262 
  263 sub NEW_ANS_ARRAY_NAME_EXTENSION {        # this keeps track of the answers which are entered implicitly,
  264                           # rather than with a specific label
  265     my $number=shift;
  266     my $row = shift;
  267     my $col = shift;
  268     if( $row == 0 && $col == 0 ){
  269       $vecnum += 1;
  270     }
  271     my $label = "ArRaY"."$number"."["."$vecnum".","."$row".","."$col"."]";
  272     $label;
  273 }
  274 
  275 # ENDDOCUMENT must come at the end of every .pg file.
  276 #   It exports the resulting text of the problem, the text to be used in HTML header material
  277 #   (for javaScript), the list of answer evaluators and any other flags.  It can appear only once and
  278 #   it MUST be the last statement in the problem.
  279 
  280 =head2 ENDDOCUMENT()
  281 
  282 ENDDOCUMENT() must the last executable statement in any problem template.  It can
  283 only appear once.  It returns
  284 an array consisting of
  285 
  286   A reference to a string containing the rendered text of the problem.
  287   A reference to a string containing text to be placed in the header
  288                (for javaScript)
  289   A reference to the array containing the answer evaluators.
  290                (May be changed to a hash soon.)
  291   A reference to an associative array (hash) containing various flags.
  292 
  293   The following flags are set by ENDDOCUMENT:
  294   (1) showPartialCorrectAnswers  -- determines whether students are told which
  295       of their answers in a problem are wrong.
  296   (2) recordSubmittedAnswers  -- determines whether students submitted answers
  297       are saved.
  298   (3) refreshCachedImages  -- determines whether the cached image of the problem
  299       in typeset mode is always refreshed (i.e. setting this to 1 means cached
  300       images are not used).
  301   (4) solutionExits   -- indicates the existence of a solution.
  302   (5) hintExits   -- indicates the existence of a hint.
  303   (6) showHintLimit -- determines the number of attempts after which hint(s) will be shown
  304 
  305   (7) PROBLEM_GRADER_TO_USE -- chooses the problem grader to be used in this order
  306     (a) A problem grader specified by the problem using:
  307         install_problem_grader(\&grader);
  308     (b) One of the standard problem graders defined in PGanswermacros.pl when set to
  309         'std_problem_grader' or 'avg_problem_grader' by the environment variable
  310         $PG_environment{PROBLEM_GRADER_TO_USE}
  311     (c) A subroutine referenced by $PG_environment{PROBLEM_GRADER_TO_USE}
  312     (d) The default &std_problem_grader defined in PGanswermacros.pl
  313 
  314 
  315 =cut
  316 
  317 sub ENDDOCUMENT {
  318 
  319     my $index=0;
  320     foreach my $label (@PG_UNLABELED_ANSWERS) {
  321         if ( defined($PG_ANSWERS[$index]) ) {
  322         $PG_ANSWERS_HASH{"$label"}= $PG_ANSWERS[$index];
  323       } else {
  324         warn "No answer provided by instructor for answer $label";
  325       }
  326       $index++;
  327     }
  328 
  329     $STRINGforOUTPUT .="\n";
  330    ##eval q{  #make sure that "main" points to the current safe compartment by evaluating these lines.
  331     $main::PG_FLAGS{'showPartialCorrectAnswers'} = $main::showPartialCorrectAnswers;
  332     $main::PG_FLAGS{'recordSubmittedAnswers'} = $main::recordSubmittedAnswers;
  333     $main::PG_FLAGS{'refreshCachedImages'} = $main::refreshCachedImages;
  334     $main::PG_FLAGS{'hintExists'} = $main::hintExists;
  335     $main::PG_FLAGS{'showHintLimit'} = $main::showHint;
  336     $main::PG_FLAGS{'solutionExists'} = $main::solutionExists;
  337     $main::PG_FLAGS{ANSWER_ENTRY_ORDER} = \@main::PG_ANSWER_ENTRY_ORDER;
  338     $main::PG_FLAGS{ANSWER_PREFIX} = $main::ANSWER_PREFIX;
  339     # install problem grader
  340     if (defined($main::PG_FLAGS{PROBLEM_GRADER_TO_USE}) ) {
  341       # problem grader defined within problem -- no further action needed
  342     } elsif ( defined( $main::envir{PROBLEM_GRADER_TO_USE} ) ) {
  343       if (ref($main::envir{PROBLEM_GRADER_TO_USE}) eq 'CODE' ) {         # user defined grader
  344         $main::PG_FLAGS{PROBLEM_GRADER_TO_USE} = $main::envir{PROBLEM_GRADER_TO_USE};
  345       } elsif ($main::envir{PROBLEM_GRADER_TO_USE} eq 'std_problem_grader' ) {
  346         if (defined(&std_problem_grader) ){
  347           $main::PG_FLAGS{PROBLEM_GRADER_TO_USE} = \&std_problem_grader; # defined in PGanswermacros.pl
  348         } # std_problem_grader is the default in any case so don't give a warning.
  349       } elsif ($main::envir{PROBLEM_GRADER_TO_USE} eq 'avg_problem_grader' ) {
  350         if (defined(&avg_problem_grader) ){
  351           $main::PG_FLAGS{PROBLEM_GRADER_TO_USE} = \&avg_problem_grader; # defined in PGanswermacros.pl
  352         }
  353         #else { # avg_problem_grader will be installed by PGtranslator so there is no need for a warning.
  354         # warn "The problem grader 'avg_problem_grader' has not been defined.  Has PGanswermacros.pl been loaded?";
  355         #}
  356       } else {
  357         warn "Error:  $main::PG_FLAGS{PROBLEM_GRADER_TO_USE} is not a known program grader.";
  358       }
  359     } elsif (defined(&std_problem_grader)) {
  360       $main::PG_FLAGS{PROBLEM_GRADER_TO_USE} = \&std_problem_grader; # defined in PGanswermacros.pl
  361     } else {
  362       # PGtranslator will install its default problem grader
  363     }
  364   ##};
  365     warn "ERROR: The problem grader is not a subroutine" unless ref( $main::PG_FLAGS{PROBLEM_GRADER_TO_USE}) eq 'CODE'
  366                      or $main::PG_FLAGS{PROBLEM_GRADER_TO_USE} = 'std_problem_grader'
  367                      or $main::PG_FLAGS{PROBLEM_GRADER_TO_USE} = 'avg_problem_grader';
  368      # return results
  369   (\$STRINGforOUTPUT, \$STRINGforHEADER_TEXT,\%PG_ANSWERS_HASH,\%main::PG_FLAGS);
  370 }
  371 
  372 
  373 
  374 =head2 INITIALIZE_PG()
  375 
  376 This is executed each C<DOCUMENT()> is called.  For backward compatibility
  377 C<loadMacros> also checks whether the C<macroDirectory> has been defined
  378 and if not, it runs C<INITIALIZE_PG()> and issues a warning.
  379 
  380 =cut
  381 
  382 
  383 1;

aubreyja at gmail dot com
ViewVC Help
Powered by ViewVC 1.0.9