Merge pull request #2875 from ruby/block-parameter

Add block parameter (`&block`) type declaration

Author: soutaro

config.yml

@@ -832,6 +832,29 @@ nodes:
       - name: comment_location
         c_type: rbs_location_range
         optional: true
+  - name: RBS::AST::Ruby::Annotations::BlockParamTypeAnnotation
+    rust_name: BlockParamTypeAnnotationNode
+    fields:
+      - name: prefix_location
+        c_type: rbs_location_range
+      - name: ampersand_location
+        c_type: rbs_location_range
+      - name: name_location
+        c_type: rbs_location_range
+        optional: true
+      - name: colon_location
+        c_type: rbs_location_range
+      - name: question_location
+        c_type: rbs_location_range
+        optional: true
+      - name: type_location
+        c_type: rbs_location_range
+      - name: type
+        c_name: type_
+        c_type: rbs_node
+      - name: comment_location
+        c_type: rbs_location_range
+        optional: true
 
 enums:
   attribute_visibility:

docs/inline.md

@@ -265,6 +265,24 @@ class Foo
 end
 ```
 
+Types of block parameter (`&block`) can be declared.
+
+```ruby
+class Foo
+  # @rbs &block: () -> void
+  def foo(&block)
+  end
+
+  # @rbs &: () -> void -- The parameter name can be omitted
+  def bar(&)
+  end
+
+  # @rbs &block: ? () -> untyped -- The `?` prefix is for optional block
+  def baz(&block)
+  end
+end
+```
+
 The `@rbs return: T` syntax declares the return type of a method:
 
 ```ruby

ext/rbs_extension/ast_translation.c

@@ -828,6 +828,26 @@ VALUE rbs_struct_to_ruby_value(rbs_translation_context_t ctx, rbs_node_t *instan
             &h
         );
     }
