ruby-next-core 0.5.3 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9779cf5c0dea7fff2e3185f6409a7ea21287d4d4b38466e7393c2cebb97d128a
-  data.tar.gz: b1ef29ce986cbaa595e3a5e257674869d3e7d5842185385728d5f70eb81996fc
+  metadata.gz: 79dd9f615898df70de6648be3805f3c0da92c80e22cd8e2cffc109958ec0811b
+  data.tar.gz: 7ed7e923ca5f2b3f6eaf27135a722f2a23e868fe65bce32f6700e74867e6d62c
 SHA512:
-  metadata.gz: 26de1a278bceaa3423b21e4f7b1c6c791e9fe3e42d319864fd0041d29f86b5946095ea42e03811169aa41be1220e4726ec57a24f19f939ec8fb197662505f2f1
-  data.tar.gz: 9ef7af94930ac374f7732e1ff71b57b4ee135be8609e0343314117f362af994c177dfa2541cfcc0802029320341e3c509b11ef8a2fdf0ab0e5d80451e902d803
+  metadata.gz: e16c8585ed3e8b5b23ccc5a7b79b80d6da6e96f539c008bc9e781e523c8451fec954b6f0e0948056de9feb231b30dd62989c26aea77890afc2037d91c0a4028a
+  data.tar.gz: b2d0d3891032b51a22ffccc600410d250da89d34332cc4797fc4e216f13ab82024520c262e43788660e041937c081a254ae7597e93e686fc23fcbd2d9df37e0c

data/CHANGELOG.md

@@ -2,6 +2,70 @@
 
 ## master
 
