r_call.pl -- R plugin for SWISH

This module make R available to SWISH using the Rserve R package. The module r_serve.pl implements a SWI-Prolog wrapper around the Rserve C++ client to realise the communication with the R server.

The Prolog view at R is inspired by real from Nicos Angelopoulos.

It consists of the following two predicates:

Var <- Expression Assign the result of evaluating the given R Expression to Var. Var can be a Prolog variable or an R expression.
<- Expression Evaluate expression, discarding the result. Possible console output is captured.

In addition, the quasi quotation r is defined. The quasi quotation takes Prolog variables as arguments and an R expression as content. Arguments (Prolog variable names) that match R identifiers cause the temporary of an R variable with that name bound to the translated Prolog value. R quasi quotations can be used as isolated goals, as well as as right-hand arguments to <-/2 and <-/1. The example below calls the R plot() function on the given Prolog list.

?- numlist(1,10,Data),
   {|r(Data)||plot(Data)|}.

Images created by the R session are transferred as SVG and sent to the SWISH console using pengine_output/1.

<-(Var, Expression) is det

Assign the result of evaluating the given R Expression to Var. Var can be a Prolog variable or an R expression.

<-(Expression) is det

Evaluate Expression, discarding the result. Possible console output is captured using the R function capture.output.

r_capture(Assignments, Command)[private]

Execute Command, presenting the R console output to the (Prolog) user.

r_call(+Fun, +Options)

Construct and possibly call an R function. Fun can be an atom or a compound, eg plot, or plot(width=3). The predicate also supports multiple output destinations. Options processed:

call(Bool): If false (default true), do not call the result.
fcall(-Term): Term is unified with the constructed call
rvar(Var): Variable for the output

Compatibility: - This is a partial implementation of the corresponding real predicate.

r_console(+Stream, ?Term)[multifile]

Hook console interaction. Currently only used for <-/1 to emit the captured output. In this cases, Stream is stdout and Term is a list of strings, each representing a line of output. The list can be empty. If the hook fails, maplist(writeln, Term) is called to write the output to current_output.

r_execute(+Assignments, +Command, -Result) is det

Execute the R command Command after binding the variables in Assignments and unify the result with Result.

Arguments:

`Assignments`	- is a list of Name=Value, where Name must be a valid R indentifier.
`Command`	- is a string holding the R command to execute

r_unbind(+Bindings)[private]

Remove the created bindings from the R environment

r_setup_console(+R)[private]

Set the notion of R's console with to the width of the Prolog console. This may be hooked by r_console_property(size(Rows,Cols) to deal with e.g., SWISH.

r(+Content, +Vars, +VarDict, -Goal) is det

Parse {|r(Arg,...||R-code|} into a the expression below. This expression may be passed to <-/2 and <-/1 as well as used directly as a goal, calling r_execute/3.

r_execute(Assignments, Command, Result)

See also: - https://cran.r-project.org/doc/manuals/r-release/R-lang.html#Parser
To be done: - Verify more of the R syntax.

diff_to_atom(+Start, +End, -Atom)[private]

True when Atom is an atom that represents the characters between Start and End, where End must be in the tail of the list Start.

rserve:r_open_hook(+Name, -R)[multifile]

Called for lazy creation to the Rserve server. Connections are per-thread. The destination depends on settings:

Unix domain socket: If rserve:socket is defined and not empty, it is taken as the path to a Unix domain socket to connect to.
TCP/IP socket: Else, if rserve:port and rserve:host is defined, we connect to the indicated host and port.

After the connection is established, the session can be configured using the hook r_init_session/1. The default calls r_setup_graphics/2 to setup graphics output to send SVG files.

r_init_session(+RConn) is semidet[multifile]

Multifile hook that is called after the Rserve server has handed us a new connection. If this hook fails, r_setup_graphics/2 is called to setup capturing graphics as SVG files.

r_setup_graphics(+Rconn, +Format) is det

Setup graphics output using files. Currently only supports Format = svg.

r_send_images is det[private]

Collect the images saved on the server and send them to SWISH using pengine_output/1.

r_display_images(+Images:list)[multifile]

Hook to display images.

Arguments:

Images - is a list of images. Each image is of the form Format(String), where Format is the file extension. Currently only uses svg. If not defined, print_message/2 is called with the term r_images(Images).

r_images(-Images:list) is semidet[private]

Collect saved image files from Rserve. This assumes that

The R connection is in the global variable R. If there is no connection, there are no images.
There are only images if there is a current device. This is closed using dev.off().
Images are called <base>%03d.<ext>, where <base> is in the global variable Rimage_base and <ext> in Rimage_ext.