Update the Rserve interface.

The primary change in this pull request is how the `rserve_get_file`
method in the `RserveClient.pl` macro works.  Previously it accepted a
second optional local filename parameter.  That parameter is no longer
honored.  If it is given it is ignored.  I don't think that there are
any problems in the OPL or Contrib that pass that argument, but even if
they do it will still work.  The filename just won't be the chosen one.
The filename should not be a problem author choice.  Furthermore,
previously the method fell back to using the Rserve remote filename.
That is also no longer used.  Instead, the `getUniqueName` method is
used that creates a filename that is dependent on the problem seed,
psvn, problem UUID, etc. That means that the filename will not change
each time that the problem is loaded. Unfortunately, the file is still
downloaded every time the problem is loaded and overwrites the existing
file (with the same contents), and that can't really be fixed without a
major revision of the Rserve setup.

Note that all changes in this pull request are backwards compatible, and
all existing problems will continue to function correctly. However, the
courses html temporary directory will no longer be filled with files
that are only used once before another copy of the file is created by
another name the next time the problem is rendered (due to a preview,
answer submission, etc.).

In addition there are two new methods added that are more convenient
than the previous methods for generating R images or csv files. Those
are the `rserve_data_url` and `rserve_plot` methods.  These handle the
details of creating these things in a much nicer way.  See the added POD
and examples in the POD for the usage and comparison to the old
approaches.

The macro code and POD are also rather heavily clean up.  The
`Rserve.pm` module is also cleaned up. The `_inherits` method is removed
from the `Rserve.pm` module, because contrary to the comments the
`inherits` method of the `$rserve` object does work in the safe
compartment, and so the `_inherits` method is not needed.

There are a couple of other related changes.

First, the `htmlLink` method now has a new calling convention for adding
additional attributes to the generated `a` tag. Previously these were
added by passing a single string argument. For example,
`htmlLink($url, 'dataset', 'download="dataset.csv"')`.  That will still
work, but passing the attributes in that way should be considered
deprecated.  Instead the attributes should be passed as additional
attribute/value pairs after the url and link text. For example,
`htmlLink($url, 'dataset', download => 'dataset.csv')`.  Of course, this
is useful for Rserve csv files to specify the filename that will be
offered when the user clicks to download a csv file.  Particularly since
the default will now be something like
`ed721060-00b2-37fb-87c4-e3eb36c7ced2___5643740d-c34f-37c8-afc5-c2369fec26e1.csv`.
Previously it would have been something like `file1231asdfasdf.csv`.
The new alias is worse, but that wasn't good either.

Author: drgrice1

conf/pg_config.dist.yml

@@ -139,6 +139,12 @@ specialPGEnvironmentVars:
   # Size in pixels of dynamically-generated images, i.e. graphs.
   onTheFlyImageSize: 400
 
+  # To enable Rserve (the R statistical server), uncomment the following two
+  # lines. The R server needs to be installed and running in order for this to
+  # work. See http://webwork.maa.org/wiki/R_in_WeBWorK for more info.
+  #Rserve:
+  #  host: localhost
+
   # Locations of CAPA resources. (Only necessary if you need to use converted CAPA problems.)
   CAPA_Tools: $Contrib_dir/CAPA/macros/CAPA_Tools/
   CAPA_MCTools: $Contrib_dir/Contrib/CAPA/macros/CAPA_MCTools/

lib/Rserve.pm

@@ -11,53 +11,34 @@ my $rserve_loaded = eval {
 sub access {
 	die 'Statistics::R::IO::Rserve could not be loaded. Have you installed the module?'
 		unless $rserve_loaded;
-
-	Statistics::R::IO::Rserve->new(@_);
+	return Statistics::R::IO::Rserve->new(@_);
 }
 
-## Evaluates an R expression guarding it inside an R `try` function
-##
-## Returns the result as a REXP if no exceptions were raised, or
-## `die`s with the text of the exception message.
+# Evaluates an R expression guarding it inside an R `try` function
+#
+# Returns the result as a REXP if no exceptions were raised, or
+# `die`s with the text of the exception message.
 sub try_eval {
 	my ($rserve, $query) = @_;
 
-	my $result = $rserve->eval("try({ $query }, silent=TRUE)");
-	die $result->to_pl->[0] if _inherits($result, 'try-error');
-	# die $result->to_pl->[0] if $result->inherits('try-error');
+	my $result = $rserve->eval("try({ $query }, silent = TRUE)");
+	die $result->to_pl->[0] if $result->inherits('try-error');
 
-	$result;
+	return $result;
 }
 
-## Returns a REXP's Perl representation, dereferencing it if it's an
-## array reference
-##
-## `REXP::to_pl` returns a string scalar for Symbol, undef for Null,
-## and an array reference to contents for all vector types. This
-## function is a utility wrapper to make it easy to assign a Vector's
-## representation to an array variable, while still working sensibly
-## for non-arrays.
+# Returns a REXP's Perl representation, dereferencing it if it's an
+# array reference
+#
+# `REXP::to_pl` returns a string scalar for Symbol, undef for Null,
+# and an array reference to contents for all vector types. This
+# function is a utility wrapper to make it easy to assign a Vector's
+# representation to an array variable, while still working sensibly
+# for non-arrays.
 sub unref_rexp {
-	my $rexp = shift;
-
+	my $rexp  = shift;
 	my $value = $rexp->to_pl;
-	if (ref($value) eq ref([])) {
-		@{$value};
-	} else {
-		$value;
-	}
-}
-
-## Reimplements method C<inherits> of class L<Statistics::R::REXP>
-## until I figure out why calling it directly doesn't work in the safe
-## compartment
-sub _inherits {
-	my ($rexp, $class) = @_;
-
-	my $attributes = $rexp->attributes;
-	return unless $attributes && $attributes->{'class'};
-
-	grep {/^$class$/} @{ $attributes->{'class'}->to_pl };
+	return ref($value) eq 'ARRAY' ? @$value : $value;
 }
 
 1;

macros/core/PGbasicmacros.pl

@@ -2231,11 +2231,6 @@ =head2 Formatting macros
                     # The function should be called either with value specified (immediate reference) or
                     # with url specified in which case the revealed text is taken from the URL $url.
                     # The $display_text is always visible and is clicked to see the contents of the knowl.
-    htmlLink($url, $text)
-                    # Places a reference to the URL with the specified text in the problem.
-                    # A common usage is \{ htmlLink(alias('prob1_help.html') \}, 'for help')
-                    # where alias finds the full address of the prob1_help.html file in the same directory
-                    # as the problem file
     iframe($url, height=>'', width=>'', id=>'', name=>'' )
                     # insert the web page referenced by $url in a space defined by height and width
                     # if the webpage contains a form then this must be inserted between
@@ -2362,18 +2357,31 @@ sub OL {
 	);
 }
 
+=head2 htmlLink
+
+Usage: C<htmlLink($url, $text, @attributes)>
+
+Places an HTML link to C<$url> with the specified C<$text> in the problem. The
+C<@attributes> are optional.  They should be provided as attribute/value pairs,
+but a single text string argument can be given (although calling C<htmlLink> in
+that way is deprecated and should not be done in new problems).  For example,
+
+    BEGIN_PGML
+    Download the [@ htmlLink($url, 'dataset', download => 'dataset.csv') @]*
+    for this problem.
+
+=cut
+
 sub htmlLink {
-	my $url           = shift;
-	my $text          = shift;
-	my $options       = shift;
-	my $sanitized_url = $url;
-	$sanitized_url =~ s/&/&amp;/g;
-	$options = ""                                             unless defined($options);
-	return "$BBOLD [ the link to '$text'  is broken ] $EBOLD" unless defined($url) and $url;
+	my ($url, $text, @options) = @_;
+	return "$BBOLD [ the link to '$text'  is broken ] $EBOLD" unless $url;
+	my $attributes = @options == 1 ? $options[0] : {@options};
 	MODES(
 		TeX  => "{\\bf \\underline{$text}}",
-		HTML => "<A HREF=\"$url\" $options>$text</A>",
-		PTX  => "<url href=\"$sanitized_url\">$text</url>",
+		HTML => ref($attributes) eq 'HASH'
+		? tag('a', href => $url, %$attributes, $text)
+		: qq{<a href="$url" $attributes>$text</a>},
+		PTX => '<url href="' . ($url =~ s/&/&amp;/g) . qq{">$text</url>},
 	);
 }