ruby-next 0.6.0 → 0.9.1
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +4 -4
- data/CHANGELOG.md +54 -0
- data/README.md +117 -13
- metadata +9 -9
checksums.yaml
CHANGED
@@ -1,7 +1,7 @@
|
|
1
1
|
---
|
2
2
|
SHA256:
|
3
|
-
metadata.gz:
|
4
|
-
data.tar.gz:
|
3
|
+
metadata.gz: 6045c8ee35bf11e9dcd74c6a41eea952b1a4bacd826a04cf4fb26a32598fe66d
|
4
|
+
data.tar.gz: e3f98fbfa40ffb93f4f6ffa935d09bdefd95660e1768dbd9e0cecaa9b5b35526
|
5
5
|
SHA512:
|
6
|
-
metadata.gz:
|
7
|
-
data.tar.gz:
|
6
|
+
metadata.gz: 170c1fb05d4a8f4440812354ea419847c72625d07e2206c7d968fec183e964cbf670391d10f19702b287bc6aa6ce394ecb204275fed9096c776fa3bdf2085246
|
7
|
+
data.tar.gz: effebc099da374e8479f5f61474a3dbb2584c66abb58a5208f6db08ebcab29d948a735c7f5478eb87864d32b98be201d576c5036330f3d18e5efe2e702d8dd0c
|
data/CHANGELOG.md
CHANGED
@@ -2,6 +2,59 @@
|
|
2
2
|
|
3
3
|
## master
|
4
4
|
|
5
|
+
## 0.9.1 (2020-06-05)
|
6
|
+
|
7
|
+
- Keep `ruby-next` version in sync with `ruby-next-core`. ([@palkan][])
|
8
|
+
|
9
|
+
Require `ruby-next-core` of the same version as `ruby-next`.
|
10
|
+
|
11
|
+
## 0.9.0 (2020-06-04)
|
12
|
+
|
13
|
+
- Add Ruby 2.3 support. ([@palkan][])
|
14
|
+
|
15
|
+
- Remove stale transpiled files when running `ruby-next nextify`. ([@palkan][])
|
16
|
+
|
17
|
+
- Add Ruby 2.4 support. ([@palkan][])
|
18
|
+
|
19
|
+
APIs for <2.5 must be backported via [backports][] gem. Refinements are not supported.
|
20
|
+
|
21
|
+
## 0.8.0 (2020-05-01) 🚩
|
22
|
+
|
23
|
+
- Add right-hand assignment support. ([@palkan][])
|
24
|
+
|
25
|
+
It is real: `13.divmod(5) => a, b`.
|
26
|
+
|
27
|
+
- Add endless methods support. ([@palkan][])
|
28
|
+
|
29
|
+
Now you can write `def foo() = :bar`.
|
30
|
+
|
31
|
+
## 0.7.0 (2020-04-29)
|
32
|
+
|
33
|
+
- Try to auto-transpile the source code on load in `.setup_gem_load_path` if transpiled files are missing. ([@palkan][])
|
34
|
+
|
35
|
+
This would make it possible to install gems from source if transpiled files do not exist in the repository.
|
36
|
+
|
37
|
+
- Use`./.rbnextrc` to define CLI args. ([@palkan][])
|
38
|
+
|
39
|
+
You can define CLI options in the configuration file to re-use them between environments or
|
40
|
+
simply avoid typing every time:
|
41
|
+
|
42
|
+
```yml
|
43
|
+
# .rbnextrc
|
44
|
+
nextify: |
|
45
|
+
--transpiler-mode=rewrite
|
46
|
+
--edge
|
47
|
+
```
|
48
|
+
|
49
|
+
- Add `--dry-run` option to CLI. ([@palkan][])
|
50
|
+
|
51
|
+
- Raise `SyntaxError` when parsing fails. ([@palkan][])
|
52
|
+
|
53
|
+
Previously, we let Parser to raise its `Parser::SyntaxError` but some exceptions
|
54
|
+
are not reported by Parser and should be handled by transpiler (and we raised `SyntaxError` in that case, as MRI does).
|
55
|
+
|
56
|
+
This change unifies the exceptions raised during transpiling.
|
57
|
+
|
5
58
|
## 0.6.0 (2020-04-23)
|
6
59
|
|
7
60
|
- Changed the way edge/proposed features are activated. ([@palkan][])
|
@@ -141,3 +194,4 @@ p a #=> 1
|
|
141
194
|
- Add `Kernel#then`. ([@palkan][])
|
142
195
|
|
143
196
|
[@palkan]: https://github.com/palkan
|
197
|
+
[backports]: https://github.com/marcandre/backports
|
data/README.md
CHANGED
@@ -1,5 +1,6 @@
|
|
1
1
|
[![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)
|
2
|
-
[![JRuby Build](https://github.com/ruby-next/ruby-next/workflows/JRuby%20Build/badge.svg)](https://github.com/ruby-next/ruby-next/actions)
|
2
|
+
[![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)
|
3
|
+
[![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)
|
3
4
|
|
4
5
|
# Ruby Next
|
5
6
|
|
@@ -17,13 +18,29 @@ Who might be interested in Ruby Next?
|
|
17
18
|
Ruby Next also aims to help the community to assess new, _experimental_, MRI features by making it easier to play with them.
|
18
19
|
That's why Ruby Next implements the `master` features as fast as possible.
|
19
20
|
|
21
|
+
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).
|
22
|
+
|
20
23
|
<a href="https://evilmartians.com/?utm_source=ruby-next">
|
21
24
|
<img src="https://evilmartians.com/badges/sponsored-by-evil-martians.svg" alt="Sponsored by Evil Martians" width="236" height="54"></a>
|
22
25
|
|
23
|
-
##
|
26
|
+
## Posts
|
27
|
+
|
28
|
+
- [Ruby Next: Make all Rubies quack alike](https://evilmartians.com/chronicles/ruby-next-make-all-rubies-quack-alike)
|
29
|
+
|
30
|
+
## Talks
|
24
31
|
|
25
32
|
- [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)
|
26
33
|
|
34
|
+
## Examples
|
35
|
+
|
36
|
+
- Ruby gems
|
37
|
+
- [anyway_config](https://github.com/palkan/anyway_config)
|
38
|
+
- [graphql-fragment_cache](https://github.com/DmitryTsepelev/graphql-ruby-fragment_cache)
|
39
|
+
- mruby
|
40
|
+
- [ACLI](https://github.com/palkan/acli)
|
41
|
+
|
42
|
+
_Please, submit a PR to add your project to the list!_
|
43
|
+
|
27
44
|
## Table of contents
|
28
45
|
|
29
46
|
- [Overview](#overview)
|
@@ -38,6 +55,7 @@ That's why Ruby Next implements the `master` features as fast as possible.
|
|
38
55
|
- [`ruby -ruby-next`](#uby-next)
|
39
56
|
- [Logging & Debugging](#logging-and-debugging)
|
40
57
|
- [RuboCop](#rubocop)
|
58
|
+
- [Using with EOL Rubies](#using-with-eol-rubies)
|
41
59
|
- [Proposed & edge features](#proposed-and-edge-features)
|
42
60
|
|
43
61
|
## Overview
|
@@ -49,8 +67,9 @@ Core provides **polyfills** for Ruby core classes APIs via Refinements (default
|
|
49
67
|
Language is responsible for **transpiling** edge Ruby syntax into older versions. It could be done
|
50
68
|
programmatically or via CLI. It also could be done in runtime.
|
51
69
|
|
52
|
-
Currently, Ruby Next supports Ruby versions 2.
|
53
|
-
|
70
|
+
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)).
|
71
|
+
|
72
|
+
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.
|
54
73
|
|
55
74
|
## Quick start
|
56
75
|
|
@@ -62,12 +81,16 @@ $ gem install ruby-next
|
|
62
81
|
|
63
82
|
# Call ruby with -ruby-next flag
|
64
83
|
$ ruby -ruby-next -e "
|
65
|
-
|
66
|
-
|
67
|
-
|
68
|
-
|
69
|
-
|
70
|
-
|
84
|
+
def greet(val) =
|
85
|
+
case val
|
86
|
+
in hello: hello if hello =~ /human/i
|
87
|
+
'🙂'
|
88
|
+
in hello: 'martian'
|
89
|
+
'👽'
|
90
|
+
end
|
91
|
+
|
92
|
+
greet(hello: 'martian') => greeting
|
93
|
+
puts greeting
|
71
94
|
"
|
72
95
|
|
73
96
|
=> 👽
|
@@ -115,6 +138,8 @@ The following _rule of thumb_ is recommended when choosing between refinements a
|
|
115
138
|
- 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 🙂)
|
116
139
|
- Use core extensions if refinements are not supported by your platform
|
117
140
|
|
141
|
+
**NOTE:** TruffleRuby doesn't fully support refinements (refining modules is not supported as of v20.1.0).
|
142
|
+
|
118
143
|
[**The list of supported APIs.**][features_core]
|
119
144
|
|
120
145
|
## Transpiling
|
@@ -160,6 +185,8 @@ You can change the transpiler mode:
|
|
160
185
|
- Via environmental variable `RUBY_NEXT_TRANSPILE_MODE=rewrite`.
|
161
186
|
- Via CLI option ([see below](#cli)).
|
162
187
|
|
188
|
+
**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+.
|
189
|
+
|
163
190
|
## CLI
|
164
191
|
|
165
192
|
Ruby Next ships with the command-line interface (`ruby-next`) which provides the following functionality:
|
@@ -181,6 +208,7 @@ Usage: ruby-next nextify DIRECTORY_OR_FILE [options]
|
|
181
208
|
--[no-]refine Do not inject `using RubyNext`
|
182
209
|
-h, --help Print help
|
183
210
|
-V Turn on verbose mode
|
211
|
+
--dry-run Print verbose output without generating files
|
184
212
|
```
|
185
213
|
|
186
214
|
The behaviour depends on whether you transpile a single file or a directory:
|
@@ -212,6 +240,7 @@ Usage: ruby-next core_ext [options]
|
|
212
240
|
-n, --name=NAME Filter extensions by name
|
213
241
|
-h, --help Print help
|
214
242
|
-V Turn on verbose mode
|
243
|
+
--dry-run Print verbose output without generating files
|
215
244
|
```
|
216
245
|
|
217
246
|
The most common use-case is to backport the APIs required by pattern matching. You can do this, for example,
|
@@ -238,7 +267,21 @@ $ ruby-next core_ext -l --name=filter --name=deconstruct
|
|
238
267
|
- StructDeconstruct
|
239
268
|
```
|
240
269
|
|
241
|
-
###
|
270
|
+
### CLI configuration file
|
271
|
+
|
272
|
+
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`.
|
273
|
+
|
274
|
+
Configuration file is a YAML with commands as keys and options as multiline strings:
|
275
|
+
|
276
|
+
```yml
|
277
|
+
# ./.rbnextrc
|
278
|
+
|
279
|
+
nextify: |
|
280
|
+
--transpiler-mode=rewrite
|
281
|
+
--edge
|
282
|
+
```
|
283
|
+
|
284
|
+
## Integrating into a gem development
|
242
285
|
|
243
286
|
We recommend _pre-transpiling_ source code to work with older versions before releasing it.
|
244
287
|
|
@@ -275,6 +318,24 @@ If you're using [runtime mode](#runtime-usage) a long with `setup_gem_load_path`
|
|
275
318
|
|
276
319
|
\* 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).
|
277
320
|
|
321
|
+
### Transpiled files vs. VCS vs. installing from source
|
322
|
+
|
323
|
+
It's a best practice to not keep generated files in repositories. In case of Ruby Next, it's a `lib/.rbnext` folder.
|
324
|
+
|
325
|
+
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.
|
326
|
+
|
327
|
+
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.
|
328
|
+
|
329
|
+
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:
|
330
|
+
|
331
|
+
- We are in the Bundler context (since that's the most common way of installing gems from source).
|
332
|
+
- Our Gemfile contains `ruby-next` gem.
|
333
|
+
- We use [`.rbnextrc`](#CLI-configuration-file) for transpiling options.
|
334
|
+
|
335
|
+
If the command fails we warn the end user.
|
336
|
+
|
337
|
+
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)`.
|
338
|
+
|
278
339
|
## Runtime usage
|
279
340
|
|
280
341
|
It is also possible to transpile Ruby source code in run-time via Ruby Next.
|
@@ -332,6 +393,12 @@ RUBYOPT="-ruby-next" ruby my_ruby_script.rb
|
|
332
393
|
ruby -ruby-next -e "puts [2, 4, 5].tally"
|
333
394
|
```
|
334
395
|
|
396
|
+
**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.:
|
397
|
+
|
398
|
+
```sh
|
399
|
+
ruby -ruby-next -r my_ruby_script.rb -e "puts my_method"
|
400
|
+
```
|
401
|
+
|
335
402
|
## Logging and debugging
|
336
403
|
|
337
404
|
Ruby Next prints some debugging information when fails to load a file in the runtime mode (and fallbacks to the built-in loading mechanism).
|
@@ -364,6 +431,40 @@ AllCops:
|
|
364
431
|
- 'lib/.rbnext/**/*'
|
365
432
|
```
|
366
433
|
|
434
|
+
**NOTE:** you need `ruby-next` gem available in the environment where you run RuboCop (having `ruby-next-core` is not enough).
|
435
|
+
|
436
|
+
## Using with EOL Rubies
|
437
|
+
|
438
|
+
We currently provide support for Ruby 2.3 and 2.4. Work on 2.2 is in progress.
|
439
|
+
|
440
|
+
Ruby Next itself relies on 2.5 features and contains polyfills only for version 2.5+ (and that won't change).
|
441
|
+
Thus, to make it work with <2.5 we need to backport some APIs ourselves.
|
442
|
+
|
443
|
+
The recommended way of doing this is to use [backports][] gem. You need to load backports **before Ruby Next**.
|
444
|
+
|
445
|
+
When using runtime features, you should do the following:
|
446
|
+
|
447
|
+
```ruby
|
448
|
+
# first, require backports upto 2.5
|
449
|
+
require "backports/2.5"
|
450
|
+
# then, load Ruby Next
|
451
|
+
require "ruby-next"
|
452
|
+
# if you need 2.6+ APIs, add Ruby Next core_ext
|
453
|
+
require "ruby-next/core_ext"
|
454
|
+
# then, load runtime transpiling
|
455
|
+
require "ruby-next/language/runtime"
|
456
|
+
# or
|
457
|
+
require "ruby-next/language/bootsnap"
|
458
|
+
```
|
459
|
+
|
460
|
+
To load backports while using `ruby-next nextify` command, you must configure the environment variable:
|
461
|
+
|
462
|
+
```sh
|
463
|
+
RUBY_NEXT_CORE_STRATEGY=backports ruby-next nextify lib/
|
464
|
+
```
|
465
|
+
|
466
|
+
**NOTE:** Make sure you have `backports` gem installed globally or added to your bundle (if you're using `bundle exec ruby-next ...`).
|
467
|
+
|
367
468
|
## Proposed and edge features
|
368
469
|
|
369
470
|
Ruby Next aims to bring edge and proposed features to Ruby community before they (hopefully) reach an official Ruby release.
|
@@ -395,11 +496,13 @@ require "ruby-next/language/runtime"
|
|
395
496
|
|
396
497
|
### Supported edge features
|
397
498
|
|
398
|
-
|
499
|
+
- "Endless" method definition (`def foo() = 42`) ([#16746](https://bugs.ruby-lang.org/issues/16746)).
|
500
|
+
|
501
|
+
- Right-hand assignment (`13.divmod(5) => a,b`) ([#15921](https://bugs.ruby-lang.org/issues/15921))
|
399
502
|
|
400
503
|
### Supported proposed features
|
401
504
|
|
402
|
-
- _Method reference_ operator (`.:`) ([
|
505
|
+
- _Method reference_ operator (`.:`) ([#13581](https://bugs.ruby-lang.org/issues/13581)).
|
403
506
|
|
404
507
|
## Contributing
|
405
508
|
|
@@ -426,3 +529,4 @@ The gem is available as open source under the terms of the [MIT License](https:/
|
|
426
529
|
[next_parser]: https://github.com/ruby-next/parser
|
427
530
|
[Bootsnap]: https://github.com/Shopify/bootsnap
|
428
531
|
[rubocop]: https://github.com/rubocop-hq/rubocop
|
532
|
+
[backports]: https://github.com/marcandre/backports
|
metadata
CHANGED
@@ -1,43 +1,43 @@
|
|
1
1
|
--- !ruby/object:Gem::Specification
|
2
2
|
name: ruby-next
|
3
3
|
version: !ruby/object:Gem::Version
|
4
|
-
version: 0.
|
4
|
+
version: 0.9.1
|
5
5
|
platform: ruby
|
6
6
|
authors:
|
7
7
|
- Vladimir Dementyev
|
8
8
|
autorequire:
|
9
9
|
bindir: bin
|
10
10
|
cert_chain: []
|
11
|
-
date: 2020-
|
11
|
+
date: 2020-06-05 00:00:00.000000000 Z
|
12
12
|
dependencies:
|
13
13
|
- !ruby/object:Gem::Dependency
|
14
14
|
name: ruby-next-core
|
15
15
|
requirement: !ruby/object:Gem::Requirement
|
16
16
|
requirements:
|
17
|
-
- -
|
17
|
+
- - '='
|
18
18
|
- !ruby/object:Gem::Version
|
19
|
-
version:
|
19
|
+
version: 0.9.1
|
20
20
|
type: :runtime
|
21
21
|
prerelease: false
|
22
22
|
version_requirements: !ruby/object:Gem::Requirement
|
23
23
|
requirements:
|
24
|
-
- -
|
24
|
+
- - '='
|
25
25
|
- !ruby/object:Gem::Version
|
26
|
-
version:
|
26
|
+
version: 0.9.1
|
27
27
|
- !ruby/object:Gem::Dependency
|
28
28
|
name: ruby-next-parser
|
29
29
|
requirement: !ruby/object:Gem::Requirement
|
30
30
|
requirements:
|
31
31
|
- - ">="
|
32
32
|
- !ruby/object:Gem::Version
|
33
|
-
version: 2.8.0.
|
33
|
+
version: 2.8.0.6
|
34
34
|
type: :runtime
|
35
35
|
prerelease: false
|
36
36
|
version_requirements: !ruby/object:Gem::Requirement
|
37
37
|
requirements:
|
38
38
|
- - ">="
|
39
39
|
- !ruby/object:Gem::Version
|
40
|
-
version: 2.8.0.
|
40
|
+
version: 2.8.0.6
|
41
41
|
- !ruby/object:Gem::Dependency
|
42
42
|
name: unparser
|
43
43
|
requirement: !ruby/object:Gem::Requirement
|
@@ -81,7 +81,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
|
|
81
81
|
requirements:
|
82
82
|
- - ">="
|
83
83
|
- !ruby/object:Gem::Version
|
84
|
-
version: 2.
|
84
|
+
version: 2.3.0
|
85
85
|
required_rubygems_version: !ruby/object:Gem::Requirement
|
86
86
|
requirements:
|
87
87
|
- - ">="
|