WolframScript: Run Your Code from Anywhere

Calling all command-line junkies: the new WolframScript is here!

Now you can evaluate Wolfram Language code, call deployed APIs and execute standalone scripts directly from your favorite command-line interface. WolframScript works like any other command-line utility, enabling flexible connections between the Wolfram System and other programs and I/O.

WolframScript comes packaged with Version 11.1 of Mathematica; on Mac, you must run the Extras installer bundled with the Wolfram System. You can also download and install a standalone version from the WolframScript home page.

Once installed, the wolframscript executable can be found in the same folder as your desktop application, and it is added to the PATH so you can call it directly from any command-line interface.

Interactive Scripting

When executed with no options, wolframscript opens a Wolfram Language console interpreter. This interactive shell (sometimes referred to as a REPL or read–eval–print loop) is a convenient way to write and run Wolfram Language code without launching the desktop front end. It also provides an alternative interface for headless servers or embedded computers (for example, a Raspberry Pi).

When running wolframscript in this way, you can simply enter a line of code and press Enter to see the result. Once you’re finished, use Quit to terminate the interactive session.

One-Shot Code Evaluations

To run a single line of code without launching the interactive shell, use the -code option. Commands entered this way are evaluated immediately by the Wolfram Engine, with the result sent to standard output. When evaluation is complete, the Wolfram kernel is terminated. This is convenient for single-use applications, like viewing the contents of a text file using Import. (In some cases you’ll need to escape inner double quotes with the \ character.)

You can also use redirection to supply a file as input through standard input. This incoming data is represented within a script by $ScriptInputString. Adding -linewise uses the standard NewLine character as a delimiter, treating each line of text as a separate input value.

Defining Functions

For more structured scripting, you can indicate a pure function using the -function option and pass in arguments with -args. By default, arguments are interpreted as strings.

With the -signature option, you can specify how arguments should be parsed in each function slot, including any format available to Interpreter—from basic numeric and string types to entities, quantities and many import/export formats. (Keep in mind that some high-level interpreter types require a connection to the Wolfram Cloud.)

Using Cloud Kernels

If you don’t have a local installation of Mathematica, you can run wolframscript in the cloud. Adding the -cloud option to the end of your command sends the computation to an available cloud kernel. You’ll be asked to authenticate the first time you run something in the cloud.

The -cloud option uses a public kernel on the Wolfram Cloud by default. If you’re connected to Wolfram Enterprise Private Cloud, you can specify a different cloud base by passing its URL (e.g. http://ift.tt/2pLtPKq) as an argument directly after -cloud.

You can open and close these connections manually using -auth and -disconnect. Each cloud requires separate authentication, and connection data is stored for use during your session. Cloud authentication is only necessary for sending dedicated computations; it doesn’t affect Wolfram Knowledgebase access.

Calling Packages and APIs

Code from Wolfram Language packages (.wl, .m) can be executed through wolframscript using the -file option. This evaluates each successive line of code in the file, terminating the kernel when finished.

Unlike with interactive scripting, results from -file are not displayed by default unless enclosed in Print, Write or some similar output function. Using the -print option sends the result of the final computation to standard output, and -print all shows intermediate results as well.

You can also call deployed APIs with the -api option. The following API (generated using APIFunction and CloudDeploy) returns a forecast of high temperatures for the next week in a given city. To call the API with wolframscript, you can reference it by URL or by UUID (the last part of the URL). Parameters are passed in by name; in this case, -args is optional.

Output Formats

By default, wolframscript gives a low-level text representation of the result. You can select the type of output you want, including any format understood by Export, using the -format option. For instance, some output may be easier to read in a table format.

When working with non-textual formats (e.g. spreadsheets, audio, video, graphics), it’s often best to write output directly to a file; you can do this using redirection.

Writing and Executing Scripts

Wolfram Language scripts (.wls) are standalone files containing Wolfram Language code that can be executed like any other application. Structurally, scripts are just packages that are launched as programs rather than notebooks by default. You can create a script from Mathematica with the File > New > Script menu item and execute it by typing its name in the command line (prepending ./ on Linux and Mac systems) or by double-clicking its icon in a file explorer.

The shebang line (starting with #!) tells the Unix environment to check the PATH for the wolframscript executable. On Unix-based systems, you can add launch options to this line by opening the script in a text editor. For instance, if you wanted to implement the travel distance function above as a standalone script, you would include the -function and -signature options in this line. (As of this writing, these options are bypassed when running scripts in Windows, but the goal is to eventually have all platforms work the same.)

To access command-line arguments, use $ScriptCommandLine within your script. Arguments are stored as a list of strings, starting with the full path of the script. In most cases, you’ll want to discard that initial value using Rest.

You may need to convert arguments to the correct data type for computations; this can be done using ToExpression. This script also checks for arguments first, printing a message if none are found.

Redirection works both ways when executing scripts, allowing for advanced applications such as the following image processing example. To maintain formatting for non-textual output, use -format when writing to a file.

You can even launch external programs directly from your script. The following will take a fundamental frequency, generate a bell sound using harmonics, export it to a temporary file and play it in your system’s default audio player.

Final Notes

WolframScript makes it easy to access Wolfram kernels from familiar, low-level interfaces for more flexible and universal computations. And with its cloud connectivity, you can access the Wolfram Language even from machines with no Wolfram System installed.

All the scripts demonstrated here are available for direct download as .wls files. You can execute them directly, change code and launch options in a text editor, or open them in Mathematica for standard notebook features like interactive execution, code highlighting and function completion.

For even more ideas, take a look at the WolframScript documentation and our tutorial on writing scripts. These examples barely scratch the surface—with the full functionality of the Wolfram Language available, the possibilities are endless.

So what are you waiting for? Let’s get scripting!

http://ift.tt/2pLyBrr