Wolfram Language & System Documentation Center

"Ruby" (External Evaluation System)

Details

ExternalEvaluate Usage

  • ExternalEvaluate["Ruby",code] executes the code string in a Ruby REPL and returns the results as a Wolfram Language expression.
  • ExternalEvaluate["Ruby""String",code] executes the code string in a Ruby REPL and returns the output as a Wolfram Language string.
  • Possible settings for "type" in ExternalEvaluate["Ruby""type",code] include:
  • "Expression"attempt to convert to a Wolfram Language expression
    "String"give the raw string output by the external evaluator
    "ExternalObject"return the result as ExternalObject

Data Types

  • The following Ruby built-in types are supported:
  • ArrayListarray of values
    BigDecimalRealarbitrary-precision real number
    BignumIntegerarbitrary-sized integer
    booleanTrue|FalseBoolean values
    ComplexComplexcomplex number
    FixnumIntegermachine-size number
    FloatRealreal-valued number
    HashAssociationassociative array
    nilNullnull value
    RationalRationalrational number
    StringStringsequence of character values

Usage Notes

  • String templates (<*…*>) can be used to evaluate and insert Wolfram Language expressions into the Ruby code string.

Supported External Operations

  • ExternalOperation["Eval","code"] represents an external evaluation of "code".
  • ExternalOperation["Eval","code",assoc] represents an external evaluation of "code" with parameters given by assoc.
  • ExternalOperation["Call",func,arg1,arg2,…] calls the function func with the given arguments arg1, arg2, ….
  • ExternalOperation["GetAttribute",obj,"attr"] gets the attribute "attr" of obj.
  • ExternalOperation["SetAttribute",obj,"attr",val] sets the attribute "attr" of obj to the given value val.
  • ExternalOperation["Cast",obj,"type"]casts obj to the given "type".

Examples

open all close all

Basic Examples  (3)

Evaluate 2+2 in Ruby and return the result:

Arrays are returned as lists:

Type > and select Ruby from the drop-down menu to get a code cell that uses ExternalEvaluate to evaluate:

[1,2,3,4].map { |n| n * 2 }

Scope  (27)

Start a Ruby session:

Concatenate strings in Ruby and return the result:

Hashes in Ruby are returned as associations:

Close the session:

Session Options  (8)

"ReturnType"  (3)

For the Ruby evaluation system, the default return type is "Expression":

Numbers, strings, lists and associations are automatically imported for the "Expression" return type:

The return type of "String" returns a string of the result by calling the Ruby method to_s:

"Evaluator"  (1)

Evaluate Ruby code using a specified "Evaluator":

"SessionProlog"  (1)

Use "SessionProlog" to perform a side effect at the start of a session:

"SessionEpilog"  (1)

Use "SessionEpilog" to perform a side effect at the end of a session:

"Prolog"  (1)

Use "Prolog" to perform a side effect before every evaluation:

"Epilog"  (1)

Use "Epilog" to perform a side effect after every evaluation:

Command Options  (10)

"Command"  (3)

When only a string of Ruby code is provided, the command is directly executed:

The above is equivalent to writing the command using this form:

Use a File wrapper to run the code in a file:

The above is equivalent to writing the command using this form:

Put code in a CloudObject:

Evaluate directly from the cloud:

The above is equivalent to writing the command using this form:

"ReturnType"  (1)

By default, the command is executed using the "ReturnType" specified during the session creation:

Specifying a "ReturnType" in the command overrides the "ReturnType" for the session:

"Arguments"  (2)

Use "Arguments" to call a Ruby function with arguments:

When a non-list argument is provided, a single argument is passed to the function:

If you need to pass a list as the first argument, you must wrap it with an extra list explicitly:

You can define a function inside "Command" and directly call it with "Arguments":

The same result can be achieved by using a Rule:

You can also pass arguments by creating an ExternalFunction:

"Constants"  (1)

Use "Constants" to permanently set global variables before the command runs:

"TemplateArguments"  (3)

When running a command, you can inline a TemplateExpression:

You can explicitly fill TemplateSlot using "TemplateArguments":

When a non-list argument is provided, a single template argument is passed to the template:

If you need to pass a list as the first argument, you must wrap it with an extra list explicitly:

You can name template slots and use an Association to pass named arguments to the template:

External Operations  (8)

"Eval"  (1)

Run an ExternalOperation that represents arbitrary code evaluation in Python:

Use the second argument to pass an evaluation context:

"Call"  (3)

Define an ExternalOperation that creates a function in Ruby:

Call the function by running the ExternalOperation "Call":

Run the operation using ExternalEvaluate:

Any argument of the "Call" operation can be an ExternalOperation:

Arguments can also be passed directly in ExternalEvaluate by doing the following:

The result is equivalent to running the following Ruby code:

Create an ExternalFunction for a Ruby function:

Call the function by running the operation "Call":

The same result can be achieved by doing the following:

Create an ExternalObject for a function in Ruby:

Call the function by running the operation "Call":

The same result can be achieved by doing the following:

Or by using ExternalObject subvalues:

Close the session:

"GetAttribute"  (2)

Start a Ruby session to work with dates:

Return an ExternalObject for a Date object:

Extract the year attribute by using "GetAttribute":

The result is equivalent to running the following Ruby code:

Delete the session:

Create an ExternalObject that represents a date:

Use ExternalOperation to get the current year:

For most evaluators, "GetAttribute" is the default operation, and ExternalOperation can be omitted:

Delete the session:

"SetAttribute"  (1)

Start a Ruby session to work with dates:

Create an object with a date:

Set the year to 2024:

Check that the year was set to 2024:

The result is equivalent to running the following Ruby code:

Delete the session:

"Cast"  (1)

Create an ExternalObject that represents the current date:

Use "Expression" to return the object as a Wolfram Language expression:

The Cast operation can also run in ExternalObject subvalues:

The symbol Expression is a shortcut for the same:

Return the object as a string:

The symbol String is a shortcut for the same:

Return the object as an ExternalObject:

The symbol ExternalObject is a shortcut for the same:

The same can be achieved by using "ReturnType" in ExternalEvaluate:

Delete the session:

Applications  (1)

Define a Wolfram Language function that calls a custom Ruby function:

Close the session: