1RUBY(1) Ruby Programmer's Reference Guide RUBY(1)
2
4 ruby — Interpreted object-oriented scripting language
5
7 ruby [--copyright] [--version] [-SUacdlnpswvy] [-0[octal]] [-C directory]
8 [-E external[:internal]] [-F[pattern]] [-I directory] [-K[c]]
9 [-T[level]] [-W[level]] [-e command] [-i[extension]] [-r library]
10 [-x[directory]] [--{enable|disable}-FEATURE] [--dump=target]
11 [--verbose] [--] [program_file] [argument ...]
12
14 Ruby is an interpreted scripting language for quick and easy object-ori‐
15 ented programming. It has many features to process text files and to do
16 system management tasks (like in Perl). It is simple, straight-forward,
17 and extensible.
18 If you want a language for easy object-oriented programming, or you don't
20 like the Perl ugliness, or you do like the concept of LISP, but don't
21 like too many parentheses, Ruby might be your language of choice.
22
24 Ruby's features are as follows:
25 Interpretive
27 Ruby is an interpreted language, so you don't have to recompile
28 programs written in Ruby to execute them.
29 Variables have no type (dynamic typing)
31 Variables in Ruby can contain data of any type. You don't have
32 to worry about variable typing. Consequently, it has a weaker
33 compile time check.
34 No declaration needed
36 You can use variables in your Ruby programs without any declara‐
37 tions. Variable names denote their scope - global, class,
38 instance, or local.
39 Simple syntax
41 Ruby has a simple syntax influenced slightly from Eiffel.
42 No user-level memory management
44 Ruby has automatic memory management. Objects no longer refer‐
45 enced from anywhere are automatically collected by the garbage
46 collector built into the interpreter.
47 Everything is an object
49 Ruby is a purely object-oriented language, and was so since its
50 creation. Even such basic data as integers are seen as objects.
51 Class, inheritance, and methods
53 Being an object-oriented language, Ruby naturally has basic fea‐
54 tures like classes, inheritance, and methods.
55 Singleton methods
57 Ruby has the ability to define methods for certain objects. For
58 example, you can define a press-button action for certain widget
59 by defining a singleton method for the button. Or, you can make
60 up your own prototype based object system using singleton meth‐
61 ods, if you want to.
62 Mix-in by modules
64 Ruby intentionally does not have the multiple inheritance as it
65 is a source of confusion. Instead, Ruby has the ability to share
66 implementations across the inheritance tree. This is often
67 called a ‘Mix-in’.
68 Iterators
70 Ruby has iterators for loop abstraction.
71 Closures
73 In Ruby, you can objectify the procedure.
74 Text processing and regular expressions
76 Ruby has a bunch of text processing features like in Perl.
77 M17N, character set independent
79 Ruby supports multilingualized programming. Easy to process texts
80 written in many different natural languages and encoded in many
81 different character encodings, without dependence on Unicode.
82 Bignums
84 With built-in bignums, you can for example calculate facto‐
85 rial(400).
86 Reflection and domain specific languages
88 Class is also an instance of the Class class. Definition of
89 classes and methods is an expression just as 1+1 is. So your pro‐
90 grams can even write and modify programs. Thus you can write
91 your application in your own programming language on top of Ruby.
92 Exception handling
94 As in Java(tm).
95 Direct access to the OS
97 Ruby can use most UNIX system calls, often used in system pro‐
98 gramming.
99 Dynamic loading
101 On most UNIX systems, you can load object files into the Ruby
102 interpreter on-the-fly.
103 Rich libraries
105 In addition to the “builtin libraries” and “standard libraries”
106 that are bundled with Ruby, a vast amount of third-party
107 libraries (“gems”) are available via the package management sys‐
108 tem called ‘RubyGems’, namely the gem(1) command. Visit
109 RubyGems.org (https://rubygems.org/) to find the gems you need,
110 and explore GitHub (https://github.com/) to see how they are
111 being developed and used.
112
114 The Ruby interpreter accepts the following command-line options
115 (switches). They are quite similar to those of perl(1).
116 --copyright Prints the copyright notice, and quits immediately without
118 running any script.
119 --version Prints the version of the Ruby interpreter, and quits
121 immediately without running any script.
122 -0[octal] (The digit “zero”.) Specifies the input record separator
124 ($/) as an octal number. If no digit is given, the null
125 character is taken as the separator. Other switches may
126 follow the digits. -00 turns Ruby into paragraph mode.
127 -0777 makes Ruby read whole file at once as a single
128 string since there is no legal character with that value.
129 -C directory
131 -X directory Causes Ruby to switch to the directory.
132 -E external[:internal]
134 --encoding external[:internal]
135 Specifies the default value(s) for external encodings and
136 internal encoding. Values should be separated with colon
137 (:).
138 You can omit the one for internal encodings, then the
140 value (Encoding.default_internal) will be nil.
141 --external-encoding=encoding
143 --internal-encoding=encoding
144 Specify the default external or internal character encod‐
145 ing
146 -F pattern Specifies input field separator ($;).
148 -I directory Used to tell Ruby where to load the library scripts.
150 Directory path will be added to the load-path variable
151 ($:).
152 -K kcode Specifies KANJI (Japanese) encoding. The default value for
154 script encodings (__ENCODING__) and external encodings
155 (Encoding.default_external) will be the specified one.
156 kcode can be one of
157 e EUC-JP
159 s Windows-31J (CP932)
161 u UTF-8
163 n ASCII-8BIT (BINARY)
165 -S Makes Ruby use the PATH environment variable to search for
167 script, unless its name begins with a slash. This is used
168 to emulate #! on machines that don't support it, in the
169 following manner:
170 #! /usr/local/bin/ruby
172 # This line makes the next one a comment in Ruby \
173 exec /usr/local/bin/ruby -S $0 $*
174 On some systems $0 does not always contain the full path‐
176 name, so you need the -S switch to tell Ruby to search for
177 the script if necessary (to handle embedded spaces and
178 such). A better construct than $* would be ${1+"$@"}, but
179 it does not work if the script is being interpreted by
180 csh(1).
181 -T[level=1] Turns on taint checks at the specified level (default 1).
183 -U Sets the default value for internal encodings
185 (Encoding.default_internal) to UTF-8.
186 -W[level=2] Turns on verbose mode at the specified level without
188 printing the version message at the beginning. The level
189 can be;
190 0 Verbose mode is "silence". It sets the
192 $VERBOSE to nil.
193 1 Verbose mode is "medium". It sets the
195 $VERBOSE to false.
196 2 (default) Verbose mode is "verbose". It sets the
198 $VERBOSE to true. -W2 is same as -w
199 -a Turns on auto-split mode when used with -n or -p. In
201 auto-split mode, Ruby executes
202 $F = $_.split
203 at beginning of each loop.
204 -c Causes Ruby to check the syntax of the script and exit
206 without executing. If there are no syntax errors, Ruby
207 will print “Syntax OK” to the standard output.
208 -d
210 --debug Turns on debug mode. $DEBUG will be set to true.
211 -e command Specifies script from command-line while telling Ruby not
213 to search the rest of the arguments for a script file
214 name.
215 -h
217 --help Prints a summary of the options.
218 -i extension Specifies in-place-edit mode. The extension, if speci‐
220 fied, is added to old file name to make a backup copy.
221 For example:
222 % echo matz > /tmp/junk
224 % cat /tmp/junk
225 matz
226 % ruby -p -i.bak -e '$_.upcase!' /tmp/junk
227 % cat /tmp/junk
228 MATZ
229 % cat /tmp/junk.bak
230 matz
231 -l (The lowercase letter “ell”.) Enables automatic line-end‐
233 ing processing, which means to firstly set $\ to the value
234 of $/, and secondly chops every line read using chop!.
235 -n Causes Ruby to assume the following loop around your
237 script, which makes it iterate over file name arguments
238 somewhat like sed -n or awk.
239 while gets
241 ...
242 end
243 -p Acts mostly same as -n switch, but print the value of
245 variable $_ at the each end of the loop. For example:
246 % echo matz | ruby -p -e '$_.tr! "a-z", "A-Z"'
248 MATZ
249 -r library Causes Ruby to load the library using require. It is use‐
251 ful when using -n or -p.
252 -s Enables some switch parsing for switches after script name
254 but before any file name arguments (or before a --). Any
255 switches found there are removed from ARGV and set the
256 corresponding variable in the script. For example:
257 #! /usr/local/bin/ruby -s
259 # prints "true" if invoked with `-xyz' switch.
260 print "true\n" if $xyz
261 -v Enables verbose mode. Ruby will print its version at the
263 beginning and set the variable $VERBOSE to true. Some
264 methods print extra messages if this variable is true. If
265 this switch is given, and no other switches are present,
266 Ruby quits after printing its version.
267 -w Enables verbose mode without printing version message at
269 the beginning. It sets the $VERBOSE variable to true.
270 -x[directory] Tells Ruby that the script is embedded in a message.
272 Leading garbage will be discarded until the first line
273 that starts with “#!” and contains the string, “ruby”.
274 Any meaningful switches on that line will be applied. The
275 end of the script must be specified with either EOF, ^D
276 (control-D), ^Z (control-Z), or the reserved word __END__.
277 If the directory name is specified, Ruby will switch to
278 that directory before executing script.
279 -y
281 --yydebug DO NOT USE.
282 Turns on compiler debug mode. Ruby will print a bunch of
284 internal state messages during compilation. Only specify
285 this switch you are going to debug the Ruby interpreter.
286 --disable-FEATURE
288 --enable-FEATURE
289 Disables (or enables) the specified FEATURE.
290 --disable-gems
291 --enable-gems Disables (or enables) RubyGems
292 libraries. By default, Ruby will load
293 the latest version of each installed
294 gem. The Gem constant is true if
295 RubyGems is enabled, false if other‐
296 wise.
297 --disable-rubyopt
299 --enable-rubyopt Ignores (or considers) the RUBYOPT
300 environment variable. By default, Ruby
301 considers the variable.
302 --disable-all
304 --enable-all Disables (or enables) all features.
305 --dump=target Dump some informations.
307 Prints the specified target. target can be one of;
309 version version description same as --version
311 usage brief usage message same as -h
313 help Show long help message same as --help
315 syntax check of syntax same as -c --yydebug
317 yydebug compiler debug mode, same as --yydebug
319 Only specify this switch if you are going to
321 debug the Ruby interpreter.
322 parsetree
324 parsetree_with_comment AST nodes tree
326 Only specify this switch if you are going to
328 debug the Ruby interpreter.
329 insns disassembled instructions
331 Only specify this switch if you are going to
333 debug the Ruby interpreter.
334 --verbose Enables verbose mode without printing version message at
336 the beginning. It sets the $VERBOSE variable to true. If
337 this switch is given, and no script arguments (script file
338 or -e options) are present, Ruby quits immediately.
339
341 RUBYLIB A colon-separated list of directories that are added to Ruby's
342 library load path ($:). Directories from this environment
343 variable are searched before the standard load path is
344 searched.
345 e.g.:
347 RUBYLIB="$HOME/lib/ruby:$HOME/lib/rubyext"
348 RUBYOPT Additional Ruby options.
350 e.g.
352 RUBYOPT="-w -Ke"
353 Note that RUBYOPT can contain only -d, -E, -I, -K, -r, -T, -U,
355 -v, -w, -W, --debug, --disable-FEATURE and --enable-FEATURE.
356 RUBYPATH A colon-separated list of directories that Ruby searches for
358 Ruby programs when the -S flag is specified. This variable
359 precedes the PATH environment variable.
360 RUBYSHELL The path to the system shell command. This environment vari‐
362 able is enabled for only mswin32, mingw32, and OS/2 platforms.
363 If this variable is not defined, Ruby refers to COMSPEC.
364 PATH Ruby refers to the PATH environment variable on calling Ker‐
366 nel#system.
367 And Ruby depends on some RubyGems related environment variables unless
369 RubyGems is disabled. See the help of gem(1) as below.
370 % gem help
372
374 The Ruby garbage collector (GC) tracks objects in fixed-sized slots, but
375 each object may have auxiliary memory allocations handled by the malloc
376 family of C standard library calls ( malloc(3), calloc(3), and
377 realloc(3)). In this documentatation, the "heap" refers to the Ruby
378 object heap of fixed-sized slots, while "malloc" refers to auxiliary
379 allocations commonly referred to as the "process heap". Thus there are
380 at least two possible ways to trigger GC:
381 1 Reaching the object limit.
383 2 Reaching the malloc limit.
385 In Ruby 2.1, the generational GC was introduced and the limits are
387 divided into young and old generations, providing two additional ways to
388 trigger a GC:
389 3 Reaching the old object limit.
391 4 Reaching the old malloc limit.
393 There are currently 4 possible areas where the GC may be tuned by the
395 following 11 environment variables:
396 RUBY_GC_HEAP_INIT_SLOTS Initial allocation slots. Intro‐
397 duced in Ruby 2.1, default: 10000.
398 RUBY_GC_HEAP_FREE_SLOTS Prepare at least this amount of
400 slots after GC. Allocate this
401 number slots if there are not
402 enough slots. Introduced in Ruby
403 2.1, default: 4096
404 RUBY_GC_HEAP_GROWTH_FACTOR Increase allocation rate of heap
406 slots by this factor. Introduced
407 in Ruby 2.1, default: 1.8, mini‐
408 mum: 1.0 (no growth)
409 RUBY_GC_HEAP_GROWTH_MAX_SLOTS Allocation rate is limited to this
411 number of slots, preventing exces‐
412 sive allocation due to
413 RUBY_GC_HEAP_GROWTH_FACTOR.
414 Introduced in Ruby 2.1, default: 0
415 (no limit)
416 RUBY_GC_HEAP_OLDOBJECT_LIMIT_FACTOR Perform a full GC when the number
418 of old objects is more than R * N,
419 where R is this factor and N is
420 the number of old objects after
421 the last full GC. Introduced in
422 Ruby 2.1.1, default: 2.0
423 RUBY_GC_MALLOC_LIMIT The initial limit of young genera‐
425 tion allocation from the malloc-
426 family. GC will start when this
427 limit is reached. Default: 16MB
428 RUBY_GC_MALLOC_LIMIT_MAX The maximum limit of young genera‐
430 tion allocation from malloc before
431 GC starts. Prevents excessive
432 malloc growth due to RUBY_GC_MAL‐
433 LOC_LIMIT_GROWTH_FACTOR. Intro‐
434 duced in Ruby 2.1, default: 32MB.
435 RUBY_GC_MALLOC_LIMIT_GROWTH_FACTOR Increases the limit of young gen‐
437 eration malloc calls, reducing GC
438 frequency but increasing malloc
439 growth until RUBY_GC_MAL‐
440 LOC_LIMIT_MAX is reached. Intro‐
441 duced in Ruby 2.1, default: 1.4,
442 minimum: 1.0 (no growth)
443 RUBY_GC_OLDMALLOC_LIMIT The initial limit of old genera‐
445 tion allocation from malloc, a
446 full GC will start when this limit
447 is reached. Introduced in Ruby
448 2.1, default: 16MB
449 RUBY_GC_OLDMALLOC_LIMIT_MAX The maximum limit of old genera‐
451 tion allocation from malloc before
452 a full GC starts. Prevents exces‐
453 sive malloc growth due to
454 RUBY_GC_OLDMAL‐
455 LOC_LIMIT_GROWTH_FACTOR. Intro‐
456 duced in Ruby 2.1, default: 128MB
457 RUBY_GC_OLDMALLOC_LIMIT_GROWTH_FACTOR Increases the limit of old genera‐
459 tion malloc allocation, reducing
460 full GC frequency but increasing
461 malloc growth until RUBY_GC_OLD‐
462 MALLOC_LIMIT_MAX is reached.
463 Introduced in Ruby 2.1, default:
464 1.2, minimum: 1.0 (no growth)
465
467 Stack size environment variables are implementation-dependent and subject
468 to change with different versions of Ruby. The VM stack is used for
469 pure-Ruby code and managed by the virtual machine. Machine stack is used
470 by the operating system and its usage is dependent on C extensions as
471 well as C compiler options. Using lower values for these may allow
472 applications to keep more Fibers or Threads running; but increases the
473 chance of SystemStackError exceptions and segmentation faults (SIGSEGV).
474 These environment variables are available since Ruby 2.0.0. All values
475 are specified in bytes.
476 RUBY_THREAD_VM_STACK_SIZE VM stack size used at thread creation.
478 default: 131072 (32-bit CPU) or 262144
479 (64-bit)
480 RUBY_THREAD_MACHINE_STACK_SIZE Machine stack size used at thread cre‐
482 ation. default: 524288 or 1048575
483 RUBY_FIBER_VM_STACK_SIZE VM stack size used at fiber creation.
485 default: 65536 or 131072
486 RUBY_FIBER_MACHINE_STACK_SIZE Machine stack size used at fiber cre‐
488 ation. default: 262144 or 524288
489
491 https://www.ruby-lang.org/ The official web site.
492 https://www.ruby-toolbox.com/ Comprehensive catalog of Ruby libraries.
493
495 · Security vulnerabilities should be reported via an email to
496 security@ruby-lang.org. Reported problems will be published after
497 being fixed.
498 · Other bugs and feature requests can be reported via the Ruby Issue
500 Tracking System (https://bugs.ruby-lang.org/). Do not report secu‐
501 rity vulnerabilities via this system because it publishes the vulner‐
502 abilities immediately.
503
505 Ruby is designed and implemented by Yukihiro Matsumoto <matz@netlab.jp>.
506 See ⟨https://bugs.ruby-lang.org/projects/ruby/wiki/Contributors⟩ for con‐
508 tributors to Ruby.
509UNIX April 14, 2018 UNIX