r_serve.pl -- SWI-Prolog Rserve client

This module provides a low-level binding to the Rserve R server process.

 r_open(-RServe, +Options) is det

Open a connection to an R server. Options:

alias(+Alias)

Give a name to the connection.

host(+Host)

Connect to Host (default: 127.0.0.1).

port(+Port)

Connect to port (default: 6311). If Port is -1, Host is interpreted as a path name and a Unix domain socket (named pipe) is used.

open(+How)

If once, turn opening a connection for the second time in a no-op.

 r_close(+Rserve) is det

Close an open connection to an R server.

 r_login(+Rserve, +User, +Password) is det

Login with the R server.

 r_assign(+Rserve, +VarName, +Value) is det

Assign a value to variable VarName in Rserve. Value follows a generic transformation of Prolog values into R values:

list

A list is translated into an R array of elements of the same type. The initial type is determined by the first element. If subsequent elements to not fit the type, the type is promoted. Currently defined promotions are:

• Integers are promoted to doubles.

boolean

The Prolog atoms true and false are mapped to R booleans.

integer

Prolog integers in the range -2147483648..2147483647 are mapped to R integers.

float

Prolog floats are mapped to R doubles.

atom

Atoms other than true and false are mapped to strings.

string

A Prolog string is always mapped to an R string. The interface assumes UTF-8 encoding for R. See the encoding setting in the Rserve config file.

c(Elem1, Elem2, ...)

A compound term with functor c is handled in the same way as a list.

 r_eval(+Rserve, +Command, -Value) is det

Send Command to Rserve and translate the resulting R expression into a Prolog representation. The transformation from R expressions to Prolog data is defined as follows:

TRUE or FALSE

The R booleans are mapped to the Prolog atoms true and false.

integer

R integers are mapped to Prolog integers.

double

R doubles are mapped to Prolog floats.

string

R strings are mapped to Prolog strings. The interface assumes UTF-8 encoding for R. See the encoding setting in the Rserve config file.

See also

- r_eval_ex/3 to map R exceptions to Prolog. By default, the non-interactive R server terminates on an exception and thus if r_eval/3 causes an R exception R terminates and Prolog receives an I/O error.

 r_eval_ex(+Rserve, +Command, -Result) is det

As r_eval/3, but captures R exceptions and translates these into Prolog exceptions.

 r_eval(+Rserve, +Command) is det

Evaluate R Command without waiting for a reply. This is called void evaluation in Rserve.

 r_read_file(+RServe, +FileName, -Content:string) is det

Read the content of a remote file into the string Content.

 r_remove_file(+RServe, +FileName) is det

Remove FileName from the server.

 r_open_hook(+Alias, -Rserve) is semidet[multifile]

Hook that is used to translate Alias into an R connection. This is called for R references if the argument is not an Rserve handle, nor an existing alias. The hook may create R on demand. One of the use cases is SWISH, where we want thread-local references to R and we want to create the R connection on the first reference and destroy it as the query dies.

 r_detach(+Rserve, -Session) is det

Detach a session to be resumed later. Session is an opaque handle to the session. The session may be resumed using r_resume/2. The session key may be exchanged with another Prolog process. Note that calling r_detach/2 closes the existing Rserve handle.

 r_resume(-Rserve, +Session) is det

 r_resume(-Rserve, +Session, +Alias) is det

Resume an R session from a key obtained using r_detach/2.

 r_server_eval(+Rserve, +Command)

Evaluate Command in the main server. The main server must be configured to allow for control commands.

 r_server_source(+Rserve, +FileName)

Process FileName on the main server. The main server must be configured to allow for control commands.

 r_server_shutdown(+Rserve)

Cause the main server to shutdown. Note that the current session (Rserve) remains valid.