"Shell" (External Evaluation System)

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)

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

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

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

echo $(date)

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

On Unix systems, make sure the file is executable:

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

Use a URL wrapper to directly run code hosted online:

Scope  (20)

Start a session:

Evaluate a command and return the result:

Extract the "ExitCode" from the result:

Extract the original command from the result:

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

Close the session:

Use "ReturnType" to specify a different return type:

Session Options  (10)

"ReturnType"  (3)

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

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

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

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

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

“Evaluator"  (2)

Evaluate code using a specified "Evaluator":

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

To run commands on Windows PowerShell, use the following:

"SessionProlog"  (2)

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

Start an external session and import an initialization file:

"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  (8)

"Command"  (5)

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

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

Create a file with a script in it:

Un Unix systems, make sure the file is executable:

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

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

Use a URL wrapper to directly run code hosted online:

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)

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

"TemplateArguments"  (2)

When running a command, you can inline a TemplateExpression:

You can explicitly fill TemplateSlot using "TemplateArguments":

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

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

Applications  (3)

Get your local network address:

ifconfig en0 | awk '$1 == "inet" {print $2}'

Use Spotlight to search for specific files on your Mac:

mdfind PersonalNotebook

Show the 10 largest open files:

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

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

Use the function:

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

Properties & Relations  (2)

Use FindExternalEvaluators to find all available Evaluators in your machine:

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

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

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

Possible Issues  (2)

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

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

ExternalEvaluate is printing output in real time:

$Output can be used to suppress Print output: