Standard Library Tour

Levels. Logger::DEBUG (0), INFO, WARN, ERROR, FATAL and UNKNOWN (5). A message is written only when its severity is at least the logger’s level. The level: keyword and level= accept a constant, a symbol (:warn) or a string ("warn"); level returns the integer. The default is DEBUG.

Four ways to log. log.info("text") (the argument is the message), log.info("progname") { "text" } (the block is evaluated only if the level is enabled, which is how to avoid building expensive messages), log.add(severity, message, progname) and log << "raw text", which writes without any formatting and ignores the level.

Exceptions as messages. An Exception passed to error is formatted by the default formatter as message (ClassName) followed by its backtrace, if it has one. A custom formatter, as above, receives the object itself and decides.

The default format is I, [2026-01-02T03:04:05.000000 #4242] INFO — shelf: hello: severity initial, time, process id, severity, progname and message. datetime_format: changes only the time. A formatter is any object with call(severity, time, progname, message); Logger::Formatter is the default.

Destinations. An IO ($stdout, $stderr), a path (the file is created, appended to, and starts with a header line unless skip_header: true), or nil for a logger that discards everything, handy in tests. With a path, Logger.new(path, 3, 1_048_576) keeps three files of at most 1 MiB, and Logger.new(path, "daily") (or "weekly", "monthly") rotates by date.

Threads. Writes to the log device are serialized by a monitor, so one logger can be shared by threads. with_level(:error) { ... } (logger 1.6.0, Ruby 3.3) changes the level for the duration of the block, for the current fiber only (so other threads keep theirs).

Buffering. Logger.new($stdout) is as buffered as $stdout is; when output goes to a pipe or a file, call $stdout.sync = true or lines can appear late and out of order with $stderr.

Do not log secrets. Passwords, tokens and full request bodies end up in files that many people can read; log identifiers instead.

Structured logging (JSON lines) is a custom formatter that returns JSON.generate(...) + "\n". Application frameworks add tagging and request ids; none of this is in the standard library.

Tags. <%= expression %> inserts the value of the expression converted with to_s; <% code %> runs code and inserts nothing; <%# comment %> is ignored; <%% produces a literal <%.

Running a template. result(binding) evaluates the template in the given binding (so local variables are visible), result_with_hash(hash) evaluates it with exactly those names as locals (the safer default, shown above), run prints the result, src returns the compiled Ruby, and def_method(klass, "name(args)") compiles the template once into a method, which is the fast way to render the same template many times.

Trim modes are chosen with trim_mode:. "-" removes the whole line around a tag written <%- …​ -%> (used above), "<>" omits the newline of lines that start with <% and end with %>, ">" omits the newline after every %>, and "%" makes a line that starts with % a line of Ruby. They can be combined ("%<>"). Without one, the blank lines left by control tags stay in the output.

No escaping. <%= %> does not escape anything. For HTML, use ERB::Util.html_escape (alias h; ERB::Escape.html_escape is the fast alias, 3.2) on every untrusted value, ERB::Util.url_encode for URL components. Frameworks add automatic escaping on top; plain ERB has none.

A template is code. Never build an ERB from untrusted input, and never render a template with a binding that exposes sensitive objects: <%= File.read("/etc/passwd") %> is valid ERB. See Security.

Ruby 4.0. The positional arguments of ERB.new (ERB.new(str, nil, "-"), with a safe level and the trim mode as the second and third arguments) were removed in erb 6.0, which ships with Ruby 4.0; ERB.new(str, nil, "-") now raises ArgumentError: wrong number of arguments (given 3, expected 1). Use ERB.new(str, trim_mode: "-"). Older tutorials, and the books this reference was cross-checked against, still show the positional form.

Pitfall. Under ruby -w, a template that contains a tag such as <% 1 %> warns possibly useless use of a literal in void context, because the compiled code is checked like any other Ruby.

The API. def_delegator(accessor, method, ali = method) defines one forwarding method, def_delegators(accessor, *methods) defines several with their own names, and delegate [:a, :b] => :@target is the hash form. The long names def_instance_delegator, def_instance_delegators and instance_delegate are the same methods. SingleForwardable does the same for one object or a module (extend SingleForwardable), as Settings does above.

The accessor is an instance variable name (:@books), a method name (:books) or a string holding a Ruby expression ("self.class", "Shelf.config"). Expressions are evaluated at every call.

Only what you list is forwarded. The example shows that push is missing: the point of forwarding over inheritance is a smaller interface. include Enumerable plus a forwarded each is the cheapest way to make a wrapper iterable.

Return value and errors. The forwarded method returns what the target returned, and an error raised by the target keeps its message. Keyword arguments and blocks are passed through.

Wrong accessor. A typo in the accessor name is only found when the method is called (NoMethodError or NameError for the accessor), not when the class is loaded.

Choosing. Use Forwardable when you want a fixed, explicit list of delegated methods. Use SimpleDelegator (next section) when you want to forward everything and override a few methods.

SimpleDelegator.new(obj) wraps any object; __getobj__ returns it and __setobj__ replaces it. super inside an overriding method calls the wrapped object’s method, as in title above.

DelegateClass(SomeClass) returns a class whose instance methods are copied from SomeClass at definition time, so the wrapper responds to exactly the public interface of that class and is slightly faster than method_missing. Inherit from it and call super in initialize to set the wrapped object.

Identity is not preserved. Delegator inherits from BasicObject, so shout.is_a?(Shelf::Book) is false and Shelf::Book === shout does not match a case branch, while shout == book is true (the delegator forwards ==). Do not use case/when on the class, or kind_of?, to examine a decorated object; use duck typing or pattern matching on its interface.

Pitfalls. Private methods of the wrapped object are not forwarded (NoMethodError). The missing-method message names the wrapper, as the output shows (undefined method 'missing' for an instance of Decorators::ShoutingBook). Wrapping changes equal?: the wrapper and the wrapped object are two objects, so identity-based collections (compare_by_identity hashes, Set of identities) treat them as different.

include Singleton makes new and allocate private, makes dup and clone raise TypeError, and defines instance, which creates the object on first use. Creation is guarded by a mutex, so concurrent first calls produce one object. In a Ractor program the instance is per Ractor, see Ractors.

A subclass of a singleton class has its own instance (A.instance.equal?(B.instance) is false).

A Marshal.load of Marshal.dump(Registry.instance) returns the same instance, not a copy; allocate is private like new.

This is not the same as a singleton class (the metaclass of an object, see Singleton Classes and Class-Level Behavior); the name is shared by accident.

Prefer simpler tools. A global that tests cannot replace is hard to test. In Ruby you rarely need the pattern: a module with extend self, a constant that holds an object, or a memoized accessor such as Shelf.config in the running gem (@config ||= ...) gives the same single point of access with less ceremony and can be reset in a test. Reach for Singleton when you truly need to forbid a second instance.

include Observable adds add_observer(observer, func = :update), delete_observer, delete_observers, count_observers, changed(state = true), changed? and notify_observers(*args).

notify_observers does nothing unless changed was called first, and it clears the changed flag afterwards. Forgetting changed is the usual bug: observers never run, and no error says so.

The observer is called with whatever arguments notify_observers received, through the method named by func; add_observer raises NoMethodError at once if the object does not respond to it (the message in the output keeps the old backtick quoting because it is written in the gem, not generated by the interpreter).

The observable keeps a strong reference to its observers, so a long-lived subject that is never told delete_observer leaks them.

Most Ruby programs use a block or a callable instead (loan.on_lend { |book| ... }), which needs no library. Choose observer for the interface it standardizes, not out of habit.

Use it for anything an attacker must not guess: session identifiers, password-reset and API tokens, salts, nonces, keys. Use Random or Kernel#rand only for simulations, shuffling and tests: Random is a deterministic Mersenne Twister whose whole future follows from the seed, as the last lines of the example show.

The methods. hex(n) returns 2n hexadecimal digits for n random bytes, base64(n), urlsafe_base64(n, padding = false), alphanumeric(n, chars: ...), random_bytes(n) and bytes(n) (binary strings), random_number (a Float, an Integer below n, or a number in a range, and also called rand), uuid (version 4) and uuid_v7 (time-ordered, Ruby 3.3, good for database keys because new values sort after old ones).

Length. The argument is the number of random bytes, not the number of characters: hex(16) is 32 characters, base64(9) is 12. The default of 16 bytes (128 bits) is adequate for tokens; shorter values can be guessed.

Comparing a secret to user input must be constant time, see OpenSSL.fixed_length_secure_compare in the Digest section.

No seeding. There is no srand for SecureRandom; a "reproducible" value from it is a bug. Tests inject the generator or stub the call.

Classes: Digest::SHA256 (use this one), Digest::SHA384, Digest::SHA512, Digest::SHA2.new(bitlen), Digest::SHA1, Digest::MD5, Digest::RMD160. There is no Digest::SHA3; use OpenSSL::Digest.new("SHA3-256").

Three ways to compute: the class methods hexdigest, digest (raw bytes) and base64digest; the file shortcut Digest::SHA256.file(path), which reads in chunks; and an instance fed with << or update for streaming, finished with hexdigest (an instance can be reset). Two digests compare with ==.

MD5 and SHA-1 are broken for collision resistance; they remain acceptable for non-adversarial uses such as de-duplication or matching a published checksum.

Passwords need a slow, salted key-derivation function, not a digest: OpenSSL::KDF.pbkdf2_hmac and scrypt (shown above with a deliberately tiny count) or a community gem such as bcrypt or argon2. A fast digest of a password can be brute-forced at billions of guesses per second.

Message authentication (is this payload from someone who knows the key?) is an HMAC, not Digest::SHA256.hexdigest(key + message) (which is vulnerable to length extension). Compare the received and the expected MAC with OpenSSL.fixed_length_secure_compare (it accepts only strings of equal length and raises ArgumentError: inputs must be of equal length otherwise) so that the comparison time does not leak how many leading characters matched.

The methods. Benchmark.realtime { } returns the elapsed seconds as a Float measured with the monotonic clock; Benchmark.measure(label) { } returns a Benchmark::Tms with utime, stime, cutime, cstime, real, total and label, and format with the %n, %u, %y, %t and %r directives; Benchmark.bm(label_width) and Benchmark.benchmark(caption, label_width, format, *labels) print the table; Benchmark.bmbm runs every job twice, a "rehearsal" first, so that warm-up and garbage collection do not favour the second job.

A warning from the gem. Under ruby -w, benchmark 0.5.0 prints warning: too many arguments for format string from benchmark.rb each time bm prints a row. It comes from the gem, not from your code, and is harmless; run the reports without -w.

Measure the right thing. Run each job long enough that it takes at least several milliseconds, outside the code you want to measure create the data, and compare more than one run. A single realtime of a microsecond-scale job measures the noise.

Prefer a counter to a clock when you can. "How many comparisons did it make?" does not vary with load. The comparisons above are 2,000 Array#include? calls against 2,000 Set#include? calls over a 2,000-element collection: the Set wins by roughly two orders of magnitude, but the ratio changes with the sizes.

For iterations per second with error bars (benchmark-ips), memory benchmarks and profilers, see Performance, Benchmarking and Profiling.

Entry points. pp obj writes to $stdout and returns obj (several arguments return an array, none returns nil); obj.pretty_inspect returns the string; PP.pp(obj, out, width) writes to any object with << using the given width; PP.singleline_pp(obj, out) prints on one line.

Width. pp wraps at the terminal width when $stdout is a terminal (since Ruby 3.1, via IO#winsize) and at 80 columns otherwise, which is why a log file and a terminal show different line breaks for the same object.

Output format. Since 3.4 hashes print as {key: value} and {"str" => 1}, and Data and Struct instances as #<data Shelf::Book ...> and #<struct ...>, exactly as inspect does, but broken over lines.

Customizing. Define pretty_print(printer) on a class and build the layout with printer.group(indent, open, close) { ... }, printer.breakable (a space, or a newline when the group does not fit), printer.seplist(items) { ... }, printer.text and printer.pp(child). To restrict which instance variables are shown, override pretty_print_instance_variables; for objects that may contain themselves, pretty_print_cycle. (Ruby 4.0 also lets a class limit what inspect shows with a private instance_variables_to_inspect method.)

Use it for debugging output and for tests that print structures, not for serialization.

Parsing. Shellwords.split (aliases shellsplit and shellwords) understands single quotes, double quotes and backslashes, and raises ArgumentError with a message such as Unmatched quote at 5: ... for an unbalanced quote. It does not expand variables, globs or $(...).

Quoting. Shellwords.escape (alias shellescape) escapes shell metacharacters with backslashes and turns the empty string into ''; Shellwords.join (alias shelljoin) does it for an array. This is for POSIX shells; it is no use for cmd.exe or PowerShell.

It is a patch, not a defence. The robust way to run a program is to avoid the shell altogether: system("cp", source, target) and Open3.capture2e("cp", source, target) pass an argument array and no shell is involved, so there is nothing to escape. Reach for Shellwords when you must build a command string for a shell you do not control (an ssh remote command, a shell script you generate), see Processes, Signals and Shell and Security.

Signature. Timeout.timeout(sec, klass = nil, message = nil) { |sec| ... }. With a klass that exception is raised instead (so callers can tell your timeout from another), with a message it replaces the default execution expired. nil and 0 mean "no limit"; negative values raise ArgumentError since Ruby 3.4 (timeout 0.4.3), and silently meant "no limit" before that.

Timeout::Error inherits from RuntimeError, so a bare rescue => e around the call swallows it. The exception the library uses internally to unwind the block, Timeout::ExitException, derives from Exception, so a bare rescue => e inside the block does not catch it; the caller of timeout sees Timeout::Error.

It is dangerous. The exception is raised in the middle of whatever the block was executing, including ensure code, a database transaction, a half-written file, or code holding a Mutex. Nothing guarantees that the interrupted code gets to restore its invariants. This is why the Ruby community’s advice has become "do not use Timeout around code you do not control".

Prefer timeouts that the operation itself supports: Net::HTTP#open_timeout, #read_timeout and #write_timeout, Socket.tcp(..., connect_timeout:), IO#timeout= (Ruby 3.2, raises IO::TimeoutError), Queue#pop(timeout:) (Ruby 3.2) and, for loops, an explicit deadline computed from Process.clock_gettime(Process::CLOCK_MONOTONIC). In Ruby 4.0, TCPSocket.new consistently raises IO::TimeoutError when its timeout expires. The details and the other caveats are in Threads and the GVL.

Fibers. Under a fiber scheduler, Timeout.timeout uses the scheduler’s timeout_after hook (Ruby 3.1), so it interrupts a blocked fiber instead of a thread; see Fibers and the Fiber Scheduler.

WeakRef.new(obj) wraps obj; weakref_alive? tells whether it is still there. Once the object has been collected, any forwarded call and __getobj__ raise WeakRef::RefError (a StandardError), with the message Invalid Reference - probably recycled.

You cannot demonstrate collection reliably. When an object is freed depends on the garbage collector, and the example above only shows the object alive while a strong reference (book) exists. Never write code or tests that expect a particular moment of collection; see Garbage Collection and Memory.

Typical use is a cache that must not prevent its entries from being freed. The simplest correct pattern is to check weakref_alive? and rebuild the value when it is false, accepting that it can die between the check and the use (rescue WeakRef::RefError).

Better tools exist. ObjectSpace::WeakMap (keys and values held weakly, compared by identity) and ObjectSpace::WeakKeyMap (Ruby 3.3; keys held weakly and compared with eql? and hash, values held strongly, as in the example, so equal strings find the same entry) are implemented in C and are what caches use today.

Users and groups. Etc.getpwuid(uid = Process.uid), Etc.getpwnam(name), Etc.getgrgid and Etc.getgrnam return Etc::Passwd and Etc::Group structs (name, uid, gid, dir, shell, …​); an unknown name raises ArgumentError (can't find user for ...). Etc.passwd and Etc.group iterate over every entry. Etc.getlogin can return nil when the process has no controlling terminal (a service or container), so Etc.getpwuid.name is the reliable way to ask "who am I".

The machine. Etc.uname returns a hash with :sysname, :nodename, :release, :version and :machine. Etc.nprocessors returns the number of processors available to the process and is the usual default for a thread or worker pool size; it does not necessarily reflect a CPU quota imposed by a container, so treat it as an upper bound.

Directories and limits. Etc.sysconfdir (where the Ruby installation keeps its configuration) and Etc.systmpdir (the system temporary directory, which Dir.tmpdir builds on), Etc.sysconf(Etc::SC_PAGESIZE) and the other SC_* constants, Etc.confstr and the CS_* constants. Many of these do not exist on Windows, where only a subset of Etc is available.

For the home directory, Dir.home and File.expand_path("~") are enough; Etc is for when you need another user’s entry.

Three formats, one library. Zlib.deflate and Zlib.inflate use the zlib format (a header and an Adler-32 checksum), Zlib.gzip and Zlib.gunzip the gzip file format (a header with a name and modification time, and a CRC-32 trailer), and Zlib::Deflate.new(level, -Zlib::MAX_WBITS) raw DEFLATE. Using inflate on gzip data is a Zlib::DataError (incorrect header check).

Streaming. Zlib::GzipWriter.open(path) and Zlib::GzipReader.open(path) behave like files and take a block; GzipReader.wrap(io)/GzipWriter.wrap(io) work on any IO (a StringIO, a socket), each_line and read(length) stream. Zlib::Deflate and Zlib::Inflate are the low-level streaming objects; set level: (Zlib::BEST_SPEED 1 to Zlib::BEST_COMPRESSION 9) to trade time for size.

Errors all inherit from Zlib::Error: Zlib::DataError (corrupt input), Zlib::BufError, Zlib::StreamError, Zlib::MemError, and Zlib::GzipFile::Error (and its subclasses CRCError, LengthError and NoFooter) for gzip files.

Checksums. Zlib.crc32 and Zlib.adler32 take an optional running value so that a checksum can be computed over chunks. They detect accidents, not tampering.

A decompression bomb is a few kilobytes that inflate to gigabytes. Never call Zlib.inflate or GzipReader#read without a length on untrusted data. The bounded_gunzip helper at the end of the example reads in chunks and stops when the output passes a limit. The same advice applies to every archive format.

ZIP and tar archives are not in the standard library (Gem::Package::TarReader aside); the community rubyzip gem is the usual choice.

Advance and look ahead. scan(re) matches at the pointer and advances; scan_until(re) searches ahead and advances past the match; skip and skip_until return the length instead of the text; check, check_until and match? do the same without moving; getch takes one character, peek(n) shows the next n bytes, scan_integer (Ruby 3.4) reads an integer (base: 16 for hexadecimal).

Inspect the state. matched, pre_match, post_match, [] (capture groups by number or name, scanner[:name]), captures, rest, eos?, pos (a byte position; charpos counts characters), pos= and unscan (undo the last match).

Anchors. A pattern is matched at the pointer; \A means "at the pointer" and ^ "at the start of a line", unless the scanner was created with StringScanner.new(string, fixed_anchor: true), in which case \A means the start of the string.

Order the rules from the most to the least specific, as in the example’s RULES table, and always provide a final failure branch that raises with the position (scanner.pos), otherwise an unexpected character loops forever or is skipped silently.

Compared to String#scan, which returns every match of a pattern, a scanner can switch patterns depending on what it has just read. For the regular-expression syntax itself see Regular Expressions.

The require that worked and then did not. A LoadError for logger, benchmark, observer, csv, base64, bigdecimal or ostruct after an upgrade, only under bundle exec, means the library became a bundled gem. Add it to the Gemfile (an application) or the gemspec (a library).

Using Timeout as a safety net. It can corrupt state; use the operation’s own timeout.

Treating Digest as a password hash, rand as a token source, or == as a MAC comparison.

Calling notify_observers without changed.

Relying on is_a? with a delegator.

Assuming WeakRef is deterministic.

Inflating untrusted compressed data in one call.

Building an ERB template from user input, or printing untrusted values with <%= %> and no escaping.

Logging secrets, or building an expensive message that a block would have avoided building.

Ruby Standard Library (4.0): the list of core extensions, default gems and bundled gems

NEWS for Ruby 4.0, 3.4, 3.3, 3.2 and 3.1

Logger, ERB, Forwardable, SimpleDelegator, Singleton and observer

SecureRandom, Digest, OpenSSL and benchmark

PP, Shellwords, Timeout, WeakRef, Etc, Zlib and StringScanner

Gem::Specification and Bundler: Gemfile

RubyGems and Bundler, Security, SOLID and Design Patterns