ruby-next-core 0.15.3 → 1.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6020fe263af1a0313e82b5633c45ee76950e7d39bd1f4e70f9d2613eb6ba3fec
-  data.tar.gz: 3a1c6da894f68e5e703f0515239bf342852d45f4f5672f68f8fe4011a0e76c57
+  metadata.gz: 5ad6cea22baa599e5a6edeb4fdda1fb7c9bd0b0d5617fb01cf4450374c7d9443
+  data.tar.gz: fa39e7d51cdf70c32dc2067000023e42dbe3b23bd1d8bf520e06a3a028d63b8d
 SHA512:
-  metadata.gz: dffe0bf9d32e02cd71aee8f5818d4413a62d96c8d595706c476bee2990823cf960240162b79d51d62036d2bb4a0076b46cba5af93c58760064aae165a82cd6e4
-  data.tar.gz: 22879525ffbbbd38921b096ef909ad79d5a87d726dae39f6a108aea2dc82ae5605e6a8e1bd9a190689e0a5da66fc897c6d8d22590f9a237416cd9a79aca43a38
+  metadata.gz: e7df787bfa90d036bbd45c7bd2dbc85f3513d922b3606dfde12ade0196f7ccb6789aba263d407fc012c7b4625d38b4aa6d7df05a5ac4e784b3b9cfc5db356b0f
+  data.tar.gz: a4c364d32b19003c219670096dd6420d415663445d68deb7e92c8d9763cc705884e7ab7e43fed81c6c084450f6a32e14bd8b50f24629256cb064c84a8bb87583

data/CHANGELOG.md

@@ -2,6 +2,38 @@
 
 ## master
 
+## 1.0.1 (2024-01-28)
+
+- Fix using Data with inheritance (`class X < Data.define(...)`). ([@palkan][])
+
+## 1.0.0 🎄
+
+- Add `it` block parameter support. ([@palkan][])
+
+- Deprecate AST transpiling mode. ([@palkan][])
+
+- Add `Data` backport. ([@palkan][], [@saturnflyer][])
+
+- Add `Time#deconstruct_keys` support. ([@palkan][])
+
+- Add anonymous rest and keyword rest arguments forwarding support (`def foo(*, **); bar(*, **) end`). ([@palkan][])
+
+- Add `MatchData#{deconstruct,deconstruct_keys}` and `#named_captures(symbolize_names: true)` support. ([@palkan][])
+
+- Add stats to `nextify`. ([@palkan][])
+
+- Add text rewriters and `--import-rewriter` option to `nextify`. ([@palkan][])
+
+- Use `.rbnextrc` arguments for runtime transpiling and auto-transpiling gems. ([@palkan][])
+
+- Stop testing Ruby <2.4. ([@palkan][])
+
+- Extract `require-hooks`. ([@palkan][])
+
+- Support passing --overwrite to CLI. ([@prog-supdex][])
+
+Use `nextify original_file --single-version --overwrite` to overwrite the original file without create new one.
+
 ## 0.15.3 (2022-10-16)
 
 - Fix handling nested const patterns. ([@palkan][])
@@ -364,3 +396,5 @@ p a #=> 1
 [backports]: https://github.com/marcandre/backports
 [@sl4vr]: https://github.com/sl4vr
 [@skryukov]: https://github.com/skryukov
+[@prog-supdex]: https://github.com/prog-supdex
+[@saturnflyer]: https://github.com/saturnflyer

data/README.md

@@ -14,11 +14,14 @@ 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][], [RubyMotion][], [Artichoke][], [Prism][].
+- **Users of non-MRI implementations** such as [mruby][], [JRuby][], [TruffleRuby][], [Natalie][], [Opal][], [RubyMotion][], [Artichoke][], [Prism][].
+- **Ruby syntax enthusiasts** who want to experiment with [custom syntax extensions](#custom-syntax-rewriters) 👩‍🔬👨‍🔬.
 
 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.
 
+See also a companion library (extracted from Ruby Next) that provides **code loading hooks** for your needs—[require-hooks][require-hooks].
+
 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).
 
 <table style="border:none;">
