rbs 1.2.1 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 99ab9c0212ca34de0fa1b8394b02713e5bc63e0904d7f95d0e1c0480635e3e39
-  data.tar.gz: 71be3592a61873855149305edc2b0ef3aabc97259e0ed46c697598fefddb4177
+  metadata.gz: ab99593166ee140ca3ffc517eddcd872c6798dcb41a991c1e67c0c16a2a86fc9
+  data.tar.gz: a4e5cdd454fb49ddd499ba3382e118f8789b5413d0607ad9e3652551839c0ca3
 SHA512:
-  metadata.gz: 608db9f87d437542fe683b336198f588c670d0632ce2733570156b253d9fd4514d4b8fefacb38db0d26ed9fac149b2bfc459ff9779334bff8fa08ec103722fde
-  data.tar.gz: 157550825a76be4dd00a8419c001404ef0ad86406340131893a3ac7be473e7cf397da8434b4a841b6dc7f9968eceb93fdbd5f729b23c52c785725be0c1516c77
+  metadata.gz: 8d660c0dd7796bad07fac8e2ee85968e91259af0a4c9fed2c8668f0d6e385a517160d5792702181e18923929a3de7ded420c84e2184cb83a852d2133c1f34050
+  data.tar.gz: 4991d9a71cd0bd2bd2832d7764a8d65a73de146fecf76d3ccd67a41599326ca45b091e559acededcd095a44cdef6e32cc01fbb742e04bba945269b4e21a6444c

data/.github/workflows/ruby.yml

@@ -18,7 +18,11 @@ jobs:
         job:
         - test
         - stdlib_test
-        - rubocop validate test_doc build test_generate_stdlib confirm_parser
+        - rubocop validate test_doc build test_generate_stdlib
+        - confirm_parser
+        exclude:
+        - container_tag: master-nightly-focal
+          job: confirm_parser
     container:
       image: rubylang/ruby:${{ matrix.container_tag }}
     steps:

data/.gitignore

@@ -1,4 +1,5 @@
 /.bundle/
+/steep/.bundle/
 /.yardoc
 /_yardoc/
 /coverage/
@@ -9,3 +10,4 @@
 /lib/rbs/parser.output
 /vendor/sigs
 /Gemfile.lock
+

data/CHANGELOG.md

@@ -2,6 +2,38 @@
 
 ## master
 
