ruby-next 0.0.1.26 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 75e0c4e0c3075a5f795dc502f0c5ded97f81655f2fa44a6dcc1097f4121cf6cc
-  data.tar.gz: 4ab75f77f5ac5bd8669709d9af390dbeddcd685973fba556167ab37c67b3d052
+  metadata.gz: a874763234ae5833fd2b6617be24fb2e600acc49c62fd39707d8da73d5810656
+  data.tar.gz: c6e73faa43b329ac1c3e0d2daff8689d677d19ed28ffb2ac8d09dea526ac1a1c
 SHA512:
-  metadata.gz: c4db7480850615e3a6fdfcdf59790d11fa5c1b4aa53a6f6f40e5c9741447d5286a35a1dfbc180640fc760264dabbe1ffc7d069b8e3fd94749bc5f92dfcd48783
-  data.tar.gz: fb790e86e46637ad819cb4b9c9b01bb2007c1a5d25bbe06edde791f6e02c6f50bc442619aa5ed9e237224354ca45d436879a8fb3751da96f855b2ac368f656e6
+  metadata.gz: a9f7d9dff8b79bcc2121b7dbaba38cd8ac5a578b249b463fa6c7a5ef25845fb12537b82e3ee240463d8156512c2039245b0465fb56249f2a6812ce1ce3ff971b
+  data.tar.gz: e909ab9742e7e1d7a32f00465bfe84c7ba3ad197b126842131a8b4601ab015cb7bf29b8c8aef7d0b5fab6b0bef5a45d1ea5a6c8f2b83d6f63be243cb19c20b8a

data/CHANGELOG.md

