Ruby Next
Make all Rubies quack like edge Ruby!
Ruby Next is a tool for supporting modern/edge CRuby features (APIs and syntax) in older versions and alternative implementations. For example, you can use pattern matching and Kernel#then
in Ruby 2.5 or mruby.
Who might be interested in Ruby Next?
- Ruby gems maintainers who want to write code using the latest Ruby version but still support older ones.
- Application developers who want to give new features a try without waiting for the final release (or, more often, for the first patch).
- Users of non-MRI implementations such as mruby, JRuby, TruffleRuby, Opal, Artichoke, Prism.
Ruby Next also aims to help the community to assess new, experimental, MRI features by making it easier to play with them.
That's why Ruby Next implements the trunk
features as fast as possible.
Links
- Ruby Next: Make old Rubies quack like a new one (RubyConf 2019)
Overview
Ruby Next consists of two parts: core and language.
Core provides polyfills for Ruby core classes APIs via Refinements. Thus, polyfills are only available in compatible runtimes (MRI, JRuby, TruffleRuby).
Language is responsible for transpiling edge Ruby syntax into older versions. It could be done programmatically or via CLI. It also could be done in runtime.
Currently, Ruby Next supports Ruby versions 2.5+ (including JRuby 9.2.8+).
Using only polyfills
First, install a gem:
# Gemfile
gem "ruby-next"
# gemspec
spec.add_dependency "ruby-next"
Then, all you need is to load the Ruby Next:
require "ruby-next"
And activate the refinement in every file where you want to use it*:
using RubyNext
Ruby Next only refines core classes if necessary; thus, this line wouldn't have any effect in the edge Ruby.
Transpiling, or using edge Ruby syntax features
Ruby Next relies on its own version of the parser gem hosted on Github Package Registry. That makes the installation process a bit more complicated than usual.
The list of supported syntax features.
Prerequisites
Currently, we rely on our custom version of Parser which is hosted on GitHub Package Registry. You must obtain an access token to use it. See the GPR docs.
Installing with Bundler
First, configure your bundler to access GPR:
bundle config --local https://rubygems.pkg.github.com/ruby-next USERNAME:ACCESS_TOKEN
Then, add to your Gemfile:
source "https://rubygems.pkg.github.com/ruby-next" do
gem "parser", "2.6.3.105"
end
gem "unparser", "~> 0.4.5"
gem "ruby-next"
NOTE: we don't add parser
and unparser
to the gem's runtime deps, 'cause they're not necessary if you only need polyfills.
gem
Installing globally via You can install ruby-next
globally by running the following commands:
gem install unparser -v "~> 0.4.5"
gem install parser -v "~> 2.6.3.100" --source "https://USERNAME:ACCESS_TOKEN@rubygems.pkg.github.com/ruby-next"
gem install ruby-next
Integrating into a gem development
We recommend pre-transpiling source code to work with older versions before releasing it.
This is how you can do that with Ruby Next:
-
Write source code using the modern/edge Ruby syntax.
-
Generate transpiled code by calling
ruby-next nextify ./lib
(e.g., before releasing or pushing to VCS).
This will produce lib/.rbnext
folder containing the transpiled files, lib/.rbnext/2.6
, lib/.rbnext/2.7
. The version in the path indicates which Ruby version is required for the original functionality. Only the source files containing new syntax are added to this folder.
NOTE: Do not edit these files manually, either run linters/type checkers/whatever against these files.
- Add the following code to your gem's entrypoint (the file that is required first and contains other
require
-s):
require "ruby-next/language/setup"
RubyNext::Language.setup_gem_load_path
The setup_gem_load_path
does the following:
- Resolves the current ruby version.
- Checks whether there are directories corresponding to the current and earlier* Ruby versions within the
.rbnext
folder. - Add the path to this directory to the
$LOAD_PATH
before the path to the gem's directory.
That's why need an entrypoint: all the subsequent require
calls will load the transpiled files instead of the original ones
due to the way feature resolving works in Ruby (scanning the $LOAD_PATH
and halting as soon as the matching file is found).
NOTE: require_relative
should be avoided due to the way we hijack the features loading mechanism.
* Ruby Next avoids storing duplicates; instead, only the code for the earlier version is created and is assumed to be used with other versions. For example, if the transpiled code is the same for Ruby 2.5 and Ruby 2.6, only the .rbnext/2.7/path/to/file.rb
is kept. That's why multiple entries are added to the $LOAD_PATH
(.rbnext/2.6
and .rbnext/2.7
in the specified order for Ruby 2.5 and only .rbnext/2.7
for Ruby 2.6).
CLI
Ruby Next ships with the command-line interface (ruby-next
) which provides the following functionality:
ruby-next nextify
— transpile file or directory into older Rubies (see, for example, the "Integrating into a gem development" section above).
It has the following interface:
$ ruby-next nextify
Usage: ruby-next nextify DIRECTORY_OR_FILE [options]
-o, --output=OUTPUT Specify output directory or file
--min-version=VERSION Specify the minimum Ruby version to support
--single-version Only create one version of a file (for the earliest Ruby version)
-V Turn on verbose mode
The behaviour depends on whether you transpile a single file or a directory:
-
When transpiling a directory, the
.rbnext
subfolder is created within the target folder with subfolders for each supported Ruby versions (e.g.,.rbnext/2.6
,.rbnext/2.7
). If you want to create only a single version (the smallest), you can also pass--single-version
flag. In that case, no version directory is created (i.e., transpiled files go into.rbnext
). -
When transpiling a file and providing the output path as a file path, only a single version is created. For example:
$ ruby-next nextify my_ruby.rb -o my_ruby_next.rb -V
Generated: my_ruby_next.rb
Runtime mode
It is also possible to transpile Ruby source code in run-time via Ruby Next.
All you need is to require "ruby-next/language/runtime"
as early as possible to hijack Kernel#require
and friends.
You can also automatically inject using RubyNext
to every* loaded file by also adding require "ruby-next/core/runtime"
.
Since the runtime mode requires Kernel monkey-patching, it should be used carefully. For example, we use it in Ruby Next tests—works perfectly. But think twice before enabling it in production.
We plan to add Bootsnap integration in the future, which would allow us to avoid monkey-patching (by relying on the bullet-proofed Bootsnap's one
* Ruby Next doesn't hijack every required file but watches only the configured directories: ./app/
, ./lib/
, ./spec/
, ./test/
(relative to the pwd
). You can configure the watch dirs:
RubyNext::Language::Runtime.watch_dirs << "path/to/other/dir"
uby-next
You can also enable runtime mode by requiring uby-next
while running a Ruby executable:
ruby -ruby-next my_ruby_script.rb
# or
RUBYOPT="-ruby-next" ruby my_ruby_script.rb
# or
ruby -ruby-next -e "puts [2, 4, 5].tally"
Contributing
Bug reports and pull requests are welcome on GitHub at https://github.com/ruby-next/ruby-next.
See also the development guide.
License
The gem is available as open source under the terms of the MIT License.