Creates an instance of an embedded Scala compiler/interpreter. Provides file path for Scala and this package's JAR file. Provides functions to enable other packages to depend on this package.

Description

The function scala creates an instance of an embedded Scala compiler/interpreter and binds a Scala object named R to permit callbacks to R. Options are available to customize where Scala is found and how it is invoked (e.g., setting the classpath and maximum heap size). Multiple interpreters can be created and each runs independently with its own memory. Each interpreter can use multiple threads/cores, but the bridge between R and Scala is not thread-safe. As such, multiple R threads/cores should not simultaneously access the same interpreter.

The functions scalaInfo and .rscalaJar provide file paths to JAR files, installation directories, the Scala executable, and this package. Note that if you only want to embed R in a Scala application, you do not need to install the package. Simply add the following line to the your SBT build.sbt file: ‘libraryDependencies += "org.ddahl" "_VERSION_"’, where _VERSION_ is the rscala version number (i.e., 1.0.14).

scalaInstall downloads and installs Scala in “~/.rscala” in the user's home directory. System administrators should install Scala globally as described here: http://www.scala-lang.org/download/install.html. In short, simply download the archive, unpack it, and add the “scala” script to the path.

The function .rscalaPackage should called by the .onLoad function of a package that wishes to depend on this package. The function should not be called elsewhere. This function sets the classpath to the JAR files in the ‘java’ directory of the package and passes the ... arguments to the scala function. This instance of Scala is available as the object s in the namespace of the package (thereby making it available to the package's function) but it is not exported from the namespace.

Usage

1
2
3
4
5
6
7
8
scala(classpath=character(0),
      serialize=FALSE, scala.home=NULL,
      heap.maximum=NULL, command.line.options=NULL, timeout=60,
      debug=FALSE, stdout=TRUE, stderr=TRUE)
scalaInfo(scala.home=NULL, verbose=FALSE)
scalaInstall()
.rscalaJar(version="")
.rscalaPackage(pkgname, classpath.appendix=character(0), ...)

Arguments

classpath

A character vector whose elements are paths to JAR files or directories which specify the classpath for the Scala compiler/interpreter.

serialize

Should standard output (stdout) and standard error (stderr) be captured and serialized back to R? FALSE (the default) is recommended except on Windows where TRUE may be needed to see output and error messages.

scala.home

A character vector of length one giving the path where Scala is installed. When set to NULL (the default), the function sequentially tries to find the Scala home by: i. using the environment variable SCALA_HOME, ii. querying the operating system search path, and iii. looking in ~/.rscala/scala-X where X is the recommended Scala version number (e.g. 2.11.8) for the package. If all these fail, the function offers to download and install Scala in the above mentioned path (if the current R session is interactive) or it downloads and installs Scala in a temporary directory (if the current R session is noninteractive).

heap.maximum

A character vector of length one used to specify the maximum heap size in the JVM. If NULL, the global option rscala.heap.maximum is queried and, if that is also NULL, Scala's default value is used. This option is ignored if command.line.options is not null.

command.line.options

A character vector whose elements are passed as command line arguments when invoking Scala. If NULL, the global option rscala.command.line.options is queried and, if that is also NULL, the value is set to NULL. A value of NULL means no extra arguments are provided. If you simply want to add to the classpath and/or set the maximum heap size, use the classpath and heap.maximum arguments.

timeout

A numeric vector of length one giving the number of seconds to wait for Scala to start before aborting. The default value is 60 seconds.

debug

An option meant only for developers of the package itself and not intended for users of the package.

stdout, stderr

Where stdout and stderr output that is not serialized is should be sent. TRUE (the default) or "" sends output to the R console (although that may not work on Windows). FALSE or NULL discards the output. Otherwise, this is the name of the file that receives the output.

verbose

A logical vector of length one indicating whether information regarding the search for the Scala installation should be displayed.

version

If "", the package JAR files for all Scala versions are returned. Or, if "2.*.*" where * is a placeholder, the JAR file for that specific major version of Scala is returned.

pkgname

A character string giving the name of the package (as provided the second argument of the .onLoad function) that wishes to depend on this package.

classpath.appendix

A character vector giving additional JAR files or directories for the Scala compiler/interpreter embedded within a package via the .rscalaPackage function. The JAR files in the ‘java’ directory of the package are already included and do not need to be added here.

...

These arguments are passed by the .rscalaPackage function to the scala function.

Value

scala returns an R object representing an embedded Scala interpreter.

scalaInfo returns a list detailing the Scala executable, version, jars, etc.

Author(s)

David B. Dahl dahl@stat.byu.edu

See Also

scalaEval, scalaSet, scalaGet, scalaDef, scalaSettings, strintrplt

Examples

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
.rscalaJar()
scalaInfo(verbose=TRUE)

## Not run: 
# Uncomment the next line to download and install Scala
# scalaInstall()

# Make an instance of the Scala interpreter and see how its output is captured.
s <- scala(serialize=TRUE)
capture.output(s %~% 'println("This is Scala "+scala.util.Properties.versionString)')

# Function defined in R
myMean <- function(x) {
  cat("Here I am in R.\n")
  s %@% 'println("Here I am in Scala.")'
  mean(x)
}

# Function defined in Scala that calls an R function
callRFunction <- s$def('functionName: String, x: Array[Double]','
  R.xx = x
  R.evalD0("y <- "+functionName+"(xx)")
')

# Have Scala call the R's myMean function with input 1:100.
callRFunction('myMean',1:100)

## End(Not run)