1RUBY(1)                Ruby Programmer's Reference Guide               RUBY(1)
2

NAME

4     ruby — Interpreted object-oriented scripting language
5

SYNOPSIS

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

DESCRIPTION

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
19     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

FEATURES

24     Ruby's features are as follows:
25
26     Interpretive
27             Ruby is an interpreted language, so you don't have to recompile
28             programs written in Ruby to execute them.
29
30     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
35     No declaration needed
36             You can use variables in your Ruby programs without any declara‐
37             tions.  Variable names denote their scope - global, class, in‐
38             stance, or local.
39
40     Simple syntax
41             Ruby has a simple syntax influenced slightly from Eiffel.
42
43     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
48     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
52     Class, inheritance, and methods
53             Being an object-oriented language, Ruby naturally has basic fea‐
54             tures like classes, inheritance, and methods.
55
56     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
63     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
69     Iterators
70             Ruby has iterators for loop abstraction.
71
72     Closures
73             In Ruby, you can objectify the procedure.
74
75     Text processing and regular expressions
76             Ruby has a bunch of text processing features like in Perl.
77
78     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
83     Bignums
84             With built-in bignums, you can for example calculate facto‐
85             rial(400).
86
87     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
93     Exception handling
94             As in Java(tm).
95
96     Direct access to the OS
97             Ruby can use most UNIX system calls, often used in system pro‐
98             gramming.
99
100     Dynamic loading
101             On most UNIX systems, you can load object files into the Ruby in‐
102             terpreter on-the-fly.
103
104     Rich libraries
105             In addition to the “builtin libraries” and “standard libraries”
106             that are bundled with Ruby, a vast amount of third-party li‐
107             braries (“gems”) are available via the package management system
108             called ‘RubyGems’, namely the gem(1) command.  Visit RubyGems.org
109             (https://rubygems.org/) to find the gems you need, and explore
110             GitHub (https://github.com/) to see how they are being developed
111             and used.
112

OPTIONS

114     The Ruby interpreter accepts the following command-line options
115     (switches).  They are quite similar to those of perl(1).
116
117     --copyright    Prints the copyright notice, and quits immediately without
118                    running any script.
119
120     --version      Prints the version of the Ruby interpreter, and quits im‐
121                    mediately without running any script.
122
123     -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
130     -C directory
131     -X directory   Causes Ruby to switch to the directory.
132
133     -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
139                    You can omit the one for internal encodings, then the
140                    value (Encoding.default_internal) will be nil.
141
142     --external-encoding=encoding
143     --internal-encoding=encoding
144                    Specify the default external or internal character encod‐
145                    ing
146
147     -F pattern     Specifies input field separator ($;).
148
149     -I directory   Used to tell Ruby where to load the library scripts.  Di‐
150                    rectory path will be added to the load-path variable ($:).
151
152     -K kcode       Specifies KANJI (Japanese) encoding. The default value for
153                    script encodings (__ENCODING__) and external encodings
154                    (Encoding.default_external) will be the specified one.
155                    kcode can be one of
156
157                          e       EUC-JP
158
159                          s       Windows-31J (CP932)
160
161                          u       UTF-8
162
163                          n       ASCII-8BIT (BINARY)
164
165     -S             Makes Ruby use the PATH environment variable to search for
166                    script, unless its name begins with a slash.  This is used
167                    to emulate #! on machines that don't support it, in the
168                    following manner:
169
170                          #! /usr/local/bin/ruby
171                          # This line makes the next one a comment in Ruby \
172                            exec /usr/local/bin/ruby -S $0 $*
173
174                    On some systems $0 does not always contain the full path‐
175                    name, so you need the -S switch to tell Ruby to search for
176                    the script if necessary (to handle embedded spaces and
177                    such).  A better construct than $* would be ${1+"$@"}, but
178                    it does not work if the script is being interpreted by
179                    csh(1).
180
181     -T[level=1]    Turns on taint checks at the specified level (default 1).
182
183     -U             Sets the default value for internal encodings
184                    (Encoding.default_internal) to UTF-8.
185
186     -W[level=2]    Turns on verbose mode at the specified level without
187                    printing the version message at the beginning. The level
188                    can be;
189
190                          0       Verbose mode is "silence". It sets the
191                                  $VERBOSE to nil.
192
193                          1       Verbose mode is "medium". It sets the
194                                  $VERBOSE to false.
195
196                          2 (default) Verbose mode is "verbose". It sets the
197                                  $VERBOSE to true.  -W2 is same as -w
198
199     -a             Turns on auto-split mode when used with -n or -p.  In
200                    auto-split mode, Ruby executes
201                          $F = $_.split
202                    at beginning of each loop.
203
204     -c             Causes Ruby to check the syntax of the script and exit
205                    without executing. If there are no syntax errors, Ruby
206                    will print “Syntax OK” to the standard output.
207
208     -d
209     --debug        Turns on debug mode.  $DEBUG will be set to true.
210
211     -e command     Specifies script from command-line while telling Ruby not
212                    to search the rest of the arguments for a script file
213                    name.
214
215     -h
216     --help         Prints a summary of the options.
217
218     -i extension   Specifies in-place-edit mode.  The extension, if speci‐
219                    fied, is added to old file name to make a backup copy.
220                    For example:
221
222                          % echo matz > /tmp/junk
223                          % cat /tmp/junk
224                          matz
225                          % ruby -p -i.bak -e '$_.upcase!' /tmp/junk
226                          % cat /tmp/junk
227                          MATZ
228                          % cat /tmp/junk.bak
229                          matz
230
231     -l             (The lowercase letter “ell”.)  Enables automatic line-end‐
232                    ing processing, which means to firstly set $\ to the value
233                    of $/, and secondly chops every line read using chomp!.
234
235     -n             Causes Ruby to assume the following loop around your
236                    script, which makes it iterate over file name arguments
237                    somewhat like sed -n or awk.
238
239                          while gets
240                            ...
241                          end
242
243     -p             Acts mostly same as -n switch, but print the value of
244                    variable $_ at the each end of the loop.  For example:
245
246                          % echo matz | ruby -p -e '$_.tr! "a-z", "A-Z"'
247                          MATZ
248
249     -r library     Causes Ruby to load the library using require.  It is use‐
250                    ful when using -n or -p.
251
252     -s             Enables some switch parsing for switches after script name
253                    but before any file name arguments (or before a --).  Any
254                    switches found there are removed from ARGV and set the
255                    corresponding variable in the script.  For example:
256
257                          #! /usr/local/bin/ruby -s
258                          # prints "true" if invoked with `-xyz' switch.
259                          print "true\n" if $xyz
260
261     -v             Enables verbose mode.  Ruby will print its version at the
262                    beginning and set the variable $VERBOSE to true.  Some
263                    methods print extra messages if this variable is true.  If
264                    this switch is given, and no other switches are present,
265                    Ruby quits after printing its version.
266
267     -w             Enables verbose mode without printing version message at
268                    the beginning.  It sets the $VERBOSE variable to true.
269
270     -x[directory]  Tells Ruby that the script is embedded in a message.
271                    Leading garbage will be discarded until the first line
272                    that starts with “#!” and contains the string, “ruby”.
273                    Any meaningful switches on that line will be applied.  The
274                    end of the script must be specified with either EOF, ^D
275                    (control-D), ^Z (control-Z), or the reserved word __END__.
276                    If the directory name is specified, Ruby will switch to
277                    that directory before executing script.
278
279     -y
280     --yydebug      DO NOT USE.
281
282                    Turns on compiler debug mode.  Ruby will print a bunch of
283                    internal state messages during compilation.  Only specify
284                    this switch you are going to debug the Ruby interpreter.
285
286     --disable-FEATURE
287     --enable-FEATURE
288                    Disables (or enables) the specified FEATURE.
289                    --disable-gems
290                    --enable-gems      Disables (or enables) RubyGems li‐
291                                       braries.  By default, Ruby will load
292                                       the latest version of each installed
293                                       gem. The Gem constant is true if
294                                       RubyGems is enabled, false if other‐
295                                       wise.
296
297                    --disable-rubyopt
298                    --enable-rubyopt   Ignores (or considers) the RUBYOPT en‐
299                                       vironment variable. By default, Ruby
300                                       considers the variable.
301
302                    --disable-all
303                    --enable-all       Disables (or enables) all features.
304
305     --dump=target  Dump some information.
306
307                    Prints the specified target.  target can be one of;
308
309                          version version description same as --version
310
311                          usage   brief usage message same as -h
312
313                          help    Show long help message same as --help
314
315                          syntax  check of syntax same as -c --yydebug
316
317                          yydebug compiler debug mode, same as --yydebug
318
319                                  Only specify this switch if you are going to
320                                  debug the Ruby interpreter.
321
322                          parsetree
323
324                          parsetree_with_comment AST nodes tree
325
326                                  Only specify this switch if you are going to
327                                  debug the Ruby interpreter.
328
329                          insns   disassembled instructions
330
331                                  Only specify this switch if you are going to
332                                  debug the Ruby interpreter.
333
334     --verbose      Enables verbose mode without printing version message at
335                    the beginning.  It sets the $VERBOSE variable to true.  If
336                    this switch is given, and no script arguments (script file
337                    or -e options) are present, Ruby quits immediately.
338

ENVIRONMENT

340     RUBYLIB    A colon-separated list of directories that are added to Ruby's
341                library load path ($:). Directories from this environment
342                variable are searched before the standard load path is
343                searched.
344
345                e.g.:
346                      RUBYLIB="$HOME/lib/ruby:$HOME/lib/rubyext"
347
348     RUBYOPT    Additional Ruby options.
349
350                e.g.
351                      RUBYOPT="-w -Ke"
352
353                Note that RUBYOPT can contain only -d, -E, -I, -K, -r, -T, -U,
354                -v, -w, -W, --debug, --disable-FEATURE and --enable-FEATURE.
355
356     RUBYPATH   A colon-separated list of directories that Ruby searches for
357                Ruby programs when the -S flag is specified.  This variable
358                precedes the PATH environment variable.
359
360     RUBYSHELL  The path to the system shell command.  This environment vari‐
361                able is enabled for only mswin32, mingw32, and OS/2 platforms.
362                If this variable is not defined, Ruby refers to COMSPEC.
363
364     PATH       Ruby refers to the PATH environment variable on calling Ker‐
365                nel#system.
366
367     And Ruby depends on some RubyGems related environment variables unless
368     RubyGems is disabled.  See the help of gem(1) as below.
369
370           % gem help
371

GC ENVIRONMENT

373     The Ruby garbage collector (GC) tracks objects in fixed-sized slots, but
374     each object may have auxiliary memory allocations handled by the malloc
375     family of C standard library calls ( malloc(3), calloc(3), and
376     realloc(3)).  In this documentatation, the "heap" refers to the Ruby ob‐
377     ject heap of fixed-sized slots, while "malloc" refers to auxiliary allo‐
378     cations commonly referred to as the "process heap".  Thus there are at
379     least two possible ways to trigger GC:
380
381           1       Reaching the object limit.
382
383           2       Reaching the malloc limit.
384
385     In Ruby 2.1, the generational GC was introduced and the limits are di‐
386     vided into young and old generations, providing two additional ways to
387     trigger a GC:
388
389           3       Reaching the old object limit.
390
391           4       Reaching the old malloc limit.
392
393     There are currently 4 possible areas where the GC may be tuned by the
394     following 11 environment variables:
395     RUBY_GC_HEAP_INIT_SLOTS                Initial allocation slots.  Intro‐
396                                            duced in Ruby 2.1, default: 10000.
397
398     RUBY_GC_HEAP_FREE_SLOTS                Prepare at least this amount of
399                                            slots after GC.  Allocate this
400                                            number slots if there are not
401                                            enough slots.  Introduced in Ruby
402                                            2.1, default: 4096
403
404     RUBY_GC_HEAP_GROWTH_FACTOR             Increase allocation rate of heap
405                                            slots by this factor.  Introduced
406                                            in Ruby 2.1, default: 1.8, mini‐
407                                            mum: 1.0 (no growth)
408
409     RUBY_GC_HEAP_GROWTH_MAX_SLOTS          Allocation rate is limited to this
410                                            number of slots, preventing exces‐
411                                            sive allocation due to
412                                            RUBY_GC_HEAP_GROWTH_FACTOR.  In‐
413                                            troduced in Ruby 2.1, default: 0
414                                            (no limit)
415
416     RUBY_GC_HEAP_OLDOBJECT_LIMIT_FACTOR    Perform a full GC when the number
417                                            of old objects is more than R * N,
418                                            where R is this factor and N is
419                                            the number of old objects after
420                                            the last full GC.  Introduced in
421                                            Ruby 2.1.1, default: 2.0
422
423     RUBY_GC_MALLOC_LIMIT                   The initial limit of young genera‐
424                                            tion allocation from the malloc-
425                                            family.  GC will start when this
426                                            limit is reached.  Default: 16MB
427
428     RUBY_GC_MALLOC_LIMIT_MAX               The maximum limit of young genera‐
429                                            tion allocation from malloc before
430                                            GC starts.  Prevents excessive
431                                            malloc growth due to RUBY_GC_MAL‐
432                                            LOC_LIMIT_GROWTH_FACTOR.  Intro‐
433                                            duced in Ruby 2.1, default: 32MB.
434
435     RUBY_GC_MALLOC_LIMIT_GROWTH_FACTOR     Increases the limit of young gen‐
436                                            eration malloc calls, reducing GC
437                                            frequency but increasing malloc
438                                            growth until RUBY_GC_MAL‐
439                                            LOC_LIMIT_MAX is reached.  Intro‐
440                                            duced in Ruby 2.1, default: 1.4,
441                                            minimum: 1.0 (no growth)
442
443     RUBY_GC_OLDMALLOC_LIMIT                The initial limit of old genera‐
444                                            tion allocation from malloc, a
445                                            full GC will start when this limit
446                                            is reached.  Introduced in Ruby
447                                            2.1, default: 16MB
448
449     RUBY_GC_OLDMALLOC_LIMIT_MAX            The maximum limit of old genera‐
450                                            tion allocation from malloc before
451                                            a full GC starts.  Prevents exces‐
452                                            sive malloc growth due to
453                                            RUBY_GC_OLDMAL‐
454                                            LOC_LIMIT_GROWTH_FACTOR.  Intro‐
455                                            duced in Ruby 2.1, default: 128MB
456
457     RUBY_GC_OLDMALLOC_LIMIT_GROWTH_FACTOR  Increases the limit of old genera‐
458                                            tion malloc allocation, reducing
459                                            full GC frequency but increasing
460                                            malloc growth until RUBY_GC_OLD‐
461                                            MALLOC_LIMIT_MAX is reached.  In‐
462                                            troduced in Ruby 2.1, default:
463                                            1.2, minimum: 1.0 (no growth)
464

STACK SIZE ENVIRONMENT

466     Stack size environment variables are implementation-dependent and subject
467     to change with different versions of Ruby.  The VM stack is used for
468     pure-Ruby code and managed by the virtual machine.  Machine stack is used
469     by the operating system and its usage is dependent on C extensions as
470     well as C compiler options.  Using lower values for these may allow ap‐
471     plications to keep more Fibers or Threads running; but increases the
472     chance of SystemStackError exceptions and segmentation faults (SIGSEGV).
473     These environment variables are available since Ruby 2.0.0.  All values
474     are specified in bytes.
475
476     RUBY_THREAD_VM_STACK_SIZE       VM stack size used at thread creation.
477                                     default: 131072 (32-bit CPU) or 262144
478                                     (64-bit)
479
480     RUBY_THREAD_MACHINE_STACK_SIZE  Machine stack size used at thread cre‐
481                                     ation.  default: 524288 or 1048575
482
483     RUBY_FIBER_VM_STACK_SIZE        VM stack size used at fiber creation.
484                                     default: 65536 or 131072
485
486     RUBY_FIBER_MACHINE_STACK_SIZE   Machine stack size used at fiber cre‐
487                                     ation.  default: 262144 or 524288
488

SEE ALSO

490     https://www.ruby-lang.org/     The official web site.
491     https://www.ruby-toolbox.com/  Comprehensive catalog of Ruby libraries.
492

REPORTING BUGS

494     Security vulnerabilities should be reported via an email to
495         security@ruby-lang.org.  Reported problems will be published after
496         being fixed.
497
498     Other bugs and feature requests can be reported via the Ruby Issue
499         Tracking System (https://bugs.ruby-lang.org/). Do not report security
500         vulnerabilities via this system because it publishes the vulnerabili‐
501         ties immediately.
502

AUTHORS

504     Ruby is designed and implemented by Yukihiro Matsumoto <matz@netlab.jp>.
505
506     See ⟨https://bugs.ruby-lang.org/projects/ruby/wiki/Contributors⟩ for con‐
507     tributors to Ruby.
508
509UNIX                            April 14, 2018                            UNIX
Impressum