RUBY(1)

📦 version 3.3.8, in debian trixie, ubuntu questing, ubuntu resolute, ubuntu stonking

💖 Ruby's Reference Guide (Section 1) 💖

okay so this is the Ruby Programmer's Reference Guide, manual section 1, and I am so ready to explain it to you 🫶 let's get into it bestie ✨

🎀 NAME 🎀

ruby — Interpreted object-oriented scripting language 🦋

🌸 SYNOPSIS 🌸

ruby [--copyright] [--version] [-SUacdlnpswvy] [-0[octal]]
     [-C directory] [-E external[:internal]] [-F[pattern]]
     [-I directory] [-K[c]] [-T[level]] [-W[level]] [-e command]
     [-i[extension]] [-r library] [-x[directory]]
     [--{enable|disable}-FEATURE] [--dump=target] [--verbose]
     [--crash-report=template] [--] [program_file] [argument ...]

🔥 DESCRIPTION 🔥

okay so Ruby is an interpreted scripting language that's built for quick and easy object-oriented programming 💅 it's got a bunch of features for processing text files and handling system management tasks (kinda like Perl does) ✨ and it's simple, straightforward, and extensible 🌈

if you want a language for easy OOP, or you're over the Perl ugliness, or you love the concept of LISP but can't handle all those parentheses 💀 then Ruby might be your language of choice 🍓

👑 FEATURES 👑

bestie, Ruby's features are giving everything, so here's the full list ✨

  • Interpretive 🧚 Ruby is an interpreted language, so you don't have to recompile your Ruby programs before you run them 🫶
  • Variables have no type (dynamic typing) 🦋 Variables in Ruby can hold data of any type, so you don't have to stress about variable typing 🙈 the tradeoff is that it has a weaker compile time check 😭
  • No declaration needed 💜 you can use variables in your Ruby programs without declaring them first 💅 the variable's name tells you its scope: global, class, instance, or local ✨
  • Simple syntax 🌸 Ruby has a simple syntax, slightly influenced by Eiffel 🎀
  • No user-level memory management 🧚 Ruby does automatic memory management for you 🙌 objects that nothing references anymore get collected automatically by the garbage collector built into the interpreter 🗑️✨
  • Everything is an object 🔮 Ruby is a purely object-oriented language, and it has been since it was created 👑 even basic stuff like integers counts as an object 🤯
  • Class, inheritance, and methods 🦋 because Ruby is OOP to its core, it naturally has the basics: classes, inheritance, and methods 💖
  • Singleton methods 🌈 Ruby lets you define methods for certain objects 🔥 for example, you can give a specific widget a press-button action by defining a singleton method on that button 🎀 you can also build your own prototype-based object system with singleton methods if you're feeling bold 💅
  • Mix-in by modules 💜 Ruby intentionally skips multiple inheritance because it's a major source of confusion 🙃 instead, it lets you share implementations across the inheritance tree 🫶 this is often called a ‘Mix-in’ ✨
  • Iterators 🍓 Ruby has iterators for loop abstraction 🔁
  • Closures 🔮 in Ruby, you can objectify the procedure 🧚
  • Text processing and regular expressions 📜 Ruby has a whole bunch of text processing features, just like Perl 💅
  • M17N, character set independent 🌍 Ruby supports multilingualized programming ✨ it's easy to process texts written in lots of different natural languages and encoded in lots of different character encodings 🌸 and it doesn't depend on Unicode 🫶
  • Bignums 🔢 with built-in bignums, you can do things like calculate factorial(400) 🤯😭
  • Reflection and domain specific languages 🪞 Class is also an instance of the Class class 🤌 defining classes and methods is an expression, just like 1+1 is 💅 so your programs can even write and modify other programs 🦋 which means you can build your application in your own programming language on top of Ruby 👑
  • Exception handling ⚡ as in Java(tm) 💀
  • Direct access to the OS 🖥️ Ruby can use most Unix system calls, which are often used in system programming 🔥
  • Dynamic loading 🌊 on most Unix systems, you can load object files into the Ruby interpreter on-the-fly ✨
  • Rich libraries 💎 besides the “builtin libraries” and “standard libraries” that come bundled with Ruby, there's a vast amount of third-party libraries (“gems”) available through the package management system called ‘RubyGems’, which you use with the gem(1) command 📦 visit RubyGems.org (https://rubygems.org/) to find the gems you need 💖 and explore GitHub (https://github.com/) to see how they're being developed and used 🫶🌈

