The All-New WolframScript

Itai Seggev, Senior Kernel Developer, Wolfram Research, Inc.
Garrett Ducharme, Software Engineer, Wolfram Research, Inc.

Join the Conversation #WolframTechConf

Outline

Interactive Use

Script Basics
Advanced Examples

Interactive Use

One-shot evaluations from the command line

Cloud evaluations from the command line, including APIFunction

Run package files from the command line

Automatically export results to any format supported by Export

Applying operations to each line of a file

[Live demo]

wolframscript -code '$Version'
wolframscript -code '$Version' -cloud

wolframscript -api https://wolfr.am/feGTbBKn -args x=hello
wolframscript -api https://wolfr.am/feGTbBKn -args x=hello y=world 

wolframscript -file afternoon.m

wolframscript -code 'StringReverse[$ScriptInputString]'  < palindromes.txt
wolframscript -code 'StringReverse[$ScriptInputString]' -linewise < palindromes.txt

Setup

WolframScript can exist outside of a Mathematica installation

Executable is self contained

Will search for “best” local kernel if doing kernel evaluation

Exact setup for interactive use platform dependent

Linux

Typically no setup needed

The installer automatically adds wolframscript to the same location as wolfram, Mathematica, and other executables (defaults to /usr/local/bin).

macOS

Not available for command-line use without running installer

Double click on Extras.pkg to install wolframscript into /usr/local/bin and add it to the path.

Windows

No automatic installer in version 11.0 (coming in 11.1).

You can launch it from the installation directory

Script Basics

Execute self-contained Wolfram (Language^™) scripts

Fully supports all Unix-like environments

Linux

OS X

Cygwin, MinGW and similar environments for Windows

All options, including cloud evaluation, can be used

[Example] squares.m

#!/usr/local/bin/wolframscript

If[Length[$ScriptCommandLine]==1,
        Print["No expressions were given to square."],

        args = Rest[$ScriptCommandLine];
        squares = Quiet @ Map[Replace[ToExpression[#], {$Failed:>ToString[#,InputForm]^2, x_ :> x^2}]&, args];
        MapThread[Print["The square of ", #1, " is ", #2, "."]&, {args, squares}]
]

More on Script Files

Must have “executable bit”

Other than first line, normal package files

Additional options go on #! line

[Example] city_distance_km.m

#!/usr/local/bin/wolframscript -function -signature City City
Round@QuantityMagnitude[GeoDistance[#1, #2],"Kilometers"]&

Detailed instructions

Create a .m file with the specified contents.

If on Windows, do one of the following:

Copy wolframscript.exe into /usr/local/bin for your Unix-like environment.

Change to path on the first line of the script to point to your (Mathematica^®) 11 installation. Note that there can be no spaces in the path, so you should use "8.3" pathnames to avoid this. Typical values for this path are:

/cygdrive/c/PROGRA~1/WOLFRA~1/Mathematica/11.0/wolframscript.exe (Cygwin)

/c/PROGRA~1/WOLFRA~1/Mathematica/11.0/wolframscript.exe (MinGW)

Make the file executable using the command chmod a+x filename.

Examples: Bell Sound

Using arguments from the command line

[Live demo]

sound_bell.wls 800
sound_bell.wls 400

sound_bell.wls

#!/usr/local/bin/wolframscript

frequency = ToExpression[$ScriptCommandLine[[2]]];

partials = frequency*{.56, .92, 1, 1.19, 1.71, 2, 2.74, 3};
amplitudes = {.25, .5, 1, .5, .25, .125, .0625, .03125};
envelope = Table[If[t < .01, 100*t, (1-t/4)^3], {t, 0, 4-1/44100, 1/44100}];
sineBank= Mean[amplitudes (AudioGenerator[{"Sin",#}, 4]&/@partials)]
audioData = AudioData[sineBank]*envelope;
sound = ListPlay[audioData, SampleRate->44100, PlayRange->All];

f = CreateFile[]<>".wav";
Export[f, sound];
Run[f]

Examples: Deployed API

Using an API

Create an API using CloudDeploy + APIFunction.

url = "https://www.wolframcloud.com/objects/e5279dc7-0a0d-4d5e-88c0-a6e0f24e87ef";
CloudDeploy[APIFunction[{"city"->"City"}, (
weather=WeatherForecastData[#city, DateObject[], UnitSystem->"Imperial"]//DeleteMissing//Normal;
StringRiffle[ToString/@weather, "\n"]
)&, ResponseForm[#, "WL", {"Result"}]&], url]

APIs can be called using full URL or just the UUID

wolframscript -api e5279dc7-0a0d-4d5e-88c0-a6e0f24e87ef -args city=Champaign

Calling an API from a script

weather.wls

#!/usr/local/bin/wolframscript -api e5279dc7-0a0d-4d5e-88c0-a6e0f24e87ef -args

Examples: Image IO

Using $ScriptInputString

The -print option

Formatting output as an image

Error and exit codes

[Live demo]

start castle.png
./color_balance.wls < castle.png > balanced.png
start balanced.png

color_balance.wls

#!wolframscript -format PNG -print
img = ImportString[$ScriptInputString, "PNG"];
If[ImageQ[img],
	Write["stderr", "It successfully loaded"]
	Write["stderr", ImageDimensions[img]]
	,
	Write["stderr", "Image could not be loaded."];
	Exit[2];
];

ColorBalance[img]

Thanks

Future directions

Integration into Windows installer

Standalone installer

Double-clickable scripts: .wls

Additional Resources:

Systems-level functionality (web page)

ref/program/wolframscript

tutorial/WolframLanguageScripts