rbs 3.0.0.dev.2 → 3.0.0.dev.3

data/core/trace_point.rbs

@@ -114,7 +114,7 @@ class TracePoint < Object
 
   # <!--
   #   rdoc-file=trace_point.rb
-  #   - TracePoint.allow_reentry
+  #   - TracePoint.allow_reentry { block }
   # -->
   # In general, while a TracePoint callback is running, other registered callbacks
   # are not called to avoid confusion by reentrance. This method allows the
@@ -124,6 +124,54 @@ class TracePoint < Object
   # If this method is called when the reentrance is already allowed, it raises a
   # RuntimeError.
   #
+  # **Example:**
+  #
+  #     # Without reentry
+  #     # ---------------
+  #
+  #     line_handler = TracePoint.new(:line) do |tp|
+  #       next if tp.path != __FILE__ # only work in this file
+  #       puts "Line handler"
+  #       binding.eval("class C; end")
+  #     end.enable
+  #
+  #     class_handler = TracePoint.new(:class) do |tp|
+  #       puts "Class handler"
+  #     end.enable
+  #
+  #     class B
+  #     end
+  #
+  #     # This script will print "Class handler" only once: when inside :line
+  #     # handler, all other handlers are ignored
+  #
+  #     # With reentry
+  #     # ------------
+  #
+  #     line_handler = TracePoint.new(:line) do |tp|
+  #       next if tp.path != __FILE__ # only work in this file
+  #       next if (__LINE__..__LINE__+3).cover?(tp.lineno) # don't be invoked from itself
+  #       puts "Line handler"
+  #       TracePoint.allow_reentry { binding.eval("class C; end") }
+  #     end.enable
+  #
+  #     class_handler = TracePoint.new(:class) do |tp|
+  #       puts "Class handler"
+  #     end.enable
+  #
+  #     class B
+  #     end
+  #
+  #     # This wil print "Class handler" twice: inside allow_reentry block in :line
+  #     # handler, other handlers are enabled.
+  #
+  # Note that the example shows the principal effect of the method, but its
+  # practical usage is for debugging libraries that sometimes require other
+  # libraries hooks to not be affected by debugger being inside trace point
+  # handling. Precautions should be taken against infinite recursion in this case
+  # (note that we needed to filter out calls by itself from :line handler,
+  # otherwise it will call itself infinitely).
+  #
   def self.allow_reentry: () { () -> void } -> void
 
   # <!--
@@ -163,7 +211,7 @@ class TracePoint < Object
   # binding of the nearest Ruby method calling the C method, since C methods
   # themselves do not have bindings.
   #
-  def binding: () -> Binding
+  def binding: () -> Binding?
 
   # <!--
   #   rdoc-file=trace_point.rb
@@ -251,7 +299,7 @@ class TracePoint < Object
   # <!--
   #   rdoc-file=trace_point.rb
   #   - trace.enable(target: nil, target_line: nil, target_thread: nil)    -> true or false
-  #   - trace.enable(target: nil, target_line: nil, target_thread: nil) { block }  -> obj
+  #   - trace.enable(target: nil, target_line: nil, target_thread: :default) { block }  -> obj
   # -->
   # Activates the trace.
   #
@@ -264,15 +312,16 @@ class TracePoint < Object
   #     trace.enable    #=> true (previous state)
   #                     #   trace is still enabled
   #
-  # If a block is given, the trace will only be enabled within the scope of the
-  # block.
+  # If a block is given, the trace will only be enabled during the block call. If
+  # target and target_line are both nil, then target_thread will default to the
+  # current thread if a block is given.
   #
   #     trace.enabled?
   #     #=> false
   #
   #     trace.enable do
   #       trace.enabled?
-  #       # only enabled for this block
+  #       # only enabled for this block and thread
   #     end
   #
   #     trace.enabled?

data/core/unbound_method.rbs

@@ -46,6 +46,22 @@
 #     um.bind(t).call   #=> :original
 #
 class UnboundMethod
+  # <!--
+  #   rdoc-file=proc.c
+  #   - meth.eql?(other_meth)  -> true or false
+  #   - meth == other_meth  -> true or false
+  # -->
+  # Two unbound method objects are equal if they refer to the same method
+  # definition.
+  #
+  #     Array.instance_method(:each_slice) == Enumerable.instance_method(:each_slice)
+  #     #=> true
+  #
+  #     Array.instance_method(:sum) == Enumerable.instance_method(:sum)
+  #     #=> false, Array redefines the method for efficiency
+  #
+  def ==: (untyped) -> bool
+
   # <!--
   #   rdoc-file=proc.c
   #   - method.clone -> new_method
