ruby-next-core 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 920bab371a964915799cae3423ebe43f77d54986a904da19e9c868efe309fc42
-  data.tar.gz: a19414277a1cc30b1f7863d765026b2c20162d51ae6aadd84def479915a641bd
+  metadata.gz: 3c192e6090c23fb8d462dae6403a3e952f661bd0972f49eaaaba064cb2b07084
+  data.tar.gz: c72d83029a820636ce4809e727ad385a5d85bffafee94db2a4764f40eccb36f4
 SHA512:
-  metadata.gz: c72c42d6ef93f871448e50d15d935001973347450b6cfc47eef3c455ffcbfee18c33e03e761315571fa4010535c0649b82882b38e951229d6141f82b45fe01af
-  data.tar.gz: 1ba4bac7b1a9c18abfc07fb9304b92393ffa61659e80d4cb99d91c606569331a3ca0cd35eb9cd64a7078dbd905cdf417abf35b24ca7742dc8eb466625d53a3f2
+  metadata.gz: 26eb5a69b3993cde39121bd19d710d5850f9dc722a807776bdf969b3fc0b52625de05f4f583e10b97fd137bc5c7a108c1c7b4582b8f541d109282c85ed244dc4
+  data.tar.gz: eed1785c806afd65b681f4b22c98658f0e2b43bc20d534ffc1382c476e600b2715d048e1e5409f65c43f92f9913531c1858b6a842348dd172526e1a2391f7865

data/CHANGELOG.md

@@ -2,6 +2,32 @@
 
 ## master
 
+## 0.3.0 (2020-02-14) 💕
+
+- Add `Time#floor` and `Time#ceil`. ([@palkan][])
+
+- Add `UnboundMethod#bind_call`. ([@palkan][])
+
+- Add `String#split` with block. ([@palkan][])
+
+- **Check for _native_ method implementation to activate a refinement.** ([@palkan][])
+
+Add a method refinement to `using RubyNext` even if the backport is present. That
+helps to avoid the conflicts with invalid monkey-patches.
+
+- Add `ruby-next core_ext` command. ([@palkan][])
+
+This command allows generating custom core extension files. Meant to be used in
+alternative Ruby implementations (mruby, Opal, etc.) not compatible with the `ruby-next-core` gem.
+
+- Add `ruby-next/core_ext`. ([@palkan][])
+
+Now you can use core extensions (monkey-patches) instead of the refinements.
+
+- Check whether pattern matching target respond to `#deconstruct` / `#deconstruct_keys`. ([@palkan][])
+
+- Fix `Struct#deconstruct_keys` to respect passed keys. ([@palkan][])
+
 ## 0.2.0 (2020-01-13) 🎄
 
 - Add `Enumerator.produce`. ([@palkan][])

data/README.md

@@ -26,8 +26,7 @@ _⚡️ The project is in a **beta** phase. That means that the main functionali
 
 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).
+Core provides **polyfills** for Ruby core classes APIs via Refinements (default strategy) or core extensions (optionally or for refinement-less environments).
 
 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.
@@ -63,6 +62,20 @@ using RubyNext
 
 Ruby Next only refines core classes if necessary; thus, this line wouldn't have any effect in the 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 a predictable behaviour. That's why we recommend using refinements for gems development.
+
+Alternatively, you can go with monkey-patches. Just add this line:
+
+```ruby
+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 🙂)
+- 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
@@ -125,17 +138,22 @@ due to the way feature resolving works in Ruby (scanning the `$LOAD_PATH` and ha
 
 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).
+### `ruby-next nextify`
+
+This command allows you to transpile a 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
+    -o, --output=OUTPUT              Specify output directory or file or stdout (use -o stdout for that)
+        --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)
+        --[no-]refine                Do not inject `using RubyNext`
+    -h, --help                       Print help
+    -V                               Turn on verbose mode
 ```
 
 The behaviour depends on whether you transpile a single file or a directory:
@@ -146,9 +164,53 @@ The behaviour depends on whether you transpile a single file or a directory:
 
 ```sh
 $ ruby-next nextify my_ruby.rb -o my_ruby_next.rb -V
+RubyNext core strategy: refine
 Generated: my_ruby_next.rb
 ```
 