+    case RBS_AST_RUBY_ANNOTATIONS_BLOCK_PARAM_TYPE_ANNOTATION: {
+        rbs_ast_ruby_annotations_block_param_type_annotation_t *node = (rbs_ast_ruby_annotations_block_param_type_annotation_t *) instance;
+
+        VALUE h = rb_hash_new();
+        rb_hash_aset(h, ID2SYM(rb_intern("location")), rbs_location_range_to_ruby_location(ctx, node->base.location));
+        rb_hash_aset(h, ID2SYM(rb_intern("prefix_location")), rbs_location_range_to_ruby_location(ctx, node->prefix_location));
+        rb_hash_aset(h, ID2SYM(rb_intern("ampersand_location")), rbs_location_range_to_ruby_location(ctx, node->ampersand_location));
+        rb_hash_aset(h, ID2SYM(rb_intern("name_location")), rbs_location_range_to_ruby_location(ctx, node->name_location)); // optional
+        rb_hash_aset(h, ID2SYM(rb_intern("colon_location")), rbs_location_range_to_ruby_location(ctx, node->colon_location));
+        rb_hash_aset(h, ID2SYM(rb_intern("question_location")), rbs_location_range_to_ruby_location(ctx, node->question_location)); // optional
+        rb_hash_aset(h, ID2SYM(rb_intern("type_location")), rbs_location_range_to_ruby_location(ctx, node->type_location));
+        rb_hash_aset(h, ID2SYM(rb_intern("type")), rbs_struct_to_ruby_value(ctx, (rbs_node_t *) node->type_));                    // rbs_node
+        rb_hash_aset(h, ID2SYM(rb_intern("comment_location")), rbs_location_range_to_ruby_location(ctx, node->comment_location)); // optional
+
+        return CLASS_NEW_INSTANCE(
+            RBS_AST_Ruby_Annotations_BlockParamTypeAnnotation,
+            1,
+            &h
+        );
+    }
     case RBS_AST_RUBY_ANNOTATIONS_CLASS_ALIAS_ANNOTATION: {
         rbs_ast_ruby_annotations_class_alias_annotation_t *node = (rbs_ast_ruby_annotations_class_alias_annotation_t *) instance;
 

ext/rbs_extension/class_constants.c

@@ -47,6 +47,7 @@ VALUE RBS_AST_Members_MethodDefinition_Overload;
 VALUE RBS_AST_Members_Prepend;
 VALUE RBS_AST_Members_Private;
 VALUE RBS_AST_Members_Public;
+VALUE RBS_AST_Ruby_Annotations_BlockParamTypeAnnotation;
 VALUE RBS_AST_Ruby_Annotations_ClassAliasAnnotation;
 VALUE RBS_AST_Ruby_Annotations_ColonMethodTypeAnnotation;
 VALUE RBS_AST_Ruby_Annotations_DoubleSplatParamTypeAnnotation;
@@ -139,6 +140,7 @@ void rbs__init_constants(void) {
     IMPORT_CONSTANT(RBS_AST_Members_Prepend, RBS_AST_Members, "Prepend");
     IMPORT_CONSTANT(RBS_AST_Members_Private, RBS_AST_Members, "Private");
     IMPORT_CONSTANT(RBS_AST_Members_Public, RBS_AST_Members, "Public");
+    IMPORT_CONSTANT(RBS_AST_Ruby_Annotations_BlockParamTypeAnnotation, RBS_AST_Ruby_Annotations, "BlockParamTypeAnnotation");
     IMPORT_CONSTANT(RBS_AST_Ruby_Annotations_ClassAliasAnnotation, RBS_AST_Ruby_Annotations, "ClassAliasAnnotation");
     IMPORT_CONSTANT(RBS_AST_Ruby_Annotations_ColonMethodTypeAnnotation, RBS_AST_Ruby_Annotations, "ColonMethodTypeAnnotation");
     IMPORT_CONSTANT(RBS_AST_Ruby_Annotations_DoubleSplatParamTypeAnnotation, RBS_AST_Ruby_Annotations, "DoubleSplatParamTypeAnnotation");

ext/rbs_extension/class_constants.h

@@ -55,6 +55,7 @@ extern VALUE RBS_AST_Members_MethodDefinition_Overload;
 extern VALUE RBS_AST_Members_Prepend;
 extern VALUE RBS_AST_Members_Private;
 extern VALUE RBS_AST_Members_Public;
+extern VALUE RBS_AST_Ruby_Annotations_BlockParamTypeAnnotation;
 extern VALUE RBS_AST_Ruby_Annotations_ClassAliasAnnotation;
 extern VALUE RBS_AST_Ruby_Annotations_ColonMethodTypeAnnotation;
 extern VALUE RBS_AST_Ruby_Annotations_DoubleSplatParamTypeAnnotation;

include/rbs/ast.h

@@ -90,50 +90,51 @@ enum rbs_node_type {
     RBS_AST_MEMBERS_PREPEND = 29,
     RBS_AST_MEMBERS_PRIVATE = 30,
     RBS_AST_MEMBERS_PUBLIC = 31,
-    RBS_AST_RUBY_ANNOTATIONS_CLASS_ALIAS_ANNOTATION = 32,
-    RBS_AST_RUBY_ANNOTATIONS_COLON_METHOD_TYPE_ANNOTATION = 33,
-    RBS_AST_RUBY_ANNOTATIONS_DOUBLE_SPLAT_PARAM_TYPE_ANNOTATION = 34,
-    RBS_AST_RUBY_ANNOTATIONS_INSTANCE_VARIABLE_ANNOTATION = 35,
-    RBS_AST_RUBY_ANNOTATIONS_METHOD_TYPES_ANNOTATION = 36,
-    RBS_AST_RUBY_ANNOTATIONS_MODULE_ALIAS_ANNOTATION = 37,
-    RBS_AST_RUBY_ANNOTATIONS_NODE_TYPE_ASSERTION = 38,
-    RBS_AST_RUBY_ANNOTATIONS_PARAM_TYPE_ANNOTATION = 39,
-    RBS_AST_RUBY_ANNOTATIONS_RETURN_TYPE_ANNOTATION = 40,
-    RBS_AST_RUBY_ANNOTATIONS_SKIP_ANNOTATION = 41,
-    RBS_AST_RUBY_ANNOTATIONS_SPLAT_PARAM_TYPE_ANNOTATION = 42,
-    RBS_AST_RUBY_ANNOTATIONS_TYPE_APPLICATION_ANNOTATION = 43,
-    RBS_AST_STRING = 44,
-    RBS_AST_TYPE_PARAM = 45,
-    RBS_METHOD_TYPE = 46,
-    RBS_NAMESPACE = 47,
-    RBS_SIGNATURE = 48,
-    RBS_TYPE_NAME = 49,
-    RBS_TYPES_ALIAS = 50,
-    RBS_TYPES_BASES_ANY = 51,
-    RBS_TYPES_BASES_BOOL = 52,
-    RBS_TYPES_BASES_BOTTOM = 53,
-    RBS_TYPES_BASES_CLASS = 54,
-    RBS_TYPES_BASES_INSTANCE = 55,
-    RBS_TYPES_BASES_NIL = 56,
-    RBS_TYPES_BASES_SELF = 57,
-    RBS_TYPES_BASES_TOP = 58,
-    RBS_TYPES_BASES_VOID = 59,
-    RBS_TYPES_BLOCK = 60,
-    RBS_TYPES_CLASS_INSTANCE = 61,
-    RBS_TYPES_CLASS_SINGLETON = 62,
-    RBS_TYPES_FUNCTION = 63,
-    RBS_TYPES_FUNCTION_PARAM = 64,
-    RBS_TYPES_INTERFACE = 65,
-    RBS_TYPES_INTERSECTION = 66,
-    RBS_TYPES_LITERAL = 67,
-    RBS_TYPES_OPTIONAL = 68,
-    RBS_TYPES_PROC = 69,
-    RBS_TYPES_RECORD = 70,
-    RBS_TYPES_RECORD_FIELD_TYPE = 71,
-    RBS_TYPES_TUPLE = 72,
-    RBS_TYPES_UNION = 73,
-    RBS_TYPES_UNTYPED_FUNCTION = 74,
-    RBS_TYPES_VARIABLE = 75,
+    RBS_AST_RUBY_ANNOTATIONS_BLOCK_PARAM_TYPE_ANNOTATION = 32,
+    RBS_AST_RUBY_ANNOTATIONS_CLASS_ALIAS_ANNOTATION = 33,
+    RBS_AST_RUBY_ANNOTATIONS_COLON_METHOD_TYPE_ANNOTATION = 34,
+    RBS_AST_RUBY_ANNOTATIONS_DOUBLE_SPLAT_PARAM_TYPE_ANNOTATION = 35,
+    RBS_AST_RUBY_ANNOTATIONS_INSTANCE_VARIABLE_ANNOTATION = 36,
+    RBS_AST_RUBY_ANNOTATIONS_METHOD_TYPES_ANNOTATION = 37,
+    RBS_AST_RUBY_ANNOTATIONS_MODULE_ALIAS_ANNOTATION = 38,
+    RBS_AST_RUBY_ANNOTATIONS_NODE_TYPE_ASSERTION = 39,
+    RBS_AST_RUBY_ANNOTATIONS_PARAM_TYPE_ANNOTATION = 40,
+    RBS_AST_RUBY_ANNOTATIONS_RETURN_TYPE_ANNOTATION = 41,
+    RBS_AST_RUBY_ANNOTATIONS_SKIP_ANNOTATION = 42,
+    RBS_AST_RUBY_ANNOTATIONS_SPLAT_PARAM_TYPE_ANNOTATION = 43,
+    RBS_AST_RUBY_ANNOTATIONS_TYPE_APPLICATION_ANNOTATION = 44,
+    RBS_AST_STRING = 45,
+    RBS_AST_TYPE_PARAM = 46,
+    RBS_METHOD_TYPE = 47,
+    RBS_NAMESPACE = 48,
+    RBS_SIGNATURE = 49,
+    RBS_TYPE_NAME = 50,
+    RBS_TYPES_ALIAS = 51,
+    RBS_TYPES_BASES_ANY = 52,
+    RBS_TYPES_BASES_BOOL = 53,
+    RBS_TYPES_BASES_BOTTOM = 54,
+    RBS_TYPES_BASES_CLASS = 55,
+    RBS_TYPES_BASES_INSTANCE = 56,
+    RBS_TYPES_BASES_NIL = 57,
+    RBS_TYPES_BASES_SELF = 58,
+    RBS_TYPES_BASES_TOP = 59,
+    RBS_TYPES_BASES_VOID = 60,
+    RBS_TYPES_BLOCK = 61,
+    RBS_TYPES_CLASS_INSTANCE = 62,
+    RBS_TYPES_CLASS_SINGLETON = 63,
+    RBS_TYPES_FUNCTION = 64,
+    RBS_TYPES_FUNCTION_PARAM = 65,
+    RBS_TYPES_INTERFACE = 66,
+    RBS_TYPES_INTERSECTION = 67,
+    RBS_TYPES_LITERAL = 68,
+    RBS_TYPES_OPTIONAL = 69,
+    RBS_TYPES_PROC = 70,
+    RBS_TYPES_RECORD = 71,
+    RBS_TYPES_RECORD_FIELD_TYPE = 72,
+    RBS_TYPES_TUPLE = 73,
+    RBS_TYPES_UNION = 74,
+    RBS_TYPES_UNTYPED_FUNCTION = 75,
+    RBS_TYPES_VARIABLE = 76,
     RBS_AST_SYMBOL,
 };
 
@@ -562,6 +563,19 @@ typedef struct rbs_ast_members_public {
 
 } rbs_ast_members_public_t;
 
+typedef struct rbs_ast_ruby_annotations_block_param_type_annotation {
+    rbs_node_t base;
+
+    rbs_location_range prefix_location;
+    rbs_location_range ampersand_location;
+    rbs_location_range name_location; /* Optional */
+    rbs_location_range colon_location;
+    rbs_location_range question_location; /* Optional */
+    rbs_location_range type_location;
+    struct rbs_node *type_;
+    rbs_location_range comment_location; /* Optional */
+} rbs_ast_ruby_annotations_block_param_type_annotation_t;
+
 typedef struct rbs_ast_ruby_annotations_class_alias_annotation {
     rbs_node_t base;
 
@@ -959,6 +973,7 @@ rbs_ast_members_method_definition_overload_t *rbs_ast_members_method_definition_
 rbs_ast_members_prepend_t *rbs_ast_members_prepend_new(rbs_allocator_t *allocator, rbs_location_range location, rbs_type_name_t *name, rbs_node_list_t *args, rbs_node_list_t *annotations, rbs_ast_comment_t *comment, rbs_location_range name_range, rbs_location_range keyword_range);
 rbs_ast_members_private_t *rbs_ast_members_private_new(rbs_allocator_t *allocator, rbs_location_range location);
 rbs_ast_members_public_t *rbs_ast_members_public_new(rbs_allocator_t *allocator, rbs_location_range location);
+rbs_ast_ruby_annotations_block_param_type_annotation_t *rbs_ast_ruby_annotations_block_param_type_annotation_new(rbs_allocator_t *allocator, rbs_location_range location, rbs_location_range prefix_location, rbs_location_range ampersand_location, rbs_location_range name_location, rbs_location_range colon_location, rbs_location_range question_location, rbs_location_range type_location, rbs_node_t *type_, rbs_location_range comment_location);
 rbs_ast_ruby_annotations_class_alias_annotation_t *rbs_ast_ruby_annotations_class_alias_annotation_new(rbs_allocator_t *allocator, rbs_location_range location, rbs_location_range prefix_location, rbs_location_range keyword_location, rbs_type_name_t *type_name, rbs_location_range type_name_location);
 rbs_ast_ruby_annotations_colon_method_type_annotation_t *rbs_ast_ruby_annotations_colon_method_type_annotation_new(rbs_allocator_t *allocator, rbs_location_range location, rbs_location_range prefix_location, rbs_node_list_t *annotations, rbs_node_t *method_type);
 rbs_ast_ruby_annotations_double_splat_param_type_annotation_t *rbs_ast_ruby_annotations_double_splat_param_type_annotation_new(rbs_allocator_t *allocator, rbs_location_range location, rbs_location_range prefix_location, rbs_location_range star2_location, rbs_location_range name_location, rbs_location_range colon_location, rbs_node_t *param_type, rbs_location_range comment_location);

lib/rbs/ast/ruby/annotations.rb

@@ -325,6 +325,47 @@ def map_type_name(&block)
             ) #: self
           end
         end
+
+        class BlockParamTypeAnnotation < Base
+          attr_reader :ampersand_location, :name_location, :colon_location, :question_location, :type_location, :type, :comment_location
+
+          def initialize(location:, prefix_location:, ampersand_location:, name_location:, colon_location:, question_location:, type_location:, type:, comment_location:)
+            super(location, prefix_location)
+            @ampersand_location = ampersand_location
+            @name_location = name_location
+            @colon_location = colon_location
+            @question_location = question_location
+            @type_location = type_location
+            @type = type
+            @comment_location = comment_location
+          end
+
+          def map_type_name(&block)
+            self.class.new(
+              location:,
+              prefix_location:,
+              ampersand_location: ampersand_location,
+              name_location: name_location,
+              colon_location: colon_location,
+              question_location: question_location,
+              type_location: type_location,
+              type: type.map_type_name { yield _1 },
+              comment_location: comment_location
+            ) #: self
+          end
+
+          def name
+            name_location&.source&.to_sym
+          end
+
+          def optional?
+            question_location ? true : false
+          end
+
+          def required?
+            !optional?
+          end
+        end
       end
     end
   end