@@ -60,14 +63,13 @@ _Please, submit a PR to add your project to the list!_
 ## Table of contents
 
 - [Overview](#overview)
-- [Quick Start](#quick-start)
+- [Quick start](#quick-start)
 - [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)
   - [Logging & Debugging](#logging-and-debugging)
 - [RuboCop](#rubocop)
@@ -75,6 +77,7 @@ _Please, submit a PR to add your project to the list!_
 - [Using with Pry](#pry)
 - [Using with EOL Rubies](#using-with-eol-rubies)
 - [Proposed & edge features](#proposed-and-edge-features)
+- [Custom syntax rewriters](#custom-syntax-rewriters)
 - [Known limitations](#known-limitations)
 
 ## Overview
@@ -86,9 +89,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.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)).
+Currently, Ruby Next supports Ruby versions 2.3+, including JRuby 9.2.8+ and TruffleRuby 20.1+ (with some limitations). Support for older versions (<2.5) slightly differs though ([see below](#using-with-eol-rubies)). Versions between 2.0 and 2.3 may work but we no longer test against them.
 
-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.
+Please [open an issue](https://github.com/ruby-next/ruby-next/issues/new/choose) or join the discussion in the existing issues if you would like us to support older Ruby versions.
 
 ## Quick start
 
@@ -100,15 +103,16 @@ $ gem install ruby-next
 
 # Call ruby with -ruby-next flag
 $ ruby -ruby-next -e "
-def greet(val) =
-  case val
+greet = proc do
+  case it
     in hello: hello if hello =~ /human/i
       '🙂'
     in hello: 'martian'
       '👽'
     end
+end
 
-puts greet(hello: 'martian')
+puts greet.call(hello: 'martian')
 "
 
 => 👽
@@ -123,12 +127,12 @@ First, install a gem:
 gem "ruby-next-core"
 
 # gemspec
-spec.add_dependency "ruby-next-core"
+spec.add_dependency "ruby-next-core", "~> 1.0"
 ```
 
-**NOTE:** we use the different _distribution_ gem, `ruby-next-core`, to provide zero-dependency, polyfills-only version.
+**NOTE:** we use a different gem for _distribution_, `ruby-next-core`, to provide a zero-dependency, polyfills-only version.
 
-Then, all you need is to load the Ruby Next:
+Then, all you need is to load Ruby Next:
 
 ```ruby
 require "ruby-next"
@@ -140,9 +144,9 @@ 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.
+Ruby Next only refines core classes if necessary; thus, this line wouldn't have any effect in 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 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 gem development.
 
 Alternatively, you can go with monkey-patches. Just add this line:
 
@@ -152,7 +156,7 @@ 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)
+- Use refinements for library 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 dependencies (if these dependencies are not using refinements 🙂)
 - Use core extensions if refinements are not supported by your platform
 
@@ -160,6 +164,16 @@ The following _rule of thumb_ is recommended when choosing between refinements a
 
 [**The list of supported APIs.**][features_core]
 
+### Data backport
+
+Ruby 3.2 has introduced a new core class—[Data](https://bugs.ruby-lang.org/issues/16122). Ruby Next provides a backport functionality which is automatically activated when you `require "ruby-next"` **if and only if the constant is undefined**. If you want to use a custom backport, make sure you loaded it first.
+
+If you want to opt-out from loading Data backport, you must set the `RUBY_NEXT_DISABLE_DATA` env variable to `true`.
+
+#### Known limitations
+
+Currently, passing Hash as a last positional argument to `Data.new` is not supported in Ruby <3.0 (due to the difference in keyword arguments handling). We recommend always using keyword arguments when initializing Data objects.
+
 ## Transpiling
 
 Ruby Next allows you to transpile\* edge Ruby syntax to older versions.
@@ -172,10 +186,10 @@ Installation:
 
 ```ruby
 # Gemfile
-gem "ruby-next"
+gem "ruby-next", "~> 1.0"
 
 # gemspec
-spec.add_dependency "ruby-next"
+spec.add_dependency "ruby-next", "~> 1.0"
 ```
 
 ```sh
@@ -187,21 +201,11 @@ gem install ruby-next
 
 ### Transpiler modes
 
-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 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).
+Since v1.0, Ruby Next only support the _rewrite_ mode, i.e., the code transformations are applied directly to the original source code. This allows us to keep formatting as close as possible to the original code.
 
 The main benefit of the rewrite mode is that it preserves the original code line numbers and layout, which is especially useful in debugging.
 
-By default, we use the rewrite mode. If you found a bug with rewrite mode which is not reproducible in the AST mode, please, let us know.
-
-You can change the transpiler mode:
-
-- From code by setting `RubyNext::Language.mode = :ast` or `RubyNext::Language.mode = :rewrite`.
-- Via environmental variable `RUBY_NEXT_TRANSPILE_MODE=ast`.
-- Via CLI option ([see below](#cli)).
+The legacy AST mode (regenerating source code from the modified abstract syntax tree) is deprecated (though still supported).
 
 ## CLI
 
@@ -219,12 +223,13 @@ Usage: ruby-next nextify DIRECTORY_OR_FILE [options]
     -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)
+        --overwrite                  Overwrites the original file with one version of --single-version (works only with --single-version or --rewrite)
         --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
+        --import-rewriter=PATHS...   Specify the paths to custom rewriters to load
     -h, --help                       Print help
     -V                               Turn on verbose mode
         --dry-run                    Print verbose output without generating files
@@ -232,7 +237,7 @@ Usage: ruby-next nextify DIRECTORY_OR_FILE [options]
 
 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`, `.rbnext/3.0`, etc.). 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 directory, the `.rbnext` subfolder is created within the target folder with subfolders for each supported Ruby versions (e.g., `.rbnext/2.7`, `.rbnext/3.1`, `.rbnext/3.4`, etc.). 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:
 
@@ -298,10 +303,12 @@ Configuration file is a YAML with commands as keys and options as multiline stri
 # ./.rbnextrc
 
 nextify: |
-  --transpiler-mode=rewrite
+  --min-version=2.7
   --edge
 ```
 
+**NOTE:** The `nextify` section is also used by auto-transpiling when installing the gem from source and by runtime transpiling.
+
 ## Integrating into a gem development
 
 We recommend _pre-transpiling_ source code to work with older versions before releasing it.
@@ -361,19 +368,21 @@ This feature, _auto-transpiling_, is **disabled** by default (will likely be ena
 
 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"`.
+All you need is to `require "ruby-next/language/runtime"` to hijack `Kernel#require` and friends before loading the files you want to transpile. 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.
+Runtime mode is backed by [require-hooks][require-hooks]—a standalone gem which has been extracted from Ruby Next. Depending on the current runtime, it picks an optimal strategy for hijacking the loading mechanism. Please, refer to its documentation for more details.
 
-Consider using [Bootsnap](#using-with-bootsnap) integration, 'cause its monkey-patching has been bullet-proofed 😉.
+\* Ruby Next doesn't hijack every required file but only the configured directories: `./app/`, `./lib/`, `./spec/`, `./test/` (relative to the `pwd`). It also excludes the `./vendor/bundle` directory by default.
 
-\* 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:
+You can customize target files via the `include_patterns` and `exclude_patterns` configuration options:
 
 ```ruby
-RubyNext::Language.watch_dirs << "path/to/other/dir"
+RubyNext::Language.include_patterns << "path/to/other/dir/*.rb"
+RubyNext::Language.exclude_patterns << "path/to/other/dir/subdir/*"
 ```
 
+**NOTE:** Directories MUST be configured before requiring `ruby-next/language/runtime`.
+
 ### Eval & similar
 
 By default, we do not hijack `Kernel.eval` and similar methods due to some limitations (e.g., there is no easy and efficient way to access the caller's scope, or _binding_, and some evaluations relies on local variables).
@@ -384,20 +393,6 @@ If you want to support transpiling in `eval`-like methods, opt-in explicitly by
 using RubyNext::Language::Eval
 ```
 
-## Using with Bootsnap
-
-[Bootsnap][] is a great tool to speed-up your application load and it's included into the default Rails Gemfile. It patches Ruby mechanism of loading source files to make it possible to cache the intermediate representation (_iseq_).
-
-Ruby Next provides a specific integration which allows to add a transpiling step to this process, thus making the transpiler overhead as small as possible, because the cached and **already transpiled** version is used if no changes were made.
-
-To enable this integration, add the following line after the `require "bootsnap/setup"`:
-
-```ruby
-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.
-
 ## `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._
@@ -490,7 +485,7 @@ pry -ruby-next/pry
 
 ## Using with EOL Rubies
 
-We currently provide support for Ruby 2.2, 2.3 and 2.4.
+We currently provide support for Ruby 2.3+.
 
 **NOTE:** By "support" here we mean using `ruby-next` CLI and runtime transpiling. Transpiled code may run on Ruby 2.0+.
 
@@ -557,13 +552,85 @@ require "ruby-next/language/runtime"
 
 ### Supported edge features
 
-It's too early, Ruby 3.1 has just been released. See its features in the [supported features list](./SUPPORTED_FEATURES.md).
+- Implicit `it` block parameter ([#19890](https://bugs.ruby-lang.org/issues/18980)).
 
 ### Supported proposed features
 
 - _Method reference_ operator (`.:`) ([#13581](https://bugs.ruby-lang.org/issues/13581)).
 - Binding non-local variables in pattern matching (`42 => @v`) ([#18408](https://bugs.ruby-lang.org/issues/18408)).
 
+## Custom syntax rewriters
+
+Wonder what would happen if Ruby get a null coalescing operator (`??=`) or some other syntactic feature you want to try out? Ruby Next is here to help you!
+
+Ruby Next allows you to write your own syntax rewriters. Full-featured rewriters (used by Ruby Next itself) operate on AST and usually require parser modifications. However, we also support text-based rewriters which can be used to experiment with new syntax much quicker without dealing with grammars, parsers and syntax trees.
+
+To implement a text-based rewriter, you need to create a new class inherited from `RubyNext::Language::Rewriters::Text` and implementing either `#rewrite` or `#safe_rewrite` method. For example, the method reference operator (`.:`) could be implemented as follows:
+
+```ruby
+class MethodReferenceRewriter < RubyNext::Language::Rewriters::Text
+  # Rewriter configuration includes its name, a syntax probe and a minimum supported Ruby version.
+  # The latter two are used to determine whether the rewriter should be activated for the current file in runtime or when running `ruby-next nextify`.
+  NAME = "method-reference"
+  SYNTAX_PROBE = "Language.:transform"
+  MIN_SUPPORTED_VERSION = Gem::Version.new(RubyNext::NEXT_VERSION)
+
+  def safe_rewrite(source)
+    source.gsub(/\.:([\w_]+)/) do |match|
+      context.track! self
+
+      ".method(:#{$1})"
+    end
+  end
+end
+
+# Add the rewriter to the list of rewriters
+RubyNext::Language.rewriters << MethodReferenceRewriter
+```
+
+The `context` object is responsible for tracking if the rewriter was used for the current file. You must call the `context.track!` method to mark the file as _dirty_ (i.e., it should be transpiled). The input parameter (`source`) is the Ruby source code of the file being transpiled and the output must be the transpiled source code.
+
+The `#safe_rewrite` method operates on the normalized source code (i.e., without comments and string literals). It's useful when you want to avoid transpiling inside strings or comments. If you want to transpile the original contents, you can use the `#rewrite` method instead.
+
+Under the hood, `#safe_rewrite` uses [Paco][] to parse the source and separate string literals from the rest of the code. You can also leverage [Paco][] in your text rewriters, if you want more control on the parsing process. For better experience, we provide a DSL to define a custom parser and the `#parse` method to use it. Here is an example of implementing the `.:` operator using a Paco parser:
+
+```ruby
+class MethodReferenceRewriter < RubyNext::Language::Rewriters::Text
+  NAME = "method-reference"
+  SYNTAX_PROBE = "Language.:transform"
+
+  parser do
+    def default
+      many(
+        alt(
+          method_ref,
+          any_char
+        )
+      )
+    end
+
+    def method_ref
+      seq(
+        string(".:").result(""),
+        method_name
+      # IMPORTANT: Use `#track!` method to mark the file as dirty
+      ).fmap { track! }.fmap { ".method(:#{_1})" }
+    end
+
+    def method_name = regexp(/[\w_]+/)
+  end
+
+  def safe_rewrite(source)
+    parse(source).join
+  end
+end
+
+# Add the rewriter to the list of rewriters
+RubyNext::Language.rewriters << MethodReferenceRewriter
+```
+
+When using the `ruby-next nextify` command, you can load custom rewriters via the `--import-rewriter` option.
+
 ## Known limitations
 
 Ruby Next aims to be _reasonably compatible_ with MRI. That means, some edge cases could be uncovered. Below is the list of known limitations.
@@ -596,6 +663,10 @@ Bug reports and pull requests are welcome on GitHub at [https://github.com/ruby-
 
 See also the [development guide](./DEVELOPMENT.md).
 
+## Acknowledgments
+
+- Thanks to [Jim Gay](https://github.com/saturnflyer) for the original Data polyfill implementation ([polyfill-data](https://github.com/saturnflyer/polyfill-data))
+
 ## License
 
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
@@ -613,6 +684,8 @@ The gem is available as open source under the terms of the [MIT License](https:/
 [parser]: https://github.com/whitequark/parser
 [unparser]: https://github.com/mbj/unparser
 [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
+[require-hooks]: https://github.com/ruby-next/require-hooks
+[Natalie]: https://natalie-lang.org
+[Paco]: https://github.com/ruby-next/paco

data/bin/mspec

@@ -0,0 +1,11 @@
+#!/usr/bin/env ruby
+
+unless File.directory?('mspec/lib')
+  $stdout.puts "Cloning mspec..."
+  system("git clone https://github.com/ruby/mspec.git mspec")
+end
+
+$:.unshift File.expand_path(File.join(__dir__, '..', 'mspec', 'lib'))
+
+require 'mspec/commands/mspec'
+MSpecMain.main(false)