This library provides an interface to the
OpenCPU API, allowing
programmers to call R functions from Racket over HTTP.
Currently, the focus is on support for the stateless
A major goal of the library is to abstract away the construction
of API URLs, allowing different servers to be used
interchangably — even servers that do not perform any HTTP
requests at all — through the current-opencpu-server
parameter. This is achieved by specifying R functions in terms
of R packages.
Specifies an R package
which corresponds to
the entities implementing the OpenCPU
R package API
Whether a package is global or user-specific is a property of the
, not of the package specification: the same package may be
global on one server
and user-specific on another. For this reason,
values are only equal?
when they are eq?
If the optional guard argument is provided to the constructor,
R functions can only be added to the package when guard returns
a non-false result. See also r-package-can-add-functions/c.
|maybe-name-str|| ||=|| |
| || ||||| ||name-str|
| || || || || |
|option|| ||=|| ||#:arg/c arg/c-expr|
| || ||||| ||#:result/c result/c-expr|
An R function is a procedure of a single argument, which must be either
a list (for by-position arguments to a function) or a hash table (for functions with
named arguments) and must satisfy the contract arg/c. Calling the function
sends a request to the server determined by current-opencpu-server,
which must support the function’s R package, and returns its result, which
must satisfy the contract result/c. (Specifically, it uses the server’s
For low-level details on the representation of R functions, see
Specifies the server
to be used for calls to R functions
will usually perform an HTTP request to some OpenCPU
server, but may implement its functionality in arbitrary ways: for example,
is a server
which doesn’t allow any
to be run.
Creates a server
that implements R functions
by performing HTTP requests
to the OpenCPU server with base url u
Any R package included in an r-user value in users
is treated as local to that user.
If pkgs is #f, all other R packages are supported and are
assumed to be installed globally. If pkgs is a list of R packages,
only the listed packages are supported as global packages.
A given R package may appear at most once, either in the pkgs
or the users argument to make-opencpu-server.
that uses the public OpenCPU server at
to implement R functions
Creates a server
that behaves like inner-server
but which caches the results of R functions
to avoid consulting
on duplicate calls.
1 Implementing New Types of Servers
to execute its implementation of the R function fn
using the argument arg
. The implementation may perform an HTTP request
to an OpenCPU server (as servers
created by make-opencpu-server
but alternatively may produce the result in any arbitrary way (e.g. by consulting a
Contracts recognizing the types of values that can be accepted and produced
by R functions
Reconizes lists that do not contain any duplicate entries
(according to equal?
Creates a flat contract accepting immutable, eq?
consisting of exactly
the symbolic form of each key-id
as keys (i.e. hashes with missing or extra keys will be rejected),
where each corresponding value must satisfy (and/c contract-expr any/r)
Thus, the resulting contract is more strict than hash/r
These contracts may be used in any context, but are particularly useful in
writing contracts for R "data frame" values, which are represented as a list
of hash tables conforming to the same dataframe-entry/c contract,
where each key-id is translated as the heading of "column" of the dataframe.
This section documents exceptions that may be raised by this library.
Note that none of the constructors for structures documented in this
section are provided.
A predicate recognizing the exceptions documented in this section.
The supertype for errors resulting from the OpenCPU HTTP server
(except contract violations, for which exn:fail:contract
is used). Direct instances of this type are currently only created
if the HTTP response has an unknown status code.
Represents an error in the OpenCPU HTTP server, which is indicated by
an HTTP status code of 502 or 503.