1 | .\"Ruby is copyrighted by Yukihiro Matsumoto <[email protected]>.
|
---|
2 | .Dd December 31, 2002
|
---|
3 | .Dt RUBY(1) "" "Ruby Programmers Reference Guide"
|
---|
4 | .\".Dt RUBY 1
|
---|
5 | .Os UNIX
|
---|
6 | .Sh NAME
|
---|
7 | .Nm ruby
|
---|
8 | .Nd Interpreted object-oriented scripting language
|
---|
9 | .Sh SYNOPSIS
|
---|
10 | .Nm
|
---|
11 | .Op Fl -copyright
|
---|
12 | .Op Fl -version
|
---|
13 | .Op Fl Sacdlnpswvy
|
---|
14 | .Op Fl 0 Ns Op Ar octal
|
---|
15 | .Op Fl C Ar directory
|
---|
16 | .Op Fl F Ar pattern
|
---|
17 | .Op Fl I Ar directory
|
---|
18 | .Op Fl K Ar c
|
---|
19 | .Op Fl T Ns Op Ar level
|
---|
20 | .Op Fl e Ar command
|
---|
21 | .Op Fl i Ns Op Ar extension
|
---|
22 | .Op Fl r Ar library
|
---|
23 | .Op Fl x Ns Op Ar directory
|
---|
24 | .Op Fl -
|
---|
25 | .Op Ar program_file
|
---|
26 | .Op Ar argument ...
|
---|
27 | .Sh DESCRIPTION
|
---|
28 | Ruby is an interpreted scripting language for quick and easy
|
---|
29 | object-oriented programming. It has many features to process text
|
---|
30 | files and to do system management tasks (as in Perl). It is simple,
|
---|
31 | straight-forward, and extensible.
|
---|
32 | .Pp
|
---|
33 | If you want a language for easy object-oriented programming, or you
|
---|
34 | don't like the Perl ugliness, or you do like the concept of LISP, but
|
---|
35 | don't like too much parentheses, Ruby may be the language of your
|
---|
36 | choice.
|
---|
37 | .Sh FEATURES
|
---|
38 | Ruby's features are as follows:
|
---|
39 | .Bl -tag -width 6n
|
---|
40 | .It Sy "Interpretive"
|
---|
41 | Ruby is an interpreted language, so you don't have to recompile
|
---|
42 | programs written in Ruby to execute them.
|
---|
43 | .Pp
|
---|
44 | .It Sy "Variables have no type (dynamic typing)"
|
---|
45 | Variables in Ruby can contain data of any type. You don't have to
|
---|
46 | worry about variable typing. Consequently, it has a weaker compile
|
---|
47 | time check.
|
---|
48 | .Pp
|
---|
49 | .It Sy "No declaration needed"
|
---|
50 | You can use variables in your Ruby programs without any declarations.
|
---|
51 | Variable names denote their scope, local, global, instance, etc.
|
---|
52 | .Pp
|
---|
53 | .It Sy "Simple syntax"
|
---|
54 | Ruby has a simple syntax influenced slightly from Eiffel.
|
---|
55 | .Pp
|
---|
56 | .It Sy "No user-level memory management"
|
---|
57 | Ruby has automatic memory management. Objects no longer referenced
|
---|
58 | from anywhere are automatically collected by the garbage collector
|
---|
59 | built into the interpreter.
|
---|
60 | .Pp
|
---|
61 | .It Sy "Everything is an object"
|
---|
62 | Ruby is the purely object-oriented language, and was so since its
|
---|
63 | creation. Even such basic data as integers are seen as objects.
|
---|
64 | .Pp
|
---|
65 | .It Sy "Class, inheritance, and methods"
|
---|
66 | Of course, as an object-oriented language, Ruby has such basic
|
---|
67 | features like classes, inheritance, and methods.
|
---|
68 | .Pp
|
---|
69 | .It Sy "Singleton methods"
|
---|
70 | Ruby has the ability to define methods for certain objects. For
|
---|
71 | example, you can define a press-button action for certain widget by
|
---|
72 | defining a singleton method for the button. Or, you can make up your
|
---|
73 | own prototype based object system using singleton methods, if you want
|
---|
74 | to.
|
---|
75 | .Pp
|
---|
76 | .It Sy "Mix-in by modules"
|
---|
77 | Ruby intentionally does not have the multiple inheritance as it is a
|
---|
78 | source of confusion. Instead, Ruby has the ability to share
|
---|
79 | implementations across the inheritance tree. This is often called
|
---|
80 | .Sq Mix-in .
|
---|
81 | .Pp
|
---|
82 | .It Sy "Iterators"
|
---|
83 | Ruby has iterators for loop abstraction.
|
---|
84 | .Pp
|
---|
85 | .It Sy "Closures"
|
---|
86 | In Ruby, you can objectify the procedure.
|
---|
87 | .Pp
|
---|
88 | .It Sy "Text processing and regular expression"
|
---|
89 | Ruby has a bunch of text processing features like in Perl.
|
---|
90 | .Pp
|
---|
91 | .It Sy "Bignums"
|
---|
92 | With built-in bignums, you can for example calculate factorial(400).
|
---|
93 | .Pp
|
---|
94 | .It Sy "Exception handling"
|
---|
95 | As in Java(tm).
|
---|
96 | .Pp
|
---|
97 | .It Sy "Direct access to the OS"
|
---|
98 | Ruby can use most
|
---|
99 | .Ux
|
---|
100 | system calls, often used in system programming.
|
---|
101 | .Pp
|
---|
102 | .It Sy "Dynamic loading"
|
---|
103 | On most
|
---|
104 | .Ux
|
---|
105 | systems, you can load object files into the Ruby interpreter
|
---|
106 | on-the-fly.
|
---|
107 | .El
|
---|
108 | .Pp
|
---|
109 | .Sh OPTIONS
|
---|
110 | Ruby interpreter accepts following command-line options (switches).
|
---|
111 | They are quite similar to those of
|
---|
112 | .Xr perl 1 .
|
---|
113 | .Bl -tag -width "1234567890123" -compact
|
---|
114 | .Pp
|
---|
115 | .It Fl -copyright
|
---|
116 | Prints the copyright notice.
|
---|
117 | .Pp
|
---|
118 | .It Fl -version
|
---|
119 | Prints the version of Ruby interpreter.
|
---|
120 | .Pp
|
---|
121 | .It Fl 0 Ns Op Ar octal
|
---|
122 | (The digit
|
---|
123 | .Dq zero . )
|
---|
124 | Specifies the input record separator
|
---|
125 | .Pf ( Li "$/" )
|
---|
126 | as an octal number. If no digit is given, the null character is taken
|
---|
127 | as the separator. Other switches may follow the digits.
|
---|
128 | .Fl 00
|
---|
129 | turns Ruby into paragraph mode.
|
---|
130 | .Fl 0777
|
---|
131 | makes Ruby read whole file at once as a single string since there is
|
---|
132 | no legal character with that value.
|
---|
133 | .Pp
|
---|
134 | .It Fl C Ar directory
|
---|
135 | Causes Ruby to switch to the directory.
|
---|
136 | .Pp
|
---|
137 | .It Fl F Ar pattern
|
---|
138 | Specifies input field separator
|
---|
139 | .Pf ( Li "$;" ) .
|
---|
140 | .Pp
|
---|
141 | .It Fl I Ar directory
|
---|
142 | Used to tell Ruby where to load the library scripts. Directory path
|
---|
143 | will be added to the load-path variable
|
---|
144 | .Pf ( Li "$:" ) .
|
---|
145 | .Pp
|
---|
146 | .It Fl K Ar kcode
|
---|
147 | Specifies KANJI (Japanese) encoding.
|
---|
148 | .Pp
|
---|
149 | .It Fl S
|
---|
150 | Makes Ruby use the
|
---|
151 | .Ev PATH
|
---|
152 | environment variable to search for script, unless if its name begins
|
---|
153 | with a slash. This is used to emulate
|
---|
154 | .Li #!
|
---|
155 | on machines that don't support it, in the following manner:
|
---|
156 | .Bd -literal -offset indent
|
---|
157 | #! /usr/local/bin/ruby
|
---|
158 | # This line makes the next one a comment in Ruby \e
|
---|
159 | exec /usr/local/bin/ruby -S $0 $*
|
---|
160 | .Ed
|
---|
161 | .Pp
|
---|
162 | .It Fl T Ns Op Ar level
|
---|
163 | Turns on taint checks at the specified level (default 1).
|
---|
164 | .Pp
|
---|
165 | .It Fl a
|
---|
166 | Turns on auto-split mode when used with
|
---|
167 | .Fl n
|
---|
168 | or
|
---|
169 | .Fl p .
|
---|
170 | In auto-split mode, Ruby executes
|
---|
171 | .Dl $F = $_.split
|
---|
172 | at beginning of each loop.
|
---|
173 | .Pp
|
---|
174 | .It Fl c
|
---|
175 | Causes Ruby to check the syntax of the script and exit without
|
---|
176 | executing. If there are no syntax errors, Ruby will print
|
---|
177 | .Dq Syntax OK
|
---|
178 | to the standard output.
|
---|
179 | .Pp
|
---|
180 | .It Fl d
|
---|
181 | .It Fl -debug
|
---|
182 | Turns on debug mode.
|
---|
183 | .Li "$DEBUG"
|
---|
184 | will be set to true.
|
---|
185 | .Pp
|
---|
186 | .It Fl e Ar command
|
---|
187 | Specifies script from command-line while telling Ruby not to search
|
---|
188 | the rest of arguments for a script file name.
|
---|
189 | .Pp
|
---|
190 | .It Fl h
|
---|
191 | .It Fl -help
|
---|
192 | Prints a summary of the options.
|
---|
193 | .Pp
|
---|
194 | .It Fl i Ar extension
|
---|
195 | Specifies in-place-edit mode. The extension, if specified, is added
|
---|
196 | to old file name to make a backup copy. For example:
|
---|
197 | .Bd -literal -offset indent
|
---|
198 | % echo matz > /tmp/junk
|
---|
199 | % cat /tmp/junk
|
---|
200 | matz
|
---|
201 | % ruby -p -i.bak -e '$_.upcase!' /tmp/junk
|
---|
202 | % cat /tmp/junk
|
---|
203 | MATZ
|
---|
204 | % cat /tmp/junk.bak
|
---|
205 | matz
|
---|
206 | .Ed
|
---|
207 | .Pp
|
---|
208 | .It Fl l
|
---|
209 | (The lowercase letter
|
---|
210 | .Dq ell . )
|
---|
211 | Enables automatic line-ending processing, which means to firstly set
|
---|
212 | .Li "$\e"
|
---|
213 | to the value of
|
---|
214 | .Li "$/" ,
|
---|
215 | and secondly chops every line read using
|
---|
216 | .Li chop! .
|
---|
217 | .Pp
|
---|
218 | .It Fl n
|
---|
219 | Causes Ruby to assume the following loop around your script, which
|
---|
220 | makes it iterate over file name arguments somewhat like
|
---|
221 | .Nm sed
|
---|
222 | .Fl n
|
---|
223 | or
|
---|
224 | .Nm awk .
|
---|
225 | .Bd -literal -offset indent
|
---|
226 | while gets
|
---|
227 | ...
|
---|
228 | end
|
---|
229 | .Ed
|
---|
230 | .Pp
|
---|
231 | .It Fl p
|
---|
232 | Acts mostly same as -n switch, but print the value of variable
|
---|
233 | .Li "$_"
|
---|
234 | at the each end of the loop. For example:
|
---|
235 | .Bd -literal -offset indent
|
---|
236 | % echo matz | ruby -p -e '$_.tr! "a-z", "A-Z"'
|
---|
237 | MATZ
|
---|
238 | .Ed
|
---|
239 | .Pp
|
---|
240 | .It Fl r Ar library
|
---|
241 | Causes Ruby to load the library using require. It is useful when using
|
---|
242 | .Fl n
|
---|
243 | or
|
---|
244 | .Fl p .
|
---|
245 | .Pp
|
---|
246 | .It Fl s
|
---|
247 | Enables some switch parsing for switches after script name but before
|
---|
248 | any file name arguments (or before a
|
---|
249 | .Fl - ) .
|
---|
250 | Any switches found there are removed from
|
---|
251 | .Li ARGV
|
---|
252 | and set the corresponding variable in the script. For example:
|
---|
253 | .Bd -literal -offset indent
|
---|
254 | #! /usr/local/bin/ruby -s
|
---|
255 | # prints "true" if invoked with `-xyz' switch.
|
---|
256 | print "true\en" if $xyz
|
---|
257 | .Ed
|
---|
258 | .Pp
|
---|
259 | On some systems
|
---|
260 | .Li "$0"
|
---|
261 | does not always contain the full pathname, so you need the
|
---|
262 | .Fl S
|
---|
263 | switch to tell Ruby to search for the script if necessary. To handle
|
---|
264 | embedded spaces or such. A better construct than
|
---|
265 | .Li "$*"
|
---|
266 | would be
|
---|
267 | .Li ${1+"$@"} ,
|
---|
268 | but it does not work if the script is being interpreted by
|
---|
269 | .Xr csh 1 .
|
---|
270 | .Pp
|
---|
271 | .It Fl v
|
---|
272 | .It Fl -verbose
|
---|
273 | Enables verbose mode. Ruby will print its version at the beginning,
|
---|
274 | and set the variable
|
---|
275 | .Li "$VERBOSE"
|
---|
276 | to true. Some methods print extra messages if this variable is true.
|
---|
277 | If this switch is given, and no other switches are present, Ruby quits
|
---|
278 | after printing its version.
|
---|
279 | .Pp
|
---|
280 | .It Fl w
|
---|
281 | Enables verbose mode without printing version message at the
|
---|
282 | beginning. It sets the
|
---|
283 | .Li "$VERBOSE"
|
---|
284 | variable to true.
|
---|
285 | .Pp
|
---|
286 | .It Fl x Ns Op Ar directory
|
---|
287 | Tells Ruby that the script is embedded in a message. Leading garbage
|
---|
288 | will be discarded until the first that starts with
|
---|
289 | .Dq #!
|
---|
290 | and contains the string,
|
---|
291 | .Dq ruby .
|
---|
292 | Any meaningful switches on that line will applied. The end of script
|
---|
293 | must be specified with either
|
---|
294 | .Li EOF ,
|
---|
295 | .Li "^D" ( Li "control-D" ) ,
|
---|
296 | .Li "^Z" ( Li "control-Z" ) ,
|
---|
297 | or reserved word
|
---|
298 | .Li __END__ .
|
---|
299 | If the directory name is specified, Ruby will switch to that directory
|
---|
300 | before executing script.
|
---|
301 | .Pp
|
---|
302 | .It Fl y
|
---|
303 | .It Fl -yydebug
|
---|
304 | Turns on compiler debug mode. Ruby will print a bunch of internal
|
---|
305 | state messages during compiling scripts. You don't have to specify
|
---|
306 | this switch, unless you are going to debug the Ruby interpreter.
|
---|
307 | .El
|
---|
308 | .Pp
|
---|
309 | .Sh ENVIRONMENT
|
---|
310 | .Bl -tag -width "RUBYLIB_PREFIX" -compact
|
---|
311 | .It Ev RUBYLIB
|
---|
312 | A colon-separated list of directories that are added to Ruby's
|
---|
313 | library load path
|
---|
314 | .Pf ( Li "$:" ) . Directories from this environment variable are searched
|
---|
315 | before the standard load path is searched.
|
---|
316 | .Pp
|
---|
317 | e.g.:
|
---|
318 | .Dl RUBYLIB="$HOME/lib/ruby:$HOME/lib/rubyext"
|
---|
319 | .Pp
|
---|
320 | .It Ev RUBYOPT
|
---|
321 | Additional Ruby options.
|
---|
322 | .Pp
|
---|
323 | e.g.
|
---|
324 | .Dl RUBYOPT="-w -Ke"
|
---|
325 | .Pp
|
---|
326 | .It Ev RUBYPATH
|
---|
327 | A colon-separated list of directories that Ruby searches for
|
---|
328 | Ruby programs when the
|
---|
329 | .Fl S
|
---|
330 | flag is specified. This variable precedes the
|
---|
331 | .Ev PATH
|
---|
332 | environment variable.
|
---|
333 | .Pp
|
---|
334 | .It Ev RUBYSHELL
|
---|
335 | The path to the system shell command. This environment variable is
|
---|
336 | enabled for only mswin32, mingw32, and OS/2 platforms. If this
|
---|
337 | variable is not defined, Ruby refers to
|
---|
338 | .Ev COMSPEC .
|
---|
339 | .Pp
|
---|
340 | .It Ev PATH
|
---|
341 | Ruby refers to the
|
---|
342 | .Ev PATH
|
---|
343 | environment variable on calling Kernel#system.
|
---|
344 | .Pp
|
---|
345 | .It Ev RUBYLIB_PREFIX
|
---|
346 | This variable is obsolete.
|
---|
347 | .El
|
---|
348 | .Pp
|
---|
349 | .Sh AUTHORS
|
---|
350 | Ruby is designed and implemented by
|
---|
351 | .An Yukihiro Matsumoto Aq [email protected] .
|
---|