Ruby 命令行选项

关于示例

此处的一些示例使用了命令行选项 -e，它会在命令行本身传递要执行的 Ruby 代码。

$ ruby -e 'puts "Hello, World."'

此处的一些示例假设文件 desiderata.txt 存在。

$ cat desiderata.txt
Go placidly amid the noise and the haste,
and remember what peace there may be in silence.
As far as possible, without surrender,
be on good terms with all persons.

Options

`-0`: 设置 `$/` (输入记录分隔符)

选项 -0 为调用的 Ruby 程序定义输入记录分隔符 $/。

该选项的可选参数必须是八进制数字，每个数字的范围是 0..7；这些数字的前面会加上数字 0 来构成一个八进制值。

如果未提供参数，则输入记录分隔符为 0x00。

如果提供了参数，它必须紧跟在选项之后（中间不能有空格或等号 '='）；参数值

0: 输入记录分隔符为 ''；参见特殊行分隔符值。
在范围 (1..0377) 内：输入记录分隔符 $/ 设置为参数的字符值。
任何其他八进制值：输入记录分隔符为 nil。

示例

$ ruby -0 -e 'p $/'
"\x00"
ruby -00 -e 'p $/'
""
$ ruby -012 -e 'p $/'
"\n"
$ ruby -015 -e 'p $/'
"\r"
$ ruby -0377 -e 'p $/'
"\xFF"
$ ruby -0400 -e 'p $/'
nil

另请参阅

选项 -a：将输入行拆分为字段。
选项 -F：设置输入字段分隔符。
选项 -l：设置输出记录分隔符；截断行。
选项 -n：在 gets 循环中运行程序。
选项 -p：-n，带打印。

`-a`：将输入行拆分为字段

选项 -a，当与选项 -n 或 -p 一起使用时，会将 $_ 处的字符串拆分为一个字符串数组，存储在 $F 中。

$ ruby -an -e 'p $F' desiderata.txt
["Go", "placidly", "amid", "the", "noise", "and", "the", "haste,"]
["and", "remember", "what", "peace", "there", "may", "be", "in", "silence."]
["As", "far", "as", "possible,", "without", "surrender,"]
["be", "on", "good", "terms", "with", "all", "persons."]

对于拆分，默认记录分隔符是 $/，默认字段分隔符是 $;。

另请参阅

选项 -0：设置 $/ (输入记录分隔符)。
选项 -F：设置输入字段分隔符。
选项 -l：设置输出记录分隔符；截断行。
选项 -n：在 gets 循环中运行程序。
选项 -p：-n，带打印。

`-c`：检查语法

选项 -c 指定将检查指定的 Ruby 程序的语法，但实际上不执行。

$ ruby -e 'puts "Foo"'
Foo
$ ruby -c -e 'puts "Foo"'
Syntax OK

`-C`：设置工作目录

选项 -C 的参数指定了调用 Ruby 程序的当前工作目录；它不会改变当前进程的工作目录。

$ basename `pwd`
ruby
$ ruby -C lib -e 'puts File.basename(Dir.pwd)'
lib
$ basename `pwd`
ruby

选项与其参数之间的空格可能会被省略。

`-d`：将 `$DEBUG` 设置为 `true`

Ruby 程序中（或被 Ruby 程序调用的）的一些代码可能包含基于全局变量 $DEBUG 的条件语句或块（例如 if $DEBUG）；这些通常会写入 $stdout 或 $stderr。

$DEBUG 的默认值为 false；选项 -d 将其设置为 true。

$ ruby -e 'p $DEBUG'
false
$ ruby -d -e 'p $DEBUG'
true

选项 --debug 是选项 -d 的别名。

`-e`：执行给定的 Ruby 代码

选项 -e 需要一个参数，即要执行的 Ruby 代码；该选项可以指定多次。

$ ruby -e 'puts "Foo"' -e 'puts "Bar"'
Foo
Bar

选项与其参数之间的空格可能会被省略。

命令可以包含其他选项，但不应包含参数（如果提供了参数，则会被忽略）。

`-E`：设置默认编码

选项 -E 需要一个参数，该参数指定了调用 Ruby 程序的默认外部编码，或者默认的外部和内部编码。

