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 Ruby interpreter accepts following command-line options (switches). They
115 are quite similar to those of perl(1).
116 --copyright Prints the copyright notice.
118 --version Prints the version of Ruby interpreter.
120 -0[octal] (The digit “zero”.) Specifies the input record separator
122 ($/) as an octal number. If no digit is given, the null
123 character is taken as the separator. Other switches may
124 follow the digits. -00 turns Ruby into paragraph mode.
125 -0777 makes Ruby read whole file at once as a single
126 string since there is no legal character with that value.
127 -C directory
129 -X directory Causes Ruby to switch to the directory.
130 -E external[:internal]
132 --encoding external[:internal]
133 Specifies the default value(s) for external encodings and
134 internal encoding. Values should be separated with colon
135 (:).
136 You can omit the one for internal encodings, then the
138 value (Encoding.default_internal) will be nil.
139 --external-encoding=encoding
141 --internal-encoding=encoding
142 Specify the default external or internal character encod‐
143 ing
144 -F pattern Specifies input field separator ($;).
146 -I directory Used to tell Ruby where to load the library scripts.
148 Directory path will be added to the load-path variable
149 ($:).
150 -K kcode Specifies KANJI (Japanese) encoding. The default value for
152 script encodings (__ENCODING__) and external encodings
153 (Encoding.default_external) will be the specified one.
154 kcode can be one of
155 e EUC-JP
157 s Windows-31J (CP932)
159 u UTF-8
161 n ASCII-8BIT (BINARY)
163 -S Makes Ruby use the PATH environment variable to search for
165 script, unless its name begins with a slash. This is used
166 to emulate #! on machines that don't support it, in the
167 following manner:
168 #! /usr/local/bin/ruby
170 # This line makes the next one a comment in Ruby \
171 exec /usr/local/bin/ruby -S $0 $*
172 On some systems $0 does not always contain the full path‐
174 name, so you need the -S switch to tell Ruby to search for
175 the script if necessary (to handle embedded spaces and
176 such). A better construct than $* would be ${1+"$@"}, but
177 it does not work if the script is being interpreted by
178 csh(1).
179 -T[level=1] Turns on taint checks at the specified level (default 1).
181 -U Sets the default value for internal encodings
183 (Encoding.default_internal) to UTF-8.
184 -W[level=2] Turns on verbose mode at the specified level without
186 printing the version message at the beginning. The level
187 can be;
188 0 Verbose mode is "silence". It sets the
190 $VERBOSE to nil.
191 1 Verbose mode is "medium". It sets the
193 $VERBOSE to false.
194 2 (default) Verbose mode is "verbose". It sets the
196 $VERBOSE to true. -W2 is same as -w
197 -a Turns on auto-split mode when used with -n or -p. In
199 auto-split mode, Ruby executes
200 $F = $_.split
201 at beginning of each loop.
202 -c Causes Ruby to check the syntax of the script and exit
204 without executing. If there are no syntax errors, Ruby
205 will print “Syntax OK” to the standard output.
206 -d
208 --debug Turns on debug mode. $DEBUG will be set to true.
209 -e command Specifies script from command-line while telling Ruby not
211 to search the rest of the arguments for a script file
212 name.
213 -h
215 --help Prints a summary of the options.
216 -i extension Specifies in-place-edit mode. The extension, if speci‐
218 fied, is added to old file name to make a backup copy.
219 For example:
220 % echo matz > /tmp/junk
222 % cat /tmp/junk
223 matz
224 % ruby -p -i.bak -e '$_.upcase!' /tmp/junk
225 % cat /tmp/junk
226 MATZ
227 % cat /tmp/junk.bak
228 matz
229 -l (The lowercase letter “ell”.) Enables automatic line-end‐
231 ing processing, which means to firstly set $\ to the value
232 of $/, and secondly chops every line read using chop!.
233 -n Causes Ruby to assume the following loop around your
235 script, which makes it iterate over file name arguments
236 somewhat like sed -n or awk.
237 while gets
239 ...
240 end
241 -p Acts mostly same as -n switch, but print the value of
243 variable $_ at the each end of the loop. For example:
244 % echo matz | ruby -p -e '$_.tr! "a-z", "A-Z"'
246 MATZ
247 -r library Causes Ruby to load the library using require. It is use‐
249 ful when using -n or -p.
250 -s Enables some switch parsing for switches after script name
252 but before any file name arguments (or before a --). Any
253 switches found there are removed from ARGV and set the
254 corresponding variable in the script. For example:
255 #! /usr/local/bin/ruby -s
257 # prints "true" if invoked with `-xyz' switch.
258 print "true\n" if $xyz
259 -v Enables verbose mode. Ruby will print its version at the
261 beginning and set the variable $VERBOSE to true. Some
262 methods print extra messages if this variable is true. If
263 this switch is given, and no other switches are present,
264 Ruby quits after printing its version.
265 -w Enables verbose mode without printing version message at
267 the beginning. It sets the $VERBOSE variable to true.
268 -x[directory] Tells Ruby that the script is embedded in a message.
270 Leading garbage will be discarded until the first line
271 that starts with “#!” and contains the string, “ruby”.
272 Any meaningful switches on that line will be applied. The
273 end of the script must be specified with either EOF, ^D
274 (control-D), ^Z (control-Z), or the reserved word __END__.
275 If the directory name is specified, Ruby will switch to
276 that directory before executing script.
277 -y
279 --yydebug DO NOT USE.
280 Turns on compiler debug mode. Ruby will print a bunch of
282 internal state messages during compilation. Only specify
283 this switch you are going to debug the Ruby interpreter.
284 --disable-FEATURE
286 --enable-FEATURE
287 Disables (or enables) the specified FEATURE.
288 --disable-gems
289 --enable-gems Disables (or enables) RubyGems
290 libraries. By default, Ruby will load
291 the latest version of each installed
292 gem. The Gem constant is true if
293 RubyGems is enabled, false if other‐
294 wise.
295 --disable-rubyopt
297 --enable-rubyopt Ignores (or considers) the RUBYOPT
298 environment variable. By default, Ruby
299 considers the variable.
300 --disable-all
302 --enable-all Disables (or enables) all features.
303 --dump=target Dump some informations.
305 Prints the specified target. target can be one of;
307 version version description same as --version
309 usage brief usage message same as -h
311 help Show long help message same as --help
313 syntax check of syntax same as -c --yydebug
315 yydebug compiler debug mode, same as --yydebug
317 Only specify this switch if you are going to
319 debug the Ruby interpreter.
320 parsetree
322 parsetree_with_comment AST nodes tree
324 Only specify this switch if you are going to
326 debug the Ruby interpreter.
327 insns disassembled instructions
329 Only specify this switch if you are going to
331 debug the Ruby interpreter.
332 --verbose Enables verbose mode without printing version message at
334 the beginning. It sets the $VERBOSE variable to true. If
335 this switch is given, and no other switches are present,
336 Ruby quits after printing its version.
337
339 RUBYLIB A colon-separated list of directories that are added to Ruby's
340 library load path ($:). Directories from this environment
341 variable are searched before the standard load path is
342 searched.
343 e.g.:
345 RUBYLIB="$HOME/lib/ruby:$HOME/lib/rubyext"
346 RUBYOPT Additional Ruby options.
348 e.g.
350 RUBYOPT="-w -Ke"
351 Note that RUBYOPT can contain only -d, -E, -I, -K, -r, -T, -U,
353 -v, -w, -W, --debug, --disable-FEATURE and --enable-FEATURE.
354 RUBYPATH A colon-separated list of directories that Ruby searches for
356 Ruby programs when the -S flag is specified. This variable
357 precedes the PATH environment variable.
358 RUBYSHELL The path to the system shell command. This environment vari‐
360 able is enabled for only mswin32, mingw32, and OS/2 platforms.
361 If this variable is not defined, Ruby refers to COMSPEC.
362 PATH Ruby refers to the PATH environment variable on calling Ker‐
364 nel#system.
365 And Ruby depends on some RubyGems related environment variables unless
367 RubyGems is disabled. See the help of gem(1) as below.
368 % gem help
370
372 The Ruby garbage collector (GC) tracks objects in fixed-sized slots, but
373 each object may have auxiliary memory allocations handled by the malloc
374 family of C standard library calls ( malloc(3), calloc(3), and
375 realloc(3)). In this documentatation, the "heap" refers to the Ruby
376 object heap of fixed-sized slots, while "malloc" refers to auxiliary
377 allocations commonly referred to as the "process heap". Thus there are
378 at least two possible ways to trigger GC:
379 1 Reaching the object limit.
381 2 Reaching the malloc limit.
383 In Ruby 2.1, the generational GC was introduced and the limits are
385 divided into young and old generations, providing two additional ways to
386 trigger a GC:
387 3 Reaching the old object limit.
389 4 Reaching the old malloc limit.
391 There are currently 4 possible areas where the GC may be tuned by the
393 following 11 environment variables:
394 RUBY_GC_HEAP_INIT_SLOTS Initial allocation slots. Intro‐
395 duced in Ruby 2.1, default: 10000.
396 RUBY_GC_HEAP_FREE_SLOTS Prepare at least this amount of
398 slots after GC. Allocate this
399 number slots if there are not
400 enough slots. Introduced in Ruby
401 2.1, default: 4096
402 RUBY_GC_HEAP_GROWTH_FACTOR Increase allocation rate of heap
404 slots by this factor. Introduced
405 in Ruby 2.1, default: 1.8, mini‐
406 mum: 1.0 (no growth)
407 RUBY_GC_HEAP_GROWTH_MAX_SLOTS Allocation rate is limited to this
409 number of slots, preventing exces‐
410 sive allocation due to
411 RUBY_GC_HEAP_GROWTH_FACTOR.
412 Introduced in Ruby 2.1, default: 0
413 (no limit)
414 RUBY_GC_HEAP_OLDOBJECT_LIMIT_FACTOR Perform a full GC when the number
416 of old objects is more than R * N,
417 where R is this factor and N is
418 the number of old objects after
419 the last full GC. Introduced in
420 Ruby 2.1.1, default: 2.0
421 RUBY_GC_MALLOC_LIMIT The initial limit of young genera‐
423 tion allocation from the malloc-
424 family. GC will start when this
425 limit is reached. Default: 16MB
426 RUBY_GC_MALLOC_LIMIT_MAX The maximum limit of young genera‐
428 tion allocation from malloc before
429 GC starts. Prevents excessive
430 malloc growth due to RUBY_GC_MAL‐
431 LOC_LIMIT_GROWTH_FACTOR. Intro‐
432 duced in Ruby 2.1, default: 32MB.
433 RUBY_GC_MALLOC_LIMIT_GROWTH_FACTOR Increases the limit of young gen‐
435 eration malloc calls, reducing GC
436 frequency but increasing malloc
437 growth until RUBY_GC_MAL‐
438 LOC_LIMIT_MAX is reached. Intro‐
439 duced in Ruby 2.1, default: 1.4,
440 minimum: 1.0 (no growth)
441 RUBY_GC_OLDMALLOC_LIMIT The initial limit of old genera‐
443 tion allocation from malloc, a
444 full GC will start when this limit
445 is reached. Introduced in Ruby
446 2.1, default: 16MB
447 RUBY_GC_OLDMALLOC_LIMIT_MAX The maximum limit of old genera‐
449 tion allocation from malloc before
450 a full GC starts. Prevents exces‐
451 sive malloc growth due to
452 RUBY_GC_OLDMAL‐
453 LOC_LIMIT_GROWTH_FACTOR. Intro‐
454 duced in Ruby 2.1, default: 128MB
455 RUBY_GC_OLDMALLOC_LIMIT_GROWTH_FACTOR Increases the limit of old genera‐
457 tion malloc allocation, reducing
458 full GC frequency but increasing
459 malloc growth until RUBY_GC_OLD‐
460 MALLOC_LIMIT_MAX is reached.
461 Introduced in Ruby 2.1, default:
462 1.2, minimum: 1.0 (no growth)
463
465 Stack size environment variables are implementation-dependent and subject
466 to change with different versions of Ruby. The VM stack is used for
467 pure-Ruby code and managed by the virtual machine. Machine stack is used
468 by the operating system and its usage is dependent on C extensions as
469 well as C compiler options. Using lower values for these may allow
470 applications to keep more Fibers or Threads running; but increases the
471 chance of SystemStackError exceptions and segmentation faults (SIGSEGV).
472 These environment variables are available since Ruby 2.0.0. All values
473 are specified in bytes.
474 RUBY_THREAD_VM_STACK_SIZE VM stack size used at thread creation.
476 default: 131072 (32-bit CPU) or 262144
477 (64-bit)
478 RUBY_THREAD_MACHINE_STACK_SIZE Machine stack size used at thread cre‐
480 ation. default: 524288 or 1048575
481 RUBY_FIBER_VM_STACK_SIZE VM stack size used at fiber creation.
483 default: 65536 or 131072
484 RUBY_FIBER_MACHINE_STACK_SIZE Machine stack size used at fiber cre‐
486 ation. default: 262144 or 524288
487
489 https://www.ruby-lang.org/ The official web site.
490 https://www.ruby-toolbox.com/ Comprehensive catalog of Ruby libraries.
491
493 · Security vulnerabilities should be reported via an email to
494 security@ruby-lang.org. Reported problems will be published after
495 being fixed.
496 · Other bugs and feature requests can be reported via the Ruby Issue
498 Tracking System (https://bugs.ruby-lang.org/). Do not report secu‐
499 rity vulnerabilities via this system because it publishes the vulner‐
500 abilities immediately.
501
503 Ruby is designed and implemented by Yukihiro Matsumoto <matz@netlab.jp>.
504 See ⟨https://bugs.ruby-lang.org/projects/ruby/wiki/Contributors⟩ for con‐
506 tributors to Ruby.
507UNIX October 31, 2015 UNIX