WolframScript

名称

wolframscript — Wolfram 语言命令行脚本解释器

概要

wolframscript -code code [-cloud [cloudbase] | -local [kernelpath] | -wstpserver [wstpserverbase]] [arg1 …]

wolframscript -file file|url [-cloud [cloudbase] | -local [kernelpath] | -wstpserver [wstpserverbase]] [arg1 …]

wolframscript -api url|uuid|file [-cloud [cloudbase] | -local [kernelpath] | -wstpserver [wstpserverbase]] [-args key=value …]

wolframscript -function code [-cloud [cloudbase] | -local [-kernelpath] | -wstpserver [wstpserverbase]] [-signature type …] [-args values …]

说明

Wolframscript 在本地、云端或 WSTPServer 运行 Wolfram 语言代码、函数和已部署的 API， 接受标准输入、命令行参数、文件、URL 等形式的输入.

选项

代码选项

-c|-code code — 给出要执行的 Wolfram 语言代码.

-f|-file file — 给出含有要执行的 Wolfram 语言代码的文件.

-api url|uuid|file — 在指定的 URL 使用 API，或来自于有指定 UUID 的云端或本地对象，也可以来自于指定的本地文件. 使用参数 key=value …….

-fun|-function code [-s|-signature type …] [-args|-- value …] — 使用参数为字符串 value …… 的函数，将其解释为类型 type ……. 如果没有给出标记 (signature)，则假设所有参数都是字符串. 标记类型可以是 $InterpreterTypes 的任意一种.

执行选项

-l|-local [kernelpath] — 在本地执行代码，使用到 Wolfram Engine 核的指定路径. 缺省情况下，kernelpath 使用本地系统中 Wolfram 语言的最新版本.

-o|-cloud [cloudbase] — 在云端执行代码，使用指定的云基 (cloud base). 缺省情况下，cloudbase 为 https://wolframcloud.com.

-wstpserver [wstpserverbase] — 在 wstpserverbase 指定的 WSTPServer 上执行代码. 默认情况下， wstpserverbase 为端口 31415.

-format type — 指定输出的格式. 可以使用任意可被 Export 接受的格式.

-charset encoding — 对输出使用 encoding. 如果想输出原始字节，编码可设为 None，或 $CharacterEncodings 中的任意一项，除了 "Unicode". 默认情况下，从终端的语言设置中推断.

-linewise — 执行从标准输入读入的每行代码.

-print [all] — 当运行脚本时，将执行脚本最后一行的结果显示出来，在指定 all 时，显示所有行的结果.

-timeout seconds [value] — 指定执行可以使用的秒数. 如果超出指定时间，返回 value 的值.

-v|-verbose — 在执行中打印额外信息.

WSTPServer 选项

-wstpserver [wstpserverbase] — 在 wstpserverbase 指定的 WSTPServer 上执行代码. 默认情况下， wstpserverbase 为端口 31415.

-startprofile file — 创建 WSTPServer 内核配置文件或使用现有内核配置文件，保存内核 ID.

-continueprofile file — 继续使用 WSTPServer 内核配置文件指定的内核.

-startprofile — 在当前壳会话中保存 WSTPServer 内核配置文件信息.

-continueprofile — 继续使用保存在当前壳会话中的 WSTPServer 内核配置文件指定的内核.

-kernelid id — 使用 WSTPServer（已分配 ID 为 id）管理的特定内核.

-kernelpool pool — 使用池 pool 中的 WSTPServer 管理的内核.

实用选项

-h|-help — 打印帮助信息.

-version — 打印 WolframScript 版本.

-auth|-authenticate [wolframid [password]] [-cloud cloudbase] — 执行云端许可验证，指定特定的 Wolfram ID 和密码，没有给出的情况下提示输入. 对不同的云可以指定不同的验证.

-username [wolframid] — 指定在云端认证使用的 Wolfram ID.

-password [password] — 指定在云端认证使用的密码.

-permissionskey key — 使用权限密钥访问云资源.

-entitlement id — 使用按需许可证授权 ID 激活内核.

-listwstpservers — 列出发现的 WSTPServer 服务的详细信息.

