Merge pull request #2632 from ruby/inline—instance-variables

Add instance variable declaration annotation

Author: soutaro

config.yml

@@ -497,3 +497,17 @@ nodes:
         c_type: rbs_location
       - name: comma_locations
         c_type: rbs_location_list
+  - name: RBS::AST::Ruby::Annotations::InstanceVariableAnnotation
+    fields:
+      - name: prefix_location
+        c_type: rbs_location
+      - name: ivar_name
+        c_type: rbs_ast_symbol
+      - name: ivar_name_location
+        c_type: rbs_location
+      - name: colon_location
+        c_type: rbs_location
+      - name: type
+        c_type: rbs_node
+      - name: comment_location
+        c_type: rbs_location

docs/inline.md

@@ -360,3 +360,31 @@ Modules accessible through ancestors (super-class/included modules) are not supp
 
 - Only single module arguments are supported (no `include A, B` syntax)
 - Module names must be constants
+
+## Instance Variables
+
+Inline RBS declaration allows defining instance variables.
+
+```ruby
+class Person
+  # @rbs @name: String
+  # @rbs @age: Integer? --
+  #   how old is the person?
+  #   `nil` means it's unspecified.
+
+  # @rbs (String name, Integer? age) -> void
+  def initialize(name, age)
+    @name = name
+    @age = age
+  end
+end
+```
+
+The `@rbs @VAR-NAME: TYPE` syntax enclosed in `class`/`module` syntax declares instance variables.
+You can add the documentation of the variable followed by two hyphones (`--`).
+
+Instance variable declarations must be under the `class`/`module` syntax, and they are ignored if written inside method definitions.
+
+### Current Limitations
+
+- Only instance variables of class/module instances are allowed

ext/rbs_extension/ast_translation.c

@@ -588,6 +588,24 @@ VALUE rbs_struct_to_ruby_value(rbs_translation_context_t ctx, rbs_node_t *instan
             &h
         );
     }