@@ -141,6 +157,38 @@ class UnboundMethod
   #
   def bind: (untyped obj) -> Method
 
+  # <!--
+  #   rdoc-file=proc.c
+  #   - meth.to_s      ->  string
+  #   - meth.inspect   ->  string
+  # -->
+  # Returns a human-readable description of the underlying method.
+  #
+  #     "cat".method(:count).inspect   #=> "#<Method: String#count(*)>"
+  #     (1..3).method(:map).inspect    #=> "#<Method: Range(Enumerable)#map()>"
+  #
+  # In the latter case, the method description includes the "owner" of the
+  # original method (`Enumerable` module, which is included into `Range`).
+  #
+  # `inspect` also provides, when possible, method argument names (call sequence)
+  # and source location.
+  #
+  #     require 'net/http'
+  #     Net::HTTP.method(:get).inspect
+  #     #=> "#<Method: Net::HTTP.get(uri_or_host, path=..., port=...) <skip>/lib/ruby/2.7.0/net/http.rb:457>"
+  #
+  # `...` in argument definition means argument is optional (has some default
+  # value).
+  #
+  # For methods defined in C (language core and extensions), location and argument
+  # names can't be extracted, and only generic information is provided in form of
+  # `*` (any number of arguments) or `_` (some positional argument).
+  #
+  #     "cat".method(:count).inspect   #=> "#<Method: String#count(*)>"
+  #     "cat".method(:+).inspect       #=> "#<Method: String#+(_)>""
+  #
+  def inspect: () -> String
+
   # <!--
   #   rdoc-file=proc.c
   #   - meth.name    -> symbol
@@ -188,30 +236,6 @@ class UnboundMethod
   def parameters: () -> ::Array[[ Symbol, Symbol ]]
                 | () -> ::Array[[ Symbol ]]
 
-  # <!--
-  #   rdoc-file=proc.c
-  #   - meth.private? -> true or false
-  # -->
-  # Returns whether the method is private.
-  #
-  def private?: () -> bool
-
-  # <!--
-  #   rdoc-file=proc.c
-  #   - meth.protected? -> true or false
-  # -->
-  # Returns whether the method is protected.
-  #
-  def protected?: () -> bool
-
-  # <!--
-  #   rdoc-file=proc.c
-  #   - meth.public? -> true or false
-  # -->
-  # Returns whether the method is public.
-  #
-  def public?: () -> bool
-
   # <!--
   #   rdoc-file=proc.c
   #   - meth.source_location  -> [String, Integer]

data/docs/collection.md

@@ -79,6 +79,10 @@ sources:
     revision: main
     repo_dir: gems
 
+  # You can also add a local path as a collection source optionaly.
+  - type: local
+    path: path/to/local/dir
+
 # A directory to install the downloaded RBSs
 path: .gem_rbs_collection
 

data/docs/syntax.md

