ruby-next 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6cc67691b20d3fa1a528a3f42d306f634b4b23aa8d5d876c4441e5cfdc08bbd9
-  data.tar.gz: ba3efeed90aefc8ab2f50979792445e5dae7dc3447715bdc38155889459b8807
+  metadata.gz: 6424a38e36c431e8c6c976ac4a0230c4a212ec125ad849ceff36a7a50ce38733
+  data.tar.gz: 736af6cc9b1d2ad462473706d84a1be8d579e5c80f7a7cf0a04a481a8d268a15
 SHA512:
-  metadata.gz: 7fd55f852c960fe4230abb6ebd512bd0b22b084659486484bfc45b3b7ee987ff77fcc9ab5932e880175063ea492bb746dc88d2e0a230fd77b9dfee78b275d88f
-  data.tar.gz: 25c136bb7761113535006f1de10fe34fafd69520c633b7693b59afca63eb7b6b64593529f80c61b494325c3a6bd0864bfd30a011502dcbd4ff41fb54911d0f4e
+  metadata.gz: 46f0a20049218e02c7d7767da662afbdabb77fb69fad18647e0e1418f9ab09da52a9c558eaeb65ea2e6516a245656f2a6f3e84a5db28d634b9acd20742507388
+  data.tar.gz: a0fe8a798e2ad64273321650959d30ef4b259349d8c0db451e2c6392ace695aef5c813c3167315b76d57f8041c792f8c49bfc29988803091fb0f8198b5d6617e

data/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 ## master
 
+## 0.5.0 (2020-03-20)
+
+- Add `rewrite` transpiler mode. ([@palkan][])
+
+Add support for rewriting the source code instead of rebuilding it from scratch to
+preserve the original layout and improve the debugging experience.
+
 ## 0.4.0 (2020-03-09)
 
 - Optimize pattern matching transpiled code. ([@palkan][])
@@ -67,7 +74,7 @@ p a #=> 1
 
 - Support hash pattern in array and vice versa. ([@palkan][])
 
-- Handle multile `-e` in `uby-next`. ([@palkan][])
+- Handle multiple `-e` in `uby-next`. ([@palkan][])
 
 ## 0.1.0 (2019-11-16)
 

data/LICENSE.txt

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2019 Vladimir Dementyev
+Copyright (c) 2019-2020 Vladimir Dementyev
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/README.md

@@ -24,6 +24,19 @@ That's why Ruby Next implements the `master` features as fast as possible.
 
 - [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)
 
+## Table of contents
+
+- [Overview](#overview)
+- [Polyfills](#using-only-polyfills)
+- [Transpiling](#transpiling)
+  - [Modes](#transpiler-modes)
+  - [CLI](#cli)
+  - [Using in gems](#integrating-into-a-gem-development)
+  - [Runtime usage](#runtime-usage)
+  - [Bootsnap integration](#using-with-bootsnap)
+  - [`ruby -ruby-next`](#uby-next)
+- [Proposed & edge features](#proposed-and-edge-features)
+
 ## Overview
 
 Ruby Next consists of two parts: **core** and **language**.
@@ -75,14 +88,16 @@ require "ruby-next/core_ext"
 The following _rule of thumb_ is recommended when choosing between refinements and monkey-patches:
 
 - Use refinements for libraries development (to avoid conflicts with others code)
-- Using core extensions could be considered for application development (no need to think about `using RubyNext`); this approach could potentially lead to conflicts with dependendices (if these dependencies are not using refinements 🙂)
+- 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
 
 [**The list of supported APIs.**][features_core]
 
-## Transpiling, or using edge Ruby syntax features
+## Transpiling
+
+Ruby Next allows you to transpile\* edge Ruby syntax to older versions.
 
-Ruby Next transpiler relies on two libraries: [parser][] and [unparser][].
+Transpiler relies on two libraries: [parser][] and [unparser][].
 
 **NOTE:** The "official" parser gem only supports the latest stable Ruby version, while Ruby Next aims to support edge and experimental Ruby features. To enable them, you should use our version of Parser (see [instructions](#using-ruby-next-parser) below).
 
@@ -103,40 +118,23 @@ gem install ruby-next
 
 [**The list of supported syntax features.**][features_syntax]
 
-### Integrating into a gem development
+### Transpiler modes
 
-We recommend _pre-transpiling_ source code to work with older versions before releasing it.
+Ruby Next currently provides two different modes of generating transpiled code: _AST_ and _rewrite_.
 
-This is how you can do that with Ruby Next:
+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.
 
-- Write source code using the modern/edge Ruby syntax.
+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).
 
-- Generate transpiled code by calling `ruby-next nextify ./lib` (e.g., before releasing or pushing to VCS).
+By default, we use the AST mode. That could likely change in the future when we collect enough feedback on the rewrite mode and fix potential bugs.
 
-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.
+The main benefit of the rewrite mode is that it preserves the original code line numbers and layout, which is especially useful in debugging.
 
-**NOTE:** Do not edit these files manually, either run linters/type checkers/whatever against these files.
+You can change the transpiler mode:
 
-- Add the following code to your gem's _entrypoint_ (the file that is required first and contains other `require`-s):
-
-```ruby
-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).
+- From code by setting `RubyNext::Language.mode = :ast` or `RubyNext::Language.mode = :rewrite`.
+- Via environmental variable `RUBY_NEXT_TRANSPILE_MODE=rewrite`.
+- Via CLI option ([see below](#cli)).
 
 ## CLI
 
@@ -155,6 +153,7 @@ Usage: ruby-next nextify DIRECTORY_OR_FILE [options]
         --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)
+        --transpile-mode=MODE        Transpiler mode (ast or rewrite). Default: ast
         --[no-]refine                Do not inject `using RubyNext`
     -h, --help                       Print help
     -V                               Turn on verbose mode
@@ -191,7 +190,7 @@ Usage: ruby-next core_ext [options]
     -V                               Turn on verbose mode
 ```
 
-The most common usecase is to backport the APIs required by pattern matching. You can do this, for example,
+The most common use-case is to backport the APIs required by pattern matching. You can do this, for example,
 by including only monkey-patches containing the `"deconstruct"` in their names:
 
 ```sh
@@ -215,7 +214,42 @@ $ ruby-next core_ext -l --name=filter --name=deconstruct
   - StructDeconstruct
 ```
 
-## Runtime mode
+### 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):
+
+```ruby
+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).
+
+## Runtime usage
 
 It is also possible to transpile Ruby source code in run-time via Ruby Next.
 
@@ -270,20 +304,23 @@ RUBYOPT="-ruby-next" ruby my_ruby_script.rb
 ruby -ruby-next -e "puts [2, 4, 5].tally"
 ```
 
-## Unofficial/experimental features
+## Proposed and edge features
 
-Ruby Next also provides support for some features not-yet-merged into Ruby master (or reverted).
+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 require a [custom parser](#using-ruby-next-parser).
 
-Currenly, the only such feature is the [_method reference_ operator](https://bugs.ruby-lang.org/issues/13581):
+Currently, the only such feature is the [_method reference_ operator](https://bugs.ruby-lang.org/issues/13581):
 
 - 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).
 
-## Using Ruby Next parser
-
 ### Prerequisites
 
 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.

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ruby-next
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Vladimir Dementyev
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2020-03-09 00:00:00.000000000 Z
+date: 2020-03-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ruby-next-core
@@ -30,14 +30,14 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 2.7.0.0
+        version: 2.7.0.5
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 2.7.0.0
+        version: 2.7.0.5
 - !ruby/object:Gem::Dependency
   name: unparser
   requirement: !ruby/object:Gem::Requirement