+    case RBS_AST_RUBY_ANNOTATIONS_INSTANCE_VARIABLE_ANNOTATION: {
+        rbs_ast_ruby_annotations_instance_variable_annotation_t *node = (rbs_ast_ruby_annotations_instance_variable_annotation_t *) instance;
+
+        VALUE h = rb_hash_new();
+        rb_hash_aset(h, ID2SYM(rb_intern("location")), rbs_loc_to_ruby_location(ctx, node->base.location));
+        rb_hash_aset(h, ID2SYM(rb_intern("prefix_location")), rbs_loc_to_ruby_location(ctx, node->prefix_location));
+        rb_hash_aset(h, ID2SYM(rb_intern("ivar_name")), rbs_struct_to_ruby_value(ctx, (rbs_node_t *) node->ivar_name)); // rbs_ast_symbol
+        rb_hash_aset(h, ID2SYM(rb_intern("ivar_name_location")), rbs_loc_to_ruby_location(ctx, node->ivar_name_location));
+        rb_hash_aset(h, ID2SYM(rb_intern("colon_location")), rbs_loc_to_ruby_location(ctx, node->colon_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_loc_to_ruby_location(ctx, node->comment_location));
+
+        return CLASS_NEW_INSTANCE(
+            RBS_AST_Ruby_Annotations_InstanceVariableAnnotation,
+            1,
+            &h
+        );
+    }
     case RBS_AST_RUBY_ANNOTATIONS_METHOD_TYPES_ANNOTATION: {
         rbs_ast_ruby_annotations_method_types_annotation_t *node = (rbs_ast_ruby_annotations_method_types_annotation_t *) instance;
 

ext/rbs_extension/class_constants.c

@@ -50,6 +50,7 @@ VALUE RBS_AST_Members_Prepend;
 VALUE RBS_AST_Members_Private;
 VALUE RBS_AST_Members_Public;
 VALUE RBS_AST_Ruby_Annotations_ColonMethodTypeAnnotation;
+VALUE RBS_AST_Ruby_Annotations_InstanceVariableAnnotation;
 VALUE RBS_AST_Ruby_Annotations_MethodTypesAnnotation;
 VALUE RBS_AST_Ruby_Annotations_NodeTypeAssertion;
 VALUE RBS_AST_Ruby_Annotations_ReturnTypeAnnotation;
@@ -136,6 +137,7 @@ void rbs__init_constants(void) {
     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_ColonMethodTypeAnnotation, RBS_AST_Ruby_Annotations, "ColonMethodTypeAnnotation");
+    IMPORT_CONSTANT(RBS_AST_Ruby_Annotations_InstanceVariableAnnotation, RBS_AST_Ruby_Annotations, "InstanceVariableAnnotation");
     IMPORT_CONSTANT(RBS_AST_Ruby_Annotations_MethodTypesAnnotation, RBS_AST_Ruby_Annotations, "MethodTypesAnnotation");
     IMPORT_CONSTANT(RBS_AST_Ruby_Annotations_NodeTypeAssertion, RBS_AST_Ruby_Annotations, "NodeTypeAssertion");
     IMPORT_CONSTANT(RBS_AST_Ruby_Annotations_ReturnTypeAnnotation, RBS_AST_Ruby_Annotations, "ReturnTypeAnnotation");

ext/rbs_extension/class_constants.h

@@ -56,6 +56,7 @@ extern VALUE RBS_AST_Members_Prepend;
 extern VALUE RBS_AST_Members_Private;
 extern VALUE RBS_AST_Members_Public;
 extern VALUE RBS_AST_Ruby_Annotations_ColonMethodTypeAnnotation;
+extern VALUE RBS_AST_Ruby_Annotations_InstanceVariableAnnotation;
 extern VALUE RBS_AST_Ruby_Annotations_MethodTypesAnnotation;
 extern VALUE RBS_AST_Ruby_Annotations_NodeTypeAssertion;
 extern VALUE RBS_AST_Ruby_Annotations_ReturnTypeAnnotation;

include/rbs/ast.h

@@ -46,43 +46,44 @@ enum rbs_node_type {
     RBS_AST_MEMBERS_PRIVATE = 30,
     RBS_AST_MEMBERS_PUBLIC = 31,
     RBS_AST_RUBY_ANNOTATIONS_COLON_METHOD_TYPE_ANNOTATION = 32,
-    RBS_AST_RUBY_ANNOTATIONS_METHOD_TYPES_ANNOTATION = 33,
-    RBS_AST_RUBY_ANNOTATIONS_NODE_TYPE_ASSERTION = 34,
-    RBS_AST_RUBY_ANNOTATIONS_RETURN_TYPE_ANNOTATION = 35,
-    RBS_AST_RUBY_ANNOTATIONS_SKIP_ANNOTATION = 36,
-    RBS_AST_RUBY_ANNOTATIONS_TYPE_APPLICATION_ANNOTATION = 37,
-    RBS_AST_STRING = 38,
-    RBS_AST_TYPE_PARAM = 39,
-    RBS_METHOD_TYPE = 40,
-    RBS_NAMESPACE = 41,
-    RBS_SIGNATURE = 42,
-    RBS_TYPE_NAME = 43,
-    RBS_TYPES_ALIAS = 44,
-    RBS_TYPES_BASES_ANY = 45,
-    RBS_TYPES_BASES_BOOL = 46,
-    RBS_TYPES_BASES_BOTTOM = 47,
-    RBS_TYPES_BASES_CLASS = 48,
-    RBS_TYPES_BASES_INSTANCE = 49,
-    RBS_TYPES_BASES_NIL = 50,
-    RBS_TYPES_BASES_SELF = 51,
-    RBS_TYPES_BASES_TOP = 52,
-    RBS_TYPES_BASES_VOID = 53,
-    RBS_TYPES_BLOCK = 54,
-    RBS_TYPES_CLASS_INSTANCE = 55,
-    RBS_TYPES_CLASS_SINGLETON = 56,
-    RBS_TYPES_FUNCTION = 57,
-    RBS_TYPES_FUNCTION_PARAM = 58,
-    RBS_TYPES_INTERFACE = 59,
-    RBS_TYPES_INTERSECTION = 60,
-    RBS_TYPES_LITERAL = 61,
-    RBS_TYPES_OPTIONAL = 62,
-    RBS_TYPES_PROC = 63,
-    RBS_TYPES_RECORD = 64,
-    RBS_TYPES_RECORD_FIELD_TYPE = 65,
-    RBS_TYPES_TUPLE = 66,
-    RBS_TYPES_UNION = 67,
-    RBS_TYPES_UNTYPED_FUNCTION = 68,
-    RBS_TYPES_VARIABLE = 69,
+    RBS_AST_RUBY_ANNOTATIONS_INSTANCE_VARIABLE_ANNOTATION = 33,
+    RBS_AST_RUBY_ANNOTATIONS_METHOD_TYPES_ANNOTATION = 34,
+    RBS_AST_RUBY_ANNOTATIONS_NODE_TYPE_ASSERTION = 35,
+    RBS_AST_RUBY_ANNOTATIONS_RETURN_TYPE_ANNOTATION = 36,
+    RBS_AST_RUBY_ANNOTATIONS_SKIP_ANNOTATION = 37,
+    RBS_AST_RUBY_ANNOTATIONS_TYPE_APPLICATION_ANNOTATION = 38,
+    RBS_AST_STRING = 39,
+    RBS_AST_TYPE_PARAM = 40,
+    RBS_METHOD_TYPE = 41,
+    RBS_NAMESPACE = 42,
+    RBS_SIGNATURE = 43,
+    RBS_TYPE_NAME = 44,
+    RBS_TYPES_ALIAS = 45,
+    RBS_TYPES_BASES_ANY = 46,
+    RBS_TYPES_BASES_BOOL = 47,
+    RBS_TYPES_BASES_BOTTOM = 48,
+    RBS_TYPES_BASES_CLASS = 49,
+    RBS_TYPES_BASES_INSTANCE = 50,
+    RBS_TYPES_BASES_NIL = 51,
+    RBS_TYPES_BASES_SELF = 52,
+    RBS_TYPES_BASES_TOP = 53,
+    RBS_TYPES_BASES_VOID = 54,
+    RBS_TYPES_BLOCK = 55,
+    RBS_TYPES_CLASS_INSTANCE = 56,
+    RBS_TYPES_CLASS_SINGLETON = 57,
+    RBS_TYPES_FUNCTION = 58,
+    RBS_TYPES_FUNCTION_PARAM = 59,
+    RBS_TYPES_INTERFACE = 60,
+    RBS_TYPES_INTERSECTION = 61,
+    RBS_TYPES_LITERAL = 62,
+    RBS_TYPES_OPTIONAL = 63,
+    RBS_TYPES_PROC = 64,
+    RBS_TYPES_RECORD = 65,
+    RBS_TYPES_RECORD_FIELD_TYPE = 66,
+    RBS_TYPES_TUPLE = 67,
+    RBS_TYPES_UNION = 68,
+    RBS_TYPES_UNTYPED_FUNCTION = 69,
+    RBS_TYPES_VARIABLE = 70,
     RBS_KEYWORD,
     RBS_AST_SYMBOL,
 };
@@ -406,6 +407,17 @@ typedef struct rbs_ast_ruby_annotations_colon_method_type_annotation {
     struct rbs_node *method_type;
 } rbs_ast_ruby_annotations_colon_method_type_annotation_t;
 
+typedef struct rbs_ast_ruby_annotations_instance_variable_annotation {
+    rbs_node_t base;
+
+    struct rbs_location *prefix_location;
+    struct rbs_ast_symbol *ivar_name;
+    struct rbs_location *ivar_name_location;
+    struct rbs_location *colon_location;
+    struct rbs_node *type;
+    struct rbs_location *comment_location;
+} rbs_ast_ruby_annotations_instance_variable_annotation_t;
+
 typedef struct rbs_ast_ruby_annotations_method_types_annotation {
     rbs_node_t base;
 
@@ -718,6 +730,7 @@ rbs_ast_members_prepend_t *rbs_ast_members_prepend_new(rbs_allocator_t *allocato
 rbs_ast_members_private_t *rbs_ast_members_private_new(rbs_allocator_t *allocator, rbs_location_t *location);
 rbs_ast_members_public_t *rbs_ast_members_public_new(rbs_allocator_t *allocator, rbs_location_t *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_t *location, rbs_location_t *prefix_location, rbs_node_list_t *annotations, rbs_node_t *method_type);
+rbs_ast_ruby_annotations_instance_variable_annotation_t *rbs_ast_ruby_annotations_instance_variable_annotation_new(rbs_allocator_t *allocator, rbs_location_t *location, rbs_location_t *prefix_location, rbs_ast_symbol_t *ivar_name, rbs_location_t *ivar_name_location, rbs_location_t *colon_location, rbs_node_t *type, rbs_location_t *comment_location);
 rbs_ast_ruby_annotations_method_types_annotation_t *rbs_ast_ruby_annotations_method_types_annotation_new(rbs_allocator_t *allocator, rbs_location_t *location, rbs_location_t *prefix_location, rbs_node_list_t *overloads, rbs_location_list_t *vertical_bar_locations);
 rbs_ast_ruby_annotations_node_type_assertion_t *rbs_ast_ruby_annotations_node_type_assertion_new(rbs_allocator_t *allocator, rbs_location_t *location, rbs_location_t *prefix_location, rbs_node_t *type);
 rbs_ast_ruby_annotations_return_type_annotation_t *rbs_ast_ruby_annotations_return_type_annotation_new(rbs_allocator_t *allocator, rbs_location_t *location, rbs_location_t *prefix_location, rbs_location_t *return_location, rbs_location_t *colon_location, rbs_node_t *return_type, rbs_location_t *comment_location);

lib/rbs/ast/ruby/annotations.rb

@@ -136,6 +136,31 @@ def map_type_name(&block)
             ) #: self
           end
         end
+
+        class InstanceVariableAnnotation < Base
+          attr_reader :ivar_name, :ivar_name_location, :colon_location, :type, :comment_location
+
+          def initialize(location:, prefix_location:, ivar_name:, ivar_name_location:, colon_location:, type:, comment_location:)
+            super(location, prefix_location)
+            @ivar_name = ivar_name
+            @ivar_name_location = ivar_name_location
+            @colon_location = colon_location
+            @type = type
+            @comment_location = comment_location
+          end
+
+          def map_type_name(&block)
+            self.class.new(
+              location:,
+              prefix_location:,
+              ivar_name:,
+              ivar_name_location:,
+              colon_location:,
+              type: type.map_type_name { yield _1 },
+              comment_location:
+            ) #: self
+          end
+        end
       end
     end
   end

lib/rbs/ast/ruby/members.rb

@@ -294,6 +294,27 @@ class AttrWriterMember < AttributeMember
 
         class AttrAccessorMember < AttributeMember
         end
+
+        class InstanceVariableMember < Base
+          attr_reader :annotation
+
+          def initialize(buffer, annotation)
+            super(buffer)
+            @annotation = annotation
+          end
+
+          def name
+            annotation.ivar_name
+          end
+
+          def type
+            annotation.type
+          end
+
+          def location
+            annotation.location
+          end
+        end
       end
     end
   end

lib/rbs/definition_builder.rb

@@ -155,7 +155,7 @@ def define_instance(definition, type_name, subst, define_class_vars:)
             member.names.each do |name|
               ivar_name = :"@#{name}"
               attr_type = member.type || Types::Bases::Any.new(location: nil)
-              
+
               insert_variable(
                 type_name,
                 definition.instance_variables,
@@ -165,6 +165,15 @@ def define_instance(definition, type_name, subst, define_class_vars:)
               )
             end
 
+          when AST::Ruby::Members::InstanceVariableMember
+            insert_variable(
+              type_name,
+              definition.instance_variables,
+              name: member.name,
+              type: member.type,
+              source: member
+            )
+
           when AST::Members::InstanceVariable
             insert_variable(
               type_name,
@@ -565,6 +574,7 @@ def insert_variable(type_name, variables, name:, type:, source:)
         declared_in: type_name,
         source: source
       )
+
       validate_variable(variables[name])
     end
 
@@ -575,7 +585,15 @@ def validate_variable(var)
       variables = [] #: Array[Definition::Variable]
       tmp_var = var
       while tmp_var
-        variables << tmp_var if tmp_var.source.is_a?(AST::Members::Var)
+        case tmp_var.source
+        when AST::Members::AttrReader, AST::Members::AttrWriter, AST::Members::AttrAccessor
+          # nop
+        when AST::Ruby::Members::AttrReaderMember, AST::Ruby::Members::AttrWriterMember, AST::Ruby::Members::AttrAccessorMember
+          # nop
+        else
+          variables << tmp_var
+        end
+
         tmp_var = tmp_var.parent_variable
       end
 
@@ -593,6 +611,10 @@ def validate_variable(var)
         if r.source.instance_of?(AST::Members::ClassInstanceVariable) && l.declared_in == r.declared_in
           raise ClassInstanceVariableDuplicationError.new(type_name: l.declared_in, variable_name: l.source.name, location: l.source.location)
         end
+      when AST::Ruby::Members::InstanceVariableMember
+        if l.declared_in == r.declared_in
+          raise InstanceVariableDuplicationError.new(type_name: l.declared_in, variable_name: l.source.name, location: l.source.location)
+        end
       end
     end
 

lib/rbs/environment.rb

@@ -378,11 +378,10 @@ def insert_ruby_decl(decl, context:, namespace:)
           if entry.is_a?(ModuleEntry)
             raise DuplicatedDeclarationError.new(name, decl, *entry.each_decl.to_a)
           end
+        else
+          entry = class_decls[name] = ClassEntry.new(name)
         end
 
-        entry = ClassEntry.new(name)
-        class_decls[name] = entry
-
         entry << [context, decl]
 
         inner_context = [context, name] #: Resolver::context
@@ -400,11 +399,10 @@ def insert_ruby_decl(decl, context:, namespace:)
           if entry.is_a?(ClassEntry)
             raise DuplicatedDeclarationError.new(name, decl, *entry.each_decl.to_a)
           end
+        else
+          entry = class_decls[name] = ModuleEntry.new(name)
         end
 
-        entry = ModuleEntry.new(name)
-        class_decls[name] = entry
-
         entry << [context, decl]
 
         inner_context = [context, name] #: Resolver::context
@@ -785,6 +783,12 @@ def resolve_ruby_member(resolver, member, context:)
           member.leading_comment,
           resolved_type_annotation
         )
+      when AST::Ruby::Members::InstanceVariableMember
+        resolved_annotation = member.annotation.map_type_name {|name| absolute_type_name(resolver, nil, name, context: context) }
+        AST::Ruby::Members::InstanceVariableMember.new(
+          member.buffer,
+          resolved_annotation
+        )
       else
         raise "Unknown member type: #{member.class}"
       end