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.
Files changed (4) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +54 -0
  3. data/README.md +117 -13
  4. metadata +9 -9
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: 7b1c1af8cbe6211f553a3111863bf727e7438220174dc3d5b1126fdd46c5c5ba
4
- data.tar.gz: 66fe1d334298706ec37cc73af042b83f6e770f8888b8a2a9227b1950d139df23
3
+ metadata.gz: 6045c8ee35bf11e9dcd74c6a41eea952b1a4bacd826a04cf4fb26a32598fe66d
4
+ data.tar.gz: e3f98fbfa40ffb93f4f6ffa935d09bdefd95660e1768dbd9e0cecaa9b5b35526
5
5
  SHA512:
6
- metadata.gz: 8a24a83d3f705da786d64878bf87c9375685508e6eb9c69b84144d02d005733fc92ff58adafa89d49721b75983ff4b8d1c8f193cd02868b613f6dc829e04907c
7
- data.tar.gz: 0c5aa1e100aec167c965c13330fc4fa71ac0210233ee800ed09ddf0cf0256b97aa52ab6cfc0d210e5aa8d19bb2220d21766f90761edb3be271efbda922adae39
6
+ metadata.gz: 170c1fb05d4a8f4440812354ea419847c72625d07e2206c7d968fec183e964cbf670391d10f19702b287bc6aa6ce394ecb204275fed9096c776fa3bdf2085246
7
+ data.tar.gz: effebc099da374e8479f5f61474a3dbb2584c66abb58a5208f6db08ebcab29d948a735c7f5478eb87864d32b98be201d576c5036330f3d18e5efe2e702d8dd0c
@@ -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
- ## Links
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.5+ (including JRuby 9.2.8+).
53
- Please, [open an issue](https://github.com/ruby-next/ruby-next/issues/new/choose) if you would like us to support older Ruby versions.
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
- case {hello: 'martian'}
66
- in hello: hello if hello =~ /human/
67
- puts '🙂'
68
- in hello: 'martian'
69
- puts '👽'
70
- end
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
- ### Integrating into a gem development
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
- Not yet.
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 (`.:`) ([link](https://bugs.ruby-lang.org/issues/13581)).
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.6.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-04-23 00:00:00.000000000 Z
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: '0'
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: '0'
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.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.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.5.0
84
+ version: 2.3.0
85
85
  required_rubygems_version: !ruby/object:Gem::Requirement
86
86
  requirements:
87
87
  - - ">="