+## 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][])
+
+It is real: `13.divmod(5) => a, b`.
+
+- Add endless methods support. ([@palkan][])
+
+Now you can write `def foo() = :bar`.
+
+## 0.7.0 (2020-04-29)
+
+- Try to auto-transpile the source code on load in `.setup_gem_load_path` if transpiled files are missing. ([@palkan][])
+
+This would make it possible to install gems from source if transpiled files do not exist in the repository.
+
+- Use`./.rbnextrc` to define CLI args. ([@palkan][])
+
+You can define CLI options in the configuration file to re-use them between environments or
+simply avoid typing every time:
+
+```yml
+# .rbnextrc
+nextify: |
+  --transpiler-mode=rewrite
+  --edge
+```
+
+- Add `--dry-run` option to CLI. ([@palkan][])
+
+- Raise `SyntaxError` when parsing fails. ([@palkan][])
+
+Previously, we let Parser to raise its `Parser::SyntaxError` but some exceptions
+are not reported by Parser and should be handled by transpiler (and we raised `SyntaxError` in that case, as MRI does).
+
+This change unifies the exceptions raised during transpiling.
+
+## 0.6.0 (2020-04-23)
+
+- Changed the way edge/proposed features are activated. ([@palkan][])
+
+Use `--edge` or `--proposed` flags for `ruby-next nextify` or
+`require "ruby-next/language/{edge,proposed}"` in your code.
+
+See more in the [Readme](./README.md#proposed-and-edge-features).
+
+- Updated RuboCop integration. ([@palkan][])
+
+Make sure you use `TargetRubyVersion: next` in your RuboCop configuration.
+
+- Upgraded to `ruby-next-parser` for edge features. ([@palkan][])
+
+It's no longer needed to use Parser gem from Ruby Next package registry.
+
 ## 0.5.3 (2020-03-25)
 
 - Enhance logging. ([@palkan][])
@@ -124,3 +188,4 @@ p a #=> 1
 - Add `Kernel#then`. ([@palkan][])
 
 [@palkan]: https://github.com/palkan
+[backports]: https://github.com/marcandre/backports

data/README.md

@@ -1,5 +1,6 @@
 [![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,16 +18,33 @@ 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)
+- mruby
+  - [ACLI](https://github.com/palkan/acli)
+
+_Please, submit a PR to add your project to the list!_
+
 ## Table of contents
 
 - [Overview](#overview)
+- [Quick Start](#quick-start)
 - [Polyfills](#using-only-polyfills)
 - [Transpiling](#transpiling)
   - [Modes](#transpiler-modes)
@@ -37,6 +55,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
@@ -48,8 +67,34 @@ 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.3+, 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
+
+The quickest way to start experimenting with Ruby Next is to install the gem and run a sample script. For example:
+
+```sh
+# Install Ruby Next globally
+$ gem install ruby-next
+
+# Call ruby with -ruby-next flag
+$ ruby -ruby-next -e "
+def greet(val) =
+  case val
+    in hello: hello if hello =~ /human/i
+      '🙂'
+    in hello: 'martian'
+      '👽'
+    end
+
+greet(hello: 'martian') => greeting
+puts greeting
+"
+
+=> 👽
+```
 
 ## Using only polyfills
 
@@ -79,7 +124,7 @@ using RubyNext
 
 Ruby Next only refines core classes if necessary; thus, this line wouldn't have any effect in the edge Ruby.
 
-**NOTE:** Even if the runtime already contains a monkey-patch with the backported functionality, we consider the method as _dirty_ and activate the refinement for it. Thus, you always have a predictable behaviour. That's why we recommend using refinements for gems development.
+**NOTE:** Even if the runtime already contains a monkey-patch with the backported functionality, we consider the method as _dirty_ and activate the refinement for it. Thus, you always have predictable behaviour. That's why we recommend using refinements for gems development.
 
 Alternatively, you can go with monkey-patches. Just add this line:
 
@@ -93,6 +138,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:** TruffleRuby doesn't fully support refinements (refining modules is not supported as of v20.1.0).
+
 [**The list of supported APIs.**][features_core]
 
 ## Transpiling
@@ -124,7 +171,7 @@ gem install ruby-next
 
 Ruby Next currently provides two different modes of generating transpiled code: _AST_ and _rewrite_.
 
-In the AST mode, we parse the source code into AST, modifies this AST and **generate a new code from AST** (using [unparser][unparser]). Thus, the transpiled code being identical in terms of functionality has a different formatting.
+In the AST mode, we parse the source code into AST, modifies this AST and **generate a new code from AST** (using [unparser][unparser]). Thus, the transpiled code being identical in terms of functionality has different formatting.
 
 In the rewrite mode, we apply changes to the source code itself, thus, keeping the original formatting of the unaffected code (in a similar way to RuboCop's autocorrect feature).
 
@@ -138,6 +185,8 @@ You can change the transpiler mode:
 - Via environmental variable `RUBY_NEXT_TRANSPILE_MODE=rewrite`.
 - Via CLI option ([see below](#cli)).
 
+**NOTE:** For the time being, Unparser [doesn't support](https://github.com/mbj/unparser/pull/142) new Ruby 2.7 AST nodes, so we always use rewrite mode in Ruby 2.7+.
+
 ## CLI
 
 Ruby Next ships with the command-line interface (`ruby-next`) which provides the following functionality:
@@ -159,6 +208,7 @@ Usage: ruby-next nextify DIRECTORY_OR_FILE [options]
         --[no-]refine                Do not inject `using RubyNext`
     -h, --help                       Print help
     -V                               Turn on verbose mode
+        --dry-run                    Print verbose output without generating files
 ```
 
 The behaviour depends on whether you transpile a single file or a directory:
@@ -190,6 +240,7 @@ Usage: ruby-next core_ext [options]
     -n, --name=NAME                  Filter extensions by name
     -h, --help                       Print help
     -V                               Turn on verbose mode
+        --dry-run                    Print verbose output without generating files
 ```
 
 The most common use-case is to backport the APIs required by pattern matching. You can do this, for example,
@@ -216,7 +267,21 @@ $ ruby-next core_ext -l --name=filter --name=deconstruct
   - StructDeconstruct
 ```
 
-### Integrating into a gem development
+### CLI configuration file
+
+You can define CLI options in the `.rbnextrc` file located in the root of your project to avoid adding them every time you run `ruby-next`.
+
+Configuration file is a YAML with commands as keys and options as multiline strings:
+
+```yml
+# ./.rbnextrc
+
+nextify: |
+  --transpiler-mode=rewrite
+  --edge
+```
+
+## Integrating into a gem development
 
 We recommend _pre-transpiling_ source code to work with older versions before releasing it.
 
@@ -253,6 +318,24 @@ 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. 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 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 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 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.
+
+If the command fails we warn the end user.
+
+This feature, _auto-transpiling_, is **disabled** by default (will likely be enabled in future versions). You can enable it by calling `RubyNext::Language.setup_gem_load_path(transpile: true)`.
+
 ## Runtime usage
 
 It is also possible to transpile Ruby source code in run-time via Ruby Next.
@@ -292,10 +375,12 @@ To enable this integration, add the following line after the `require "bootsnap/
 require "ruby-next/language/bootsnap"
 ```
 
-**NOTE:** there is no way to invalidate the cache when you upgrade Ruby Next (e.g., due to the bug fixes), so you should do this manually.
+**NOTE:** There is no way to invalidate the cache when you upgrade Ruby Next (e.g., due to the bug fixes), so you should do this manually.
 
 ## `uby-next`
 
+_This is [not a typo](https://github.com/ruby-next/ruby-next/pull/8), that’s the way `ruby -ruby-next` works: it’s equal to `ruby -r uby-next`, and [`uby-next.rb`](https://github.com/ruby-next/ruby-next/blob/master/lib/uby-next.rb) is a special file that activates the runtime mode._
+
 You can also enable runtime mode by requiring `uby-next` while running a Ruby executable:
 
 ```sh
@@ -308,6 +393,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).
@@ -328,7 +419,7 @@ require:
   - ruby-next/rubocop
 ```
 
-**NOTE:** You should use `TargetRubyVersion: 2.7`.
+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 ...`.
 
@@ -340,57 +431,78 @@ AllCops:
     - 'lib/.rbnext/**/*'
 ```
 
-## Proposed and edge features
+**NOTE:** you need `ruby-next` gem available in the environment where you run RuboCop (having `ruby-next-core` is not enough).
 
-Ruby Next aims to bring edge and proposed features to Ruby community before they (hopefully) reach an official Ruby release.
-This includes:
+## Using with EOL Rubies
 
-- Features already merged to [master](https://github.com/ruby/ruby) (_edge_)
-- Features proposed in [Ruby bug tracker](https://bugs.ruby-lang.org/) (_proposed_)
-- Features once merged to master but got reverted.
+We currently provide support for Ruby 2.3 and 2.4. Work on 2.2 is in progress.
 
-These features require a [custom parser](#using-ruby-next-parser).
+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.
 
-Currently, the only such feature is the [_method reference_ operator](https://bugs.ruby-lang.org/issues/13581):
+The recommended way of doing this is to use [backports][] gem. You need to load backports **before Ruby Next**.
 
-- Add `--enable-method-reference` option to `nextify` command when using CLI.
-- OR add it programmatically when using a runtime mode (see [example](https://github.com/ruby-next/ruby-next/blob/master/default.mspec)).
-- OR set `RUBY_NEXT_ENABLE_METHOD_REFERENCE=1` environment variable (works with CLI as well).
+When using runtime features, you should do the following:
 
-### Prerequisites
+```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"
+```
 
-Our own version of [parser][next_parser] gem is hosted on Github Package Registry. That makes the installation process a bit more complicated than usual.
+To load backports while using `ruby-next nextify` command, you must configure the environment variable:
 
-You must obtain an access token to use it. See the [GPR docs](https://help.github.com/en/github/managing-packages-with-github-package-registry/configuring-rubygems-for-use-with-github-package-registry#authenticating-to-github-package-registry).
+```sh
+RUBY_NEXT_CORE_STRATEGY=backports ruby-next nextify lib/
+```
 
-### Installing with Bundler
+**NOTE:** Make sure you have `backports` gem installed globally or added to your bundle (if you're using `bundle exec ruby-next ...`).
 
-First, configure your bundler to access GPR:
+## Proposed and edge features
 
-```sh
-bundle config --local https://rubygems.pkg.github.com/ruby-next USERNAME:ACCESS_TOKEN
-```
+Ruby Next aims to bring edge and proposed features to Ruby community before they (hopefully) reach an official Ruby release.
+This includes:
+
+- Features already merged to [master](https://github.com/ruby/ruby) (_edge_)
+- Features proposed in [Ruby bug tracker](https://bugs.ruby-lang.org/) (_proposed_)
+- Features once merged to master but got reverted.
+
+These features are disabled by default, you must opt-in in one of the following ways:
 
-Then, add to your Gemfile:
+- Add `--edge` or `--proposed` option to `nextify` command when using CLI.
+- Enable programmatically when using a runtime mode:
 
 ```ruby
-source "https://rubygems.pkg.github.com/ruby-next" do
-  gem "parser", "~> 2.7.0.100", "< 2.7.1"
-end
+# It's important to load language module first
+require "ruby-next/language"
 
-gem "ruby-next"
+require "ruby-next/language/edge"
+# or
+require "ruby-next/language/proposed"
+
+# and then activate the runtime mode
+require "ruby-next/language/runtime"
+# or require "ruby-next/language/bootsnap"
 ```
 
-**NOTE:** we don't add `parser` and `unparser` to the gem's runtime deps, 'cause they're not necessary if you only need polyfills.
+- Set `RUBY_NEXT_EDGE=1` or `RUBY_NEXT_PROPOSED=1` environment variable.
 
-### Installing globally via `gem`
+### Supported edge features
 
-You can install `ruby-next` globally by running the following commands:
+- "Endless" method definition (`def foo() = 42`) ([#16746](https://bugs.ruby-lang.org/issues/16746)).
 
-```sh
-gem install parser -v "~> 2.7.0.100" -v "< 2.7.1" --source "https://USERNAME:ACCESS_TOKEN@rubygems.pkg.github.com/ruby-next"
-gem install ruby-next
-```
+- Right-hand assignment (`13.divmod(5) => a,b`) ([#15921](https://bugs.ruby-lang.org/issues/15921))
+
+### Supported proposed features
+
+- _Method reference_ operator (`.:`) ([#13581](https://bugs.ruby-lang.org/issues/13581)).
 
 ## Contributing
 
@@ -417,3 +529,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

@@ -5,11 +5,11 @@ $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
 
 require "bundler/setup"
 
-require "ruby-next/language"
+ENV["RUBY_NEXT_EDGE"] = "1"
+ENV["RUBY_NEXT_PROPOSED"] = "1"
 
-# optional parsers
-require "ruby-next/language/rewriters/method_reference"
-RubyNext::Language.rewriters << RubyNext::Language::Rewriters::MethodReference
+require "ruby-next/language"
+require "ruby-next/language/rewriters/runtime"
 
 contents =
   if File.exist?(ARGV[0])
@@ -18,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/ruby-next.rb

@@ -11,10 +11,10 @@ module RubyNext
 
   # Defines last minor version for every major version
   LAST_MINOR_VERSIONS = {
-    2 => 7
+    2 => 8
   }.freeze
 
-  LATEST_VERSION = [2, 7].freeze
+  LATEST_VERSION = [2, 8].freeze
 
   class << self
     def next_version(version = RUBY_VERSION)
@@ -34,5 +34,6 @@ module RubyNext
   end
 
   require_relative "ruby-next/core"
+  require_relative "ruby-next/core_ext" if RubyNext::Core.core_ext?
   require_relative "ruby-next/logging"
 end