NEWS for Ruby 3.1.0¶ ↑

This document is a list of user-visible feature changes since the 3.0.0 release, except for bug fixes.

Note that each entry is kept to a minimum, see links for details.

Language changes¶ ↑

The block argument can now be anonymous if the block will only be passed to another method. [Feature #11256]
```
def foo(&)
  bar(&)
end
```

Pin operator now takes an expression. [Feature #17411]

Prime.each_cons(2).lazy.find_all{_1 in [n, ^(n + 2)]}.take(3).to_a
#=> [[3, 5], [5, 7], [11, 13]]

Pin operator now supports instance, class, and global variables. [Feature #17724]
```
@n = 5
Prime.each_cons(2).lazy.find{_1 in [n, ^@n]}
#=> [3, 5]
```
One-line pattern matching is no longer experimental.
Parentheses can be omitted in one-line pattern matching. [Feature #16182]
```
[0, 1] => _, x
{y: 2} => y:
x #=> 1
y #=> 2
```
Multiple assignment evaluation order has been made consistent with single assignment evaluation order. With single assignment, Ruby uses a left-to-right evaluation order. With this code:
```
foo[0] = bar
```
The following evaluation order is used:
1. foo
2. bar
3. []= called on the result of foo
In Ruby before 3.1.0, multiple assignment did not follow this evaluation order. With this code:
```
foo[0], bar.baz = a, b
```
Versions of Ruby before 3.1.0 would evaluate in the following order
1. a
2. b
3. foo
4. []= called on the result of foo
5. bar
6. baz= called on the result of bar
Starting in Ruby 3.1.0, the evaluation order is now consistent with single assignment, with the left-hand side being evaluated before the right-hand side:
1. foo
2. bar
3. a
4. b
5. []= called on the result of foo
6. baz= called on the result of bar
[Bug #4443]
Values in Hash literals and keyword arguments can be omitted. [Feature #14579]

For example,
- {x:, y:} is a syntax sugar of {x: x, y: y}.
- foo(x:, y:) is a syntax sugar of foo(x: x, y: y).
Constant names, local variable names, and method names are allowed as key names. Note that a reserved word is considered as a local variable or method name even if it's a pseudo variable name such as self.
Non main-Ractors can get instance variables (ivars) of classes/modules if ivars refer to shareable objects. [Feature #17592]
A command syntax is allowed in endless method definitions, i.e., you can now write def foo = puts "Hello". Note that private def foo = puts "Hello" does not parse. [Feature #17398]

Command line options¶ ↑

--disable-gems is now explicitly declared as “just for debugging”. Never use it in any real-world codebase. [Feature #17684]

Core classes updates¶ ↑

Note: We’re only listing outstanding class updates.

Array
- Array#intersect? is added. [Feature #15198]

Class

Class#subclasses, which returns an array of classes directly inheriting from the receiver, not including singleton classes. [Feature #18273]

class A; end
class B < A; end
class C < B; end
class D < A; end
A.subclasses    #=> [D, B]
B.subclasses    #=> [C]
C.subclasses    #=> []

Enumerable
- Enumerable#compact is added. [Feature #17312]
- Enumerable#tally now accepts an optional hash to count. [Feature #17744]
- Enumerable#each_cons and each_slice to return a receiver. [GH-1509]
```
[1, 2, 3].each_cons(2){}
# 3.0 => nil
# 3.1 => [1, 2, 3]

[1, 2, 3].each_slice(2){}
# 3.0 => nil
# 3.1 => [1, 2, 3]
```
Enumerator::Lazy
- Enumerator::Lazy#compact is added. [Feature #17312]
File
- File.dirname now accepts an optional argument for the level to strip path components. [Feature #12194]
GC
- "GC.measure_total_time = true" enables the measurement of GC. Measurement can introduce overhead. It is enabled by default. GC.measure_total_time returns the current setting. GC.stat[:time] or GC.stat(:time) returns measured time in milli-seconds. [[Feature #10917]]
- GC.total_time returns measured time in nano-seconds. [[Feature #10917]]
Integer
- Integer.try_convert is added. [Feature #15211]
Kernel
- Kernel#load now accepts a module as the second argument, and will load the file using the given module as the top-level module. [Feature #6210]
Marshal
- Marshal.load now accepts a freeze: true option. All returned objects are frozen except for Class and Module instances. Strings are deduplicated. [Feature #18148]
MatchData
- MatchData#match is added [Feature #18172]
- MatchData#match_length is added [Feature #18172]
Method / UnboundMethod
- Method#public?, Method#private?, Method#protected?, UnboundMethod#public?, UnboundMethod#private?, UnboundMethod#protected? have been added. [Feature #11689]
Module
- Module#prepend now modifies the ancestor chain if the receiver already includes the argument. Module#prepend still does not modify the ancestor chain if the receiver has already prepended the argument. [Bug #17423]
- Module#private, public, protected, and module_function will now return their arguments. If a single argument is given, it is returned. If no arguments are given, nil is returned. If multiple arguments are given, they are returned as an array. [Feature #12495]
Process
- Process._fork is added. This is a core method for fork(2). Do not call this method directly; it is called by existing fork methods: Kernel.#fork, Process.fork, and IO.popen(“-”). Application monitoring libraries can overwrite this method to hook fork events. [Feature #17795]
Struct
- Passing only keyword arguments to Struct#initialize is warned. You need to use a Hash literal to set a Hash to a first member. [Feature #16806]
- StructClass#keyword_init? is added [Feature #18008]
String
- Update Unicode version to 13.0.0 [Feature #17750] and Emoji version to 13.0 [Feature #18029]
- String#unpack and String#unpack1 now accept an offset: keyword argument to start the unpacking after an arbitrary number of bytes have been skipped. If offset is outside of the string bounds ArgumentError is raised. [Feature #18254]
Thread
- Thread#native_thread_id is added. [Feature #17853]
Thread::Backtrace
- Thread::Backtrace.limit, which returns the value to limit backtrace length set by --backtrace-limit command line option, is added. [Feature #17479]
Thread::Queue
- Thread::Queue.new now accepts an Enumerable of initial values. [Feature #17327]
Time
- Time.new now accepts optional in: keyword argument for the timezone, as well as Time.at and Time.now, so that is now you can omit minor arguments to Time.new. [Feature #17485]
```
Time.new(2021, 12, 25, in: "+07:00")
#=> 2021-12-25 00:00:00 +0700
```
  At the same time, time component strings are converted to integers more strictly now.
```
Time.new(2021, 12, 25, "+07:30")
#=> invalid value for Integer(): "+07:30" (ArgumentError)
```
  Ruby 3.0 or earlier returned probably unexpected result 2021-12-25 07:00:00, not 2021-12-25 07:30:00 nor 2021-12-25 00:00:00 +07:30.
- Time#strftime supports RFC 3339 UTC for unknown offset local time, -0000, as %-z. [Feature #17544]
TracePoint
- TracePoint.allow_reentry is added to allow reenter while TracePoint callback. [Feature #15912]
$LOAD_PATH
- $LOAD_PATH.resolve_feature_path does not raise. [Feature #16043]
Fiber Scheduler
- Add support for Addrinfo.getaddrinfo using address_resolve hook. [Feature #17370]
- Introduce non-blocking Timeout.timeout using timeout_after hook. [Feature #17470]
- Introduce new scheduler hooks io_read and io_write along with a low level IO::Buffer for zero-copy read/write. [Feature #18020]
- IO hooks io_wait, io_read, io_write, receive the original IO object where possible. [Bug #18003]
- Make Monitor fiber-safe. [Bug #17827]
- Replace copy coroutine with pthread implementation. [Feature #18015]
Refinement
- New class which represents a module created by Module#refine. include and prepend are deprecated, and import_methods is added instead. [Bug #17429]

Stdlib updates¶ ↑

The following default gem are updated.
- RubyGems 3.3.3
- base64 0.1.1
- benchmark 0.2.0
- bigdecimal 3.1.1
- bundler 2.3.3
- cgi 0.3.1
- csv 3.2.2
- date 3.2.2
- did_you_mean 1.6.1
- digest 3.1.0
- drb 2.1.0
- erb 2.2.3
- error_highlight 0.3.0
- etc 1.3.0
- fcntl 1.0.1
- fiddle 1.1.0
- fileutils 1.6.0
- find 0.1.1
- io-console 0.5.10
- io-wait 0.2.1
- ipaddr 1.2.3
- irb 1.4.1
- json 2.6.1
- logger 1.5.0
- net-http 0.2.0
- net-protocol 0.1.2
- nkf 0.1.1
- open-uri 0.2.0
- openssl 3.0.0
- optparse 0.2.0
- ostruct 0.5.2
- pathname 0.2.0
- pp 0.3.0
- prettyprint 0.1.1
- psych 4.0.3
- racc 1.6.0
- rdoc 6.4.0
- readline 0.0.3
- readline-ext 0.1.4
- reline 0.3.0
- resolv 0.2.1
- rinda 0.1.1
- ruby2_keywords 0.0.5
- securerandom 0.1.1
- set 1.0.2
- stringio 3.0.1
- strscan 3.0.1
- tempfile 0.1.2
- time 0.2.0
- timeout 0.2.0
- tmpdir 0.1.2
- un 0.2.0
- uri 0.11.0
- yaml 0.2.0
- zlib 2.1.1
- RubyGems 3.3.3
- base64 0.1.1
- benchmark 0.2.0
- bigdecimal 3.1.1
- bundler 2.3.3
- cgi 0.3.1
- csv 3.2.2
- date 3.2.2
- did_you_mean 1.6.1
- digest 3.1.0
- drb 2.1.0
- erb 2.2.3
- error_highlight 0.3.0
- etc 1.3.0
- fcntl 1.0.1
- fiddle 1.1.0
- fileutils 1.6.0
- find 0.1.1
- io-console 0.5.10
- io-wait 0.2.1
- ipaddr 1.2.3
- irb 1.4.1
- json 2.6.1
- logger 1.5.0
- net-http 0.2.0
- net-protocol 0.1.2
- nkf 0.1.1
- open-uri 0.2.0
- openssl 3.0.0
- optparse 0.2.0
- ostruct 0.5.2
- pathname 0.2.0
- pp 0.3.0
- prettyprint 0.1.1
- psych 4.0.3
- racc 1.6.0
- rdoc 6.4.0
- readline 0.0.3
- readline-ext 0.1.4
- reline 0.3.0
- resolv 0.2.1
- rinda 0.1.1
- ruby2_keywords 0.0.5
- securerandom 0.1.1
- set 1.0.2
- stringio 3.0.1
- strscan 3.0.1
- tempfile 0.1.2
- time 0.2.0
- timeout 0.2.0
- tmpdir 0.1.2
- un 0.2.0
- uri 0.11.0
- yaml 0.2.0
- zlib 2.1.1
The following bundled gems are updated.
- minitest 5.15.0
- power_assert 2.0.1
- rake 13.0.6
- test-unit 3.5.3
- rexml 3.2.5
- rbs 2.0.0
- typeprof 0.21.1
- minitest 5.15.0
- power_assert 2.0.1
- rake 13.0.6
- test-unit 3.5.3
- rexml 3.2.5
- rbs 2.0.0
- typeprof 0.21.1
The following default gems are now bundled gems.
- net-ftp 0.1.3
- net-imap 0.2.2
- net-pop 0.1.1
- net-smtp 0.3.1
- matrix 0.4.2
- prime 0.1.2
- debug 1.4.0
- net-ftp 0.1.3
- net-imap 0.2.2
- net-pop 0.1.1
- net-smtp 0.3.1
- matrix 0.4.2
- prime 0.1.2
- debug 1.4.0
The following gems has been removed from the Ruby standard library.
- dbm
- gdbm
- tracer
- dbm
- gdbm
- tracer
Coverage measurement now supports suspension. You can use Coverage.suspend to stop the measurement temporarily, and Coverage.resume to restart it. See [Feature #18176] in detail.
Random::Formatter is moved to random/formatter.rb, so that you can use Random#hex, Random#base64, and so on without SecureRandom. [Feature #18190]

Compatibility issues¶ ↑

Note: Excluding feature bug fixes.

rb_io_wait_readable, rb_io_wait_writable and rb_wait_for_single_fd are deprecated in favour of rb_io_maybe_wait_readable, rb_io_maybe_wait_writable and rb_io_maybe_wait respectively. rb_thread_wait_fd and rb_thread_fd_writable are deprecated. [Bug #18003]

Stdlib compatibility issues¶ ↑

ERB#initialize warns safe_level and later arguments even without -w. [Feature #14256]
lib/debug.rb is replaced with debug.gem
Kernel#pp in lib/pp.rb uses the width of IO#winsize by default. This means that the output width is automatically changed depending on your terminal size. [Feature #12913]
Psych 4.0 changes Psych.load as safe_load by the default. You may need to use Psych 3.3.2 for migrating to this behavior. [Bug #17866]

C API updates¶ ↑

Documented. [GH-4815]
rb_gc_force_recycle is deprecated and has been changed to a no-op. [Feature #18290]

Implementation improvements¶ ↑

Inline cache mechanism is introduced for reading class variables. [Feature #17763]
instance_eval and instance_exec now only allocate a singleton class when required, avoiding extra objects and improving performance. [GH-5146]
The performance of Struct accessors is improved. [GH-5131]
mandatory_only? builtin special form to improve performance on builtin methods. [GH-5112]
Experimental feature Variable Width Allocation in the garbage collector. This feature is turned off by default and can be enabled by compiling Ruby with flag USE_RVARGC=1 set. [Feature #18045] [Feature #18239]

JIT¶ ↑

Rename Ruby 3.0’s --jit to --mjit, and alias --jit to --yjit on non-Windows x86-64 platforms and to --mjit on others.

MJIT¶ ↑

The default --mjit-max-cache is changed from 100 to 10000.
JIT-ed code is no longer cancelled when a TracePoint for class events is enabled.
The JIT compiler no longer skips compilation of methods longer than 1000 instructions.
--mjit-verbose and --mjit-warning output “JIT cancel” when JIT-ed code is disabled because TracePoint or GC.compact is used.

YJIT: New experimental in-process JIT compiler¶ ↑

New JIT compiler available as an experimental feature. [Feature #18229]

See this blog post introducing the project.

Disabled by default, use --yjit command-line option to enable YJIT.
Performance improvements on benchmarks based on real-world software, up to 22% on railsbench, 39% on liquid-render.
Fast warm-up times.
Limited to Unix-like x86-64 platforms for now.

Static analysis¶ ↑

RBS¶ ↑

Generics type parameters can be bounded (PR).

# `T` must be compatible with the `_Output` interface.
# `PrettyPrint[String]` is ok, but `PrettyPrint[Integer]` is a type error.
class PrettyPrint[T < _Output]
  interface _Output
    def <<: (String) -> void
  end

  attr_reader output: T

  def initialize: (T output) -> void
end

Type aliases can be generic. (PR)

# Defines a generic type `list`.
type list[T] = [ T, list[T] ]
             | nil

type str_list = list[String]
type int_list = list[Integer]

rbs collection has been introduced to manage gems’ RBSs.
Many signatures for built-in and standard libraries have been added/updated.
It includes many bug fixes and performance improvements too.

See the CHANGELOG.md for more information.

TypeProf¶ ↑

Experimental IDE support has been implemented.
Many bug fixes and performance improvements since Ruby 3.0.0.

Debugger¶ ↑

A new debugger debug.gem is bundled. debug.gem is a fast debugger implementation, and it provides many features like remote debugging, colorful REPL, IDE (VSCode) integration, and more. It replaces lib/debug.rb standard library.
rdbg command is also installed into bin/ directory to start and control debugging execution.

error_highlight¶ ↑

A built-in gem called error_highlight has been introduced. It shows fine-grained error locations in the backtrace.

Example: title = json[:article][:title]

If json is nil, it shows:

$ ruby test.rb
test.rb:2:in `<main>': undefined method `[]' for nil:NilClass (NoMethodError)

title = json[:article][:title]
            ^^^^^^^^^^

If json[:article] returns nil, it shows:

$ ruby test.rb
test.rb:2:in `<main>': undefined method `[]' for nil:NilClass (NoMethodError)

title = json[:article][:title]
                      ^^^^^^^^

This feature is enabled by default. You can disable it by using a command-line option --disable-error_highlight. See the repository in detail.

`IRB` Autocomplete and Document Display¶ ↑

The IRB now has an autocomplete feature, where you can just type in the code, and the completion candidates dialog will appear. You can use Tab and Shift+Tab to move up and down.

If documents are installed when you select a completion candidate, the documentation dialog will appear next to the completion candidates dialog, showing part of the content. You can read the full document by pressing Alt+d.

Miscellaneous changes¶ ↑

lib/objspace/trace.rb is added, which is a tool for tracing the object allocation. Just by requiring this file, tracing is started immediately. Just by Kernel#p, you can investigate where an object was created. Note that just requiring this file brings a large performance overhead. This is only for debugging purposes. Do not use this in production. [Feature #17762]
Now exceptions raised in finalizers will be printed to STDERR, unless $VERBOSE is nil. [Feature #17798]
ruby -run -e httpd displays URLs to access. [Feature #17847]
Add ruby -run -e colorize to colorize Ruby code using IRB::Color.colorize_code.