The standard C-based Ruby implementation is invoked from the command line like this:
ruby [options
] [--]program
[arguments
]
options
is zero or more command-line arguments that affect the operation
of the interpreter. The legal
arguments are described shortly.
program
is the name of the file that
holds the Ruby program to be run. If the name of the program begins with
a hyphen, precede it with --
to force
it to be treated as a program name rather than as an option. If you use
a single hyphen as the program name, or omit
program
and
arguments
altogether, the interpreter will
read program text from standard input.
Finally, arguments
is any number of
additional tokens on the command line. These tokens become the elements
of the ARGV
array.
The subsections that follow describe the options supported by the
standard C-based Ruby implementation. Note that you may set the
RUBYOPT
environment
variable to include any of the -W
,
-w
, -v
, -d
,
-I
, -r
, -K
,
-E
, and -T
options. These will automatically be
applied to every invocation of the interpreter, as if they were
specified on the command line, unless the command line
includes --disable-rubyopt
.
The following options are probably the most commonly used. Most Ruby implementations can be expected to support these options or to provide a work-alike alternative:
-w
This option enables warnings about deprecated or problematic code and
sets $VERBOSE
to true
. Many Ruby programmers use this
option routinely to ensure that their code is clean.
-e
script
This option runs the Ruby code in script
.
If more than one -e
option is
specified, their associated scripts are treated as separate
lines of code. Also, if one or more -e
option is specified, the
interpreter does not load or run any
program
specified on the command
line.
To enable succinct one-liner scripts, Ruby code specified
with the -e
option may use
the Regexp
matching shortcut
explained later in this chapter.
-I
path
This option adds the directories in path
to the
beginning of the global $LOAD_PATH
array. This specifies
directories to be searched by the load
and require
methods (but does not affect
the loading of the program
specified
on the command line).
Multiple -I
options may
appear in the command line and each may list one or more
directories. If multiple directories are specified with a single
-I
option, they should be
separated from each other with :
on Unix and Unix-like systems and
with ;
on Windows
systems.
-r
library
This option loads the specified library
before running
the specified program. This option works as if the first line of
the program were:
require 'library
'
The space between the -r
and the name of the library is
optional and often omitted.
-rubygems
This frequently used command-line argument is not a true
option but simply a clever application of the -r
option. It loads the module named
ubygems
(with no r) from the
standard library. Conveniently, the ubygems
module simply loads the real
rubygems
module. Ruby 1.9 can
load installed gems without this module, so this option is only
necessary in Ruby 1.8.
--disable-gems
This Ruby 1.9 option prevents the addition of gem
installation directories to the default load path. If you have
many gems installed, and you are running a program that does not
use those gems (or a program that explicitly manages its own
dependencies with the gem
method), you may find that your program startup time is reduced
with this option.
-d
--debug
These options set the global variables $DEBUG
and $VERBOSE
to true
. Your program, or library code,
used by your program may print debugging output or take other
action when these variables are set.
-h
This option displays a list of interpreter options and exits.
The following options control the type or the amount of information the Ruby interpreter displays:
-W
-W2
--verbose
These are all synonyms for -w
: they enable verbose warnings and
set $VERBOSE
to true
.
-W0
-v
This option prints the Ruby version number. If no program is specified,
it exits rather than reading a program from standard input. If a
program is specified, run it as if --verbose
(or -w
) had been specified.
--version
--copyright
--help
These options print Ruby version number, copyright information, or
command-line help and exit. --help
is a synonym for -h
. --version
differs from -v
in that it never runs a specified
program.
The following options are used to specify the default external encoding of the Ruby process and the default source encoding for files that do not specify their own encoding with a coding comment. If none of these options is specified, then the default external encoding is derived from the locale and the default source encoding is ASCII (see Program Encoding for more on source encoding and default external encoding):
-K
code
In Ruby 1.8, this option specifies the source encoding of
the script and sets the global variable $KCODE
. In Ruby 1.9, it sets the
default external encoding of the Ruby process and specifies a
default source encoding.
Specify a code
of a
, A
, n
, or N
for ASCII; u
or U
for Unicode; e
or E
for EUC-JP; and s
or S
for SJIS. (EUC-JP and SJIS are
common Japanese encodings.)
-E
encodings
--encoding=
encodings
These Ruby 1.9 options allow you to specify the default external
encoding, the default internal encoding or both. The
encodings
string is the
case-insensitive name of one or two encodings, separated by a
colon. To specify just a default external encoding, simply use
the name of the desired encoding. To specify two encodings, list
the default external first, followed by a colon and the default
internal. To specify just a default internal encoding, use a
colon followed by the default internal encoding name.
-U
Specifies a default internal encoding of UTF-8. Equivalent
to --encoding=:utf-8
.
The following options alter Ruby’s default text processing behavior, or are
helpful when writing one-line scripts with the -e
option:
-0
xxx
This option is the digit 0
, not the letter O.
xxx
should be between zero and three
octal digits. When specified, these digits are the ASCII code of
the input record separator character and set the $/
variable. This defines “a line” for
gets
and similar methods.
-0
by itself sets $/
to character code 0
. -00
is special; it puts Ruby into
“paragraph mode” in which lines are separated by two adjacent
newline characters.
-a
This option automatically splits each line of input into fields and stores
the fields in $F
. This option
only works with -n
or
-p
looping options and adds
the code $F =
$_.split
at the start of each iteration. See also
-F
.
-F
fieldsep
This option sets the input field separator $;
to fieldsep
. This affects the
behavior of split
when called
with no arguments. See -a
.
fieldsep
may be a
single character or an arbitrary regular expression, without the
delimiting slashes. Depending on your shell, you may need to
quote or double the backslashes in any regular expression
specified on the command line.
-i
[ext
]This option edits the files specified on the command line in place.
Lines are read from the files specified on the command line, and
output goes back to those same files. If
ext
is specified, a backup copy of
the files is made, adding ext
to the
filename.
-l
This option makes the output record separator $
the same as the input record
separator $/
(see -0
), so that that line ending is
automatically added to text output with print
. This option is intended for use
with -p
or -n
. When used with one of those
options, it automatically calls chop
to remove the input record
separator from each line of input.
-n
This option runs the program as if it were enclosed in the following loop:
while gets # Read a line of input into $_ $F = split if $-a # Split $_ into fields if -a was specified chop! if $-l # Chop line ending off $_ if -l was specified # Program text here end
This option works in Ruby 1.9 even though the global
functions chop!
and split
are no longer available in that
version of the language.
This option is often used with -e
. See also -p
.
-p
This option runs the program as if it were written in the following loop:
while gets # Read a line of input into $_ $F = split if $-a # Split $_ into fields if -a was specified chop! if $-l # Chop line ending off $_ if -l was specified # Program text here print # Output $_ (adding $/ if -l was specified) end
This option works in Ruby 1.9 even though the global
functions chop!
and split
are no longer available in that
version of the language.
This option is often used with -e
. See also -n
.
The following options don’t fit into any of the previous categories:
-c
This option parses the program and report any syntax errors, but does not run it.
-C
dir
-X
dir
These options change the current directory to dir
before running the program.
-s
When this option is specified, the interpreter
preprocesses any arguments that appear after the program name
and begin with a hyphen. For arguments of the form -x=y
, it sets $x
to y
. For arguments of the form -x
, it sets $x
to true
. The preprocessed arguments are
removed from ARGV
.
-S
This option looks for the specified program file relative to the
path specified in the RUBY_PATH
environment variable. If it
is not found there, it looks for it relative to the PATH
environment variable. And if it
is still not found, it looks for it normally.
-T
n
This option sets $SAFE
to n
, or to 1
if
n
is omitted. See Security for more.
-x
[dir
]This option extracts Ruby source from the program file by discarding any lines
before the first that starts #!ruby
. For compatibility with the
capital -X
option, this
option also allows a directory to be specified.
3.133.156.251