rbs 3.0.0.dev.1 → 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/constants.c

@@ -10,7 +10,7 @@ VALUE RBS_AST_TypeParam;
 
 VALUE RBS_AST_Declarations;
 
-VALUE RBS_AST_Declarations_Alias;
+VALUE RBS_AST_Declarations_TypeAlias;
 VALUE RBS_AST_Declarations_Constant;
 VALUE RBS_AST_Declarations_Global;
 VALUE RBS_AST_Declarations_Interface;
@@ -18,6 +18,13 @@ VALUE RBS_AST_Declarations_Module;
 VALUE RBS_AST_Declarations_Module_Self;
 VALUE RBS_AST_Declarations_Class;
 VALUE RBS_AST_Declarations_Class_Super;
+VALUE RBS_AST_Declarations_ModuleAlias;
+VALUE RBS_AST_Declarations_ClassAlias;
+
+VALUE RBS_AST_Directives;
+VALUE RBS_AST_Directives_Use;
+VALUE RBS_AST_Directives_Use_SingleClause;
+VALUE RBS_AST_Directives_Use_WildcardClause;
 
 VALUE RBS_AST_Members;
 VALUE RBS_AST_Members_Alias;
@@ -80,7 +87,7 @@ void rbs__init_constants(void) {
 
   RBS_AST_Declarations = rb_const_get(RBS_AST, rb_intern("Declarations"));
 
-  RBS_AST_Declarations_Alias = rb_const_get(RBS_AST_Declarations, rb_intern("Alias"));
+  RBS_AST_Declarations_TypeAlias = rb_const_get(RBS_AST_Declarations, rb_intern("TypeAlias"));
   RBS_AST_Declarations_Constant = rb_const_get(RBS_AST_Declarations, rb_intern("Constant"));
   RBS_AST_Declarations_Global = rb_const_get(RBS_AST_Declarations, rb_intern("Global"));
   RBS_AST_Declarations_Interface = rb_const_get(RBS_AST_Declarations, rb_intern("Interface"));
@@ -88,6 +95,13 @@ void rbs__init_constants(void) {
   RBS_AST_Declarations_Module_Self = rb_const_get(RBS_AST_Declarations_Module, rb_intern("Self"));
   RBS_AST_Declarations_Class = rb_const_get(RBS_AST_Declarations, rb_intern("Class"));
   RBS_AST_Declarations_Class_Super = rb_const_get(RBS_AST_Declarations_Class, rb_intern("Super"));
+  RBS_AST_Declarations_ClassAlias = rb_const_get(RBS_AST_Declarations, rb_intern("ClassAlias"));
+  RBS_AST_Declarations_ModuleAlias = rb_const_get(RBS_AST_Declarations, rb_intern("ModuleAlias"));
+
+  RBS_AST_Directives = rb_const_get(RBS_AST, rb_intern("Directives"));
+  RBS_AST_Directives_Use = rb_const_get(RBS_AST_Directives, rb_intern("Use"));
+  RBS_AST_Directives_Use_SingleClause = rb_const_get(RBS_AST_Directives_Use, rb_intern("SingleClause"));
+  RBS_AST_Directives_Use_WildcardClause = rb_const_get(RBS_AST_Directives_Use, rb_intern("WildcardClause"));
 
   RBS_AST_Members = rb_const_get(RBS_AST, rb_intern("Members"));
   RBS_AST_Members_Alias = rb_const_get(RBS_AST_Members, rb_intern("Alias"));

data/ext/rbs_extension/constants.h

@@ -9,7 +9,7 @@ extern VALUE RBS_AST_Comment;
 extern VALUE RBS_AST_TypeParam;
 
 extern VALUE RBS_AST_Declarations;
-extern VALUE RBS_AST_Declarations_Alias;
+extern VALUE RBS_AST_Declarations_TypeAlias;
 extern VALUE RBS_AST_Declarations_Class_Super;
 extern VALUE RBS_AST_Declarations_Class;
 extern VALUE RBS_AST_Declarations_Constant;
@@ -17,6 +17,13 @@ extern VALUE RBS_AST_Declarations_Global;
 extern VALUE RBS_AST_Declarations_Interface;
 extern VALUE RBS_AST_Declarations_Module_Self;
 extern VALUE RBS_AST_Declarations_Module;
+extern VALUE RBS_AST_Declarations_ModuleAlias;
+extern VALUE RBS_AST_Declarations_ClassAlias;
+
+extern VALUE RBS_AST_Directives;
+extern VALUE RBS_AST_Directives_Use;
+extern VALUE RBS_AST_Directives_Use_SingleClause;
+extern VALUE RBS_AST_Directives_Use_WildcardClause;
 
 extern VALUE RBS_AST_Members;
 extern VALUE RBS_AST_Members_Alias;

data/ext/rbs_extension/extconf.rb

@@ -1,4 +1,4 @@
 require 'mkmf'
 $INCFLAGS << " -I$(top_srcdir)" if $extmk
-append_cflags ['-std=c99']
+append_cflags ['-std=gnu99']
 create_makefile 'rbs_extension'