[LON-CAPA-cvs] cvs: rat / lonuserstate.pm

foxr foxr at source.lon-capa.org
Tue Aug 9 05:15:50 EDT 2011


foxr		Tue Aug  9 09:15:50 2011 EDT

  Modified files:              
    /rat	lonuserstate.pm 
  Log:
  More comments.
  
  
-------------- next part --------------
Index: rat/lonuserstate.pm
diff -u rat/lonuserstate.pm:1.139 rat/lonuserstate.pm:1.140
--- rat/lonuserstate.pm:1.139	Thu Aug  4 10:57:26 2011
+++ rat/lonuserstate.pm	Tue Aug  9 09:15:50 2011
@@ -1,7 +1,7 @@
 # The LearningOnline Network with CAPA
 # Construct and maintain state and binary representation of course for user
 #
-# $Id: lonuserstate.pm,v 1.139 2011/08/04 10:57:26 foxr Exp $
+# $Id: lonuserstate.pm,v 1.140 2011/08/09 09:15:50 foxr Exp $
 #
 # Copyright Michigan State University Board of Trustees
 #
@@ -131,6 +131,17 @@
 
 # --------------------------------------------------------- Loads from disk
 
+
+#
+#  Loads a map file.
+#  Note that this may implicitly recurse via parse_resource if one of the resources
+#  is itself composed.
+#
+# Parameters:
+#    uri         - URI of the map file.
+#    parent_rid  - Resource id in the map of the parent resource (0.0 for the top level map)
+#
+#
 sub loadmap { 
     my ($uri,$parent_rid)=@_;
 
@@ -280,7 +291,13 @@
 
 	    my $rndseed=&Apache::lonnet::rndseed($seed);
 	    &Apache::lonnet::setup_random_from_rndseed($rndseed);
-	    @map_ids=&math::Random::random_permutation(@map_ids); # randomorder.
+
+	    # Take the set of map ids we have decoded and permute them to a
+	    # random order based on the seed set above. All of this is
+	    # processing the randomorder parameter if it is set, not
+	    # randompick.
+
+	    @map_ids=&math::Random::random_permutation(@map_ids); 
 	}
 
 
@@ -289,11 +306,9 @@
 	$hash{'map_start_'.$uri} = $from_rid;
 	$hash{'type_'.$from_rid}='start';
 
-	# Create links to reflect this random ordering.
-	# BUG?  If there are conditions, this invalidates them?  Then again
-	# with randompick there's no gaurentee the resources required for the
-	# conditinos to work will be selected into the map.
-	# so randompick is inconsistent with a map that has conditions?
+	# Create links to reflect the random re-ordering done above.
+	# In the code to process the map XML, we did not process links or conditions
+	# if randomorder was set.  This means that for an instructor to choose
 
 	while (my $to = shift(@map_ids)) {
 	    &make_link(++$linkpc,$lpc,$to,$from);
@@ -310,8 +325,8 @@
     $parser = HTML::TokeParser->new(\$instr);
     $parser->attr_encoded(1);
 
-    # last parse out the mapalias params so as to ignore anything
-    # refering to non-existant resources
+    # last parse out the mapalias params.  Thes provide mnemonic
+    # tags to resources that can be used in conditions
 
     while (my $token = $parser->get_token) {
 	next if ($token->[0] ne 'S');
@@ -721,12 +736,50 @@
 	}
     }
 }
