Bindings for the R interpreter.
It encapsulates the functionalities of the libR.so shared library provided by the R software. This enables us to embed the R interpreter into Objective Caml, to execute R code from Objective Caml and to exchange data structures between R and Objective Caml. A lot of information on R internals can be found in the official documentation as well as in this document.
THREAD SAFETY
It is important to understand that this binding is a rather low-level binding of R functionality. As such, it is no more thread-safe than R itself, which is not thread-safe at all. Therefore, avoid real threading unless you know what you're doing...
DATA CONVERSION
R is an array-oriented language. Therefore, simple values such as a boolean, a string, a number, are in fact encapsulated, in R, in an array of booleans, an array of strings, an array of numbers. For a simple value, the array has only one element.
Moreover, as R is scientific software, it is important that data types be correctly matched between Objective Caml and R. At the moment, they are not. I am thinking here of the 31/32 bit issues, or 63/64 bit issue, or, for instance.
Internal representation of R values.
Low-level SEXP typing.
type 'a sxp = private sexptype nilsxp = [ `Nil ] sxptype symsxp = [ `Sym ] sxptype langsxp = [ `Lang ] sxptype listsxp = [ `List ] sxptype dotsxp = [ `Dot ] sxptype closxp = [ `Clo ] sxptype envsxp = [ `Env ] sxptype promsxp = [ `Prom ] sxptype specialsxp = [ `Special ] sxptype builtinsxp = [ `Builtin ] sxptype vecsxp = [ `Vec ] sxptype charsxp = [ `Char ] sxptype lglsxp = [ `Lgl ] sxptype intsxp = [ `Int ] sxptype realsxp = [ `Real ] sxptype strsxp = [ `Str ] sxptype rawsxp = [ `Raw ] sxptype exprsxp = [ `Expr ] sxptype 'a nonempty_list = [< `List | `Lang | `Dots ] as 'aR-ints: Language objects (LANGSXP) are calls (including formulae and so on). Internally they are pairlists with first element a reference to the function to be called with remaining elements the actual arguments for the call. Although this is not enforced, many places in the code assume that the pairlist is of length one or more, often without checking.
type internallist = [ | `Nil| `List| `Lang| `Dots
]Type of low-level internal list. In R, such * internal lists may be empty, a pairlist or * a call which is somewhat similar to closure * ready for execution.
type 'a pairlist = [< `Nil | `List ] as 'atype vector = [ | `Char| `Lgl| `Int| `Real| `Str| `Raw| `Expr| `Vec
]module type SXP = sig ... endVector types
R is an array-oriented language. Therefore, simple values such as a boolean, a string, a number, are in fact encapsulated, in R, in an array of booleans, an array of strings, an array of numbers. For a simple value, the array has only one element.
module type Vector = sig ... endR array of integer values
R array of boolean values
Value inspection
Algebraic datatype reflecting R's dynamic typing.
Parsing R code.
type parse_status = | Parse_Null| Parse_OK| Parse_Incomplete| Parse_Error| Parse_EOFOutcome of a parsing request.
Exception raised when parsing fails.
val parse_string : ?max:int -> string -> langsxp listParse a string of R code into R calls.
Parse the first R statement in the given R code.
Evaluation of R code and calls.
exception Runtime_error of langsxp * stringval symbol : ?generic:bool -> string -> Sexp.tRetrieves an R symbol from the symbol table, given its name.
val eval_string : string -> Sexp.tstring takes a string containing R code, and feeds it to the R interpreter. You get the resulting value back. The typing of this function is deliberately unsafe in order to allow the user to type it precisely.
Bug: currently, if you try to execute a statement that refers to symbols that haven't been loaded, you get a segfault. For instance, evaluating a string containing the rbinom symbol without the R.stats package being loaded raises a segfault.
Convenience functions to wrap up arguments, when mapping R functions to Objective Caml functions.
val arg : 'a Enc.t -> ?name:string -> 'a -> argval opt_arg : 'a Enc.t -> string -> 'a option -> argcall f args evaluates an the R function f with respect to a list of arguments. Argument None is ignored, and Some (name,
sexp) is the argument whose optional name is name and whose value is sexp. The typing of this function is deliberately unsafe in order to allow the user to type it precisely.
Initialisation
We provide two mechanisms to activate an R interpreter from OCaml-R:
The first mechanism consists of low-level bindings to the initialisation and termination functions of the libR.so shared library. While this is a rather flexible approach, it has the downside of not being a very static approach, specifically if your intention if to write Objective Caml bindings for a dependent bunch of R packages.
The second mechanism is a static, functorial approach: You just have to create a module with the Interpreter functor to initialise the R interpreter. You provide initialisation details through a module of module type Environment, and Interpreter will set it up correctly.
This functorial facility is available from the OCaml_R module: This OCaml_R module has the sole purpose of initialising the R interpreter with the Standard Environment module. No need to worry about initialisation details.
To create bindings for a dependent bunch of R packages, you simply have to make them depend on the findlib R.interpreter package, which involves the OCaml_R module. This is also convenient on the toplevel, where you simply have to have to invoke the #require "R.interpreter" directive to set up the interpreter.
exception Initialisation_failedDenotes failure to initialise the R interpreter.
val init :
?name:string ->
?argv:string list ->
?env:(string * string) list ->
?packages:string list option ->
?sigs:bool ->
unit ->
unitinit initialises the embedded R interpreter.
val terminate : unit -> unitTerminates the R session.
Environment is the type of a module containing all necessary informations and data in order to set up the R interpreter properly.
The Standard module contains initialisation details for libR.so. These informations are determined when the binding is being compiled.
Functor used to initialise statically an R interpreter, given initialisation details provided by the provided Env module.