WOLFRAM

Details

  • On macOS and Linux platforms, most shells are supported, including sh, bash, zsh, csh. On Windows, the Windows command prompt and PowerShell are supported.

ExternalEvaluate Usage

  • ExternalEvaluate["Shell",code] executes a string in an operating system shell and returns the result as a Wolfram Language expression.
  • ExternalEvaluate["Shell"form,code] executes the command string and returns the result in the specified form. Possible specifications for form are "Expression", "StandardOutput", "StandardError", "ExitCode" and "Association".

Usage Notes

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

Examples

open allclose all

Basic Examples  (2)Summary of the most common use cases

Run a command in your default shell and return the result:

Out[1]=1

If a command "ExitCode" is not 0, a Failure object is returned:

Out[2]=2

Type > to get a Shell code cell that uses ExternalEvaluate to evaluate:

echo $(date)
Out[6]=6

Use the File wrapper to execute code contained in a file:

Out[1]=1

On Unix systems, make sure the file is executable:

Out[2]=2
Out[3]=3

Deploy code using CloudDeploy and then run the code directly from a CloudObject:

Out[4]=4
Out[5]=5

Use a URL wrapper to directly run code hosted online:

Out[6]=6

Scope  (20)Survey of the scope of standard use cases

Start a session:

Out[1]=1

Evaluate a command and return the result:

Out[2]=2

Extract the "ExitCode" from the result:

Out[3]=3

Extract the original command from the result:

Out[4]=4

Extract the "StandardOutput" and "StandardError" from the result:

Out[5]=5

Close the session:

Use "ReturnType" to specify a different return type:

Out[1]=1
Out[2]=2
Out[3]=3

Session Options  (10)

"ReturnType"  (3)

For Shell systems, the default return type is "Expression":

Out[1]=1

With the return type of "Expression", the result will be a Success or a Failure depending on the exit code:

Out[2]=2

You can extract additional information about the program's output using the properties "StandardOutput", "StandardError" and "ExitCode":

Out[3]=3
Out[4]=4

Possible values for "ReturnType" are "Expression", "StandardOutput", "StandardError" and "ExitCode":

Out[1]=1
Out[2]=2
Out[3]=3
Out[4]=4

You can use a Rule to quickly specify the "ReturnType":

Out[1]=1

Evaluator"  (2)

Evaluate code using a specified "Evaluator":

Out[1]=1

On Windows, use the following to run a command using cmd.exe:

Out[1]=1

To run commands on Windows PowerShell, use the following:

Out[2]=2

"SessionProlog"  (2)

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

Out[1]=1

Start an external session and import an initialization file:

Out[1]=1

"SessionEpilog"  (1)

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

Out[1]=1

"Prolog"  (1)

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

Out[1]=1

"Epilog"  (1)

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

Out[1]=1

Command Options  (8)

"Command"  (5)

When a string is provided, the command is directly executed:

Out[1]=1

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

Out[2]=2

Create a file with a script in it:

Out[1]=1

Un Unix systems, make sure the file is executable:

Out[2]=2

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

Out[3]=3

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

Out[4]=4
Out[1]=1

Use a URL wrapper to directly run code hosted online:

Out[1]=1

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

Out[2]=2

Put code in a CloudObject:

Out[1]=1

Evaluate directly from the cloud:

Out[2]=2

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

Out[3]=3

"ReturnType"  (1)

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

Out[1]=1

"TemplateArguments"  (2)

When running a command, you can inline a TemplateExpression:

Out[1]=1
Out[1]=1

You can explicitly fill TemplateSlot using "TemplateArguments":

Out[2]=2

If you need more than one argument, you can use a List:

Out[3]=3

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

Out[1]=1

Applications  (3)Sample problems that can be solved with this function

Get your local network address:

ifconfig en0 | awk '$1 == "inet" {print $2}'
Out[10]=10

Use Spotlight to search for specific files on your Mac:

mdfind PersonalNotebook
Out[4]=4

Show the 10 largest open files:

lsof / | awk '{ if($7 > 1048576) print $7/1048576 "MB" " " $9 " " $1 }' | sort -n -u | tail
Out[7]=7

Create a function to make sure that a local Git repository is up to date:

Use the function:

Out[2]=2

Use Shell to automate the download of a Git repository, build the program from source and run the program:

Out[1]=1

Properties & Relations  (2)Properties of the function, and connections to other functions

Use FindExternalEvaluators to find all available Evaluators in your machine:

Out[1]=1

Use "Evaluator" to manually specify a shell on your machine:

Out[2]=2

Powershell.exe is a valid "Evaluator" on a Windows system:

Out[3]=3
Out[4]=4

RunProcess can also be used to execute shell commands, but it does not print output interactively:

Out[1]=1
Out[2]=2

Possible Issues  (2)Common pitfalls and unexpected behavior

ExternalEvaluate is unable to interrupt if the program is asking for input:

Out[1]=1

When running external commands that are requiring user input, it is advised to run them in a non-interactive mode:

Out[2]=2

ExternalEvaluate is printing output in real time:

$Output can be used to suppress Print output:

Out[2]=2