-config|-configure [key=value …] — 通过指定特定配置变量的值对 WolframScript 进行配置.

-disconnect [-cloud cloudbase] — 从云端断开，并移除验证信息.

详细信息

Wolfram 语言脚本

#!wolframscript … 行中指定的选项将被忽略，除非脚本由 Unix 样式的壳启动.

在 #!wolframscript 脚本中可以使用所有标准选项.

当设置为 #!wolframscript -function …… 时，可以在命令行脚本中给出函数的每个参数.

当设置为 #!wolframscript -api …… 时，可以按 -key value …… 形式在命令行脚本中给出 API 的参数.

可以用 Exit[code]指定在执行脚本时退出的代码.

没有设置 -print 时，不传送任何输出到 stdout，除非使用 Print[expr] 命令明确指出.

当有选项 -print 时，把脚本最后一行的结果传送到 stdout.

当有选项 -print all 时，脚本中每一行命令的结果产生后都被传送到 stdout.

-linewise 选项可用来多次运行脚本，每次取一行 stdin 作为输入.

命令行输入

在 Wolfram 语言代码中，可以用 $ScriptInputString 获取按标准输入形式给出的脚本输入.

可以用 $ScriptCommandLine 获取命令行中给出的参数.

输出格式

TotalWidth 的缺省设置为 Infinity.

API 参数

如果 API 支持多个参数，如 x-url、x-format 和 _timeout，可将它们用在 wolframscript -api 命令中.

代码位置

在 wolframscript -api uuid 中，如果存在，就用 LocalObject["uuid"]，否则使用 CloudObject["uuid"].

WSTPServer 用法的详细说明

WolframScript 可使用 DNS Service Discovery (DNS-SD)，以找出网络上已播发的 WSTPServer 服务.

如果使用选项 -listwstpservers，WolframScript 将显示它找到的 WSTPServer 服务.

如果使用选项 -wstpserver wstpserverbase，wstpserverbase 可以是形式为 port[@hostname] 的链接名称、WSTPServer 服务的名称或形式为 wstp://hostname[:port][/kernelSpecifier] 的 URL. 默认情况下， wstpserverbase 为 31415. kernelSpecifier 可以是内核 ID 或池的名称. 如果提供了 kernelSpecifier，WolframScript 将使用由 WSTPServer 管理的指定内核. 如果 kernelSpecifier 被省略，WolframScript 将使用来自默认内核池的 WSTPServer 提供的内核.

如果没有给出选项 -wstpserver wstpserverbase，WolframScript 将尝试连接到默认 wstpserverbase的 WSTPServer. 如果该连接失败，WolframScript 将尝试连接到自动发现的 WSTPServer 服务.

WolframScript 主要使用配置文件与 WSTPServer 交互. 配置文件中含有对 WSTPServer 管理的内核的描述. 该描述所必须采用的形式在下面的“配置文件的变量”部分给出.

如果给出选项 -startprofile file，WolframScript 将在 file 中创建配置. 如果 file 已存在，WolframScript 将使用 file 所描述的内核，但它会忽略文件中任何内核 ID. WolframScript 将在 file 中保存使用的内核的 ID，以供 -continueprofile file将来使用.

如果给出选项 -startprofile，如果没有提供 file 且是从壳开始运行，WolframScript 将使用的内核的 ID 临时保存在当前壳会话中，以供 -continueprofile 将来使用. 这种行为也适用于提供了 -wstpserver，但没有提供 -continueprofile 的情况. WolframScript 将使用默认内核池中的 WSTPServer 提供的内核. 保存的 ID 将在给出 -startprofile 后的三个小时内过期. 如果没有提供 file，且如果没有从壳开始运行，WolframScript 可能会失败.

如果给出选项 -continueprofile file，WolframScript 将从由先前提供给 -startprofile file 的配置 file 指定的 WSTPServer 管理的内核继续运行. 如果之前没有将 file 提供给 -startprofile，WolframScript 将失败.

如果给出选项 -continueprofile，如果没有提供 file 且是从壳开始运行，WolframScript 将从之前由 -startprofile 在当前壳会话中使用的 WSTPServer 管理的内核继续运行. 如果在当前壳会话中没有使用 -startprofile，WolframScript 将失败.