@@ -0,0 +1,38 @@
+# Change log
+
+## master
+
+## 0.1.0 (2019-11-16)
+
+- Add pattern matching. ([@palkan][])
+
+- Add numbered parameters. ([@palkan][])
+
+- Add arguments forwarding. ([@palkan][])
+
+- Add `Enumerable#filter_map`. ([@palkan][])
+
+- Add `Enumerable#filter/filter!`. ([@palkan][])
+
+- Add multiple arguments support to `Hash#merge`. ([@palkan][])
+
+- Add `Array#intersection`, `Array#union`, `Array#difference`. ([@palkan][])
+
+- Add `Enumerable#tally`. ([@palkan][])
+
+- Implement gem integration flow. ([@palkan][])
+
+  - Transpile code via `ruby-next nextify`.
+  - Setup load path via `RubyNext::Language.setup_gem_load_Path`.
+
+- Add `ruby-next nextify` command. ([@palkan][])
+
+- Add endless Range support. ([@palkan][])
+
+- Add method reference syntax support. ([@palkan][])
+
+- Add `Proc#<<` and `Proc#>>`. ([@palkan][])
+
+- Add `Kernel#then`. ([@palkan][])
+
+[@palkan]: https://github.com/palkan

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2019 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
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -1,14 +1,204 @@
-# Ruby Next Playground
+[![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)
 
-> Make older Rubies quack like edge Ruby!
+# Ruby Next
 
-## Resources
+> Make all Rubies quack like edge Ruby!
 
-- [Pattern Matching, RubyKaigi 2019](https://speakerdeck.com/k_tsj/pattern-matching-new-feature-in-ruby-2-dot-7?slide=15)
-- [parser + pattern matching](https://github.com/whitequark/parser/pull/574)
-- [vernacular-ast](https://github.com/kddeisz/vernacular-ast)
-- [iseq_builder](https://github.com/youchan/iseq_builder)
-- [unparser](https://github.com/mbj/unparser)
-- [TOPLEVEL_BINDING.eval + require_relative](https://bugs.ruby-lang.org/issues/4487)
-- [malloc_trim](https://github.com/tessi/malloc_trim)
-- [Ruby changes](https://rubyreferences.github.io/rubychanges)
+Ruby Next is a tool for supporting modern/edge CRuby features (APIs and syntax) in older versions and alternative implementations. For example, you can use pattern matching and `Kernel#then` in Ruby 2.5 or [mruby][].
+
+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][], [Artichoke][], [Prism][].
+
+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 `trunk` features as fast as possible.
+
+_⚡️ The project is in early alpha stage and looking for the first adopters. Main functionality has been implemented (see [the list][features]) but APIs could change in the future._
+
+## Overview
+
+Ruby Next consists of two parts: **core** and **language**.
+
+Core provides **polyfills** for Ruby core classes APIs via Refinements.
+Thus, polyfills are only available in compatible runtimes (MRI, JRuby, TruffleRuby).
+
+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.
+
+## Using only polyfills
+
+First, install a gem:
+
+```ruby
+# Gemfile
+gem "ruby-next"
+
+# gemspec
+spec.add_dependency "ruby-next"
+```
+
+Then, all you need is to load the Ruby Next:
+
+```ruby
+require "ruby-next"
+```
+
+And activate the refinement in every file where you want to use it\*:
+
+```ruby
+using RubyNext
+```
+
+Ruby Next only refines core classes if necessary; thus, this line wouldn't have any effect in the edge Ruby.
+
+[**The list of supported APIs.**][features_core]
+
+## Transpiling, or using edge Ruby syntax features
+
+Ruby Next relies on its own version of the [parser][] gem hosted on Github Package Registry. That makes the installation process a bit more complicated than usual.
+
+[**The list of supported syntax features.**][features_syntax]
+
+### Installing with Bundler
+
+First, configure your bundler to access GPR:
+
+```sh
+bundle config --local https://rubygems.pkg.github.com/ruby-next USERNAME:ACCESS_TOKEN
+```
+
+Then, add to your Gemfile:
+
+```ruby
+source "https://rubygems.pkg.github.com/ruby-next" do
+  gem "parser", "2.6.3.102"
+end
+
+gem "unparser", "~> 0.4.5"
+gem "ruby-next"
+```
+
+**NOTE:** we don't add `parser` and `unparser` to the gem's runtime deps, 'cause they're not necessary if you only need polyfills.
+
+### Installing globally via `gem`
+
+Currently unavailable due to the limitations of Github Package Registry. See [issue](https://github.community/t5/GitHub-Actions/Can-t-install-Ruby-gem-after-publishing-to-Github-Package/m-p/35192/thread-id/2126).
+
+### 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).
+
+## CLI
+
+Ruby Next ships with the command-line interface (`ruby-next`) which provides the following functionality:
+
+- `ruby-next nextify` — transpile file or directory into older Rubies (see, for example, the "Integrating into a gem development" section above).
+
+It has the following interface:
+
+```sh
+$ ruby-next nextify
+Usage: ruby-next nextify DIRECTORY_OR_FILE [options]
+    -o, --output=OUTPUT     Specify output directory or file
+    --min-version=VERSION   Specify the minimum Ruby version to support
+    --single-version        Only create one version of a file (for the earliest Ruby version)
+    -V                      Turn on verbose mode
+```
+
+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`). 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:
+
+```sh
+$ ruby-next nextify my_ruby.rb -o my_ruby_next.rb -V
+Generated: my_ruby_next.rb
+```
+
+## Runtime mode
+
+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"`.
+
+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.
+
+We plan to add [Bootsnap][] integration in the future, which would allow us to avoid monkey-patching (by relying on the bullet-proofed Bootsnap's one 😉).
+
+\* 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:
+
+```ruby
+RubyNext::Language::Runtime.watch_dirs << "path/to/other/dir"
+```
+
+## `uby-next`
+
+You can also enable runtime mode by requiring `uby-next` while running a Ruby executable:
+
+```sh
+ruby -ruby-next my_ruby_script.rb
+
+# or
+RUBYOPT="-ruby-next" ruby my_ruby_script.rb
+
+# or
+ruby -ruby-next -e "puts [2, 4, 5].tally"
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at [https://github.com/ruby-next/ruby-next](ttps://github.com/ruby-next/ruby-next).
+
+See also the [development guide](./DEVELOPMENT.md).
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+[features]: ./SUPPORTED_FEATURES.md
+[features_core]: ./SUPPORTED_FEATURES.md#Core
+[features_syntax]: ./SUPPORTED_FEATURES.md#Syntax
+[mruby]: https://mruby.org
+[JRuby]: https://www.jruby.org
+[TruffleRuby]: https://github.com/oracle/truffleruby
+[Opal]: https://opalrb.com
+[Artichoke]: https://github.com/artichoke/artichoke
+[Prism]: https://github.com/prism-rb/prism
+[parser]: https://github.com/whitequark/parser
+[Bootsnap]: https://github.com/Shopify/bootsnap

data/bin/parse

@@ -0,0 +1,19 @@
+#!/usr/bin/env ruby
+
+lib = File.expand_path("../../lib", __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+$VERBOSE = nil
+
+require "bundler/setup"
+
+require "ruby-next/language"
+
+contents =
+  if File.exist?(ARGV[0])
+    File.read(ARGV[0])
+  else
+    ARGV[0]
+  end
+
+ast = RubyNext::Language::Parser.parse(contents)
+puts ast

data/bin/ruby-next

@@ -0,0 +1,16 @@
+#!/usr/bin/env ruby
+
+lib_path = File.expand_path("../lib", __dir__)
+$LOAD_PATH.unshift(lib_path) unless $LOAD_PATH.include?(lib_path)
+
+require "ruby-next/cli"
+
+begin
+  cli = RubyNext::CLI.new
+  cli.run(ARGV)
+rescue => e
+  raise e if $DEBUG
+  STDERR.puts e.message
+  STDERR.puts e.backtrace.join("\n")
+  exit 1
+end

data/bin/transform

@@ -0,0 +1,18 @@
+#!/usr/bin/env ruby
+
+lib = File.expand_path("../../lib", __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+$VERBOSE = nil
+
+require "bundler/setup"
+
+require "ruby-next/language"
+
+contents =
+  if File.exist?(ARGV[0])
+    File.read(ARGV[0])
+  else
+    ARGV[0]
+  end
+
+puts RubyNext::Language.transform(contents)

data/lib/ruby-next/cli.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require "ruby-next"
+require "ruby-next/language"
+
+require "ruby-next/commands/base"
+require "ruby-next/commands/nextify"
+
+module RubyNext
+  # Command line interface for RubyNext
+  class CLI
+    class << self
+      attr_accessor :verbose
+    end
+
+    self.verbose = false
+
+    COMMANDS = {
+      "nextify" => Commands::Nextify
+    }.freeze
+
+    def initialize
+    end
+
+    def run(args = ARGV)
+      maybe_print_version(args)
+
+      command = args.shift
+
+      raise "Command must be specified!" unless command
+
+      COMMANDS.fetch(command) do
+        raise "Unknown command: #{command}. Available commands: #{COMMANDS.keys.join(",")}"
+      end.run(args)
+    end
+
+    private
+
+    def maybe_print_version(args)
+      args = args.dup
+      begin
+        OptionParser.new do |opts|
+          opts.banner = "Usage: ruby-next COMMAND [options]"
+
+          opts.on("-v", "--version", "Print version") do
+            STDOUT.puts RubyNext::VERSION
+            exit 0
+          end
+        end.parse!(args)
+      rescue OptionParser::InvalidOption
+        # skip and pass all args to the command's parser
+      end
+    end
+  end
+end

data/lib/ruby-next/commands/base.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require "optparse"
+
+module RubyNext
+  module Commands
+    class Base
+      class << self
+        def run(args)
+          new(args).run
+        end
+      end
+
+      def initialize(args)
+        parse! args
+      end
+
+      def parse!(*)
+        raise NotImplementedError
+      end
+
+      def run
+        raise NotImplementedError
+      end
+
+      def log(msg)
+        return unless CLI.verbose
+        $stdout.puts msg
+      end
+
+      def base_parser
+        OptionParser.new do |opts|
+          yield opts
+
+          opts.on("-V", "Turn on verbose mode") do
+            CLI.verbose = true
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ruby-next/commands/nextify.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "pathname"
+
+using RubyNext
+
+module RubyNext
+  module Commands
+    class Nextify < Base
+      attr_reader :lib_path, :paths, :out_path, :min_version, :single_version
+
+      def run
+        paths.each do |path|
+          contents = File.read(path)
+          transpile path, contents
+        end
+      end
+
+      def parse!(args)
+        @min_version = MIN_SUPPORTED_VERSION
+        @single_version = false
+
+        optparser = base_parser do |opts|
+          opts.banner = "Usage: ruby-next nextify DIRECTORY_OR_FILE [options]"
+
+          opts.on("-o", "--output=OUTPUT", "Specify output directory or file or stdout") do |val|
+            @out_path = val
+          end
+
+          opts.on("--min-version=VERSION", "Specify the minimum Ruby version to support") do |val|
+            @min_version = Gem::Version.new(val)
+          end
+
+          opts.on("--single-version", "Only create one version of a file (for the earliest Ruby version)") do
+            @single_version = true
+          end
+        end
+
+        @lib_path = args[0]
+
+        unless lib_path&.then(&File.method(:exist?))
+          $stdout.puts optparser.help
+          exit 0
+        end
+
+        optparser.parse!(args)
+
+        @paths =
+          if File.directory?(lib_path)
+            Dir[File.join(lib_path, "**/*.rb")]
+          elsif File.file?(lib_path)
+            [lib_path].tap do |_|
+              @lib_path = File.dirname(lib_path)
+            end
+          end
+      end
+
+      private
+
+      def transpile(path, contents, version: min_version)
+        rewriters = Language.rewriters.select { |rw| rw.unsupported_version?(version) }
+
+        context = Language::TransformContext.new
+        new_contents = Language.transform contents, context: context, rewriters: rewriters
+
+        return unless context.dirty?
+
+        versions = context.sorted_versions
+        version = versions.shift
+
+        # First, store already transpiled contents in the minimum required version dir
+        save new_contents, path, version
+
+        return if versions.empty? || single_version?
+
+        # Then, generate the source code for the next version
+        transpile path, contents, version: version
+      end
+
+      def save(contents, path, version)
+        return $stdout.puts(contents) if out_path == "stdout"
+
+        paths = [Pathname.new(path).relative_path_from(Pathname.new(lib_path))]
+
+        paths.unshift(version.segments[0..1].join(".")) unless single_version?
+
+        next_path =
+          if out_path
+            if out_path.end_with?(".rb")
+              out_path
+            else
+              File.join(out_path, *paths)
+            end
+          else
+            File.join(
+              lib_path,
+              RUBY_NEXT_DIR,
+              *paths
+            )
+          end
+
+        FileUtils.mkdir_p File.dirname(next_path)
+
+        File.write(next_path, contents)
+
+        log "Generated: #{next_path}"
+      end
+
+      alias single_version? single_version
+    end
+  end
+end

data/lib/ruby-next/core/array/difference_union_intersection.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+unless [].respond_to?(:union)
+  RubyNext.module_eval do
+    refine Array do
+      def union(*others)
+        others.reduce(Array.new(self).uniq) { |acc, arr| acc | arr }
+      end
+    end
+  end
+end
+
+unless [].respond_to?(:difference)
+  RubyNext.module_eval do
+    refine Array do
+      def difference(*others)
+        others.reduce(Array.new(self)) { |acc, arr| acc - arr }
+      end
+    end
+  end
+end
+
+unless [].respond_to?(:intersection)
+  RubyNext.module_eval do
+    refine Array do
+      def intersection(*others)
+        others.reduce(Array.new(self)) { |acc, arr| acc & arr }
+      end
+    end
+  end
+end

data/lib/ruby-next/core/enumerable/filter.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+unless [].respond_to?(:filter)
+  RubyNext.module_eval do
+    refine Enumerable do
+      alias filter select
+    end
+
+    # Refine Array seprately, 'cause refining modules is vulnerable to prepend:
+    # - https://bugs.ruby-lang.org/issues/13446
+    #
+    # Also, Array also have `filter!`
+    refine Array do
+      alias filter select
+      alias filter! select!
+    end
+
+    refine Hash do
+      alias filter select
+      alias filter! select!
+    end
+  end
+end

data/lib/ruby-next/core/enumerable/filter_map.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+unless [].respond_to?(:filter_map)
+  module RubyNext
+    module Core
+      module EnumerableFilterMap
+        def filter_map
+          if block_given?
+            result = []
+            each do |element|
+              res = yield element
+              result << res if res
+            end
+            result
+          else
+            Enumerator.new do |yielder|
+              result = []
+              each do |element|
+                res = yielder.yield element
+                result << res if res
+              end
+              result
+            end
+          end
+        end
+      end
+    end
+  end
+
+  RubyNext.module_eval do
+    refine Enumerable do
+      include RubyNext::Core::EnumerableFilterMap
+    end
+
+    refine Enumerator::Lazy do
+      def filter_map
+        Enumerator::Lazy.new(self) do |yielder, *values|
+          result = yield(*values)
+          yielder << result if result
+        end
+      end
+    end
+
+    # Refine Array seprately, 'cause refining modules is vulnerable to prepend:
+    # - https://bugs.ruby-lang.org/issues/13446
+    refine Array do
+      include RubyNext::Core::EnumerableFilterMap
+    end
+  end
+end