rbs 1.8.0 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9b12d92ea4eeeb5dbd6de6c5d58351b0306bdcd017d0f1e51a36599766bfded3
-  data.tar.gz: d60cfb836027441a5bb3f85fbebb0e2ab9bc03c49a21f00c3f10d4ab8dd1de65
+  metadata.gz: f6c23428bebbddb53710d5f77761d75bdcafa38d988b9fdc62b20563ff3eb60a
+  data.tar.gz: 65c065d547aed025238d0350800830e31e18a3fcd21db73406a7374202517b80
 SHA512:
-  metadata.gz: 9ef926a62415189173d41204d1a16674a4a8331e3fdefafe00a4e52c9cbf0f3eb84281194a5b5c43027455334c13ea0ab14e1b3f0a6b8d5f5644cb80733a246b
-  data.tar.gz: ce07016eee6b4142a66a28d8c7ffc356b3d4fdd747027f2dd521b347efcb6ac791385e903a1e3b9f8d468ec66e13995e341516137ceba990db511982c6d0d206
+  metadata.gz: c0fbada9d621cb2e1cd2a3793ad208d78a50f826c1c58e03eb5d256f8e6fa024446549f2943c85e37dc0ad1170672b66651dab66d5f8eb3d0a0f9b5757e9315e
+  data.tar.gz: 505fcfdf431ac0c904325494157fab4c5b1855b200ba1d416be0cf3680c173ac302517eb99a93d6657a0344a1fa198a2455498fec493f6b240a96d7b8cddf994

data/CHANGELOG.md

@@ -2,9 +2,87 @@
 
 ## master
 