@@ -501,6 +501,8 @@ private alias foo bar       # Syntax error
 ```markdown
 _decl_ ::= _class-decl_                         # Class declaration
          | _module-decl_                        # Module declaration
+         | _class-alias-decl_                   # Class alias declaration
+         | _module-alias-decl_                  # Module alias declaration
          | _interface-decl_                     # Interface declaration
          | _type-alias-decl_                    # Type alias declaration
          | _const-decl_                         # Constant declaration
@@ -512,6 +514,10 @@ _class-decl_ ::= `class` _class-name_ _module-type-parameters_ _members_ `end`
 _module-decl_ ::= `module` _module-name_ _module-type-parameters_ _members_ `end`
                 | `module` _module-name_ _module-type-parameters_ `:` _module-self-types_ _members_ `end`
 
+_class-alias-decl_ ::= `class` _class-name_ `=` _class-name_
+
+_module-alias-decl_ ::= `module` _module-name_ `=` _module-name_
+
 _module-self-types_ ::= _class-name_ _type-arguments_ `,` _module-self-types_            (Class instance)
                       | _interface-name_ _type-arguments_ `,` _module-self-types_        (Interface)
 
@@ -554,6 +560,32 @@ end
 
 The `Enumerable` module above requires `each` method for enumerating objects.
 
+### Class/module alias declaration
+
+An alias of a class or module can be defined in RBS.
+
+```rbs
+module Foo = Kernel
+
+class Bar = Array
+```
+
+The syntax defines a class and the definition is equivalent to the right-hand-side.
+
+```
+class Baz < Bar[String]    # Class alias can be inherited
+  include Foo              # Module alias can be included
+end
+```
+
+ This is a definition corresponding to the following Ruby code.
+
+ ```ruby
+ Foo = Kernel
+
+ Bar = Array
+ ```
+
 ### Interface declaration
 
 Interface declaration can have parameters but allows only a few of the members.
@@ -696,6 +728,29 @@ type int_printer = PrettyPrint[Integer]      # Type error
 
 The upper bound must be one of a class instance type, interface type, or class singleton type.
 
+### Directives
+
+Directives are placed at the top of a file and provides per-file-basis features.
+
+```
+_use-directive_ ::= `use` _use-clauses_
+
+_use-clauses_ ::= _use-clause_ `,` ... `,` _use-clause_
+
+_use-clause_ ::= _type-name_                           # Single use clause
+               | _type-name_ `as` _simple-type-name_   # Single use clause with alias
+               | _namespace_                           # Wildcard use clause
+```
+
+The *use directive* defines relative type names that is an alias of other type names.
+We can use the simple type names if it is declared with *use*.
+
+```
+use RBS::Namespace        # => Defines `Namespace`
+use RBS::TypeName as TN   # => Defines `TN`
+use RBS::AST::*           # => Defines modules under `::RBS::AST::` namespace
+```
+
 ### Comments
 
 You can write single line comments. Comments must be on their own line. Comments can lead with whitespace.

data/ext/rbs_extension/parser.c

@@ -2724,13 +2724,12 @@ VALUE parse_signature(parserstate *state) {
   VALUE dirs = rb_ary_new();
   VALUE decls = rb_ary_new();
 
+  while (state->next_token.type == kUSE) {
+    rb_ary_push(dirs, parse_use_directive(state));
+  }
+
   while (state->next_token.type != pEOF) {
-    if (state->next_token.type == kUSE) {
-      VALUE use = parse_use_directive(state);
-      rb_ary_push(dirs, use);
-    } else  {
-      rb_ary_push(decls, parse_decl(state));
-    }
+    rb_ary_push(decls, parse_decl(state));
   }
 
   VALUE ret = rb_ary_new();

data/lib/rbs/cli.rb

@@ -1076,11 +1076,16 @@ EOB
         config_path.write(<<~'YAML')
           # Download sources
           sources:
-            - name: ruby/gem_rbs_collection
+            - type: git
+              name: ruby/gem_rbs_collection
               remote: https://github.com/ruby/gem_rbs_collection.git
               revision: main
               repo_dir: gems
 
+          # You can specify local directories as sources also.
+          # - type: local
+          #   path: path/to/your/local/repository
+
           # A directory to install the downloaded RBSs
           path: .gem_rbs_collection
 

data/lib/rbs/collection/cleaner.rb

@@ -16,7 +16,14 @@ module RBS
           version or raise
           next if needed? gem_name, version
 
-          FileUtils.remove_entry_secure(dir.to_s)
+          case
+          when dir.symlink?
+            dir.unlink
+          when dir.directory?
+            FileUtils.remove_entry_secure(dir.to_s)
+          else
+            raise
+          end
         end
       end
 

data/lib/rbs/collection/config/lockfile.rb

@@ -75,7 +75,7 @@ module RBS
           if gems = data["gems"]
             gems.each do |gem|
               src = gem["source"]
-              source = Sources.from_config_entry(src)
+              source = Sources.from_config_entry(src, base_directory: lockfile_path.dirname)
               lockfile.gems[gem["name"]] = {
                 name: gem["name"],
                 version: gem["version"],
@@ -106,6 +106,8 @@ module RBS
               meta_path = fullpath.join(gem[:name], gem[:version], Sources::Git::METADATA_FILENAME)
               raise CollectionNotAvailable unless meta_path.exist?
               raise CollectionNotAvailable unless library_data(gem) == YAML.load(meta_path.read)
+            when Sources::Local
+              raise CollectionNotAvailable unless fullpath.join(gem[:name], gem[:version]).symlink?
             end
           end
         end

data/lib/rbs/collection/config/lockfile_generator.rb

@@ -105,27 +105,29 @@ module RBS
           unless locked
             source =
               if src_data
-                Sources.from_config_entry(src_data)
+                Sources.from_config_entry(src_data, base_directory: config.config_path.dirname)
               else
-                find_source(name: name) or return
+                find_source(name: name)
               end
 
-            installed_version = version
-            best_version = find_best_version(version: installed_version, versions: source.versions(name))
+            if source
+              installed_version = version
+              best_version = find_best_version(version: installed_version, versions: source.versions(name))
 
-            locked = {
-              name: name,
-              version: best_version.to_s,
-              source: source,
-            }
+              locked = {
+                name: name,
+                version: best_version.to_s,
+                source: source,
+              }
+            end
           end
 
-          locked or raise
-
-          lockfile.gems[name] = locked
+          if locked
+            lockfile.gems[name] = locked
 
-          locked[:source].dependencies_of(locked[:name], locked[:version])&.each do |dep|
-            assign_stdlib(name: dep["name"], from_gem: name)
+            locked[:source].dependencies_of(locked[:name], locked[:version])&.each do |dep|
+              assign_stdlib(name: dep["name"], from_gem: name)
+            end
           end
 
           gem_hash[name].dependencies.each do |dep|

data/lib/rbs/collection/config.rb

@@ -66,7 +66,7 @@ module RBS
       def sources
         @sources ||= (
           @data['sources']
-            .map { |c| Sources.from_config_entry(c) }
+            .map { |c| Sources.from_config_entry(c, base_directory: @config_path.dirname) }
             .push(Sources::Stdlib.instance)
             .push(Sources::Rubygems.instance)
         )

data/lib/rbs/collection/sources/git.rb

@@ -45,7 +45,12 @@ module RBS
 
           gem_dir = dest.join(name, version)
 
-          if gem_dir.directory?
+          case
+          when gem_dir.symlink?
+            stdout.puts "Updating to #{format_config_entry(name, version)} from a local source"
+            gem_dir.unlink
+            _install(dest: dest, name: name, version: version)
+          when gem_dir.directory?
             prev = load_metadata(dir: gem_dir)
 
             if prev == metadata_content(name: name, version: version)
@@ -55,9 +60,11 @@ module RBS
               FileUtils.remove_entry_secure(gem_dir.to_s)
               _install(dest: dest, name: name, version: version)
             end
-          else
+          when !gem_dir.exist?
             stdout.puts "Installing #{format_config_entry(name, version)}"
             _install(dest: dest, name: name, version: version)
+          else
+            raise
           end
         end
 

data/lib/rbs/collection/sources/local.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module RBS
+  module Collection
+    module Sources
+      class Local
+        include Base
+
+        attr_reader :path, :full_path
+  
+        def initialize(path:, base_directory:)
+          # TODO: resolve relative path from dir of rbs_collection.yaml
+          @path = Pathname(path)
+          @full_path = base_directory / path
+        end
+
+        def has?(name, version)
+          if version
+            @full_path.join(name, version).directory?
+          else
+            not versions(name).empty?
+          end
+        end
+
+        def versions(name)
+          @full_path.join(name).glob('*/').map { |path| path.basename.to_s }
+        end
+
+        # Create a symlink instead of copying file to refer files in @path.
+        # By avoiding copying RBS files, the users do not need re-run `rbs collection install`
+        # when the RBS files are updated.
+        def install(dest:, name:, version:, stdout:)
+          from = @full_path.join(name, version)
+          gem_dir = dest.join(name, version)
+
+          case
+          when gem_dir.symlink? && gem_dir.readlink == from
+            stdout.puts "Using #{name}:#{version} (#{from})"
+          when gem_dir.symlink?
+            prev = gem_dir.readlink
+            gem_dir.unlink
+            _install(from, dest.join(name, version))
+            stdout.puts "Updating #{name}:#{version} to #{from} from #{prev}"
+          when gem_dir.directory?
+            # TODO: Show version of git source
+            FileUtils.remove_entry_secure(gem_dir.to_s)
+            _install(from, dest.join(name, version))
+            stdout.puts "Updating #{name}:#{version} from git source"
+          when !gem_dir.exist?
+            _install(from, dest.join(name, version))
+            stdout.puts "Installing #{name}:#{version} (#{from})"
+          else
+            raise
+          end
+        end
+
+        private def _install(src, dst)
+          dst.dirname.mkpath
+          File.symlink(src, dst)
+        end
+
+        def manifest_of(name, version)
+          gem_dir = @full_path.join(name, version)
+          raise unless gem_dir.exist?
+
+          manifest_path = gem_dir.join('manifest.yaml')
+          YAML.safe_load(manifest_path.read) if manifest_path.exist?
+        end
+
+        def to_lockfile
+          {
+            'type' => 'local',
+            'path' => @path.to_s,
+          }
+        end
+      end
+    end
+  end
+end

data/lib/rbs/collection/sources.rb

@@ -4,11 +4,12 @@ require_relative './sources/base'
 require_relative './sources/git'
 require_relative './sources/stdlib'
 require_relative './sources/rubygems'
+require_relative './sources/local'
 
 module RBS
   module Collection
     module Sources
-      def self.from_config_entry(source_entry)
+      def self.from_config_entry(source_entry, base_directory:)
         case source_entry['type']
         when 'git', nil # git source by default
           # @type var source_entry: Git::source_entry
@@ -18,6 +19,12 @@ module RBS
             remote: source_entry["remote"],
             repo_dir: source_entry["repo_dir"]
           )
+        when 'local'
+          # @type var source_entry: Local::source_entry
+          Local.new(
+            path: source_entry['path'],
+            base_directory: base_directory,
+          )
         when 'stdlib'
           Stdlib.instance
         when 'rubygems'

data/lib/rbs/environment.rb

@@ -773,13 +773,14 @@ module RBS
       hash
     end
 
-    def reject
+    def unload(buffers)
       env = Environment.new
 
-      declarations.each do |decl|
-        unless yield(decl)
-          env << decl
-        end
+      buffers_decls.each do |buf, decls|
+        next if buffers.include?(buf)
+
+        dirs = buffer_directives.fetch(buf)
+        env.add_signature(buffer: buf, directives: dirs, decls: decls)
       end
 
       env

data/lib/rbs/environment_loader.rb

@@ -47,8 +47,9 @@ module RBS
       when path
         dirs << path
       when library
-        if library == 'rubygems'
-          RBS.logger.warn '`rubygems` has been moved to core library, so it is always loaded. Remove explicit loading `rubygems`'
+        case library
+        when 'rubygems', 'set'
+          RBS.logger.warn "`#{library}` has been moved to core library, so it is always loaded. Remove explicit loading `#{library}`"
           return
         end
 

