rbs 2.8.4 → 3.8.1

data/docs/gem.md

@@ -0,0 +1,57 @@
+# Releasing a gem with RBS
+
+You can release the RBS type definition of your gem included in the gem package. Just add your RBS files inside `/sig` directory, put them in your rubygem package, and release a new version. RBS gem will load the RBS files from your gem package automatically.
+
+## `/sig` directory
+
+RBS gem tries to load a type definition of a gem from gem package first. It checks if there is `/sig` directory in the gem package and loads `*.rbs` files from the directory. So, everything you have to do to make your type definition available are:
+
+1. Add `/sig` directory in your gem package
+2. Put your RBS files inside the directory
+3. Make sure the RBS files are included in the gem package
+
+### Hidden RBS files
+
+If you have RBS files you don't want to export to the gem users, you can put the files under a directory that starts with `_``.
+
+Assume you have three RBS files in your gem package:
+
+* `/sig/foo.rbs`
+* `/sig/bar/baz.rbs`
+* `/sig/_private/internal.rbs`
+
+`foo.rbs` and `baz.rbs` will be loaded from the gem package, but the `internal.rbs` will be skipped. This is only when you load RBS files of a *library*, for example through `-r` option given to `rbs` command. If you load RBS files as *source code*, for example through `-I` option given to `rbs` command, the hidden RBS files will be loaded too.
+
+* `rbs -r your-gem` => Loading a library
+* `rbs -I sig` => Loading RBS files as source code
+
+### Adding `manifest.yaml`
+
+`manifest.yaml` lets you declare dependencies to standard libraries. Here is an example, from [RBS gem](https://github.com/ruby/rbs/blob/6b3d0f976a50b3974d0bff26ea8fa9931053f38b/sig/manifest.yaml).
+
+```yaml
+dependencies:
+  - name: json
+  - name: logger
+  - name: optparse
+  - name: pathname
+  - name: rdoc
+  - name: tsort
+```
+
+Note that you don't have to write the dependencies that are included in your `.gemspec`. RBS will detect the dependencies between gems, declared in `.gemspec`. `manifest.yaml` is a material for undeclared dependencies, which usually is for standard libraries.
+
+## Testing your type definition
+
+If you develop your gem using a static type checker, like [Steep](https://github.com/soutaro/steep), your type definition will be (mostly) correct and reliable. If not, we strongly recommend adding extra tests focusing on the RBS type definitions.
+
+`RBS::UnitTest` is a library to do that. `assert_send_type` is the most important assertion.
+
+```rb
+assert_send_type '(Regexp) { (String) -> String } -> String',
+                 'hello', :gsub, /hello/, &proc { "foo" }
+```
+
+It calls `String#gsub` method and confirms if given arguments and the return value has correct types.
+
+You can find examples under `test/stdlib` directory of [RBS repository](https://github.com/ruby/rbs/blob/6b3d0f976a50b3974d0bff26ea8fa9931053f38b/test/stdlib/String_test.rb).

data/docs/rbs_by_example.md

@@ -6,20 +6,20 @@ The purpose of this doc is to teach you how to write RBS signatures by using the
 
 ## Examples
 
+In each example, the first snippet is for *Ruby* and the second one is for *RBS*.
+
 ### Zero argument methods
 
 **Example:** `String#empty?`
 
 ```ruby
-# .rb
 "".empty?
 # => true
 "hello".empty?
 # => false
 ```
 
-```ruby
-# .rbs
+```rbs
 class String
   def empty?: () -> bool
 end
@@ -32,14 +32,13 @@ end
 **Example:** `String#include?`
 
 ```ruby
-# .rb
 "homeowner".include?("house")
 # => false
 "homeowner".include?("meow")
 # => true
 ```
 
-```ruby
+```rbs
 class String
   def include?: (String) -> bool
 end
@@ -53,7 +52,6 @@ boolean value
 **Example:** `String#end_with?`
 
 ```ruby
-# .rb
 "hello?".end_with?("!")
 # => false
 "hello?".end_with?("?")
@@ -64,8 +62,7 @@ boolean value
 # => false
 ```
 
-```ruby
-# .rbs
+```rbs
 class String
   def end_with?: (*String) -> bool
 end
@@ -79,7 +76,6 @@ returns a boolean value.
 **Example:** `String#ljust`
 
 ```ruby
-# .rb
 "hello".ljust(4)
 #=> "hello"
 "hello".ljust(20)
@@ -88,8 +84,7 @@ returns a boolean value.
 #=> "hello123412341234123"
 ```
 
-```ruby
-# .rbs
+```rbs
 class String
   def ljust: (Integer, ?String) -> String
 end
@@ -102,7 +97,6 @@ end
 **Example:** `Array#*`
 
 ```ruby
-# .rb
 [1, 2, 3] * ","
 # => "1,2,3"
 [1, 2, 3] * 2
@@ -112,8 +106,7 @@ end
 *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
+```rbs
 class Array[Elem]
   def *: (String) -> String
        | (Integer) -> Array[Elem]
@@ -128,7 +121,6 @@ end
 **Example:** `String#<<`
 
 ```ruby
-# .rb
 a = "hello "
 a << "world"
 #=> "hello world"
@@ -136,8 +128,7 @@ a << 33
 #=> "hello world!"
 ```
 
-```ruby
-# .rbs
+```rbs
 class String
   def <<: (String | Integer) -> String
 end
@@ -148,7 +139,6 @@ end
 ### Nilable types
 
 ```ruby
-# .rb
 [1, 2, 3].first
 # => 1
 [].first
@@ -159,8 +149,7 @@ end
 # => []
 ```
 
-```ruby
-# .rbs
+```rbs
 class Enumerable[Elem]
   def first: () -> Elem?
            | (Integer) -> Array[Elem]
@@ -183,7 +172,6 @@ The `?` syntax is a convenient shorthand for a union with nil. An equivalent uni
 **Example**: `String#lines`
 
 ```ruby
-# .rb
 "hello\nworld\n".lines
 # => ["hello\n", "world\n"]
 "hello  world".lines(' ')
@@ -192,8 +180,7 @@ The `?` syntax is a convenient shorthand for a union with nil. An equivalent uni
 # => ["hello", "world"]
 ```
 
-```ruby
-# .rbs
+```rbs
 class String
   def lines: (?String, ?chomp: bool) -> Array[String]
 end
@@ -209,12 +196,11 @@ Keyword arguments are declared similar to in ruby, with the keyword immediately
 **Example**: `Time.now`
 
 ```ruby
-# .rb
 Time.now
 # => 2009-06-24 12:39:54 +0900
 ```
 
-```ruby
+```rbs
 class Time
   def self.now: () -> Time
 end
@@ -228,7 +214,6 @@ end
 **Example**: `Array#filter`
 
 ```ruby
-# .rb
 [1,2,3,4,5].filter {|num| num.even? }
 # => [2, 4]
 %w[ a b c d e f ].filter {|v| v =~ /[aeiou]/ }
@@ -236,8 +221,7 @@ end
 [1,2,3,4,5].filter
 ```
 
-```ruby
-# .rbs
+```rbs
 class Array[Elem]
   def filter: () { (Elem) -> boolish } -> ::Array[Elem]
             | () -> ::Enumerator[Elem, ::Array[Elem]]
@@ -260,8 +244,7 @@ h.keys
 # => ["a", "b", "c", "d"]
 ```
 
-```ruby
-# .rbs
+```rbs
 class Hash[K, V]
   def keys: () -> Array[K]
 end
@@ -273,7 +256,6 @@ Generic types in RBS are parameterized at declaration time. These type variables
 
 
 ```ruby
-# .rb
 a = [ "a", "b", "c", "d" ]
 a.collect {|x| x + "!"}
 # => ["a!", "b!", "c!", "d!"]
@@ -281,8 +263,7 @@ a.collect.with_index {|x, i| x * i}
 # => ["", "b", "cc", "ddd"]
 ```
 
-```ruby
-# .rbs
+```rbs
 class Array[Elem]
   def collect: [U] () { (Elem) -> U } -> Array[U]
              | () -> Enumerator[Elem, Array[untyped]]
@@ -302,7 +283,7 @@ In this example, the method receives its signature from the inferred return type
 # => [[2, 4, 6], [1, 3, 5]]
 ```
 
-```ruby
+```rbs
 class Enumerable[Elem]
   def partition: () { (Elem) -> boolish } -> [Array[Elem], Array[Elem]]
                | () -> ::Enumerator[Elem, [Array[Elem], Array[Elem] ]]
@@ -318,7 +299,7 @@ Tuples can be of any size, and they can have mixed types.
 # => {1=>1, 2=>4, 3=>9, 4=>16, 5=>25}
 ```
 
-```ruby
+```rbs
 class Enumerable[Elem]
   def to_h: () -> ::Hash[untyped, untyped]
           | [T, U] () { (Elem) -> [T, U] } -> ::Hash[T, U]

data/docs/repo.md

@@ -13,7 +13,7 @@ Assume there is a rubygem called `bug-free-doodle` and our application depends o
 
 One workaround is to add type definitions of the library in the application signatures.
 
-```
+```rbs
 # sig/polyfill/bug-free-doodle.rbs
 
 module Bug

data/docs/sigs.md

@@ -18,7 +18,7 @@ See [syntax guide](syntax.md).
 When you finish writing signature, you may want to test the signature.
 rbs provides a feature to test your signature.
 
-```
+```console
 $ RBS_TEST_TARGET='Foo::*' bundle exec ruby -r rbs/test/setup test/foo_test.rb
 ```
 
@@ -74,7 +74,7 @@ The `rbs` test framework tries to the best error message for overloaded methods
 
 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
+```rbs
 # First definition
 class C
   def foo: () -> untyped
@@ -99,14 +99,14 @@ The design of the signature testing aims to be non-intrusive. The setup is done
 You need to require `rbs/test/setup` for signature testing.
 You can do it using `-r` option through command line argument or the `RUBYOPT` environment variable.
 
-```
+```console
 $ ruby -r rbs/test/setup run_tests.rb
 $ RUBYOPT='-rrbs/test/setup' rake test
 ```
 
 When you are using Bundler, you may need to require `bundler/setup` explicitly.
 
-```
+```console
 $ RUBYOPT='-rbundler/setup -rrbs/test/setup' bundle exec rake test
 ```
 
@@ -130,7 +130,7 @@ You need to specify `RBS_TEST_TARGET` to run the test, and you can customize the
 You may need to specify `-r` or `-I` to load signatures.
 The default is `-I sig`.
 
-```
+```shell
 RBS_TEST_OPT='-r pathname -I sig'
 ```
 
@@ -144,7 +144,7 @@ You can see the backtrace how the type error is caused and debug your program or
 
 So, a typical command line to start the test would look like the following:
 
-```
+```console
 $ RBS_TEST_LOGLEVEL=error \
   RBS_TEST_TARGET='Kaigi::*' \
   RBS_TEST_SKIP='Kaigi::MonkeyPatch' \
@@ -160,7 +160,7 @@ $ RBS_TEST_LOGLEVEL=error \
 
 You can skip installing the instrumentation per-method basis using `rbs:test:skip` annotation.
 
-```
+```rbs
 class String
   %a{rbs:test:skip} def =~: (Regexp) -> Integer?
 end

data/docs/stdlib.md

@@ -10,7 +10,7 @@ We support writing tests for core/stdlib signatures.
 
 First, execute `generate:stdlib_test` rake task with a class name that you want to test.
 
-```bash
+```console
 $ bundle exec rake 'generate:stdlib_test[String]'
 Created: test/stdlib/String_test.rb
 ```
@@ -47,7 +47,6 @@ end
 class StringTest < Test::Unit::TestCase
   include TypeAssertions
 
-  # library "pathname", "set", "securerandom"     # Declare library signatures to load
   testing "::String"
 
   def test_gsub
@@ -73,17 +72,76 @@ end
 
 You need include `TypeAssertions` which provide useful methods for you.
 `testing` method call tells which class is the subject of the class.
-`assert_send_type` method call asserts to be valid types and confirms to be able to execute without exceptions.
-And you write the sample programs which calls all of the patterns of overloads.
+You may need `library` call to test a library if the type definition is provided as a library (under `stdlib` dir).
 
 Note that the instrumentation is based on refinements and you need to write all method calls in the unit class definitions.
 If the execution of the program escape from the class definition, the instrumentation is disabled and no check will be done.
 
+#### 📣 Method type assertions
+
+`assert_send_type` method call asserts to be valid types and confirms to be able to execute without exceptions.
+And you write the sample programs which calls all of the patterns of overloads.
+
+We recommend write method types as _simple_ as possible inside the assertion.
+It's not very easy to define _simple_, but we try to explain it with a few examples.
+
+* Instead of `(String | Integer) -> Symbol?`, use `(String) -> Symbol` or `(Integer) -> nil`, because we know the exact argument type we are passing in the test
+* Instead of `self`, `instance`, or `class`, use concrete types like `String`, `singleton(IO)`, because we know the exact type of the receiver
+* Sometimes, you need union types if the method is nondeterministic -- `() -> (Integer | String)` for `[1, ""].sample` (But you can rewrite the test code as `[1].sample` instead)
+* Sometimes, you need union types for heterogeneous collections -- `() { (Integer | String) -> String } -> Array[String | Integer]` for `[1, "2"].each {|i| i.to_s }` (But you can rewrite the test code as `[1, 2].each {|i| i.to_s }`)
+* Using `void` is allowed if the RBS definition is `void`
+
+Generally _simple_ means:
+
+* The type doesn't contain `self`, `instance`, `class`, `top`, `bot`, and `untyped`
+* The type doesn't contain unions and optionals
+
+Use them if you cannot write the test without them.
+
+One clear exception to using _simple_ types is when you use `with_int` or family helpers, that yield values with each case of the given union:
+
+```ruby
+def test_something
+  with_int(3) do |int|
+    # Yields twice with `Integer` and `ToInt`
+    assert_send_type(
+      "(int) -> Integer",
+      some, :test, int
+    )
+  end
+end
+```
+
+It's clear having type aliases makes sense.
+
+#### 📣 Constant type assertions
+
+We also have `assert_const_type` method, to test the type of constant is correct with respect to RBS type definition.
+
+```ruby
+class FloatConstantTest < Test::Unit::TestCase
+  include TypeAssertions
+
+  def test_infinity
+    assert_const_type "Float", "Float::INFINITY"
+  end
+end
+```
+
+It confirms:
+
+1. The type of constant `Float::INFINITY` is `Float`
+2. The type of constant `Float::INFINITY` is correct with respect to RBS definition
+
+We don't have any strong recommendation about where the constants test should be written in.
+The `FloatConstantTest` example defines a test case only for the constant tests.
+You may write the tests inside `FloatInstanceTest` or `FloatSingletonTest`.
+
 ### Running tests
 
 You can run the test with:
 
-```
+```console
 $ bundle exec rake stdlib_test                # Run all tests
 $ bundle exec ruby test/stdlib/String_test.rb # Run specific tests
 ```