jrc (version 0.6.0)

callFunction: Trigger a function call

Description

Calls a function in a web page by its name. It can also pass a list of arguments for the function and save the returned result to a variable.

Usage

callFunction(
  name,
  arguments = NULL,
  assignTo = NULL,
  wait = 0,
  sessionId = NULL,
  thisArg = NULL,
  ...
)

Arguments

name

Name of the function. If the function is a method of some object its name must contain the full chain of calls (e.g. myArray.sort or Math.rand).

arguments

List of arguments for the function. Note that in JavaScript arguments must be given in a fixed order, naming is not necessary and will be ignored.

assignTo

Name of a variable to which will be assigned the returned value of the called function.

wait

If wait > 0, after sending the message, R will wait for a reply for a given number of seconds. For this time (or until the reply is received), execution of other commands will be halted. Any incoming message from the session will be considered as a reply.

sessionId

An ID of the session to which the function call should be sent. Can also be a vector of multiple session IDs. If NULL, the function call will be sent to all currently active sessions.

thisArg

JavaScript functions (methods) can belong to some object, which is referred to as this inside the function (e.g. in someObject.myFunction() function myFunction is a method of someObject). thisArg specifies object that will be known as this inside the function. If NULL, the function will use its parent as this object (as it happens in JavaScript by default).

...

further arguments passed to sendData. It is used to send arguments to the web page.

Details

JavaScript counterpart is jrc.callFunction(name, arguments, assignTo, package, internal). Its arguments are:

name

Name of an R function. If function name hasn't been previously added to the list of allowed functions (see allowFunctions or allowedFunctions argument of openPage), attempt to call it from a web page will require manual authorization on the R side.

arguments (optional)

arguments for the function. This should be an Array (for unnamed arguments) or an Object with argument names as keys (for named arguments).

assignTo (optional)

Name of the variable to which the returned value of the function will be assigned in the R session. If the variable name hasn't been previously added to the list of allowed variables (see allowVariables or allowedVariables argument of openPage), attempt to assign it from a web page will require manual authorization on the R side.

package (optional)

If the function needs to be imported from an installed package, name of this package.

internal (optional)

Whether assignment of the function returned value should happen internally or not. If true, result will be stored in the session environment and can be accessed from the outside with getSessionVariable function. If false, result will be saved to the outer environment of the app (see setEnvironment). By default, uses true for variables that already exist in the session environment (see setSessionVariables or sessionVariables argument of the openPage function) and false otherwise.

This function is a wrapper around callFunction method of class Session.

See Also

authorize, allowFunctions, allowVariables, setEnvironment, getSessionIds.

Examples

if (FALSE) {
# to run this example an installed web browser is required
openPage()
callFunction("alert", list("Some alertText"))
callFunction("Math.random", assignTo = "randomNumber")
sendCommand("alert(randomNumber)")
closePage()
}