rbs 1.1.0 → 1.3.0

data/docs/rbs_by_example.md

@@ -0,0 +1,328 @@
+# RBS By Example
+
+## Goal
+
+The purpose of this doc is to teach you how to write RBS signatures by using the standard library's methods as a guide.
+
+## Examples
+
+### Zero argument methods
+
+**Example:** `String#empty?`
+
+```ruby
+# .rb
+"".empty?
+# => true
+"hello".empty?
+# => false
+```
+
+```ruby
+# .rbs
+class String
+  def empty?: () -> bool
+end
+```
+
+`String`'s `#empty` method takes no parameters, and returns a boolean value
+
+### Single argument methods
+
+**Example:** `String#include?`
+
+```ruby
+# .rb
+"homeowner".include?("house")
+# => false
+"homeowner".include?("meow")
+# => true
+```
+
+```ruby
+class String
+  def include?: (String) -> bool
+end
+```
+
+`String`'s `include?` method takes one argument, a `String`, and returns a
+boolean value
+
+### Variable argument methods
+
+**Example:** `String#end_with?`
+
+```ruby
+# .rb
+"hello?".end_with?("!")
+# => false
+"hello?".end_with?("?")
+# => true
+"hello?".end_with?("?", "!")
+# => true
+"hello?".end_with?(".", "!")
+# => false
+```
+
+```ruby
+# .rbs
+class String
+  def end_with?: (*String) -> bool
+end
+```
+
+`String`'s `#end_with?` method takes any number of `String` arguments, and
+returns a boolean value.
+
+### Optional positional arguments
+
+**Example:** `String#ljust`
+
+```ruby
+# .rb
+"hello".ljust(4)
+#=> "hello"
+"hello".ljust(20)
+#=> "hello               "
+"hello".ljust(20, '1234')
+#=> "hello123412341234123"
+```
+
+```ruby
+# .rbs
+class String
+  def ljust: (Integer, ?String) -> String
+end
+```
+
+`String`'s `ljust` takes one `Integer` argument, and an optional `String` argument, indicated by the the `?` prefix marker. It returns a `String`.
+
+### Multiple signatures for a single method
+
+**Example:** `Array#*`
+
+```ruby
+# .rb
+[1, 2, 3] * ","
+# => "1,2,3"
+[1, 2, 3] * 2
+# => [1, 2, 3, 1, 2, 3]
+```
+
+*Note:* Some of the signatures after this point include type variables (e.g. `Elem`, `T`).
+For now, it's safe to ignore them, but they're included for completeness.
+
+```ruby
+# .rbs
+class Array[Elem]
+  def *: (String) -> String
+       | (Integer) -> Array[Elem]
+end
+```
+
+`Array`'s `*` method, when given a `String` returns a `String`. When given an
+`Integer`, it returns an `Array` of the same contained type `Elem` (in our example case, `Elem` corresponds to `Integer`).
+
+### Union types
+
+**Example:** `String#<<`
+
+```ruby
+# .rb
+a = "hello "
+a << "world"
+#=> "hello world"
+a << 33
+#=> "hello world!"
+```
+
+```ruby
+# .rbs
+class String
+  def <<: (String | Integer) -> String
+end
+```
+
+`String`'s `<<` operator takes either a `String` or an `Integer`, and returns a `String`.
+
+### Nilable types
+
+```ruby
+# .rb
+[1, 2, 3].first
+# => 1
+[].first
+# => nil
+[1, 2, 3].first(2)
+# => [1, 2]
+[].first(2)
+# => []
+```
+
+```ruby
+# .rbs
+class Enumerable[Elem]
+  def first: () -> Elem?
+           | (Integer) -> Array[Elem]
+end
+```
+
+`Enumerable`'s `#first` method has two different signatures.
+
+When called with no arguments, the return value will either be an instance of
+whatever type is contained in the enumerable, or `nil`. We represent that with
+the type variable `Elem`, and the `?` suffix nilable marker.
+
+When called with an `Integer` positional argument, the return value will be an
+`Array` of whatever type is contained.
+
+The `?` syntax is a convenient shorthand for a union with nil. An equivalent union type woould be `(Elem | nil)`.
+
+### Keyword Arguments
+
+**Example**: `String#lines`
+
+```ruby
+# .rb
+"hello\nworld\n".lines
+# => ["hello\n", "world\n"]
+"hello  world".lines(' ')
+# => ["hello ", " ", "world"]
+"hello\nworld\n".lines(chomp: true)
+# => ["hello", "world"]
+```
+
+```ruby
+# .rbs
+class String
+  def lines: (?String, ?chomp: bool) -> Array[String]
+end
+```
+
+`String`'s `#lines` method take two arguments: one optional String argument, and another optional boolean keyword argument. It returns an `Array` of `String`s.
+
+Keyword arguments are declared similar to in ruby, with the keyword immediately followed by a colon. Keyword arguments that are optional are indicated as optional using the same `?` prefix as positional arguments.
+
+
+### Class methods
+
+**Example**: `Time.now`
+
+```ruby
+# .rb
+Time.now
+# => 2009-06-24 12:39:54 +0900
+```
+
+```ruby
+class Time
+  def self.now: () -> Time
+end
+```
+
+`Time`'s class method `now` takes no arguments, and returns an instance of the
+`Time` class.
+
+### Block Arguments
+
+**Example**: `Array#filter`
+
+```ruby
+# .rb
+[1,2,3,4,5].select {|num| num.even? }
+# => [2, 4]
+%w[ a b c d e f ].select {|v| v =~ /[aeiou]/ }
+# => ["a", "e"]
+[1,2,3,4,5].filter
+```
+
+```ruby
+# .rbs
+class Array[Elem]
+  def filter: () { (Elem) -> boolish } -> ::Array[Elem]
+            | () -> ::Enumerator[Elem, ::Array[Elem]]
+end
+```
+
+`Array`'s `#filter` method, when called with no arguments returns an Enumerator.
+
+When called with a block, the method returns an `Array` of whatever type the original contained. The block will take one argument, of the type of the contained value, and the block will return a truthy or falsy value.
+
+`boolish` is a special keyword for any type that will be treated as if it were a `bool`.
+
+### Type Variables
+
+**Example**: `Hash`, `Hash#keys`
+
+```ruby
+h = { "a" => 100, "b" => 200, "c" => 300, "d" => 400 }
+h.keys
+# => ["a", "b", "c", "d"]
+```
+
+```ruby
+# .rbs
+class Hash[K, V]
+  def keys: () -> Array[K]
+end
+```
+
+Generic types in RBS are parameterized at declaration time. These type variables are then available throughout all the methods contained in the `class` block.
+
+`Hash`'s `#keys` method takes no arguments, and returns an `Array` of the first type parameter. In the above example, `a` is of concrete type `Hash[String, Integer]`, so `#keys` returns an `Array` for `String`.
+
+
+```ruby
+# .rb
+a = [ "a", "b", "c", "d" ]
+a.collect {|x| x + "!"}
+# => ["a!", "b!", "c!", "d!"]
+a.collect.with_index {|x, i| x * i}
+# => ["", "b", "cc", "ddd"]
+```
+
+```ruby
+# .rbs
+class Array[Elem]
+  def collect: [U] () { (Elem) -> U } -> Array[U]
+             | () -> Enumerator[Elem, Array[untyped]]
+end
+```
+
+Type variables can also be introduced in methods. Here, in `Array`'s `#collect` method, we introduce a type variable `U`. The block passed to `#collect` will receive a parameter of type `Elem`, and return a value of type `U`. Then `#collect` will return an `Array` of type `U`.
+
+In this example, the method receives its signature from the inferred return type of the passed block. When then block is absent, as in when the method returns an `Enumerator`, we can't infer the type, and so the return value of the enumerator can only be described as `Array[untyped]`.
+
+### Tuples
+
+**Examples**: `Enumerable#partition`, `Enumerable#to_h`
+
+```ruby
+(1..6).partition { |v| v.even? }
+# => [[2, 4, 6], [1, 3, 5]]
+```
+
+```ruby
+class Enumerable[Elem]
+  def partition: () { (Elem) -> boolish } -> [Array[Elem], Array[Elem]]
+               | () -> ::Enumerator[Elem, [Array[Elem], Array[Elem] ]]
+end
+```
+
+`Enumerable`'s `partition` method, when given a block, returns a 2-item tuple of `Array`s containing the original type of the `Enumerable`.
+
+Tuples can be of any size, and they can have mixed types.
+
+```ruby
+(1..5).to_h {|x| [x, x ** 2]}
+# => {1=>1, 2=>4, 3=>9, 4=>16, 5=>25}
+```
+
+```ruby
+class Enumerable[Elem]
+  def to_h: () -> ::Hash[untyped, untyped]
+          | [T, U] () { (Elem) -> [T, U] } -> ::Hash[T, U]
+end
+```
+
+`Enumerable`'s `to_h` method, when given a block that returns a 2-item tuple, returns a `Hash` with keys the type of the first position in the tuple, and values the type of the second position in the tuple.