+## 2.0.0 (2021-12-24)
+
+### Bounded Generics
+
+RBS 2.0 ships with _bounded generics_, which improves the expressiveness of the language by adding a new syntax to define constraints on type parameters.
+
+```rbs
+class PrettyPrint[T < _Output]
+  interface _Output
+    def <<: (String) -> void
+  end
+
+  attr_reader output: T
+
+  def initialize: (T output) -> void
+end
+```
+
+This is the motivating example I found in the [prettyprint library](https://github.com/ruby/prettyprint).
+The `#initialize` receives a object of type `T` and it must have `#<<` method.
+This is defined with `< _Output` syntax in the example.
+It means _`T` has to be compatible with `_Output` interface._
+`PrettyPrint[String]` is okay, but `PrettyPrint[Integer]` is a type error.
+
+See [the PR for details](https://github.com/ruby/rbs/pull/844).
+
+### RBS Collection manager
+
+RBS Collection feature is generally available on RBS 2.0. In short, it is Bundler for RBS. You can manage RBSs of standard libraries and third party gems with `rbs collection` subcommand.
+
+```bash
+$ rbs collection init
+created: rbs_collection.yaml
+
+# The `install` command set up RBS files and creates `rbs_collection.lock.yaml` file
+$ rbs collection install
+Installing actionpack:6.0 (actionpack@ce6664cec73)
+(...snip...)
+Using tsort:0 (/path/to/rbs-2.0.0/stdlib/tsort/0)
+It's done! 21 gems' RBSs now installed.
+
+# Now you can use `rbs`, `typeprof` and `steep` commands with the dependencies out of the box!
+$ rbs validate
+$ typeprof app.rb
+$ steep check
+```
+
+RBS 2.0 also introduces `manifest.yaml` to declare the dependencies from your gems to standard libraries explicitly.
+See [the documentation](https://github.com/ruby/rbs/blob/master/docs/collection.md) for more information.
+
+### Breaking changes
+
+This version contains a bug fix, which potentially breaks the compatibility with older versions.
+The super class names in class definitions are now resolved in _outer_ context.
+It was an incompatibility with Ruby and [this PR](https://github.com/ruby/rbs/pull/856) fixed the problem.
+
+### Signature updates
+
+* uri ([\#846](https://github.com/ruby/rbs/pull/846), [\#852](https://github.com/ruby/rbs/pull/852), [\#851](https://github.com/ruby/rbs/pull/851), [\#850](https://github.com/ruby/rbs/pull/850), [#849](https://github.com/ruby/rbs/pull/849))
+
+### Language updates
+
+* Bounded generics ([\#844](https://github.com/ruby/rbs/pull/844))
+* Resolve super type names in outer context ([\#856](https://github.com/ruby/rbs/pull/856))
+
+### Library changes
+
+* Add `manifest.yaml` for collection to specify stdlib dependencies ([\#808](https://github.com/ruby/rbs/pull/808))
+* Remove experimental warning of `rbs collection` ([\#855](https://github.com/ruby/rbs/pull/855))
+* Add the utility `#map_type` methods ([\#841](https://github.com/ruby/rbs/pull/841))
+
+## 1.8.1 (2021-12-13)
+
+### Library changes
+
+* Validate `extend` arguments ([\#840](https://github.com/ruby/rbs/pull/840))
+* Allow a relative path as git remote in collection ([\#839](https://github.com/ruby/rbs/pull/839))
+
 ## 1.8.0 (2021-12-02)
 
-RBS 1.8.0 ships with a language feature enchancement, _generic type alias_.
+RBS 1.8.0 ships with a language feature enhancement, _generic type alias_.
 You can define a type alias with type parameters now.
 
 ```rbs
@@ -45,7 +123,7 @@ You can find the detail in the [PR](https://github.com/ruby/rbs/pull/823).
 This version replaces `RBS::Parser` implementation from pure Ruby code based on [Racc](https://github.com/ruby/racc) to C extension.
 It improves the RBS file parsing performance up to 5 times faster. :rocket:
 
-* There are some incompatibilties to drop obsolete syntax rules: `super` keyword and `any` type are no longer supported.
+* There are some incompatibilities to drop obsolete syntax rules: `super` keyword and `any` type are no longer supported.
 * [re2c](https://github.com/skvadrik/re2c) is used to generate lexical generator.
 
 When you want to change the parser/lexer, change the files under `ext/rbs_extension` directory and run `rake compile` to compile the extension.
@@ -158,7 +236,7 @@ This release includes feature enhancements including recursive `type` definition
 
 ### Library changes
 
-* Add Recursiive type alias defnition validation ([\#719](https://github.com/ruby/rbs/pull/719))
+* Add Recursive type alias definition validation ([\#719](https://github.com/ruby/rbs/pull/719))
 * Generate included modules with complete name ([\#731](https://github.com/ruby/rbs/pull/731))
 * Fix `rbs-prototype-rb` error when multi assign with const ([\#740](https://github.com/ruby/rbs/pull/740))
 
@@ -186,7 +264,7 @@ This release is to fix a bug introduced by parser update in 1.3.0.
 
 ### Summary
 
-RBS 1.3.0 includes bug fixees of the parser and class/module definition validations.
+RBS 1.3.0 includes bug fixes of the parser and class/module definition validations.
 
 ### Signature updates
 

data/docs/collection.md

@@ -7,7 +7,6 @@
 * `git(1)`
 * `Gemfile.lock`
 
-
 ## Usage
 
 ### Setup
@@ -65,9 +64,13 @@ Finally the third party RBSs are available! `rbs` commands, such as `rbs validat
 
 ## Configuration
 
+### `rbs_collection.yaml`
+
 Configure `rbs collection` with editing `rbs_collection.yaml`.
 
 ```yaml
+# rbs_collection.yaml
+
 # Download sources.
 # You can add own collection git repository.
 sources:
@@ -92,6 +95,25 @@ gems:
     ignore: true
 ```
 
+### `manifest.yaml`
+
+If you are a gem maintainer, you can write `manifest.yaml`.
+You need to put the file if the gem has implicit dependencies, which don't appear in `Gemfile.lock`. You have to write standard libraries' dependencies in most cases.
+For example:
+
+```yaml
+# manifest.yaml
+
+dependencies:
+  # If your gem depends on pathname but the gemspec doesn't include pathname,
+  # you need to write the following.
+  - name: pathname
+```
+
+If the gem's RBS is managed with [ruby/gem_rbs_collection](https://github.com/ruby/gem_rbs_collection), put it as `gems/GEM_NAME/VERSION/manifest.yaml`.  For example, `gems/activesupport/6.0/manifest.yaml`.
+If the gem's RBS is included in the gem package, put it as `sig/manifest.yaml`.
+
+
 ## Files / Directories
 
 * `rbs_collection.yaml`

data/docs/syntax.md

@@ -288,12 +288,12 @@ _method-member_ ::= `def` _method-name_ `:` _method-types_            # Instance
                   | `def self.` _method-name_ `:` _method-types_      # Singleton method
                   | `def self?.` _method-name_ `:` _method-types_     # Singleton and instance method
 
-_method-types_ ::=                                                       # Empty
-                 | _type-parameters_ _method-type_ `|` _method-types_    # Overloading types
-                 | `...`                                                 # Overloading for duplicate definitions
+_method-types_ ::= _method-type-parameters_ _method-type_                       # Single method type
+                 | _method-type-parameters_ _method-type_ `|` _method-types_    # Overloading types
+                 | `...`                                                        # Overloading for duplicate definitions
 
-_type-parameters_ ::=                                                 # Empty
-                    | `[` _type-variable_ `,` etc. `]`
+_method-type-parameters_ ::=                                                    # Empty
+                           | `[` _type-variable_ `,` ... `]`
 
 _attribute-member_ ::= _attribute-type_ _method-name_ `:` _type_                     # Attribute
                      | _attribute-type_ _method-name_ `(` _ivar-name_ `) :` _type_   # Attribute with variable name specification
@@ -443,48 +443,13 @@ _const-name_ ::= _namespace_ /[A-Z]\w*/
 _global-name_ ::= /$[a-zA-Z]\w+/ | ...
 
 _module-type-parameters_ ::=                                                  # Empty
-                           | `[` _module-type-parameter_ `,` etc. `]`
-
-_module-type-parameter_ ::= _check_ _variance_ _type-variable_
-_variance_ ::= `out` | `in`
-_check_ ::= # Empty
-          | `unchecked`
+                           | `[` _module-type-parameter_ `,` ... `]`
 ```
 
 ### Class declaration
 
 Class declaration can have type parameters and superclass. When you omit superclass, `::Object` is assumed.
 
-```
-class Ref[A] < Object
-  attr_reader value: A
-  def initialize: (value: A) -> void
-end
-```
-
-For classes with type parameters, you may specify if they are "invariant" (default), "covariant" (`out`) or "contravariant" (`in`). See [this definition of covariance and contravariance](https://en.wikipedia.org/wiki/Covariance_and_contravariance_(computer_science)).
-
-For example, an `Array` of `String` can almost be considered to be an `Array` of `Object`, but not the reverse, so we can think of:
-
-```
-class Array[out T]
-  # etc.
-end
-```
-
-There's a limitation with this is for mutable objects (like arrays): a mutation could invalidate this.
-If an array of String is passed to a method as an array of Objects, and that method adds an Integer to the array, the promise is broken.
-
-In those cases, one must use the `unchecked` keyword:
-
-```
-class Array[unchecked out T]
-  # etc.
-end
-```
-
-This is how `Array` is actually defined in RBS.
-
 ### Module declaration
 
 Module declaration takes optional _self type_ parameter, which defines a constraint about a class when the module is mixed.
@@ -555,6 +520,94 @@ You can declare a global variable.
 $LOAD_PATH: Array[String]
 ```
 
+### Generics
+
+```md
+_module-type-parameter_ ::= _generics-unchecked_ _generics-variance_ _type-variable_ _generics-bound_
+
+_method-type-param_ ::= _type-variable_ _generics-bound_
+
+_generics-bound_ ::=                       (No type bound)
+                   | `<` _bound-type_      (The generics parameter is bounded)
+
+_bound-type_ ::= _class-name_ _type-arguments_       (Class instance type)
+              | _interface-name_ _type-arguments_    (Interface type)
+              | `singleton(` _class-name_ `)`        (Class singleton type)
+
+_generics-variance_ ::=               (Invariant)
+                      | `out`         (Covariant)
+                      | `in`          (Contravariant)
+
+_generics-unchecked_ ::=              (Empty)
+                       | `unchecked`  (Skips variance annotation validation)
+```
+
+RBS allows class/module/interface/type alias definitions and methods to be generic.
+
+```rbs
+# Simple generic class definition
+class Stack[T]
+  def push: (T) -> void
+
+  def pop: () -> T
+end
+```
+
+For classes with type parameters, you may specify if they are "invariant" (default), "covariant" (`out`) or "contravariant" (`in`). See [this definition of covariance and contravariance](https://en.wikipedia.org/wiki/Covariance_and_contravariance_(computer_science)).
+
+For example, an `Array` of `String` can almost be considered to be an `Array` of `Object`, but not the reverse, so we can think of:
+
+```
+# The `T` type parameter is covariant.
+class Array[out T]
+  # etc.
+end
+```
+
+There's a limitation with this is for mutable objects (like arrays): a mutation could invalidate this.
+If an array of `String` is passed to a method as an array of `Objects`, and that method adds an Integer to the array, the promise is broken.
+
+In those cases, one must use the `unchecked` keyword:
+
+```rbs
+# Skips the validation of variance of the type parameter `T`.
+# The type safety prohibits `out` type parameters to appear at _negative_ position (== method parameter), but we want `Array` to have it.
+class Array[unchecked out T]
+  def include?: (T) -> bool
+end
+```
+
+This is how `Array` is actually defined in RBS.
+
+Note that RBS doesn't allow specifying variance related annotations to generic method types.
+
+```rbs
+class Foo
+  def bar: [out T] () -> T    # Syntax error
+end
+```
+
+You can also specify the _upper bound_ of the type parameter.
+
+```rbs
+class PrettyPrint[T < _Output]
+  interface _Output
+    def <<: (String) -> void
+  end
+
+  attr_reader output: T
+end
+```
+
+If a type parameter has an upper bound, the type parameter must be instantiated with types that is a subclass of the upper bound.
+
+```rbs
+type str_printer = PrettyPrint[String]    # OK
+type int_printer = PrettyPrint[Integer]      # Type error
+```
+
+The upper bound must be one of a class instance type, interface type, or class singleton type.
+
 ### 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

@@ -6,12 +6,10 @@ VALUE RBS;
 VALUE RBS_AST;
 VALUE RBS_AST_Comment;
 VALUE RBS_AST_Annotation;
+VALUE RBS_AST_TypeParam;
 
 VALUE RBS_AST_Declarations;
 
-VALUE RBS_AST_Declarations_ModuleTypeParams;
-VALUE RBS_AST_Declarations_ModuleTypeParams_TypeParam;
-
 VALUE RBS_AST_Declarations_Alias;
 VALUE RBS_AST_Declarations_Constant;
 VALUE RBS_AST_Declarations_Global;
@@ -77,12 +75,10 @@ void rbs__init_constants() {
   RBS_AST = rb_const_get(RBS, rb_intern("AST"));
   RBS_AST_Comment = rb_const_get(RBS_AST, rb_intern("Comment"));
   RBS_AST_Annotation = rb_const_get(RBS_AST, rb_intern("Annotation"));
+  RBS_AST_TypeParam = rb_const_get(RBS_AST, rb_intern("TypeParam"));
 
   RBS_AST_Declarations = rb_const_get(RBS_AST, rb_intern("Declarations"));
 
-  RBS_AST_Declarations_ModuleTypeParams = rb_const_get(RBS_AST_Declarations, rb_intern("ModuleTypeParams"));
-  RBS_AST_Declarations_ModuleTypeParams_TypeParam = rb_const_get(RBS_AST_Declarations_ModuleTypeParams, rb_intern("TypeParam"));
-
   RBS_AST_Declarations_Alias = rb_const_get(RBS_AST_Declarations, rb_intern("Alias"));
   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"));

data/ext/rbs_extension/constants.h

@@ -6,6 +6,7 @@ extern VALUE RBS;
 extern VALUE RBS_AST;
 extern VALUE RBS_AST_Annotation;
 extern VALUE RBS_AST_Comment;
+extern VALUE RBS_AST_TypeParam;
 
 extern VALUE RBS_AST_Declarations;
 extern VALUE RBS_AST_Declarations_Alias;
@@ -16,8 +17,6 @@ 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_ModuleTypeParams_TypeParam;
-extern VALUE RBS_AST_Declarations_ModuleTypeParams;
 
 extern VALUE RBS_AST_Members;
 extern VALUE RBS_AST_Members_Alias;