# No option -E.
$ ruby -e 'p [Encoding::default_external, Encoding::default_internal]'
[#<Encoding:UTF-8>, nil]
# Option -E with default external encoding.
$ ruby -E cesu-8 -e 'p [Encoding::default_external, Encoding::default_internal]'
[#<Encoding:CESU-8>, nil]
# Option -E with default external and internal encodings.
$ ruby -E utf-8:cesu-8 -e 'p [Encoding::default_external, Encoding::default_internal]'
[#<Encoding:UTF-8>, #<Encoding:CESU-8>]

选项与其参数之间的空格可能会被省略。

另请参阅

选项 –external-encoding：设置默认外部编码。
选项 –internal-encoding：设置默认内部编码。

选项 --encoding 是选项 -E 的别名。

`-F`：设置输入字段分隔符

选项 -F，当与选项 -a 一起使用时，指定其参数将用作拆分时使用的输入字段分隔符。

$ ruby -an -Fs -e 'p $F' desiderata.txt
["Go placidly amid the noi", "e and the ha", "te,\n"]
["and remember what peace there may be in ", "ilence.\n"]
["A", " far a", " po", "", "ible, without ", "urrender,\n"]
["be on good term", " with all per", "on", ".\n"]

参数可以是正则表达式。

$ ruby -an -F'[.,]\s*' -e 'p $F' desiderata.txt
["Go placidly amid the noise and the haste"]
["and remember what peace there may be in silence"]
["As far as possible", "without surrender"]
["be on good terms with all persons"]

参数必须紧跟在选项之后（中间不能有空格或等号 '='）。

另请参阅

选项 -0：设置 $/ (输入记录分隔符)。
选项 -a：将输入行拆分为字段。
选项 -l：设置输出记录分隔符；截断行。
选项 -n：在 gets 循环中运行程序。
选项 -p：-n，带打印。

`-h`：打印简短帮助信息

选项 -h 打印一条简短的帮助消息，其中包含单破折号选项（例如 -I），并且很大程度上省略了双破折号选项（例如 --version）。

参数和其他选项将被忽略。

要获取更长的帮助消息，请使用选项 --help。

`-i`：设置 ARGF 原地模式

选项 -i 为调用的 Ruby 程序设置 ARGF 原地模式；参见 ARGF#inplace_mode=。

$ ruby -e 'p ARGF.inplace_mode'
nil
$ ruby -i -e 'p ARGF.inplace_mode'
""
$ ruby -i.bak -e 'p ARGF.inplace_mode'
".bak"

`-I`：添加到 `$LOAD_PATH`

选项 -I 的参数指定了一个目录，该目录将被添加到全局变量 $LOAD_PATH 的数组中；该选项可以指定多次。

$ pushd /tmp
$ ruby -e 'p $LOAD_PATH.size'
8
$ ruby -I my_lib -I some_lib -e 'p $LOAD_PATH.size'
10
$ ruby -I my_lib -I some_lib -e 'p $LOAD_PATH.take(2)'
["/tmp/my_lib", "/tmp/some_lib"]
$ popd

选项与其参数之间的空格可能会被省略。

`-l`：设置输出记录分隔符；截断行

选项 -l，当与选项 -n 或 -p 一起使用时，通过以下方式修改行尾处理：

将全局变量输出记录分隔符 $\ 设置为输入记录分隔符 $/ 的当前值；这会影响面向行的输出（例如来自 Kernel#puts 的输出）。
对每一行读取的内容调用 String#chop!。

不带选项 -l (未截断)

$ ruby -n -e 'p $_' desiderata.txt
"Go placidly amid the noise and the haste,\n"
"and remember what peace there may be in silence.\n"
"As far as possible, without surrender,\n"
"be on good terms with all persons.\n"

带有选项 -l (已截断)

$ ruby -ln -e 'p $_' desiderata.txt
"Go placidly amid the noise and the haste,"
"and remember what peace there may be in silence."
"As far as possible, without surrender,"
"be on good terms with all persons."

另请参阅

选项 -0：设置 $/ (输入记录分隔符)。
选项 -a：将输入行拆分为字段。
选项 -F：设置输入字段分隔符。
选项 -n：在 gets 循环中运行程序。
选项 -p：-n，带打印。

`-n`：在 `gets` 循环中运行程序

选项 -n 会在 Kernel#gets 循环中运行您的程序。

while gets
  # Your Ruby code.
end

请注意，gets 读取下一行并将全局变量 $_ 设置为最后读取的行。

$ ruby -n -e 'puts $_' desiderata.txt
Go placidly amid the noise and the haste,
and remember what peace there may be in silence.
As far as possible, without surrender,
be on good terms with all persons.

另请参阅

选项 -0：设置 $/ (输入记录分隔符)。
选项 -a：将输入行拆分为字段。
选项 -F：设置输入字段分隔符。
选项 -l：设置输出记录分隔符；截断行。
选项 -p：-n，带打印。

`-p`：`-n`，带打印

选项 -p 类似于选项 -n，但也会打印每一行。

$ ruby -p -e 'puts $_.size' desiderata.txt
42
Go placidly amid the noise and the haste,
49
and remember what peace there may be in silence.
39
As far as possible, without surrender,
35
be on good terms with all persons.

另请参阅

选项 -0：设置 $/ (输入记录分隔符)。
选项 -a：将输入行拆分为字段。
选项 -F：设置输入字段分隔符。
选项 -l：设置输出记录分隔符；截断行。
选项 -n：在 gets 循环中运行程序。

`-r`：要求加载库

选项 -r 的参数指定了一个要在执行 Ruby 程序之前加载的库；该选项可以指定多次。

$ ruby -e 'p defined?(JSON); p defined?(CSV)'
nil
nil
$ ruby -r CSV -r JSON -e 'p defined?(JSON); p defined?(CSV)'
"constant"
"constant"

选项与其参数之间的空格可能会被省略。

`-s`：定义全局变量

选项 -s 指定“自定义选项”将在调用的 Ruby 程序中定义一个全局变量。

自定义选项必须出现在程序名称 *之后*。
自定义选项必须以单个破折号（例如 -foo）开头，而不是双破折号（例如 --foo）。
全局变量的名称基于选项名称：对于自定义选项 -foo，全局变量为 $foo。
全局变量的值是字符串选项参数（如果提供），否则为 true。

可以提供多个自定义选项。

$ cat t.rb
p [$foo, $bar]
$ ruby t.rb
[nil, nil]
$ ruby -s t.rb -foo=baz
["baz", nil]
$ ruby -s t.rb -foo
[true, nil]
$ ruby -s t.rb -foo=baz -bar=bat
["baz", "bat"]

该选项不能与选项 -e 一起使用。

`-S`：搜索 `ENV['PATH']` 中的目录

选项 -S 指定 Ruby 解释器将搜索（如果需要）程序 PATH 环境变量中的目录；程序将在 shell 的当前工作目录中执行（不一定在找到程序的目录中）。

此示例会将路径 'tmp/' 添加到 PATH 环境变量中。

$ export PATH=/tmp:$PATH
$ echo "puts File.basename(Dir.pwd)" > /tmp/t.rb
$ ruby -S t.rb
ruby

`-v`：打印版本；设置 `$VERBOSE`

选项 -v 打印 Ruby 版本并设置全局变量 $VERBOSE。

$ ruby -e 'p $VERBOSE'
false
$ ruby -v -e 'p $VERBOSE'
ruby 3.3.0 (2023-12-25 revision 5124f9ac75) [x64-mingw-ucrt]
true

`-w`：`-W1` 的同义词

选项 -w（小写字母）等同于选项 -W1（大写字母）。

`-W`：设置警告策略

任何 Ruby 代码都可以通过调用方法 Kernel#warn 来创建*警告消息*；Ruby 核心和标准库中的方法也可以创建警告消息。此类消息可能会打印到 $stderr（或者不打印，具体取决于某些设置）。

选项 -W 通过设置全局变量 $-W 的初始值，来帮助确定特定警告消息是否会被写入。

-W0：将 $-W 设置为 0（静默；无警告）。
-W1：将 $-W 设置为 1（中等详细程度）。
-W2：将 $-W 设置为 2（高详细程度）。
-W：与 -W2 相同（高详细程度）。
未提供选项：与 -W1 相同（中等详细程度）。

$-W 的值反过来决定了（如果有的话）哪些警告消息将被打印到 $stdout（参见 Kernel#warn）。

$ ruby -W1 -e 'p $foo'
nil
$ ruby -W2 -e 'p $foo'
-e:1: warning: global variable '$foo' not initialized
nil

Ruby 代码还可以为特定类别定义警告；这些是已定义类别的默认设置。

Warning[:experimental] # => true
Warning[:deprecated]   # => false
Warning[:performance]  # => false

它们也可以被设置。

Warning[:experimental] = false
Warning[:deprecated]   = true
Warning[:performance]  = true

您可以通过在类别名称前添加 no- 来抑制一个类别。

$ ruby -W:no-experimental -e 'p IO::Buffer.new'
#<IO::Buffer>

`-x`：执行文本中找到的 Ruby 代码

选项 -x 执行一段 Ruby 程序，其代码嵌入在其他非代码文本中。

Ruby 代码

开始于第一个以 '#! 开头并包含字符串 'ruby' 的行之后。
结束于以下任何一个之前：
- 文件结尾。
- 一行由 '__END__' 组成，
- 字符 Ctrl-D 或 Ctrl-Z。

示例

$ cat t.txt
Leading garbage.
#!ruby
puts File.basename(Dir.pwd)
__END__
Trailing garbage.

$ ruby -x t.txt
ruby

可选参数指定了要查找文本文件的目录；Ruby 代码在该目录中执行。

$ cp t.txt /tmp/
$ ruby -x/tmp t.txt
tmp
$

如果提供了参数，它必须紧跟在选项之后（中间不能有空格或等号 '='）。

`--backtrace-limit`：设置回溯限制

选项 --backtrace-limit 设置回溯中显示的条目数量限制。

参见 Thread::Backtrace.limit。

`--copyright`：打印 Ruby 版权

选项 --copyright 打印版权消息。

$ ruby --copyright
ruby - Copyright (C) 1993-2024 Yukihiro Matsumoto

`--debug`：`-d` 的别名

选项 --debug 是选项 -d 的别名。

`--disable`：禁用功能

选项 --disable 指定要禁用的功能；参数是要禁用的功能的逗号分隔列表。

ruby --disable=gems,rubyopt t.rb

支持的功能

gems：Rubygems（默认：启用）。
did_you_mean：did_you_mean（默认：启用）。
rubyopt：RUBYOPT 环境变量（默认：启用）。
frozen-string-literal：冻结所有字符串字面量（默认：禁用）。
jit：JIT 编译器（默认：禁用）。

另请参见选项 –enable。

`--dump`：转储项目

选项 --dump 指定要转储的项目；参数是要转储项目的逗号分隔列表。

某些参数值会导致命令的行为与提供了不同选项时一样。

--dump=copyright：与选项 –copyright 相同。
--dump=help：与选项 –help 相同。
--dump=syntax：与选项 -c 相同。
--dump=usage：与选项 -h 相同。
--dump=version：与选项 –version 相同。

有关其他参数值和示例，请参见选项 –dump。

`--enable`：启用功能

选项 --enable 指定要启用的功能；参数是要启用的功能的逗号分隔列表。

ruby --enable=gems,rubyopt t.rb

有关功能，请参见选项 –disable。

`--encoding`：`-E` 的别名。

选项 --encoding 是选项 -E 的别名。

`--external-encoding`：设置默认外部编码

选项 --external-encoding 设置调用 Ruby 程序的默认外部编码；有关 encoding 的值，请参见编码：名称和别名。

$ ruby -e 'puts Encoding::default_external'
UTF-8
$ ruby --external-encoding=cesu-8 -e 'puts Encoding::default_external'
CESU-8

`--help`：打印帮助信息

选项 --help 打印详细的帮助消息。

参数和其他选项将被忽略。

要获取更短的帮助消息，请使用选项 -h。

`--internal-encoding`：设置默认内部编码

选项 --internal-encoding 设置调用 Ruby 程序的默认内部编码；有关 encoding 的值，请参见编码：名称和别名。

$ ruby -e 'puts Encoding::default_internal.nil?'
true
$ ruby --internal-encoding=cesu-8 -e 'puts Encoding::default_internal'
CESU-8

`--jit`

选项 --jit 是选项 --yjit 的别名，它启用 YJIT；有关其他 YJIT 选项，请参见 YJIT 文档。

`--verbose`：设置 `$VERBOSE`

选项 --verbose 将全局变量 $VERBOSE 设置为 true 并禁用从 $stdin 输入。

`--version`：打印 Ruby 版本

选项 --version 打印 Ruby 解释器的版本，然后退出。