ruby-next-core 0.8.0 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bb8a0798576c2859d40a9bcc7ce9b4c5a9bcdd2560a603bdf14b897a1248edc2
-  data.tar.gz: 38f599eb8a725bb52ad7a7ae66342c3450da6906366a8d6e53304484ca60a1b5
+  metadata.gz: 6cab7345f16f61d3a35a307024885c4b9a0055bb946f473bdd5a386b27175ec2
+  data.tar.gz: c3b2004bf5cd1b9dd49d2a7892bd3e88472a632f4cdc8da310bdb56fb96171d9
 SHA512:
-  metadata.gz: abdb54f137bce953dfe24eaa29dcb35c057534821ac2dbd5a4b3092608aa88b6a2e8ac81032f86766d2eda29c70bbc0b2acd79f72dcd2490d230cd92a34af00b
-  data.tar.gz: ff4087bb6b6ecf1cc159166b0a4a8bcc650d2ef1ee315f3eeee5e8b8b1f3005ce560c4fcd7ffd5673cef206fbaf7f3fca2e0f0a594fda042b5f5178d43ea2a5b
+  metadata.gz: 4f6b3d6f64e0303e1b69fa5a99ececcf605c7413285c05feb03d9308da8449296fbea96b8779a3ac6b72dca8351ac10cd20f11161b1581ac6a60a85d951ca0d3
+  data.tar.gz: 44e5f05020cae47e13d1a89627c94d890b07daccd1e7dcf51e2e4e0eed208fca2c946e4db674f53fa0581477a368e80c73474ffc657a53f55c1e962bd3d668ba

data/CHANGELOG.md

@@ -2,6 +2,51 @@
 
 ## master
 
+## 0.10.0 (2020-09-02)
+
+- Add proposed shorthand Hash syntax. ([@palkan][])
+
+You can try it: `x = 1; y = 2; data = {x, y}`.
+
+- Add leading argument support to args forwarding. ([@palkan][])
+
+`def a(...) b(1, ...); end`.
+
+- Add `Hash#except`. ([@palkan][])
+
+`{a: 1, b: 2}.except(:a) == {b: 2}`
+
+- Add find pattern support. ([@palkan][])
+
+Now you can do: `[0, 1, 2] in [*, 1 => a, *c]`.
+
+- Add Ruby 2.2 support. ([@palkan][])
+
+With support for safe navigation operator (`&.`) and squiggly heredocs (`<<~TXT`).
+
+## 0.9.2 (2020-06-24)
+
+- Support passing rewriters to CLI. ([@sl4vr][])
+
+Use `nextify --list-rewriters` to view all available rewriters.
+Use `nextify` with `--rewrite=REWRITERS...` option to specify which particular rewriters to use.
+
+## 0.9.1 (2020-06-05)
+
+- Keep `ruby-next` version in sync with `ruby-next-core`. ([@palkan][])
+
+Require `ruby-next-core` of the same version as `ruby-next`.
+
+## 0.9.0 (2020-06-04)
+
+- Add Ruby 2.3 support. ([@palkan][])
+
+- Remove stale transpiled files when running `ruby-next nextify`. ([@palkan][])
+
+- Add Ruby 2.4 support. ([@palkan][])
+
+APIs for <2.5 must be backported via [backports][] gem. Refinements are not supported.
+
 ## 0.8.0 (2020-05-01) 🚩
 
 - Add right-hand assignment support. ([@palkan][])
@@ -178,3 +223,5 @@ p a #=> 1
 - Add `Kernel#then`. ([@palkan][])
 
 [@palkan]: https://github.com/palkan
+[backports]: https://github.com/marcandre/backports
+[@sl4vr]: https://github.com/sl4vr

data/README.md