-
+#
+#  Parse mapalias parameters.
+#  these are tags of the form:
+#  <param to="nn" 
+#         value="some-alias-for-resourceid-nn" 
+#         name="parameter_0_mapalias" 
+#         type="string" />
+#  A map alias is a textual name for a resource:
+#    - The to  attribute identifies the resource (this gets level qualified below)
+#    - The value attributes provides the alias string.
+#    - name must be of the regexp form: /^parameter_(0_)*mapalias$/
+#    - e.g. the string 'parameter_' followed by 0 or more "0_" strings
+#      terminating with the string 'mapalias'.
+#      Examples:
+#         'parameter_mapalias', 'parameter_0_mapalias', parameter_0_0_mapalias'
+#  Invalid to ids are silently ignored.
+#
+#  Parameters:
+#     token - The token array fromthe HMTML::TokeParser
+#     lpc   - The current map level counter.
+#
 sub parse_mapalias_param {
     my ($token,$lpc) = @_;
+
+    # Fully qualify the to value and ignore the alias if there is no
+    # corresponding resource.
+
     my $referid=$lpc.'.'.$token->[2]->{'to'};
     return if (!exists($hash{'src_'.$referid}));
 
+    # If this is a valid mapalias parameter, 
+    # Append the target id to the count_mapalias element for that
+    # alias so that we can detect doubly defined aliases
+    # e.g.:
+    #  <param to="1" value="george" name="parameter_0_mapalias" type="string" />
+    #  <param to="2" value="george" name="parameter_0_mapalias" type="string" />
+    #
+    #  The example above is trivial but the case that's important has to do with
+    #  constructing a map that includes a nested map where the nested map may have
+    #  aliases that conflict with aliases established in the enclosing map.
+    #
+    # ...and create/update the hash mapalias entry to actually store the alias.
+    #
+
     if ($token->[2]->{'name'}=~/^parameter_(0_)*mapalias$/) {
 	&count_mapalias($token->[2]->{'value'},$referid);
 	$hash{'mapalias_'.$token->[2]->{'value'}}=$referid;
@@ -735,6 +788,10 @@
 
 # --------------------------------------------------------- Simplify expression
 
+
+#
+#  Someone should really comment this to describe what it does to what and why.
+#
 sub simplify {
     my $expression=shift;
 # (0&1) = 1
@@ -758,9 +815,38 @@
 
 # -------------------------------------------------------- Build condition hash
 
+#
+#  Traces a route recursively through the map after it has been loaded
+#  (I believe this really visits each resourcde that is reachable fromt he
+#  start top node.
+#
+#  - Marks hidden resources as hidden.
+#  - Marks which resource URL's must be encrypted.
+#  - Figures out (if necessary) the first resource in the map.
+#  - Further builds the chunks of the big hash that define how 
+#    conditions work
+#
+#  Note that the tracing strategy won't visit resources that are not linked to
+#  anything or islands in the map (groups of resources that form a path but are not
+#  linked in to the path that can be traced from the start resource...but that's ok
+#  because by definition, those resources are not reachable by users of the course.
+#
+# Parameters:
+#   sofar    - _URI of the prior entry or 0 if this is the top.
+#   rid      - URI of the resource to visit.
+#   beenhere - list of resources (each resource enclosed by &'s) that have
+#              already been visited.
+#   encflag  - If true the resource that resulted in a recursive call to us
+#              has an encoded URL (which means contained resources should too). 
+#   hdnflag  - If true,the resource that resulted in a recursive call to us
+#              was hidden (which means contained resources should be hidden too).
+# Returns
+#    new value indicating how far the map has been traversed (the sofar).
+#
 sub traceroute {
     my ($sofar,$rid,$beenhere,$encflag,$hdnflag)=@_;
     my $newsofar=$sofar=simplify($sofar);
+
     unless ($beenhere=~/\&\Q$rid\E\&/) {
 	$beenhere.=$rid.'&';  
 	my ($mapid,$resid)=split(/\./,$rid);
@@ -776,10 +862,12 @@
 
 	my $encrypt=&Apache::lonnet::EXT('resource.0.encrypturl',$symb);
 	if ($encflag || lc($encrypt) eq 'yes') { $encurl{$rid}=1; }
+
 	if (($retfrid eq '') && ($hash{'src_'.$rid})
 	    && ($hash{'src_'.$rid}!~/\.sequence$/)) {
 	    $retfrid=$rid;
 	}
+
 	if (defined($hash{'conditions_'.$rid})) {
 	    $hash{'conditions_'.$rid}=simplify(
            '('.$hash{'conditions_'.$rid}.')|('.$sofar.')');
@@ -789,8 +877,11 @@
 
 	# if the expression is just the 0th condition keep it
 	# otherwise leave a pointer to this condition expression
+
 	$newsofar = ($sofar eq '0') ? $sofar : '_'.$rid;
 
+	# Recurse if the resource is a map:
+
 	if (defined($hash{'is_map_'.$rid})) {
 	    if (defined($hash{'map_start_'.$hash{'src_'.$rid}})) {
 		$sofar=$newsofar=
@@ -801,9 +892,18 @@
 				$hdnflag || $hiddenurl{$rid});
 	    }
 	}
+
+	# Processes  links to this resource:
+	#  - verify the existence of any conditionals on the link to here.
+	#  - Recurse to any resources linked to us.
+	#
 	if (defined($hash{'to_'.$rid})) {
 	    foreach my $id (split(/\,/,$hash{'to_'.$rid})) {
 		my $further=$sofar;
+		#
+		# If there's a condition associated with this link be sure
+		# it's been defined else that's an error:
+		#
                 if ($hash{'undercond_'.$id}) {
 		    if (defined($hash{'condid_'.$hash{'undercond_'.$id}})) {
 			$further=simplify('('.'_'.$rid.')&('.
@@ -812,6 +912,7 @@
 			$errtext.=&mt('<br />Undefined condition ID: [_1]',$hash{'undercond_'.$id});
 		    }
                 }
+		#  Recurse to resoruces that have to's to us.
                 $newsofar=&traceroute($further,$hash{'goesto_'.$id},$beenhere,
 				      $encflag,$hdnflag);
 	    }
@@ -822,16 +923,33 @@
 
 # ------------------------------ Cascading conditions, quick access, parameters
 
+#
+#  Seems a rather strangely named sub given what the comment above says it does.
+
+
 sub accinit {
     my ($uri,$short,$fn)=@_;
     my %acchash=();
     my %captured=();
     my $condcounter=0;
     $acchash{'acc.cond.'.$short.'.0'}=0;
+
+    # This loop is only interested in conditions and 
+    # parameters in the big hash:
+
     foreach my $key (keys(%hash)) {
+
+	# conditions:
+
 	if ($key=~/^conditions/) {
 	    my $expr=$hash{$key};
+
 	    # try to find and factor out common sub-expressions
+	    # Any subexpression that is found is simplified, removed from
+	    # the original condition expression and the simplified sub-expression
+	    # substituted back in to the epxression..I'm not actually convinced this
+	    # factors anything out...but instead maybe simplifies common factors(?)
+
 	    foreach my $sub ($expr=~m/(\(\([_\.\d]+(?:\&[_\.\d]+)+\)(?:\|\([_\.\d]+(?:\&[_\.\d]+)+\))+\))/g) {
 		my $orig=$sub;
 
@@ -845,11 +963,16 @@
 		$expr=~s/\Q$orig\E/$sub/;
 	    }
 	    $hash{$key}=$expr;
+
+           # If not yet seen, record in acchash and that we've seen it.
+
 	    unless (defined($captured{$expr})) {
 		$condcounter++;
 		$captured{$expr}=$condcounter;
 		$acchash{'acc.cond.'.$short.'.'.$condcounter}=$expr;
 	    } 
+        # Parameters:
+
 	} elsif ($key=~/^param_(\d+)\.(\d+)/) {
 	    my $prefix=&Apache::lonnet::encode_symb($hash{'map_id_'.$1},$2,
 						    $hash{'src_'.$1.'.'.$2});
@@ -863,6 +986,8 @@
 	    }
 	}
     }
+    # This loop only processes id entries in the big hash.
+
     foreach my $key (keys(%hash)) {
 	if ($key=~/^ids/) {
 	    foreach my $resid (split(/\,/,$hash{$key})) {
@@ -1226,6 +1351,9 @@
     $pc=0;
     &clear_mapalias_count();
     &processversionfile(%cenv);
+
+    # URI Of the map file.
+
     my $furi=&Apache::lonnet::clutter($uri);
     #
     #  the map staring points.
@@ -1234,7 +1362,17 @@
     $hash{'title_0.0'}=&Apache::lonnet::metadata($uri,'title');
     $hash{'ids_'.$furi}='0.0';
     $hash{'is_map_0.0'}=1;
+
+    # Load the map.. note that loadmap may implicitly recurse if the map contains 
+    # sub-maps.
+
+
     &loadmap($uri,'0.0');
+
+    #  The code below only executes if there is a starting point for the map>
+    #  Q/BUG??? If there is no start resource for the map should that be an error?
+    #
+
     if (defined($hash{'map_start_'.$uri})) {
         &Apache::lonnet::appenv({"request.course.id"  => $short,
                                  "request.course.fn"  => $fn,


More information about the LON-CAPA-cvs mailing list