[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 2984 - (download) (as text) (annotate)
Wed Nov 3 22:00:56 2004 UTC (15 years, 3 months ago) by dpvc
File size: 18553 byte(s)
Modifications needed for the control of jsMath's "missing font"
message.

    1 # This file provided the fundamental macros for the pg language
    2 # These macros define the interface between the problems written by
    3 # the professor and the processing which occurs in the script
    4 # processProblem.pl
    5 
    6 
    7 BEGIN {
    8   be_strict();
    9 }
   10 
   11 sub _PG_init{
   12 
   13 }
   14 
   15 #package PG;
   16 
   17 
   18 =head1 NAME
   19 
   20   PG.pl --- located in the courseScripts directory.
   21   Defines the Program Generating language at the most basic level.
   22 
   23 =head1 SYNPOSIS
   24 
   25   The basic PG problem structure:
   26 
   27   DOCUMENT();          # should be the first statment in the problem
   28   loadMacros(.....);   # (optional) load other macro files if needed.
   29                        # (loadMacros is defined in F<dangerousMacros.pl>)
   30 
   31   HEADER_TEXT(...);    # (optional) used only for inserting javaScript into problems.
   32 
   33   #            #  insert text of problems
   34   TEXT("Problem text to be",
   35        "displayed. Enter 1 in this blank:",
   36        ANS_RULE(1,30)  #  ANS_RULE() defines an answer blank 30 characters long.
   37                        #  It is defined in F<PGbasicmacros.pl>
   38        );
   39 
   40 
   41   ANS( answer_evalutors);  # see F<PGanswermacros.pl> for examples of answer evaluatiors.
   42 
   43   ENDDOCUMENT()        # must be the last statement in the problem
   44 
   45 
   46 
   47 =head1 DESCRIPTION
   48 
   49 As described in the synopsis, this file and the macros C<DOCUMENT()> and C<ENDDOCUMENT()> determine
   50 the interface between problems written in the PG language and the rest of B<WeBWorK>, in particular
   51 the subroutine C<createPGtext(()> in the file F<translate.pl>.
   52 
   53 C<DOCUMENT()> must be the first statement in each problem template.
   54 It  initializes variables,
   55 in particular all of the contents of the
   56 environment variable  become defined in the problem enviroment.
   57 (See
   58 L</webwork_system_html/docs/techdescription/pglanguage/PGenvironment.html>)
   59 
   60 ENDDOCUMENT() must the last executable statement in any problem template.  It returns
   61 the rendered problem, answer evaluators and other flags to the rest of B<WeBWorK>, specificially
   62 to the routine C<createPGtext()> defined in F<translate.pl>
   63 
   64 
   65 The C<HEADER_TEXT()>, C<TEXT()>, and C<ANS()> functions load the
   66 header text string, the problem text string.
   67 and the answer evaulator queue respectively.
   68 
   69 
   70 =cut
   71 
   72 
   73 #  Private variables for the PG.pl file.
   74 
   75 my ($STRINGforOUTPUT, $STRINGforHEADER_TEXT, @PG_ANSWERS, @PG_UNLABELED_ANSWERS);
   76 my %PG_ANSWERS_HASH ;
   77 
   78 # my variables are unreliable if two DOCUMENTS were to be called before and ENDDOCUMENT
   79 # there could be conflicts.  As I understand the behavior of the Apache child
   80 # this cannot occur -- a child finishes with one request before obtaining the next
   81 
   82 #   DOCUMENT must come early in every .pg file, before any answers or text are
   83 # defined.  It initializes the variables.
   84 # It can appear only once.
   85 
   86 =head2 DOCUMENT()
   87 
   88 C<DOCUMENT()> must be the first statement in each problem template.  It can
   89 only be used once in each problem.
   90 
   91 C<DOCUMENT()> initializes some empty variables and via C<INITIALIZE_PG()> unpacks the
   92 variables in the C<%envir> variable which is implicitly passed to the problem. It must
   93 be the first statement in any problem template. It
   94 also unpacks any answers submitted and places them in the C<@submittedAnswer> list,
   95 saves the problem seed in C<$PG_original_problemSeed> in case you need it later, and
   96 initializes the pseudo random number generator object in C<$PG_random_generator>.
   97 
   98 You can reset the standard number generator using the command:
   99 
  100   $PG_random_generator->srand($new_seed_value);
  101 
  102 (See also C<SRAND> in the L<PGbasicmacros.pl> file.)
  103 
  104 The
  105 environment variable contents is defined in
  106 L</webwork_system_html/docs/techdescription/pglanguage/PGenvironment.html>
  107 
  108 
  109 =cut
  110 
  111 sub DOCUMENT {
  112 
  113   $STRINGforOUTPUT ="";
  114     $STRINGforHEADER_TEXT ="";
  115   @PG_ANSWERS=();
  116 
  117   @PG_UNLABELED_ANSWERS = ();
  118   %PG_ANSWERS_HASH = ();
  119   # FIXME:  We are initializing these variables into both Safe::Root1 (the cached safe compartment)
  120   # and Safe::Root2 (the current one)
  121   # There is a good chance they won't be properly updated in one or the other of these compartments.
  122 
  123 #   @main::PG_ANSWER_ENTRY_ORDER = ();
  124 #   $main::ANSWER_PREFIX = 'AnSwEr';
  125 #   %main::PG_FLAGS=();  #global flags
  126 #   $main::showPartialCorrectAnswers = 0 unless defined($main::showPartialCorrectAnswers );
  127 #   $main::showHint = 1 unless defined($main::showHint);
  128 #   $main::solutionExists =0;
  129 #   $main::hintExists =0;
  130 #   %main::gifs_created = ();
  131   eval(q!
  132   @main::PG_ANSWER_ENTRY_ORDER = ();
  133   $main::ANSWER_PREFIX = 'AnSwEr';
  134   %main::PG_FLAGS=();  #global flags
  135   $main::showPartialCorrectAnswers = 0 unless defined($main::showPartialCorrectAnswers );
  136   $main::showHint = 1 unless defined($main::showHint);
  137   $main::solutionExists =0;
  138   $main::hintExists =0;
  139   %main::gifs_created = ();
  140 
  141     !);
  142 #    warn eval(q! "PG.pl:  The envir variable $main::{envir} is".join(" ",%main::envir)!);
  143     my $rh_envir = eval(q!\%main::envir!);
  144     my %envir    = %$rh_envir;
  145 
  146     # Save the file name for use in error messages
  147     my ($callpkg,$callfile) = caller(0);
  148     $envir{__files__}{$callfile} = $envir{templateDirectory}.$envir{fileName};
  149 
  150     #no strict;
  151     foreach  my  $var (keys %envir) {
  152       eval(q!$main::!.$var.q! = $main::envir{!.$var.q!}! );  #whew!! makes sure $var is interpolated but $main:: is evaluated at run time.
  153     #    warn eval(q! "var $var is defined ". $main::!.$var);
  154         warn "Problem defining ", q{\$main::}.$var, " while initializing the PG problem: $@" if $@;
  155     }
  156     #use strict;
  157     #FIXME these strict pragmas don't seem to be needed and they cause trouble in perl 5.6.0
  158 
  159 
  160 
  161     eval(q!
  162   @main::submittedAnswers = @{$main::refSubmittedAnswers} if defined($main::refSubmittedAnswers);
  163   $main::PG_original_problemSeed = $main::problemSeed;
  164   $main::PG_random_generator = new PGrandom($main::problemSeed) || die "Can't create random number generator.";
  165   $main::ans_rule_count = 0;  # counts questions
  166 
  167     # end unpacking of environment variables.
  168     $main::QUIZ_PREFIX = '' unless defined($main::QUIZ_PREFIX)
  169 
  170   !);
  171 #   @main::submittedAnswers = @{$main::refSubmittedAnswers} if defined($main::refSubmittedAnswers);
  172 #   $main::PG_original_problemSeed = $main::problemSeed;
  173 #   $main::PG_random_generator = new PGrandom($main::problemSeed) || die "Can't create random number generator.";
  174 #   $main::ans_rule_count = 0;  # counts questions
  175 
  176     # end unpacking of environment variables.
  177 #   $main::QUIZ_PREFIX = '' unless defined($main::QUIZ_PREFIX)
  178 
  179   if ($main::envir{displayMode} eq 'HTML_jsMath') {
  180     my $prefix = "";
  181     if (!$main::envir{jsMath}{reportMissingFonts}) {
  182       $prefix .= '<SCRIPT>function NoFontMessage() {}</SCRIPT>';
  183     } elsif ($main::envir{jsMath}{missingFontMessage}) {
  184       $prefix .=
  185         '<SCRIPT>'.
  186         '  function NoFontMessage() {'.
  187         '    document.writeln(\'<DIV CLASS="noFontMessage">'.
  188           $main::envir{jsMath}{missingFontMessage}.'</DIV>\');'.
  189         '  }' .
  190         '</SCRIPT>';
  191     }
  192     $STRINGforOUTPUT =
  193       $prefix .
  194       '<SCRIPT SRC="'.$main::envir{jsMathURL}.'"></SCRIPT>' . "\n" .
  195       '<NOSCRIPT><CENTER><FONT COLOR="#CC0000">' .
  196       '<B>Warning: the mathematics on this page requires JavaScript.<BR>' .
  197       'If your browser supports it, be sure it is enabled.</B>'.
  198       '</FONT></CENTER><p></NOSCRIPT>' .
  199       $STRINGforOUTPUT;
  200   }
  201 
  202   $STRINGforOUTPUT = '<SCRIPT SRC="'.$main::envir{asciimathURL}.'"></SCRIPT>' . "\n" .
  203                            '<SCRIPT>mathcolor = "black"</SCRIPT>' . $STRINGforOUTPUT
  204     if ($main::envir{displayMode} eq 'HTML_asciimath');
  205 
  206 }
  207 
  208 sub inc_ans_rule_count {
  209   eval(q!++$main::ans_rule_count!); # evalute at runtime to get correct main::
  210 }
  211 # HEADER_TEXT is for material which is destined to be placed in the header of the html problem -- such
  212 #   as javaScript code.
  213 
  214 =head2 HEADER_TEXT()
  215 
  216 
  217   HEADER_TEXT("string1", "string2", "string3");
  218 
  219 The C<HEADER_TEXT()>
  220 function concatenates its arguments and places them in the output
  221 header text string.  It is used for material which is destined to be placed in
  222 the header of the html problem -- such as javaScript code.
  223  It can be used more than once in a file.
  224 
  225 
  226 =cut
  227 
  228 sub HEADER_TEXT {
  229   my @in = @_;
  230   $STRINGforHEADER_TEXT .= join(" ",@in);
  231   }
  232 
  233 # TEXT is the function which defines text which will appear in the problem.
  234 # All text must be an argument to this function.  Any other statements
  235 #   are calculations (done in perl) which will not directly appear in the
  236 # output.  Think of this as the "print" function for the .pg language.
  237 # It can be used more than once in a file.
  238 
  239 =head2 TEXT()
  240 
  241   TEXT("string1", "string2", "string3");
  242 
  243 The C<TEXT()> function concatenates its arguments and places them in the output
  244 text string. C<TEXT()> is the function which defines text which will appear in the problem.
  245 All text must be an argument to this function.  Any other statements
  246 are calculations (done in perl) which will not directly appear in the
  247 output.  Think of this as the "print" function for the .pg language.
  248 It can be used more than once in a file.
  249 
  250 =cut
  251 
  252 sub TEXT {
  253   my @in = @_;
  254   $STRINGforOUTPUT .= join(" ",@in);
  255   }
  256 
  257 
  258 
  259 =head2 ANS()
  260 
  261   ANS(answer_evaluator1, answer_evaluator2, answer_evaluator3,...)
  262 
  263 Places the answer evaluators in the unlabeled answer_evaluator queue.  They will be paired
  264 with unlabeled answer rules (answer entry blanks) in the order entered.  This is the standard
  265 method for entering answers.
  266 
  267   LABELED_ANS(answer_evaluater_name1, answer_evaluator1, answer_evaluater_name2,answer_evaluator2,...)
  268 
  269 Places the answer evaluators in the labeled answer_evaluator hash.  This allows pairing of
  270 labeled answer evaluators and labeled answer rules which may not have been entered in the same
  271 order.
  272 
  273 =cut
  274 
  275 sub ANS{             # store answer evaluators which have not been explicitly labeled
  276   my @in = @_;
  277   while (@in ) {
  278          warn("<BR><B>Error in ANS:$in[0]</B> -- inputs must be references to
  279                       subroutines<BR>")
  280       unless ref($in[0]);
  281       push(@PG_ANSWERS, shift @in );
  282       }
  283 }
  284 sub LABELED_ANS {  #a better alias for NAMED_ANS
  285   &NAMED_ANS;
  286 }
  287 
  288 sub NAMED_ANS{     # store answer evaluators which have been explicitly labeled (submitted in a hash)
  289   my @in = @_;
  290   while (@in ) {
  291     my $label = shift @in;
  292     $label = eval(q!$main::QUIZ_PREFIX.$label!);
  293     my $ans_eval = shift @in;
  294     TEXT("<BR><B>Error in NAMED_ANS:$in[0]</B>
  295           -- inputs must be references to subroutines<BR>")
  296       unless ref($ans_eval);
  297     $PG_ANSWERS_HASH{$label}= $ans_eval;
  298   }
  299 }
  300 sub RECORD_ANS_NAME {     # this maintains the order in which the answer rules are printed.
  301   my $label = shift;
  302   eval(q!push(@main::PG_ANSWER_ENTRY_ORDER, $label)!);
  303   $label;
  304 }
  305 
  306 sub NEW_ANS_NAME {        # this keeps track of the answers which are entered implicitly,
  307                           # rather than with a specific label
  308     my $number=shift;
  309     my $prefix = eval(q!$main::QUIZ_PREFIX.$main::ANSWER_PREFIX!);
  310     my $label = $prefix.$number;
  311     push(@PG_UNLABELED_ANSWERS,$label);
  312     $label;
  313 }
  314 sub ANS_NUM_TO_NAME {     # This converts a number to an answer label for use in
  315                           # radio button and check box answers. No new answer
  316                           # name is recorded.
  317     my $number=shift;
  318     my $label = eval(q!$main::QUIZ_PREFIX.$main::ANSWER_PREFIX!).$number;
  319     $label;
  320 }
  321 
  322 my $vecnum;
  323 
  324 sub RECORD_FORM_LABEL  {             # this stores form data (such as sticky answers), but does nothing more
  325                                      # it's a bit of hack since we are storing these in the KEPT_EXTRA_ANSWERS queue even if they aren't answers per se.
  326   my $label   = shift;             # the label of the input box or textarea
  327     eval(q!push(@main::KEPT_EXTRA_ANSWERS, $label)!); #put the labels into the hash to be caught later for recording purposes
  328     $label;
  329 }
  330 sub NEW_ANS_ARRAY_NAME {        # this keeps track of the answers which are entered implicitly,
  331                           # rather than with a specific label
  332     my $number=shift;
  333     $vecnum = 0;
  334     my $row = shift;
  335     my $col = shift;
  336 #   my $label = "ArRaY"."$number"."["."$vecnum".","."$row".","."$col"."]";
  337     my $label = "ArRaY"."$number"."__"."$vecnum".":"."$row".":"."$col"."__";
  338     push(@PG_UNLABELED_ANSWERS,$label);
  339     $label;
  340 }
  341 
  342 sub NEW_ANS_ARRAY_NAME_EXTENSION {        # this keeps track of the answers which are entered implicitly,
  343                           # rather than with a specific label
  344     my $number=shift;
  345     my $row = shift;
  346     my $col = shift;
  347     if( $row == 0 && $col == 0 ){
  348       $vecnum += 1;
  349     }
  350     #FIXME   change made to conform to HTML 4.01 standards.  "Name" attributes can only contain
  351     # alphanumeric characters,   _ : and .
  352     # Also need to make corresponding changes in PGmorematrixmacros.  grep for ArRaY.
  353     #my $label = "ArRaY"."$number"."["."$vecnum".","."$row".","."$col"."]";
  354     my $label = "ArRaY"."$number"."__"."$vecnum".":"."$row".":"."$col"."__";
  355     eval(q!push(@main::KEPT_EXTRA_ANSWERS, $label)!);#put the labels into the hash to be caught later for recording purposes
  356     $label;
  357 }
  358 
  359 # ENDDOCUMENT must come at the end of every .pg file.
  360 #   It exports the resulting text of the problem, the text to be used in HTML header material
  361 #   (for javaScript), the list of answer evaluators and any other flags.  It can appear only once and
  362 #   it MUST be the last statement in the problem.
  363 
  364 =head2 ENDDOCUMENT()
  365 
  366 ENDDOCUMENT() must the last executable statement in any problem template.  It can
  367 only appear once.  It returns
  368 an array consisting of
  369 
  370   A reference to a string containing the rendered text of the problem.
  371   A reference to a string containing text to be placed in the header
  372                (for javaScript)
  373   A reference to the array containing the answer evaluators.
  374                (May be changed to a hash soon.)
  375   A reference to an associative array (hash) containing various flags.
  376 
  377   The following flags are set by ENDDOCUMENT:
  378   (1) showPartialCorrectAnswers  -- determines whether students are told which
  379       of their answers in a problem are wrong.
  380   (2) recordSubmittedAnswers  -- determines whether students submitted answers
  381       are saved.
  382   (3) refreshCachedImages  -- determines whether the cached image of the problem
  383       in typeset mode is always refreshed (i.e. setting this to 1 means cached
  384       images are not used).
  385   (4) solutionExits   -- indicates the existence of a solution.
  386   (5) hintExits   -- indicates the existence of a hint.
  387   (6) showHintLimit -- determines the number of attempts after which hint(s) will be shown
  388 
  389   (7) PROBLEM_GRADER_TO_USE -- chooses the problem grader to be used in this order
  390     (a) A problem grader specified by the problem using:
  391         install_problem_grader(\&grader);
  392     (b) One of the standard problem graders defined in PGanswermacros.pl when set to
  393         'std_problem_grader' or 'avg_problem_grader' by the environment variable
  394         $PG_environment{PROBLEM_GRADER_TO_USE}
  395     (c) A subroutine referenced by $PG_environment{PROBLEM_GRADER_TO_USE}
  396     (d) The default &std_problem_grader defined in PGanswermacros.pl
  397 
  398 
  399 =cut
  400 
  401 sub ENDDOCUMENT {
  402 
  403     my $index=0;
  404     foreach my $label (@PG_UNLABELED_ANSWERS) {
  405         if ( defined($PG_ANSWERS[$index]) ) {
  406         $PG_ANSWERS_HASH{"$label"}= $PG_ANSWERS[$index];
  407       #warn "recording answer label = $label";
  408       } else {
  409         warn "No answer provided by instructor for answer $label";
  410       }
  411       $index++;
  412     }
  413 
  414     $STRINGforOUTPUT .="\n";
  415    eval q{  #make sure that "main" points to the current safe compartment by evaluating these lines.
  416     $main::PG_FLAGS{'showPartialCorrectAnswers'} = $main::showPartialCorrectAnswers;
  417     $main::PG_FLAGS{'recordSubmittedAnswers'} = $main::recordSubmittedAnswers;
  418     $main::PG_FLAGS{'refreshCachedImages'} = $main::refreshCachedImages;
  419     $main::PG_FLAGS{'hintExists'} = $main::hintExists;
  420     $main::PG_FLAGS{'showHintLimit'} = $main::showHint;
  421     $main::PG_FLAGS{'solutionExists'} = $main::solutionExists;
  422     $main::PG_FLAGS{ANSWER_ENTRY_ORDER} = \@main::PG_ANSWER_ENTRY_ORDER;
  423     $main::PG_FLAGS{KEPT_EXTRA_ANSWERS} = \@main::KEPT_EXTRA_ANSWERS;##need to keep array labels that don't call "RECORD_ANS_NAME"
  424     $main::PG_FLAGS{ANSWER_PREFIX} = $main::ANSWER_PREFIX;
  425     # install problem grader
  426     if (defined($main::PG_FLAGS{PROBLEM_GRADER_TO_USE}) ) {
  427       # problem grader defined within problem -- no further action needed
  428     } elsif ( defined( $main::envir{PROBLEM_GRADER_TO_USE} ) ) {
  429       if (ref($main::envir{PROBLEM_GRADER_TO_USE}) eq 'CODE' ) {         # user defined grader
  430         $main::PG_FLAGS{PROBLEM_GRADER_TO_USE} = $main::envir{PROBLEM_GRADER_TO_USE};
  431       } elsif ($main::envir{PROBLEM_GRADER_TO_USE} eq 'std_problem_grader' ) {
  432         if (defined(&std_problem_grader) ){
  433           $main::PG_FLAGS{PROBLEM_GRADER_TO_USE} = \&std_problem_grader; # defined in PGanswermacros.pl
  434         } # std_problem_grader is the default in any case so don't give a warning.
  435       } elsif ($main::envir{PROBLEM_GRADER_TO_USE} eq 'avg_problem_grader' ) {
  436         if (defined(&avg_problem_grader) ){
  437           $main::PG_FLAGS{PROBLEM_GRADER_TO_USE} = \&avg_problem_grader; # defined in PGanswermacros.pl
  438         }
  439         #else { # avg_problem_grader will be installed by PGtranslator so there is no need for a warning.
  440         # warn "The problem grader 'avg_problem_grader' has not been defined.  Has PGanswermacros.pl been loaded?";
  441         #}
  442       } else {
  443         warn "Error:  $main::PG_FLAGS{PROBLEM_GRADER_TO_USE} is not a known program grader.";
  444       }
  445     } elsif (defined(&std_problem_grader)) {
  446       $main::PG_FLAGS{PROBLEM_GRADER_TO_USE} = \&std_problem_grader; # defined in PGanswermacros.pl
  447     } else {
  448       # PGtranslator will install its default problem grader
  449     }
  450 
  451     warn "ERROR: The problem grader is not a subroutine" unless ref( $main::PG_FLAGS{PROBLEM_GRADER_TO_USE}) eq 'CODE'
  452                      or $main::PG_FLAGS{PROBLEM_GRADER_TO_USE} = 'std_problem_grader'
  453                      or $main::PG_FLAGS{PROBLEM_GRADER_TO_USE} = 'avg_problem_grader';
  454      # return results
  455     };
  456 
  457     $STRINGforOUTPUT .= '<SCRIPT> jsMath.ProcessBeforeShowing() </SCRIPT>'
  458       if ($main::envir{displayMode} eq 'HTML_jsMath');
  459 
  460     if ($main::envir{displayMode} eq 'HTML_asciimath') {
  461       $STRINGforOUTPUT .= '<SCRIPT> translate() </SCRIPT>';
  462       $STRINGforHEADER_TEXT .=
  463         '<object id="mathplayer" classid="clsid:32F66A20-7614-11D4-BD11-00104BD3F987">' . "\n" .
  464         '</object><?import namespace="mml" implementation="#mathplayer"?>'
  465   unless ($STRINGforHEADER_TEXT =~ m/mathplayer/);
  466     }
  467 
  468   (\$STRINGforOUTPUT, \$STRINGforHEADER_TEXT,\%PG_ANSWERS_HASH,eval(q!\%main::PG_FLAGS!));
  469 }
  470 
  471 
  472 
  473 =head2 INITIALIZE_PG()
  474 
  475 This is executed each C<DOCUMENT()> is called.  For backward compatibility
  476 C<loadMacros> also checks whether the C<macroDirectory> has been defined
  477 and if not, it runs C<INITIALIZE_PG()> and issues a warning.
  478 
  479 =cut
  480 
  481 
  482 1;

aubreyja at gmail dot com
ViewVC Help
Powered by ViewVC 1.0.9