data/lib/rbs/errors.rb

@@ -20,7 +20,25 @@ module RBS
   class LoadingError < BaseError; end
   class DefinitionError < BaseError; end
 
+  module DetailedMessageable
+    def detailed_message(highlight: false, **)
+      indent = " " * location.start_column
+      marker = "^" * (location.end_column - location.start_column)
+
+      io = StringIO.new
+      io.puts super
+      io.puts
+      io.print "\e[1m" if highlight
+      io.puts "  #{location.buffer.lines[location.end_line - 1]}"
+      io.puts "  #{indent}#{marker}"
+      io.print "\e[m" if highlight
+      io.string
+    end
+  end
+
   class ParsingError < BaseError
+    include DetailedMessageable
+
     attr_reader :location
     attr_reader :error_message
     attr_reader :token_type

data/lib/rbs/locator.rb

@@ -2,21 +2,24 @@
 
 module RBS
   class Locator
-    attr_reader :decls
+    attr_reader :decls, :dirs, :buffer
 
-    def initialize(decls:)
+    def initialize(buffer:, dirs:, decls:)
+      @buffer = buffer
+      @dirs = dirs
       @decls = decls
     end
 
-    def buffer
-      decls[0].location&.buffer or raise
-    end
-
     def find(line:, column:)
       pos = buffer.loc_to_pos([line, column])
 
