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