+### `ruby-next core_ext`
+
+This command could be used to generate a Ruby file with a configurable set of core extensions.
+
+Use this command if you want to backport new Ruby features to Ruby implementations not compatible with RubyGems.
+
+It has the following interface:
+
+```sh
+$ ruby-next core_ext
+Usage: ruby-next core_ext [options]
+    -o, --output=OUTPUT              Specify output file or stdout (default: ./core_ext.rb)
+    -l, --list                       List all available extensions
+        --min-version=VERSION        Specify the minimum Ruby version to support
+    -n, --name=NAME                  Filter extensions by name
+    -h, --help                       Print help
+    -V                               Turn on verbose mode
+```
+
+The most common usecase 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
+ruby-next core_ext -n deconstruct -o pattern_matching_core_ext.rb
+```
+
+To list all available (are matching if `--min-version` or `--name` specified) monkey-patches, use the `-l` switch:
+
+```sh
+$ ruby-next core_ext -l --name=filter --name=deconstruct
+2.6 extensions:
+  - ArrayFilter
+  - EnumerableFilter
+  - HashFilter
+
+2.7 extensions:
+  - ArrayDeconstruct
+  - EnumerableFilterMap
+  - EnumeratorLazyFilterMap
+  - HashDeconstructKeys
+  - StructDeconstruct
+```
+
 ## Runtime mode
 
 It is also possible to transpile Ruby source code in run-time via Ruby Next.

data/bin/ruby-next

@@ -11,6 +11,6 @@ begin
 rescue => e
   raise e if $DEBUG
   STDERR.puts e.message
-  STDERR.puts e.backtrace.join("\n")
+  STDERR.puts e.backtrace.join("\n") if ENV["RUBY_NEXT_DEBUG"] == "1"
   exit 1
 end

data/lib/ruby-next/cli.rb

@@ -5,6 +5,7 @@ require "ruby-next/language"
 
 require "ruby-next/commands/base"
 require "ruby-next/commands/nextify"
+require "ruby-next/commands/core_ext"
 
 module RubyNext
   # Command line interface for RubyNext
@@ -16,7 +17,8 @@ module RubyNext
     self.verbose = false
 
     COMMANDS = {
-      "nextify" => Commands::Nextify
+      "nextify" => Commands::Nextify,
+      "core_ext" => Commands::CoreExt
     }.freeze
 
     def initialize
@@ -25,9 +27,15 @@ module RubyNext
     def run(args = ARGV)
       maybe_print_version(args)
 
-      command = args.shift
+      command = extract_command(args)
 
-      raise "Command must be specified!" unless command
+      # Handle top-level help
+      unless command
+        maybe_print_help
+        raise "Command must be specified!"
+      end
+
+      args.delete(command)
 
       COMMANDS.fetch(command) do
         raise "Unknown command: #{command}. Available commands: #{COMMANDS.keys.join(",")}"
@@ -39,6 +47,35 @@ module RubyNext
     def maybe_print_version(args)
       args = args.dup
       begin
+        optparser.parse!(args)
+      rescue OptionParser::InvalidOption
+        # skip and pass all args to the command's parser
+      end
+    end
+
+    def maybe_print_help
+      return unless @print_help
+
+      STDOUT.puts optparser.help
+      exit 0
+    end
+
+    def extract_command(source_args)
+      args = source_args.dup
+      unknown_args = []
+      command = nil
+      begin
+        command, = optparser.permute!(args)
+      rescue OptionParser::InvalidOption => e
+        unknown_args += e.args
+        args = source_args - unknown_args
+        retry
+      end
+      command
+    end
+
+    def optparser
+      @optparser ||= begin
         OptionParser.new do |opts|
           opts.banner = "Usage: ruby-next COMMAND [options]"
 
@@ -46,9 +83,11 @@ module RubyNext
             STDOUT.puts RubyNext::VERSION
             exit 0
           end
-        end.parse!(args)
-      rescue OptionParser::InvalidOption
-        # skip and pass all args to the command's parser
+
+          opts.on("-h", "--help", "Print help") do
+            @print_help = true
+          end
+        end
       end
     end
   end

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

@@ -0,0 +1,166 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "pathname"
+
+module RubyNext
+  module Commands
+    class CoreExt < Base
+      using RubyNext
+
+      attr_reader :out_path, :min_version, :names, :list, :filter, :original_command
+      alias list? list
+
+      def run
+        log "Select core extensions for Ruby v#{min_version}" \
+            "#{filter ? " and matching #{filter.inspect}" : ""}"
+
+        matching_patches.then do |patches|
+          next print_list(patches) if list?
+          generate_core_ext(patches)
+        end
+      end
+
+      def parse!(args)
+        print_help = false
+        @min_version = MIN_SUPPORTED_VERSION
+        @original_command = "ruby-next core_ext #{args.join(" ")}"
+        @names = []
+        @list = false
+        @out_path = File.join(Dir.pwd, "core_ext.rb")
+
+        optparser = base_parser do |opts|
+          opts.banner = "Usage: ruby-next core_ext [options]"
+
+          opts.on("-o", "--output=OUTPUT", "Specify output file or stdout (default: ./core_ext.rb)") do |val|
+            @out_path = val
+          end
+
+          opts.on("-l", "--list", "List all available extensions") do
+            @list = true
+          end
+
+          opts.on("--min-version=VERSION", "Specify the minimum Ruby version to support") do |val|
+            @min_version = Gem::Version.new(val)
+          end
+
+          opts.on("-n", "--name=NAME", "Filter extensions by name") do |val|
+            names << val
+          end
+
+          opts.on("-h", "--help", "Print help") do
+            print_help = true
+          end
+        end
+
+        optparser.parse!(args)
+
+        if print_help
+          $stdout.puts optparser.help
+          exit 0
+        end
+
+        @filter = /(#{names.join("|")})/i unless names.empty?
+      end
+
+      private
+
+      def matching_patches
+        RubyNext::Core.patches.extensions
+          .values
+          .flatten
+          .filter do |patch|
+          next if min_version && Gem::Version.new(patch.version) <= min_version
+          next if filter && !filter.match?(patch.name)
+          true
+        end
+      end
+
+      def print_list(patches)
+        grouped_patches = patches.group_by(&:version).sort_by(&:first)
+        grouped_patches.each do |(group, patches)|
+          $stdout.puts "#{group} extensions:\n"
+          $stdout.puts patches.sort_by(&:name).map { |patch| "  - #{patch.name}" }.join("\n")
+          $stdout.puts "\n"
+        end
+      end
+
+      def generate_core_ext(patches)
+        grouped_patches = patches.group_by(&:mod).sort_by { |(mod, patch)| mod.singleton_class? ? mod.inspect : mod.name }
+
+        buffer = []
+
+        buffer << "# frozen_string_literal: true\n"
+
+        buffer << generation_meta
+
+        grouped_patches.each do |mod, patches|
+          singleton = mod.singleton_class?
+          extend_name = singleton ? patches.first.singleton.name : mod.name
+          prepend_name = singleton ? "#{patches.first.singleton.name}.singleton_class" : mod.name
+
+          prepended, extended = patches.partition(&:prepend?)
+
+          prepended.map do |patch|
+            name = "RubyNext::Core::#{patch.name}"
+
+            buffer << <<~RUBY
+              module #{name}
+              #{indent_and_trim(patch.body)}
+              end
+
+              #{prepend_name}.prepend #{name}
+            RUBY
+
+            name
+          end
+
+          class_or_module = mod.is_a?(Class) ? "class" : "module"
+
+          buffer << "#{class_or_module} #{extend_name}"
+
+          buffer << "  class << self" if singleton
+
+          indent_size = singleton ? 4 : 2
+
+          buffer << extended.map do |patch|
+            indent_and_trim(patch.body, indent_size)
+          end.join("\n\n")
+
+          buffer << "  end" if singleton
+
+          buffer << "end\n"
+        end
+
+        contents = buffer.join("\n")
+
+        return $stdout.puts(contents) if out_path == "stdout"
+
+        FileUtils.mkdir_p File.dirname(out_path)
+        File.write(out_path, contents)
+
+        log "Generated: #{out_path}"
+      end
+
+      def generation_meta
+        <<~MSG
+          # Generated by RubyNext v#{RubyNext::VERSION} using the following command:
+          #
+          #   #{original_command}
+          #
+        MSG
+      end
+
+      def indent_and_trim(src, size = 2)
+        new_src = src.dup
+        # indent code using <size> spaces
+        new_src.gsub!(/^/, " " * size)
+        # remove empty lines
+        new_src.gsub!(/^\s+$/, "")
+        # remove traling blank lines
+        new_src.gsub!(/\n\z/, "")
+        new_src
+      end
+    end
+  end
+end

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

@@ -3,14 +3,15 @@
 require "fileutils"
 require "pathname"
 
-using RubyNext
-
 module RubyNext
   module Commands
     class Nextify < Base
+      using RubyNext
+
       attr_reader :lib_path, :paths, :out_path, :min_version, :single_version
 
       def run
+        log "RubyNext core strategy: #{RubyNext::Core.strategy}"
         paths.each do |path|
           contents = File.read(path)
           transpile path, contents
@@ -18,6 +19,7 @@ module RubyNext
       end
 
       def parse!(args)
+        print_help = false
         @min_version = MIN_SUPPORTED_VERSION
         @single_version = false
 
@@ -40,15 +42,28 @@ module RubyNext
             require "ruby-next/language/rewriters/method_reference"
             Language.rewriters << Language::Rewriters::MethodReference
           end
+
+          opts.on("--[no-]refine", "Do not inject `using RubyNext`") do |val|
+            Core.strategy = :core_ext unless val
+          end
+
+          opts.on("-h", "--help", "Print help") do
+            print_help = true
+          end
         end
 
         @lib_path = args[0]
 
-        unless lib_path&.then(&File.method(:exist?))
+        if print_help
           $stdout.puts optparser.help
           exit 0
         end
 
+        unless lib_path&.then(&File.method(:exist?))
+          $stdout.puts optparser.help
+          exit 2
+        end
+
         optparser.parse!(args)
 
         @paths =