+      dirs.each do |dir|
+        array = [] #: Array[component]
+        find_in_directive(pos, dir, array) and return array
+      end
+
       decls.each do |decl|
-        array = []
+        array = [] #: Array[component]
         find_in_decl(pos, decl: decl, array: array) and return array
       end
 
@@ -36,6 +39,22 @@ module RBS
       end
     end
 
+    def find_in_directive(pos, dir, array)
+      if test_loc(pos, location: dir.location)
+        array.unshift(dir)
+
+        dir.clauses.each do |clause|
+          if test_loc(pos, location: clause.location)
+            array.unshift(clause)
+            find_in_loc(pos, location: clause.location, array: array)
+            return true
+          end
+        end
+      end
+
+      false
+    end
+
     def find_in_decl(pos, decl:, array:)
       if test_loc(pos, location: decl.location)
         array.unshift(decl)

data/lib/rbs/sorter.rb

@@ -34,7 +34,7 @@ module RBS
         -3
       when Declarations::Constant
         -2
-      when Declarations::Class, Declarations::Module
+      when Declarations::Class, Declarations::Module, Declarations::Interface
         -1
       when Members::Include
         0.0
@@ -102,7 +102,7 @@ module RBS
         member.name.to_s
       when Declarations::TypeAlias
         member.name.to_s
-      when Declarations::Class, Declarations::Module
+      when Declarations::Class, Declarations::Module, Declarations::Interface
         member.name.to_s
       else
         raise