范例

命令行代码

在本地 Wolfram Engine 上执行 Wolfram 语言代码 2+2：

$ wolframscript -code 2+2
4

在 Wolfram 云中执行 Wolfram 语言代码 2+2，需要时提示输入许可验证：

$ wolframscript -cloud -code 2+2
4

如果网络上有可用的正在运行的 WSTPServer，在该 WSTPServer 上运行 Wolfram 语言代码 2+2：

$ wolframscript -wstpserver -code 2+2
4

在本地运行 Wolfram 语言代码，对 Unix 样式的壳的输入进行转义：

$ wolframscript -code 'StringReverse["hello"]'
olleh

在本地运行 Wolfram 语言代码，对 Windows cmd.exe 壳的输入进行转义：

> wolframscript -code StringReverse[\"hello\"]
olleh

执行代码并把结果放入文件中：

$ wolframscript -code "Graphics3D[Sphere[ ]]" -format PNG > file.png

文件代码

从文件中执行 Wolfram 语言代码，返回产生的最终结果：

$ wolframscript -file test.wl
12345

从本地文件中获取代码，但是在云端运行代码：

$ wolframscript -cloud -file test.wl
12345

脚本文件

设置为在本地执行 Wolfram 语言代码文件：

file.wls 
#!/usr/bin/env wolframscript
Print[2+2]
$ ./file.wls
4

在 Unix 样式的壳中运行 Wolfram 云中的 Wolfram 语言代码的文件：

file.wls 
#!/usr/bin/env wolframscript -cloud
Print[2+2]
$ ./file.wls
4

在 Unix 样式的壳中正在运行的 WSTPServer 中执行 Wolfram 语言代码的文件：

file.wls 
#!/usr/bin/env wolframscript -wstpserver
Print[2+2]
$ ./file.wls
4

使用命令行参数的文件：

file.wls 
#!/usr/bin/env wolframscript
Print[ToExpression[$ScriptCommandLine[[2]]]^2]
$ ./file.wls 5
25

一个能给出函数的文件，其参数来自 Unix 样式的壳中的命令行：

file.wls 
#!/usr/bin/env wolframscript -function -signature City City
GeoDistance[#1, #2]&
$ ./file.wls "New York" London
Quantity[3453.7070027090986, Miles]

交互操作

在交互 REPL 中运行 Wolfram 语言：

$ wolframscript
Wolfram {RelatedLinks-NeuralNetRepository.png}.{RelatedLinks-NeuralNetRepository.png} Kernel for {RelatedLinks-NeuralNetRepository.png}
Copyright 1988-{RelatedLinks-NeuralNetRepository.png} Wolfram Research, Inc.

In[1]:= 2+2

Out[1]= 4

In[2]:=

使用正在运行的 WSTPServer 在交互 REPL 中运行 Wolfram 语言：

$ wolframscript -wstpserver

In[1]:= 2+2

Out[1]= 4

In[2]:=

API

运行云端 API：

$ wolframscript -api https://wolfr.am/bNvKWq2U -args x=1 y=2
3

从云中获取 API 代码，但在本地运行 API：

$ wolframscript -api https://wolfr.am/bNvKWq2U -local -args x=1 y=2
3

更多范例

登录不同的云账户：

$ wolframscript -authenticate
Enter WolframID: example-user@wolfram.com
Password:

Success. Saving connection data.

提供证书而不使用提示：

$ wolframscript -username example-user@wolfram.com -password XXXXXX
Success. Saving connection data.

断开与云端的连接，清除连接信息：

$ wolframscript -disconnect

反转输入文件每一行的字符串，将结果写入 Unix 样式的壳中的另一个文件：

$ wolframscript -code 'StringReverse[$ScriptInputString]' -linewise < file1 > file2

反转输入文件每一行的字符串，用 Windows 的 cmd.exe 将结果写入另一个文件：

> wolframscript -code StringReverse[$ScriptInputString] -linewise < file1 > file2

使用超时限制计算：

$ wolframscript -code "Do[Print[i];Pause[1], {i,10}]" -timeout 3
1
2
3
$TimedOut

在 Unix 样式的壳中使用特定的字符集进行输出：

$ wolframscript -code 'Alphabet["Greek"]' -charset UTF8
{α, β, γ, δ, ε, ζ, η, θ, ι, κ, λ, μ, ν, ξ, ο, π, ρ, σ, τ, υ, φ, χ, ψ, ω}

通过 Windows 的 cmd.exe 使用特定的字符集进行输出：

> wolframscript -code Alphabet[\"Greek\"] -charset UTF8
{α, β, γ, δ, ε, ζ, η, θ, ι, κ, λ, μ, ν, ξ, ο, π, ρ, σ, τ, υ, φ, χ, ψ, ω}

在 Unix 样式的壳中，通过脚本中的选项 -print 和 -format 产生一幅图像：

file.wls 
#!/usr/bin/env wolframscript -print -format PNG
ListLinePlot[RandomFunction[WienerProcess[],{0,10,0.01},10]]
$ ./file.wls > plot.png

在 Unix 样式的壳中使用 -print All 选项显示脚本执行过程中产生的每一个结果：

file.wls 
#!/usr/bin/env wolframscript -print All
"Using -print All print will each result"
a = 2+2; (* This line won't print because the ; suppresses output *)
a
$ ./file.wls
Using -print All will each result
4

创建一个由 PermissionsKey 保护的 API，并把密钥传给 WolframScript，以便访问：

$ wolframscript -api 83aa0bc2-8e0c-4ef6-b314-48e0bf283196 -args n=5 -permissionskey thekey
25

检查 WolframScript 的版本：

$ wolframscript -version
WolframScript 1.2.0 for MacOSX-x86-64

配置使用特别的 WolframEngine：

$ wolframscript -config WOLFRAMSCRIPT_KERNELPATH=/Applications/Mathematica.app/MacOS/WolframKernel
Configured:WOLFRAMSCRIPT_KERNELPATH=/Applications/Mathematica.app/MacOS/WolframKernel

文件

缺省配置文件：

  • %APPDATA%\Wolfram\WolframScript\WolframScript.conf
    		Windows
    ~/Library/Application\ Support/Wolfram/WolframScript/WolframScript.conf
    		Macintosh
    ~/.config/Wolfram/WolframScript/WolframScript.conf
    		Unix

缺省认证文件夹：

  • %LOCALAPPDATA%\Wolfram\WolframScript\
    		Windows
    ~/Library/Caches/Wolfram/WolframScript/
    		Macintosh
    ~/.cache/Wolfram/WolframScript/
    		Unix

WOLFRAM 语言变量

下列变量会在 WolframScript 开始执行时被设置.

$CommandLine — 一系列字符串给出使用的完整的命令行.

$ScriptCommandLine — 为正在运行的脚本准备的一系列命令行参数. 这些参数出现在 -option 给出的选项之后.

$ScriptInputString — 一个通过标准输入给出脚本输入的字符串. 在脚本的每次迭代中，选项 -linewise 用一行标准输入载入该变量.

环境变量

WOLFRAMSCRIPT_AUTHENTICATIONPATH — 存储验证信息的文件夹.

WOLFRAMSCRIPT_CONFIGURATIONPATH — 存储永久配置信息的文件.

WOLFRAMSCRIPT_CLOUDBASE — WolframScript 中使用的缺省云基 (cloud base).

WOLFRAMSCRIPT_ENTITLEMENTID — 用于激活内核的按需许可证授权 ID.

WOLFRAMSCRIPT_KERNELPATH — 到缺省的本地可执行 Wolfram Engine 核的路径.

WSTPSERVER 配置文件的变量

WSTPSERVER — 管理所需内核的 WSTPServer 的 WSTPServer base.

POOL — 所需内核组成的池的名称.

KERNELPATH — 所需内核的内核路径.

KEEPALIVE — 关于是否在解除所需内核的桥接时关闭内核的布尔设置.

RESERVEONDISCONNECT — 关于是否在解除所需内核的桥接时保留内核的布尔设置.

如果一个配置文件的变量没有提供，WolframScript 将不会选择由 WSTPServer 根据该配置文件变量管理的内核.