@@ -1,5 +1,7 @@
+[![Cult Of Martians](http://cultofmartians.com/assets/badges/badge.svg)](https://cultofmartians.com/tasks/ruby-next-cli-rewriters.html#task)
 [![Gem Version](https://badge.fury.io/rb/ruby-next.svg)](https://rubygems.org/gems/ruby-next) [![Build](https://github.com/ruby-next/ruby-next/workflows/Build/badge.svg)](https://github.com/ruby-next/ruby-next/actions)
-[![JRuby Build](https://github.com/ruby-next/ruby-next/workflows/JRuby%20Build/badge.svg)](https://github.com/ruby-next/ruby-next/actions)
+[![JRuby Build](https://github.com/ruby-next/ruby-next/workflows/JRuby%20Build/badge.svg)](https://github.com/ruby-next/ruby-next/actions?query=workflow%3A%22TruffleRuby+Build%22)
+[![TruffleRuby Build](https://github.com/ruby-next/ruby-next/workflows/TruffleRuby%20Build/badge.svg)](https://github.com/ruby-next/ruby-next/actions?query=workflow%3A%22TruffleRuby+Build%22)
 
 # Ruby Next
 
@@ -17,13 +19,31 @@ Who might be interested in Ruby Next?
 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 `master` features as fast as possible.
 
+Read more about the motivation behind the Ruby Next in this post: [Ruby Next: Make all Rubies quack alike](https://evilmartians.com/chronicles/ruby-next-make-all-rubies-quack-alike).
+
 <a href="https://evilmartians.com/?utm_source=ruby-next">
 <img src="https://evilmartians.com/badges/sponsored-by-evil-martians.svg" alt="Sponsored by Evil Martians" width="236" height="54"></a>
 
-## Links
+## Posts
+
+- [Ruby Next: Make all Rubies quack alike](https://evilmartians.com/chronicles/ruby-next-make-all-rubies-quack-alike)
+
+## Talks
 
 - [Ruby Next: Make old Rubies quack like a new one](https://noti.st/palkan/j3i2Dr/ruby-next-make-old-rubies-quack-like-a-new-one) (RubyConf 2019)
 
+## Examples
+
+- Ruby gems
+  - [anyway_config](https://github.com/palkan/anyway_config)
+  - [graphql-fragment_cache](https://github.com/DmitryTsepelev/graphql-ruby-fragment_cache)
+- Rails applications
+  - [anycable_rails_demo](https://github.com/anycable/anycable_rails_demo)
+- mruby
+  - [ACLI](https://github.com/palkan/acli)
+
+_Please, submit a PR to add your project to the list!_
+
 ## Table of contents
 
 - [Overview](#overview)
@@ -38,6 +58,7 @@ That's why Ruby Next implements the `master` features as fast as possible.
   - [`ruby -ruby-next`](#uby-next)
   - [Logging & Debugging](#logging-and-debugging)
 - [RuboCop](#rubocop)
+- [Using with EOL Rubies](#using-with-eol-rubies)
 - [Proposed & edge features](#proposed-and-edge-features)
 
 ## Overview
@@ -49,8 +70,9 @@ Core provides **polyfills** for Ruby core classes APIs via Refinements (default
 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+).
-Please, [open an issue](https://github.com/ruby-next/ruby-next/issues/new/choose) if you would like us to support older Ruby versions.
+Currently, Ruby Next supports Ruby versions 2.2+, including JRuby 9.2.8+ and TruffleRuby 20.1+ (with some limitations). Support for EOL versions (<2.5) slightly differs though ([see below](#using-with-eol-rubies)).
+
+Please, [open an issue](https://github.com/ruby-next/ruby-next/issues/new/choose) or join the discussion in the existing ones if you would like us to support older Ruby versions.
 
 ## Quick start
 
@@ -119,6 +141,8 @@ The following _rule of thumb_ is recommended when choosing between refinements a
 - Using core extensions could be considered for application development (no need to think about `using RubyNext`); this approach could potentially lead to conflicts with dependencies (if these dependencies are not using refinements 🙂)
 - Use core extensions if refinements are not supported by your platform
 
+**NOTE:** _Edge_ APIs (i.e., from the Ruby's master branch) are included by default.
+
 [**The list of supported APIs.**][features_core]
 
 ## Transpiling
@@ -179,12 +203,15 @@ It has the following interface:
 ```sh
 $ ruby-next nextify
 Usage: ruby-next nextify DIRECTORY_OR_FILE [options]
-    -o, --output=OUTPUT              Specify output directory or file or stdout (use -o stdout for that)
+    -o, --output=OUTPUT              Specify output directory or file or stdout
         --min-version=VERSION        Specify the minimum Ruby version to support
         --single-version             Only create one version of a file (for the earliest Ruby version)
-        --enable-method-reference    Enable reverted method reference syntax (requires custom parser)
+        --edge                       Enable edge (master) Ruby features
+        --proposed                   Enable proposed/experimental Ruby features
         --transpile-mode=MODE        Transpiler mode (ast or rewrite). Default: ast
         --[no-]refine                Do not inject `using RubyNext`
+        --list-rewriters             List available rewriters
+        --rewrite=REWRITERS...       Specify particular Ruby features to rewrite
     -h, --help                       Print help
     -V                               Turn on verbose mode
         --dry-run                    Print verbose output without generating files
@@ -297,17 +324,17 @@ If you're using [runtime mode](#runtime-usage) a long with `setup_gem_load_path`
 
 \* 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).
 
-### Transpiled files vs. VSC vs. installing from source
+### Transpiled files vs. VCS vs. installing from source
 
 It's a best practice to not keep generated files in repositories. In case of Ruby Next, it's a `lib/.rbnext` folder.
 
-We recommend adding this folder only to the gem package (i.e., it should be added to your `spec.files`) and ignore it in your VSC (e.g., `echo ".rbnext/" >> .gitignore`). That would make transpiled files available in releases without polluting your repository.
+We recommend adding this folder only to the gem package (i.e., it should be added to your `spec.files`) and ignore it in your VCS (e.g., `echo ".rbnext/" >> .gitignore`). That would make transpiled files available in releases without polluting your repository.
 
-What if someone decides to install your gem from the VSC source? They would likely face some syntax errors due to the missing transpiled files.
+What if someone decides to install your gem from the VCS source? They would likely face some syntax errors due to the missing transpiled files.
 
 To solve this problem, Ruby Next _tries_ to transpile the source code when you call `#setup_gem_load_path`. It does this by calling `bundle exec ruby-next nextify <lib_dir> -o <next_dir>`. We make the following assumptions:
 
-- We in the Bundler context (since that's the most common way of installing gems from source).
+- We are in the Bundler context (since that's the most common way of installing gems from source).
 - Our Gemfile contains `ruby-next` gem.
 - We use [`.rbnextrc`](#CLI-configuration-file) for transpiling options.
 
@@ -372,6 +399,12 @@ RUBYOPT="-ruby-next" ruby my_ruby_script.rb
 ruby -ruby-next -e "puts [2, 4, 5].tally"
 ```
 
+**NOTE:** running Ruby scripts directly or executing code via `-e` option is not supported in TruffleRuby. You can still use `-ruby-next` to transpile required files, e.g.:
+
+```sh
+ruby -ruby-next -r my_ruby_script.rb -e "puts my_method"
+```
+
 ## Logging and debugging
 
 Ruby Next prints some debugging information when fails to load a file in the runtime mode (and fallbacks to the built-in loading mechanism).
@@ -396,6 +429,8 @@ You must set `TargetRubyVersion: next` to make RuboCop use a Ruby Next parser.
 
 Alternatively, you can load the patch from the command line by running: `rubocop -r ruby-next/rubocop ...`.
 
+We recommend using the latest RuboCop version, 'cause it has support for new nodes built-in.
+
 Also, when pre-transpiling source code with `ruby-next nextify`, we suggest ignoring the transpiled files:
 
 ```yml
@@ -406,6 +441,40 @@ AllCops:
 
 **NOTE:** you need `ruby-next` gem available in the environment where you run RuboCop (having `ruby-next-core` is not enough).
 
+## Using with EOL Rubies
+
+We currently provide support for Ruby 2.2, 2.3 and 2.4.
+
+Ruby Next itself relies on 2.5 features and contains polyfills only for version 2.5+ (and that won't change).
+Thus, to make it work with <2.5 we need to backport some APIs ourselves.
+
+The recommended way of doing this is to use [backports][] gem. You need to load backports **before Ruby Next**.
+
+When using runtime features, you should do the following:
+
+```ruby
+# first, require backports upto 2.5
+require "backports/2.5"
+# then, load Ruby Next
+require "ruby-next"
+# if you need 2.6+ APIs, add Ruby Next core_ext
+require "ruby-next/core_ext"
+# then, load runtime transpiling
+require "ruby-next/language/runtime"
+# or
+require "ruby-next/language/bootsnap"
+```
+
+To load backports while using `ruby-next nextify` command, you must configure the environment variable:
+
+```sh
+RUBY_NEXT_CORE_STRATEGY=backports ruby-next nextify lib/
+```
+
+**NOTE:** Make sure you have `backports` gem installed globally or added to your bundle (if you're using `bundle exec ruby-next ...`).
+
+**NOTE:** For Ruby 2.2, safe navigation operator (`&.`) and squiggly heredocs (`<<~TXT`) support is provided.
+
 ## Proposed and edge features
 
 Ruby Next aims to bring edge and proposed features to Ruby community before they (hopefully) reach an official Ruby release.
@@ -439,12 +508,16 @@ require "ruby-next/language/runtime"
 
 - "Endless" method definition (`def foo() = 42`) ([#16746](https://bugs.ruby-lang.org/issues/16746)).
 
-- Right-hand assignment (`13.divmod(5) => a,b`) ([#15921](https://bugs.ruby-lang.org/issues/15921))
+- Right-hand assignment (`13.divmod(5) => a,b`) ([#15921](https://bugs.ruby-lang.org/issues/15921)).
+
+- Find pattern (`[0, 1, 2] in [*, 1 => a, *c]`) ([#16828](https://bugs.ruby-lang.org/issues/16828)).
 
 ### Supported proposed features
 
 - _Method reference_ operator (`.:`) ([#13581](https://bugs.ruby-lang.org/issues/13581)).
 
+- Shorthand Hash notation (`data = {x, y}`) ([#15236](https://bugs.ruby-lang.org/issues/15236)).
+
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at [https://github.com/ruby-next/ruby-next](ttps://github.com/ruby-next/ruby-next).
@@ -470,3 +543,4 @@ The gem is available as open source under the terms of the [MIT License](https:/
 [next_parser]: https://github.com/ruby-next/parser
 [Bootsnap]: https://github.com/Shopify/bootsnap
 [rubocop]: https://github.com/rubocop-hq/rubocop
+[backports]: https://github.com/marcandre/backports

data/bin/transform

@@ -9,6 +9,7 @@ ENV["RUBY_NEXT_EDGE"] = "1"
 ENV["RUBY_NEXT_PROPOSED"] = "1"
 
 require "ruby-next/language"
+require "ruby-next/language/rewriters/runtime"
 
 contents =
   if File.exist?(ARGV[0])
@@ -17,4 +18,11 @@ contents =
     ARGV[0]
   end
 
-puts RubyNext::Language.transform(contents)
+opts =
+  if ARGV[1] && ARGV[1] == "--current"
+    {rewriters: RubyNext::Language.current_rewriters}
+  else
+    {}
+  end
+
+puts RubyNext::Language.transform(contents, **opts)

data/lib/.rbnext/2.3/ruby-next/commands/core_ext.rb

@@ -0,0 +1,167 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "pathname"
+
+module RubyNext
+  module Commands
+    class CoreExt < Base
+      using RubyNext
+
+      attr_reader :out_path, :min_version, :names, :list, :filter, :original_command
+      alias list? list
+
+      def run
+        log "Select core extensions for Ruby v#{min_version}" \
+            "#{filter ? " and matching #{filter.inspect}" : ""}"
+
+        matching_patches.then do |patches|
+          next print_list(patches) if list?
+          generate_core_ext(patches)
+        end
+      end
+
+      def parse!(args)
+        print_help = false
+        @min_version = MIN_SUPPORTED_VERSION
+        @original_command = "ruby-next core_ext #{args.join(" ")}"
+        @names = []
+        @list = false
+        @out_path = File.join(Dir.pwd, "core_ext.rb")
+
+        optparser = base_parser do |opts|
+          opts.banner = "Usage: ruby-next core_ext [options]"
+
+          opts.on("-o", "--output=OUTPUT", "Specify output file or stdout (default: ./core_ext.rb)") do |val|
+            @out_path = val
+          end
+
+          opts.on("-l", "--list", "List all available extensions") do
+            @list = true
+          end
+
+          opts.on("--min-version=VERSION", "Specify the minimum Ruby version to support") do |val|
+            @min_version = Gem::Version.new(val)
+          end
+
+          opts.on("-n", "--name=NAME", "Filter extensions by name") do |val|
+            names << val
+          end
+
+          opts.on("-h", "--help", "Print help") do
+            print_help = true
+          end
+        end
+
+        optparser.parse!(args)
+
+        if print_help
+          $stdout.puts optparser.help
+          exit 0
+        end
+
+        @filter = /(#{names.join("|")})/i unless names.empty?
+      end
+
+      private
+
+      def matching_patches
+        RubyNext::Core.patches.extensions
+          .values
+          .flatten
+          .select do |patch|
+          next if min_version && Gem::Version.new(patch.version) <= min_version
+          next if filter && !filter.match?(patch.name)
+          true
+        end
+      end
+
+      def print_list(patches)
+        grouped_patches = patches.group_by(&:version).sort_by(&:first)
+        grouped_patches.each do |(group, patches)|
+          $stdout.puts "#{group} extensions:\n"
+          $stdout.puts patches.sort_by(&:name).map { |patch| "  - #{patch.name}" }.join("\n")
+          $stdout.puts "\n"
+        end
+      end
+
+      def generate_core_ext(patches)
+        grouped_patches = patches.group_by(&:mod).sort_by { |(mod, patch)| mod.singleton_class? ? mod.inspect : mod.name }
+
+        buffer = []
+
+        buffer << "# frozen_string_literal: true\n"
+
+        buffer << generation_meta
+
+        grouped_patches.each do |mod, patches|
+          singleton = mod.singleton_class?
+          extend_name = singleton ? patches.first.singleton.name : mod.name
+          prepend_name = singleton ? "#{patches.first.singleton.name}.singleton_class" : mod.name
+
+          prepended, extended = patches.partition(&:prepend?)
+
+          prepended.map do |patch|
+            name = "RubyNext::Core::#{patch.name}"
+
+            buffer << <<-RUBY
+             module #{name}
+             #{indent_and_trim(patch.body)}
+             end
+             #{prepend_name}.prepend #{name}
+            RUBY
+
+            name
+          end
+
+          class_or_module = mod.is_a?(Class) ? "class" : "module"
+
+          buffer << "#{class_or_module} #{extend_name}"
+
+          buffer << "  class << self" if singleton
+
+          indent_size = singleton ? 4 : 2
+
+          buffer << extended.map do |patch|
+            indent_and_trim(patch.body, indent_size)
+          end.join("\n\n")
+
+          buffer << "  end" if singleton
+
+          buffer << "end\n"
+        end
+
+        contents = buffer.join("\n")
+
+        return $stdout.puts(contents) if out_path == "stdout"
+
+        unless CLI.dry_run?
+          FileUtils.mkdir_p File.dirname(out_path)
+          File.write(out_path, contents)
+        end
+
+        log "Generated: #{out_path}"
+      end
+
+      def generation_meta
+        <<-MSG
+# Generated by Ruby Next v#{RubyNext::VERSION} using the following command:
+#
+#   #{original_command}
+#
+        MSG
+      end
+
+      def indent_and_trim(src, size = 2)
+        new_src = src.dup
+        # indent code using <size> spaces
+        new_src.gsub!(/^/, " " * size)
+        # remove empty lines
+        new_src.gsub!(/^\s+$/, "")
+        # remove traling blank lines
+        new_src.delete_suffix!("\n")
+        new_src
+      end
+    end
+  end
+end