+## 1.3.0 (2021-07-20)
+
+### Summary
+
+RBS 1.3.0 includes bug fixees of the parser and class/module definition validations.
+
+### Signature updates
+
+* dbm ([#718](https://github.com/ruby/rbs/pull/718))
+* net-http ([#686](https://github.com/ruby/rbs/pull/686))
+* optparse ([#693](https://github.com/ruby/rbs/pull/693))
+* resolv ([#697](https://github.com/ruby/rbs/pull/697))
+* socket ([#699](https://github.com/ruby/rbs/pull/699))
+* `IO` ([#698](https://github.com/ruby/rbs/pull/698))
+* `Marshal` ([#684](https://github.com/ruby/rbs/pull/684))
+* `Mutex` ([#683](https://github.com/ruby/rbs/pull/683))
+* `Array#shift` ([#707](https://github.com/ruby/rbs/pull/707))
+* `BasicObject#method_missing` ([#707](https://github.com/ruby/rbs/pull/706), [#710](https://github.com/ruby/rbs/pull/710))
+* `Kernel#caller` ([#705](https://github.com/ruby/rbs/pull/705))
+
+### Library changes
+
+* Interface names starting with lower case characters are now syntax error ([#678](https://github.com/ruby/rbs/pull/678), [#720](https://github.com/ruby/rbs/pull/720))
+* Mixins of classes are rejected ([#681](https://github.com/ruby/rbs/pull/681))
+* Generate prototype of `initialize` method with return type `void` ([#685](https://github.com/ruby/rbs/pull/685))
+* Let `prototype runtime` generate class/module declarations in nested syntax ([#700](https://github.com/ruby/rbs/pull/700))
+* Fix race condition for multi-thread support ([#702](https://github.com/ruby/rbs/pull/702))
+
+### Miscellaneous
+
+* Add new doc `docs/rbs_by_example.md` ([#694](https://github.com/ruby/rbs/pull/694))
+
 ## 1.2.1 (2021-05-27)
 
 This release includes the following minor changes:

data/README.md

@@ -7,7 +7,7 @@ It also allows declaring constants and global variables.
 The following is a small example of RBS for a chat app.
 
 <!-- run-start:a.rbs:bundle exec rbs -I a.rbs validate -->
-```rbs
+```rb
 module ChatApp
   VERSION: String
 

data/Rakefile

@@ -54,6 +54,15 @@ task :validate => :parser do
       lib << "singleton"
     end
 
+    if lib == ["net-http"]
+      lib << "uri"
+    end
+
+    if lib == ["resolv"]
+      lib << "socket"
+      lib << "timeout"
+    end
+
     sh "#{ruby} #{rbs} #{lib.map {|l| "-r #{l}"}.join(" ")} validate --silent"
   end
 end

data/Steepfile

@@ -7,6 +7,7 @@ target :lib do
   library "set", "pathname", "json", "logger", "monitor", "tsort"
   signature "stdlib/strscan/0/"
   signature "stdlib/rubygems/0/"
+  signature "stdlib/optparse/0/"
 end
 
 # target :lib do

data/core/array.rbs

@@ -1637,7 +1637,7 @@ class Array[unchecked out Elem] < Object
   #     args           #=> ["filename"]
   #
   def shift: () -> Elem?
-           | (?int n) -> ::Array[Elem]
+           | (int n) -> ::Array[Elem]
 
   # Returns a new array with elements of `self` shuffled.
   #

data/core/basic_object.rbs

@@ -215,7 +215,7 @@ class BasicObject
   #     r.xxiii   #=> 23
   #     r.mm      #=> 2000
   #
-  def method_missing: (Symbol, *untyped) -> untyped
+  def method_missing: (Symbol, *untyped, **untyped) ?{ (*untyped, **untyped) -> untyped } -> untyped
 
   # Invoked as a callback whenever a singleton method is added to the receiver.
   #

data/core/io.rbs

@@ -746,7 +746,7 @@ class IO < Object
 
   def self.readlines: (String name, ?String sep, ?Integer limit, ?external_encoding: String external_encoding, ?internal_encoding: String internal_encoding, ?encoding: String encoding, ?textmode: untyped textmode, ?binmode: untyped binmode, ?autoclose: untyped autoclose, ?mode: String mode) -> ::Array[String]
 
-  def self.select: (::Array[io]? read_array, ?::Array[io]? write_array, ?::Array[io]? error_array, ?Integer? timeout) -> ::Array[::Array[io]]?
+  def self.select: (::Array[io]? read_array, ?::Array[io]? write_array, ?::Array[io]? error_array, ?Numeric? timeout) -> ::Array[::Array[io]]?
 
   def self.sysopen: (String path, ?String mode, ?String perm) -> Integer
 

data/core/kernel.rbs

@@ -13,8 +13,8 @@
 module Kernel : BasicObject
   private
 
-  def self?.caller: (?Integer start_or_range, ?Integer length) -> ::Array[String]?
-            | (?::Range[Integer] start_or_range) -> ::Array[String]?
+  def self?.caller: (Integer start_or_range, ?Integer length) -> ::Array[String]?
+            | (::Range[Integer] start_or_range) -> ::Array[String]?
             | () -> ::Array[String]
 
   def self?.caller_locations: (?Integer start_or_range, ?Integer length) -> ::Array[Thread::Backtrace::Location]?

data/core/marshal.rbs

@@ -136,8 +136,8 @@ module Marshal
   #     ThreadGroup, Continuation
   # *   objects which define singleton methods
   #
-  def self.dump: (Object arg0, ?IO arg1, ?Integer arg2) -> Object
-               | (Object arg0, ?Integer arg1) -> Object
+  def self.dump: (untyped obj, untyped port, ?Integer limit) -> untyped
+               | (untyped obj, ?Integer limit) -> String
 
   # Returns the result of converting the serialized data in source into a Ruby
   # object (possibly with associated subordinate objects). source may be either an
@@ -147,7 +147,8 @@ module Marshal
   # Never pass untrusted data (including user supplied input) to this method.
   # Please see the overview for further details.
   #
-  def self.load: (String arg0, ?Proc arg1) -> Object
+  def self.load: (String | untyped port) -> untyped
+               | [A] (String | untyped port, ^(untyped) -> A) -> A
 
   alias self.restore self.load
 end

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.