✨ OPTIONS ✨

okay so the Ruby interpreter takes a bunch of command-line switches (aka options) 💅 they're pretty similar to the ones in perl(1), so if you've met perl you'll feel right at home 🫶

  • --copyright — shows the copyright notice and bounces immediately, without running any script 📜
  • --version — shows which version of the Ruby interpreter you're on, then quits right away without running anything 🔖
  • -0[octal] — (that's a digit "zero", not the letter o 🙈) sets the input record separator ($/) using an octal number. No digit at all means the null character becomes the separator. other switches can come after the digits too. -00 flips Ruby into paragraph mode 📄 and -0777 makes Ruby slurp the whole file in as one single string, since no legal character has that value 🧠
  • -C directory, -X directory — makes Ruby switch to that directory 📂🦋
  • -E external[:internal], --encoding external[:internal] — sets the default external and internal encodings 🌈 separate the two with a colon (:). you can leave off the internal one, and then Encoding.default_internal ends up as nil 🫠
  • --external-encoding=encoding, --internal-encoding=encoding — sets the default external or internal character encoding, your call 🎀
  • -F pattern — sets the input field separator ($;) 🍓
  • -I directory — tells Ruby where to look for library scripts. that directory gets added to the load-path variable ($:) 🧚
  • -K kcode — sets the KANJI (Japanese) encoding ✨ the default for script encodings (__ENCODING__) and external encodings (Encoding.default_external) becomes whatever you pick. kcode can be one of these:
    • e — EUC-JP
    • s — Windows-31J (CP932)
    • u — UTF-8
    • n — ASCII-8BIT (BINARY)
  • -S — makes Ruby hunt for the script using the PATH environment variable, unless its name starts with a slash 🔍 this is basically how people fake #! on machines that can't do it. it looks like this:
#! /usr/local/bin/ruby
# This line makes the next one a comment in Ruby \
  exec /usr/local/bin/ruby -S $0 $*
⚠️ heads up bestie: on some systems $0 doesn't always hold the full pathname, so you need -S so Ruby can search for the script if it has to (that covers embedded spaces and stuff). a better construct than $* would be ${1+"$@"}, but that one breaks if csh(1) is the thing interpreting the script 🙃
  • -T[level=1] — turns on taint checks at the level you give it (default is 1) 🔒
  • -U — sets the default internal encoding (Encoding.default_internal) to UTF-8 💜
  • -W[level=2] — turns on verbose mode at the level you choose, without printing the version message at the start 📢 the levels are:
    • 0 — "silence" mode, which sets $VERBOSE to nil 🤫
    • 1 — "medium" mode, which sets $VERBOSE to false 😐
    • 2 (default) — "verbose" mode, which sets $VERBOSE to true 📣 and -W2 is the exact same thing as -w
  • -a — turns on auto-split mode, but only when you pair it with -n or -p ✂️ in auto-split mode, Ruby runs $F = $_.split at the start of each loop
  • --backtrace-limit=num — caps how many lines a backtrace can have at num lines (default is -1, which means no limit) 📉
  • -c — checks the syntax of the script and exits without actually running it 🧐 if everything's clean, Ruby prints "Syntax OK" to standard output ✅
  • -d, --debug — turns on debug mode, and $DEBUG gets set to true 🐛
  • -e command — hands Ruby the script straight from the command line, and tells Ruby not to go looking through the other arguments for a script file name 💻
  • -h, --help — shows a summary of the options 🆘
  • -i extension — turns on in-place-edit mode 🪄 if you give an extension, it gets tacked onto the old file name to make a backup copy. check this iconic example:
% echo matz > /tmp/junk
% cat /tmp/junk
matz
% ruby -p -i.bak -e '$_.upcase!' /tmp/junk
% cat /tmp/junk
MATZ
% cat /tmp/junk.bak
matz
  • -l — (that's a lowercase letter "ell" 💀) turns on automatic line-ending processing. it first sets $\ to the value of $/, then chops every line read with chomp! ✂️
  • -n — makes Ruby wrap your script in a loop that goes over the file name arguments, kinda like sed -n or awk 🔁 it assumes this loop around your code:
while gets
  ...
end
  • -p — acts mostly the same as -n, but it also prints the value of $_ at the end of each loop 🖨️ like this:
% echo matz | ruby -p -e '$_.tr! "a-z", "A-Z"'
MATZ
  • -r library — loads the library using require 📚 super handy alongside -n or -p
  • -s — turns on some switch parsing for switches that come after the script name but before any file name arguments (or before a --) 🎛️ any switches it finds get removed from ARGV and set the matching variable inside the script. like so:
#! /usr/local/bin/ruby -s
# prints "true" if invoked with `-xyz' switch.
print "true\n" if $xyz
  • -v — turns on verbose mode 📣 Ruby prints its version at the start and sets $VERBOSE to true. some methods print extra messages when that variable is true. if -v is the only switch you give, Ruby quits right after printing its version 👋
  • -w — turns on verbose mode without printing the version message at the start, and sets $VERBOSE to true 🔊
  • -x[directory] — tells Ruby the script is embedded in a message 📨 any leading garbage gets tossed until the first line that starts with "#!" and contains the string "ruby". any meaningful switches on that line get applied. the script has to end with EOF, ^D (control-D), ^Z (control-Z), or the reserved word __END__ 🔚 if you give a directory name, Ruby switches to that directory before running the script 📂
  • -y, --yydebug — ⚠️ this option is not guaranteed to be compatible. it turns on compiler debug mode, and Ruby spits out a bunch of internal state messages during compilation 🌀 only use this if you're actually debugging the Ruby interpreter itself 🙅‍♀️
  • --disable-FEATURE, --enable-FEATURE — disables (or enables) the FEATURE you name 🎚️ the features are:
    • --disable-gems, --enable-gems — disables (or enables) RubyGems libraries 💎 by default, Ruby loads the latest version of each installed gem. the Gem constant is true if RubyGems is enabled and false if it isn't
    • --disable-rubyopt, --enable-rubyopt — ignores (or considers) the RUBYOPT environment variable 🌸 by default, Ruby considers it
    • --disable-all, --enable-all — disables (or enables) every feature at once 🧨
  • --dump=target — dumps some information 🗑️✨ it prints the target you pick, and target can be one of these:
    • version — prints the version description (same as --version)
    • usage — prints a brief usage message (same as -h)
    • help — shows the long help message (same as --help)
    • syntax — checks the syntax (same as -c --yydebug)

or one of these, which are meant for debugging the interpreter 🧪:

  • yydebug — enables compiler debug mode (same as --yydebug)
  • parsetree — prints a textual representation of the Ruby AST for the program 🌳
  • parsetree_with_comment — prints a textual representation of the Ruby AST for the program, but each node is annotated with the Ruby source code it came from 🏷️
  • insns — prints a list of disassembled bytecode instructions 🔬
  • insns_without_opt — prints the list of disassembled bytecode instructions before any optimizations get applied 🫣
  • --verbose — turns on verbose mode without printing the version message at the start, and sets $VERBOSE to true 📢 if you give this and no script arguments (a script file or -e options), Ruby quits immediately 🏃‍♀️
  • --crash-report=template — sets the template for the path name where the crash report gets saved 💥 check the RUBY_CRASH_REPORT environment variable for the details 🫶

🌈 ENVIRONMENT 🌈

okay so the environment variables are where Ruby lets you sneak in your own settings 💅 every one of these is a little knob you can twist, bestie

  • RUBYLIB 🎀 — a colon-separated list of directories that get tacked onto Ruby's library load path ($:). These folders get searched before the standard load path, so they're first in line 👑

e.g.:

RUBYLIB="$HOME/lib/ruby:$HOME/lib/rubyext"
  • RUBYOPT 🦋 — extra Ruby options, just for you ✨

e.g.

RUBYOPT="-w -Ke"

ngl this one is picky. RUBYOPT can only contain -d, -E, -I, -K, -r, -T, -U, -v, -w, -W, --debug, --disable-FEATURE and --enable-FEATURE. Anything else is a no-go 🙅‍♀️

  • RUBYPATH 🧚 — a colon-separated list of directories Ruby hunts through for Ruby programs when you use the -S flag. This one goes before PATH in the search order 💜
  • RUBYSHELL 🐚 — the path to the system shell command. This one is only enabled on mswin32, mingw32, and OS/2 platforms, so it's a Windows-and-OS/2 kinda thing 💀 If it isn't defined, Ruby falls back to COMSPEC
  • PATH 🍓 — Ruby checks the PATH environment variable when it calls Kernel#system

And Ruby depends on some RubyGems related environment variables unless RubyGems is disabled. For the deets, check the help of gem(1) like so:

% gem help

🗑️ GC ENVIRONMENT 🗑️

okay the garbage collector (GC) is the bestie that cleans up after your objects 🧹 It tracks objects in fixed-sized slots, but each object can also have extra memory allocated through the malloc family of C standard library calls (malloc(3), calloc(3), and realloc(3)). In this doc, the "heap" means the Ruby object heap of fixed-sized slots, while "malloc" means those auxiliary allocations, aka the "process heap". So there are at least two ways to trigger GC:

  1. Reaching the object limit.
  2. Reaching the malloc limit.

In Ruby 2.1, the generational GC showed up and the limits got split into young and old generations, which gives two more ways to trigger a GC 🌸

  1. Reaching the old object limit.
  2. Reaching the old malloc limit.

There are currently 4 possible areas where the GC can be tuned, using these 11 environment variables 🎛️

  • RUBY_GC_HEAP_INIT_SLOTS 🌱 — initial allocation slots, applied to all slot sizes. Introduced in Ruby 2.1, default: 10000.
  • RUBY_GC_HEAP_%d_INIT_SLOTS 🌿 — initial allocation of slots in one specific heap. You can find the available heaps in the keys of GC.stat_heap. Introduced in Ruby 3.3.
  • RUBY_GC_HEAP_FREE_SLOTS 🫧 — keeps at least this many slots ready after a GC, and allocates this many if there aren't enough. Introduced in Ruby 2.1, default: 4096.
  • RUBY_GC_HEAP_GROWTH_FACTOR 📈 — multiplies how fast heap slots get allocated by this factor. Introduced in Ruby 2.1, default: 1.8, minimum: 1.0 (no growth).
  • RUBY_GC_HEAP_GROWTH_MAX_SLOTS 🛑 — caps the allocation rate at this many slots, so RUBY_GC_HEAP_GROWTH_FACTOR can't go wild. Introduced in Ruby 2.1, default: 0 (no limit).
  • RUBY_GC_HEAP_OLDOBJECT_LIMIT_FACTOR 🧓 — runs a full GC when the number of old objects is more than R * N, where R is this factor and N is the number of old objects after the last full GC. Introduced in Ruby 2.1.1, default: 2.0.
  • RUBY_GC_MALLOC_LIMIT 🍼 — the starting limit of young generation allocation from the malloc family. GC kicks off once this limit is hit. Default: 16MB.
  • RUBY_GC_MALLOC_LIMIT_MAX 🧢 — the biggest the young generation malloc limit can get before GC starts. It stops malloc from growing out of control because of RUBY_GC_MALLOC_LIMIT_GROWTH_FACTOR. Introduced in Ruby 2.1, default: 32MB.
  • RUBY_GC_MALLOC_LIMIT_GROWTH_FACTOR 🌷 — raises the young generation malloc limit, so GC runs less often but malloc grows more, until RUBY_GC_MALLOC_LIMIT_MAX is reached. Introduced in Ruby 2.1, default: 1.4, minimum: 1.0 (no growth).
  • RUBY_GC_OLDMALLOC_LIMIT 🕰️ — the starting limit of old generation allocation from malloc. A full GC starts when this limit is reached. Introduced in Ruby 2.1, default: 16MB.
  • RUBY_GC_OLDMALLOC_LIMIT_MAX 🏔️ — the maximum old generation malloc allocation before a full GC starts. It prevents excessive malloc growth caused by RUBY_GC_OLDMALLOC_LIMIT_GROWTH_FACTOR. Introduced in Ruby 2.1, default: 128MB.
  • RUBY_GC_OLDMALLOC_LIMIT_GROWTH_FACTOR 🪄 — raises the old generation malloc limit, so full GCs happen less often but malloc grows more, until RUBY_GC_OLDMALLOC_LIMIT_MAX is reached. Introduced in Ruby 2.1, default: 1.2, minimum: 1.0 (no growth).

🧵 STACK SIZE ENVIRONMENT 🧵

the stack size variables are implementation-dependent and can change between Ruby versions, so don't get too attached 🙈 The VM stack handles pure-Ruby code and is managed by the virtual machine. The machine stack is used by the operating system and depends on C extensions and C compiler options. Lower values can let you keep more Fibers or Threads running, but the chance of SystemStackError exceptions and segmentation faults (SIGSEGV) goes up 😭 These variables exist since Ruby 2.0.0, and all values are in bytes.

  • RUBY_THREAD_VM_STACK_SIZE 🧶 — VM stack size used when a thread is created. default: 524288 (32-bit CPU) or 1048575 (64-bit)
  • RUBY_THREAD_MACHINE_STACK_SIZE 🪡 — machine stack size used when a thread is created. default: 524288 or 1048575
  • RUBY_FIBER_VM_STACK_SIZE 🦄 — VM stack size used when a fiber is created. default: 65536 or 131072
  • RUBY_FIBER_MACHINE_STACK_SIZE 🐉 — machine stack size used when a fiber is created. default: 262144 or 524288

💥 CRASH REPORT ENVIRONMENT 💥

  • RUBY_CRASH_REPORT 📝 — the template for the path name used to save a crash report. default: none

🏷️ Naming crash report files

the template can have % specifiers that get swapped out for the following values when a crash report file is made:

  • %% — a single % character.
  • %e — basename of the executable.
  • %E — pathname of the executable, with slashes (/) swapped for exclamation marks (!).
  • %f — basename of the program name, $0.
  • %F — pathname of the program name, $0, with slashes (/) swapped for exclamation marks (!).
  • %p — PID of the dumped process.
  • %t — time of the dump, as seconds since the Epoch, 1970-01-01 00:00:00 +0000 (UTC).
  • %NNN — a character code in octal.

a lone % at the end of the template gets dropped from the core filename, and so does any % followed by a character that isn't in the list above 🫠 Everything else in the template is taken literally. The template can include / characters, which act as delimiters for directory names 📁

🚰 Piping crash reports to a program

if the first character of this file is a pipe symbol (|), the rest of the line is treated as the command line for a program (or script) that gets run 🚀

the pipe template gets split on spaces into an argument list before the template parameters are expanded 🧩

🔗 SEE ALSO 🔗

🐛 REPORTING BUGS 🐛

  • Security vulnerabilities should be emailed to security@ruby-lang.org. Reported problems get published after they're fixed 🔒
  • Other bugs and feature requests can go to the Ruby Issue Tracking System (https://bugs.ruby-lang.org/). > Do not report security vulnerabilities through this system, because it publishes them immediately 🚨

👑 AUTHORS 👑

Ruby was designed and implemented by Yukihiro Matsumoto <matz@netlab.jp> 💖

see ⟨https://github.com/ruby/ruby/graphs/contributors⟩ for everyone else who contributed to Ruby 🫶

UNIX, April 14, 2018, RUBY(1) — that's the whole page, bestie, you're officially a Ruby manpage pro now 🎀✨ periodt 💅

📦 where this page comes from