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.