data/docs/sigs.md

@@ -26,7 +26,7 @@ The test installs instrumentations to spy the method calls and check if argument
 If errors are reported by the test, you will fix the signature.
 You will be sure that you ship a correct signature finally.
 
-The instrumentations are implemneted using `Module#prepend`.
+The instrumentations are implemented using `Module#prepend`.
 It defines a module with same name of methods, which asserts the type of arguments/return values and calls `super`.
 
 ## Type errors
@@ -70,6 +70,23 @@ ERROR -- : [Kaigi::Conference#speakers] UnexpectedBlockError: unexpected block i
 The error means there is a type error on overloaded methods.
 The `rbs` test framework tries to the best error message for overloaded methods too, but it reports the `UnresolvedOverloadingError` when it fails.
 
+### DuplicatedMethodDefinitionError
+
+The error is reported when a method is defined multiple times, as RBS does not allow duplicate method definitions. When you need to overload a method, use the `...` syntax:
+
+```ruby
+# First definition
+class C
+  def foo: () -> untyped
+end
+
+# Second definition, use `...` syntax to tell RBS that we're overloading the method
+class C
+  def foo: () -> untyped
+         | ...
+end
+```
+
 ## Setting up the test
 
 The design of the signature testing aims to be non-intrusive. The setup is done in two steps:
@@ -114,9 +131,11 @@ You may need to specify `-r` or `-I` to load signatures.
 The default is `-I sig`.
 
 ```
-RBS_TEST_OPT='-r set -r pathname -I sig'
+RBS_TEST_OPT='-r pathname -I sig'
 ```
 
+Replacing `pathname` with the `stdlib` you want to include. For example, if you need to load `Set` and `BigDecimal` in `stdlib`, you would need to have `RBS_TEST_OPT='-r set -r bigdecimal -I sig'`
+
 `RBS_TEST_LOGLEVEL` can be used to configure log level. Defaults to `info`.
 
 `RBS_TEST_RAISE` may help to debug the type signatures.

data/docs/stdlib.md

@@ -57,7 +57,7 @@ But it will help you to have an overview of the signatures you are trying to wri
 
 ### What to do with existing RBS files
 
-Generating prototypes will override everything, so the problem is if there is a RBS files already.
+Generating prototypes will overwrite existing RBS files, which might be undesirable.
 You can try to find missing parts, or you can start from the scratch.
 
 One non-trivial but absolutely better solution is to make a tool:

data/docs/syntax.md

@@ -11,8 +11,8 @@ _type_ ::= _class-name_ _type-arguments_                (Class instance type)
          | _type_ `|` _type_                            (Union type)
          | _type_ `&` _type_                            (Intersection type)
          | _type_ `?`                                   (Optional type)
-         | `{` _record-name_ `:` _type_ `,` ... `}`     (Record type)
-         | `[]` | `[` _type_ `,` ... `]`                (Tuples)
+         | `{` _record-name_ `:` _type_ `,` etc. `}`     (Record type)
+         | `[]` | `[` _type_ `,` etc. `]`                (Tuples)
          | _type-variable_                              (Type variables)
          | `^(` _parameters_ `) ->` _type_              (Proc type)
          | `self`
@@ -36,7 +36,7 @@ _namespace_ ::=                                         (Empty namespace)
               | _namespace_ /[A-Z]\w*/ `::`             (Namespace)
 
 _type-arguments_ ::=                                    (No application)
-                   | `[` _type_ `,` ... `]`             (Type application)
+                   | `[` _type_ `,` etc. `]`             (Type application)
 
 _literal_ ::= _string-literal_
             | _symbol-literal_
@@ -203,7 +203,6 @@ We can see an example at the definition of `Enumerable#find`:
 ```
 module Enumerable[Elem, Return]
   def find: () { (Elem) -> boolish } -> Elem?
-  ...
 end
 ```
 
@@ -233,11 +232,11 @@ _parameters_ ::= _required-positionals_ _optional-positionals_ _rest-positional_
 
 _parameter_ ::= _type_ _var-name_                                  # Parameter with var name
               | _type_                                             # Parameter without var name
-_required-positionals_ ::= _parameter_ `,` ...
-_optional-positionals_ ::= `?` _parameter_ `,` ...
+_required-positionals_ ::= _parameter_ `,` etc.
+_optional-positionals_ ::= `?` _parameter_ `,` etc.
 _rest-positional_ ::=                                              # Empty
                     | `*` _parameter_
-_trailing-positionals_ ::= _parameter_ `,` ...
+_trailing-positionals_ ::= _parameter_ `,` etc.
 _keywords_ ::=                                                     # Empty
              | `**` _parameter_                                    # Rest keyword
              | _keyword_ `:` _parameter_ `,` _keywords_            # Required keyword
@@ -292,9 +291,10 @@ _method-member_ ::= `def` _method-name_ `:` _method-types_            # Instance
 _method-types_ ::=                                                       # Empty
                  | `super`                                               # `super` overloading
                  | _type-parameters_ _method-type_ `|` _method-types_    # Overloading types
+                 | `...`                                                 # Overloading for duplicate definitions
 
 _type-parameters_ ::=                                                 # Empty
-                    | `[` _type-variable_ `,` ... `]`
+                    | `[` _type-variable_ `,` etc. `]`
 
 _attribute-member_ ::= _attribute-type_ _method-name_ `:` _type_                     # Attribute
                      | _attribute-type_ _method-name_ `(` _ivar-name_ `) :` _type_   # Attribute with variable name specification
@@ -352,9 +352,6 @@ def +: (Float | Integer) -> (Float | Integer)
      | (Numeric) -> Numeric
 ```
 
-Method types can end with `super` which means the methods from existing definitions.
-This is useful to define an _extension_, which adds a new variation to the existing method preserving the original behavior.
-
 ### Attribute definition
 
 Attribute definitions help to define methods and instance variables based on the convention of `attr_reader`, `attr_writer` and `attr_accessor` methods in Ruby.
@@ -450,7 +447,7 @@ _const-name_ ::= _namespace_ /[A-Z]\w*/
 _global-name_ ::= /$[a-zA-Z]\w+/ | ...
 
 _module-type-parameters_ ::=                                                  # Empty
-                           | `[` _module-type-parameter_ `,` ... `]`
+                           | `[` _module-type-parameter_ `,` etc. `]`
 
 _module-type-parameter_ ::= _check_ _variance_ _type-variable_
 _variance_ ::= `out` | `in`
@@ -475,7 +472,7 @@ For example, an `Array` of `String` can almost be considered to be an `Array` of
 
 ```
 class Array[out T]
-  # ...
+  # etc.
 end
 ```
 
@@ -486,7 +483,7 @@ In those cases, one must use the `unchecked` keyword:
 
 ```
 class Array[unchecked out T]
-  # ...
+  # etc.
 end
 ```