413 lines
9.3 KiB
Groff
Executable File
413 lines
9.3 KiB
Groff
Executable File
.TH RUBY 1 "Ruby Programmers Reference Guide" "December 31, 2002" "UNIX"
|
|
.SH NAME
|
|
\fBruby\fP
|
|
\- Interpreted object-oriented scripting language
|
|
.SH SYNOPSIS
|
|
.br
|
|
\fBruby\fP
|
|
[\fB\--copyright\fP]
|
|
[\fB\--version\fP]
|
|
[\fB\-Sacdlnpswvy\fP]
|
|
[\fB\-0\fP[\fIoctal\fP]]
|
|
[\fB\-C\fP \fIdirectory\fP]
|
|
[\fB\-F\fP \fIpattern\fP]
|
|
[\fB\-I\fP \fIdirectory\fP]
|
|
[\fB\-K\fP \fIc\fP]
|
|
[\fB\-T\fP[\fIlevel\fP]]
|
|
[\fB\-e\fP \fIcommand\fP]
|
|
[\fB\-i\fP[\fIextension\fP]]
|
|
[\fB\-r\fP \fIlibrary\fP]
|
|
[\fB\-x\fP[\fIdirectory\fP]]
|
|
[\fB\--\fP]
|
|
[\fIprogram_file\fP]
|
|
[\fIargument\fP ...]
|
|
.SH DESCRIPTION
|
|
Ruby is an interpreted scripting language for quick and easy
|
|
object-oriented programming. It has many features to process text
|
|
files and to do system management tasks (as in Perl). It is simple,
|
|
straight-forward, and extensible.
|
|
|
|
If you want a language for easy object-oriented programming, or you
|
|
don't like the Perl ugliness, or you do like the concept of LISP, but
|
|
don't like too much parentheses, Ruby may be the language of your
|
|
choice.
|
|
.SH FEATURES
|
|
Ruby's features are as follows:
|
|
.TP
|
|
.B "Interpretive"
|
|
Ruby is an interpreted language, so you don't have to recompile
|
|
programs written in Ruby to execute them.
|
|
|
|
.TP
|
|
.B "Variables have no type (dynamic typing)"
|
|
Variables in Ruby can contain data of any type. You don't have to
|
|
worry about variable typing. Consequently, it has a weaker compile
|
|
time check.
|
|
|
|
.TP
|
|
.B "No declaration needed"
|
|
You can use variables in your Ruby programs without any declarations.
|
|
Variable names denote their scope, local, global, instance, etc.
|
|
|
|
.TP
|
|
.B "Simple syntax"
|
|
Ruby has a simple syntax influenced slightly from Eiffel.
|
|
|
|
.TP
|
|
.B "No user-level memory management"
|
|
Ruby has automatic memory management. Objects no longer referenced
|
|
from anywhere are automatically collected by the garbage collector
|
|
built into the interpreter.
|
|
|
|
.TP
|
|
.B "Everything is an object"
|
|
Ruby is the purely object-oriented language, and was so since its
|
|
creation. Even such basic data as integers are seen as objects.
|
|
|
|
.TP
|
|
.B "Class, inheritance, and methods"
|
|
Of course, as an object-oriented language, Ruby has such basic
|
|
features like classes, inheritance, and methods.
|
|
|
|
.TP
|
|
.B "Singleton methods"
|
|
Ruby has the ability to define methods for certain objects. For
|
|
example, you can define a press-button action for certain widget by
|
|
defining a singleton method for the button. Or, you can make up your
|
|
own prototype based object system using singleton methods, if you want
|
|
to.
|
|
|
|
.TP
|
|
.B "Mix-in by modules"
|
|
Ruby intentionally does not have the multiple inheritance as it is a
|
|
source of confusion. Instead, Ruby has the ability to share
|
|
implementations across the inheritance tree. This is often called
|
|
`Mix-in'.
|
|
|
|
.TP
|
|
.B "Iterators"
|
|
Ruby has iterators for loop abstraction.
|
|
|
|
.TP
|
|
.B "Closures"
|
|
In Ruby, you can objectify the procedure.
|
|
|
|
.TP
|
|
.B "Text processing and regular expression"
|
|
Ruby has a bunch of text processing features like in Perl.
|
|
|
|
.TP
|
|
.B "Bignums"
|
|
With built-in bignums, you can for example calculate factorial(400).
|
|
|
|
.TP
|
|
.B "Exception handling"
|
|
As in Java(tm).
|
|
|
|
.TP
|
|
.B "Direct access to the OS"
|
|
Ruby can use most
|
|
UNIX
|
|
system calls, often used in system programming.
|
|
|
|
.TP
|
|
.B "Dynamic loading"
|
|
On most
|
|
UNIX
|
|
systems, you can load object files into the Ruby interpreter
|
|
on-the-fly.
|
|
|
|
.SH OPTIONS
|
|
Ruby interpreter accepts following command-line options (switches).
|
|
They are quite similar to those of
|
|
\fBperl\fP(1).
|
|
|
|
.TP
|
|
\fB\--copyright\fP
|
|
Prints the copyright notice.
|
|
|
|
.TP
|
|
\fB\--version\fP
|
|
Prints the version of Ruby interpreter.
|
|
|
|
.TP
|
|
\fB\-0\fP[\fIoctal\fP]
|
|
(The digit
|
|
``zero''.)
|
|
Specifies the input record separator
|
|
("$/")
|
|
as an octal number. If no digit is given, the null character is taken
|
|
as the separator. Other switches may follow the digits.
|
|
\fB\-00\fP
|
|
turns Ruby into paragraph mode.
|
|
\fB\-0777\fP
|
|
makes Ruby read whole file at once as a single string since there is
|
|
no legal character with that value.
|
|
|
|
.TP
|
|
\fB\-C\fP \fIdirectory\fP
|
|
Causes Ruby to switch to the directory.
|
|
|
|
.TP
|
|
\fB\-F\fP \fIpattern\fP
|
|
Specifies input field separator
|
|
("$;").
|
|
|
|
.TP
|
|
\fB\-I\fP \fIdirectory\fP
|
|
Used to tell Ruby where to load the library scripts. Directory path
|
|
will be added to the load-path variable
|
|
("$:").
|
|
|
|
.TP
|
|
\fB\-K\fP \fIkcode\fP
|
|
Specifies KANJI (Japanese) encoding.
|
|
|
|
.TP
|
|
\fB\-S\fP
|
|
Makes Ruby use the
|
|
.IR PATH
|
|
environment variable to search for script, unless if its name begins
|
|
with a slash. This is used to emulate
|
|
#!
|
|
on machines that don't support it, in the following manner:
|
|
|
|
#! /usr/local/bin/ruby
|
|
.br
|
|
# This line makes the next one a comment in Ruby \e
|
|
.br
|
|
exec /usr/local/bin/ruby -S $0 $*
|
|
.br
|
|
|
|
.TP
|
|
\fB\-T\fP[\fIlevel\fP]
|
|
Turns on taint checks at the specified level (default 1).
|
|
|
|
.TP
|
|
\fB\-a\fP
|
|
Turns on auto-split mode when used with
|
|
\fB\-n\fP
|
|
or
|
|
\fB\-p\fP.
|
|
In auto-split mode, Ruby executes
|
|
.nf
|
|
\& $F = $_.split
|
|
.fi
|
|
at beginning of each loop.
|
|
|
|
.TP
|
|
\fB\-c\fP
|
|
Causes Ruby to check the syntax of the script and exit without
|
|
executing. If there are no syntax errors, Ruby will print
|
|
``Syntax OK''
|
|
to the standard output.
|
|
|
|
.TP
|
|
\fB\-d\fP
|
|
.TP
|
|
\fB\--debug\fP
|
|
Turns on debug mode.
|
|
"$DEBUG"
|
|
will be set to true.
|
|
|
|
.TP
|
|
\fB\-e\fP \fIcommand\fP
|
|
Specifies script from command-line while telling Ruby not to search
|
|
the rest of arguments for a script file name.
|
|
|
|
.TP
|
|
\fB\-h\fP
|
|
.TP
|
|
\fB\--help\fP
|
|
Prints a summary of the options.
|
|
|
|
.TP
|
|
\fB\-i\fP \fIextension\fP
|
|
Specifies in-place-edit mode. The extension, if specified, is added
|
|
to old file name to make a backup copy. For example:
|
|
|
|
% echo matz > /tmp/junk
|
|
.br
|
|
% cat /tmp/junk
|
|
.br
|
|
matz
|
|
.br
|
|
% ruby -p -i.bak -e '$_.upcase!' /tmp/junk
|
|
.br
|
|
% cat /tmp/junk
|
|
.br
|
|
MATZ
|
|
.br
|
|
% cat /tmp/junk.bak
|
|
.br
|
|
matz
|
|
.br
|
|
|
|
.TP
|
|
\fB\-l\fP
|
|
(The lowercase letter
|
|
``ell''.)
|
|
Enables automatic line-ending processing, which means to firstly set
|
|
"$\e"
|
|
to the value of
|
|
"$/",
|
|
and secondly chops every line read using
|
|
chop!.
|
|
|
|
.TP
|
|
\fB\-n\fP
|
|
Causes Ruby to assume the following loop around your script, which
|
|
makes it iterate over file name arguments somewhat like
|
|
\fBsed\fP
|
|
\fB\-n\fP
|
|
or
|
|
\fBawk\fP.
|
|
|
|
while gets
|
|
.br
|
|
...
|
|
.br
|
|
end
|
|
.br
|
|
|
|
.TP
|
|
\fB\-p\fP
|
|
Acts mostly same as -n switch, but print the value of variable
|
|
"$_"
|
|
at the each end of the loop. For example:
|
|
|
|
% echo matz | ruby -p -e '$_.tr! "a-z", "A-Z"'
|
|
.br
|
|
MATZ
|
|
.br
|
|
|
|
.TP
|
|
\fB\-r\fP \fIlibrary\fP
|
|
Causes Ruby to load the library using require. It is useful when using
|
|
\fB\-n\fP
|
|
or
|
|
\fB\-p\fP.
|
|
|
|
.TP
|
|
\fB\-s\fP
|
|
Enables some switch parsing for switches after script name but before
|
|
any file name arguments (or before a
|
|
\fB\--\fP).
|
|
Any switches found there are removed from
|
|
ARGV
|
|
and set the corresponding variable in the script. For example:
|
|
|
|
#! /usr/local/bin/ruby -s
|
|
.br
|
|
# prints "true" if invoked with `-xyz' switch.
|
|
.br
|
|
print "true\en" if $xyz
|
|
.br
|
|
|
|
On some systems
|
|
"$0"
|
|
does not always contain the full pathname, so you need the
|
|
\fB\-S\fP
|
|
switch to tell Ruby to search for the script if necessary. To handle
|
|
embedded spaces or such. A better construct than
|
|
"$*"
|
|
would be
|
|
${1+"$@"},
|
|
but it does not work if the script is being interpreted by
|
|
\fBcsh\fP(1).
|
|
|
|
.TP
|
|
\fB\-v\fP
|
|
.TP
|
|
\fB\--verbose\fP
|
|
Enables verbose mode. Ruby will print its version at the beginning,
|
|
and set the variable
|
|
"$VERBOSE"
|
|
to true. Some methods print extra messages if this variable is true.
|
|
If this switch is given, and no other switches are present, Ruby quits
|
|
after printing its version.
|
|
|
|
.TP
|
|
\fB\-w\fP
|
|
Enables verbose mode without printing version message at the
|
|
beginning. It sets the
|
|
"$VERBOSE"
|
|
variable to true.
|
|
|
|
.TP
|
|
\fB\-x\fP[\fIdirectory\fP]
|
|
Tells Ruby that the script is embedded in a message. Leading garbage
|
|
will be discarded until the first that starts with
|
|
``#!''
|
|
and contains the string,
|
|
``ruby''.
|
|
Any meaningful switches on that line will applied. The end of script
|
|
must be specified with either
|
|
EOF,
|
|
"^D" ("control-D"),
|
|
"^Z" ("control-Z"),
|
|
or reserved word
|
|
__END__.
|
|
If the directory name is specified, Ruby will switch to that directory
|
|
before executing script.
|
|
|
|
.TP
|
|
\fB\-y\fP
|
|
.TP
|
|
\fB\--yydebug\fP
|
|
Turns on compiler debug mode. Ruby will print a bunch of internal
|
|
state messages during compiling scripts. You don't have to specify
|
|
this switch, unless you are going to debug the Ruby interpreter.
|
|
|
|
.SH ENVIRONMENT
|
|
.TP
|
|
.B RUBYLIB
|
|
A colon-separated list of directories that are added to Ruby's
|
|
library load path
|
|
("$:"). Directories from this environment variable are searched
|
|
before the standard load path is searched.
|
|
|
|
e.g.:
|
|
.nf
|
|
\& RUBYLIB="$HOME/lib/ruby:$HOME/lib/rubyext"
|
|
.fi
|
|
|
|
.TP
|
|
.B RUBYOPT
|
|
Additional Ruby options.
|
|
|
|
e.g.
|
|
.nf
|
|
\& RUBYOPT="-w -Ke"
|
|
.fi
|
|
|
|
.TP
|
|
.B RUBYPATH
|
|
A colon-separated list of directories that Ruby searches for
|
|
Ruby programs when the
|
|
\fB\-S\fP
|
|
flag is specified. This variable precedes the
|
|
.IR PATH
|
|
environment variable.
|
|
|
|
.TP
|
|
.B RUBYSHELL
|
|
The path to the system shell command. This environment variable is
|
|
enabled for only mswin32, mingw32, and OS/2 platforms. If this
|
|
variable is not defined, Ruby refers to
|
|
.IR COMSPEC.
|
|
|
|
.TP
|
|
.B PATH
|
|
Ruby refers to the
|
|
.IR PATH
|
|
environment variable on calling Kernel#system.
|
|
|
|
.TP
|
|
.B RUBYLIB_PREFIX
|
|
This variable is obsolete.
|
|
|
|
.SH AUTHORS
|
|
Ruby is designed and implemented by
|
|
Yukihiro Matsumoto <matz@netlab.jp>.
|