rbs 3.1.3 → 3.2.0

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
@@ -83,7 +82,7 @@ If the execution of the program escape from the class definition, the instrument
 
 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
 ```

data/docs/syntax.md

@@ -51,7 +51,7 @@ _proc_ ::= _parameters?_ _self-type-binding?_ _block?_ `->` _type_
 
 Class instance type denotes _an instance of a class_.
 
-```
+```rbs
 Integer                      # Instance of Integer class
 ::Integer                    # Instance of ::Integer class
 Hash[Symbol, String]         # Instance of Hash class with type application of Symbol and String
@@ -61,7 +61,7 @@ Hash[Symbol, String]         # Instance of Hash class with type application of S
 
 Interface type denotes _type of a value which can be a subtype of the interface_.
 
-```
+```rbs
 _ToS                          # _ToS interface
 ::MyApp::_Each[String]        # Interface name with namespace and type application
 ```
@@ -72,7 +72,7 @@ Alias type denotes an alias declared with _alias declaration_.
 
 The name of type aliases starts with lowercase `[a-z]`.
 
-```
+```rbs
 name
 ::JSON::t                    # Alias name with namespace
 list[Integer]                # Type alias can be generic
@@ -82,7 +82,7 @@ list[Integer]                # Type alias can be generic
 
 Class singleton type denotes _the type of a singleton object of a class_.
 
-```
+```rbs
 singleton(String)
 singleton(::Hash)            # Class singleton type cannot be parametrized.
 ```
@@ -91,7 +91,7 @@ singleton(::Hash)            # Class singleton type cannot be parametrized.
 
 Literal type denotes _a type with only one value of the literal_.
 
-```
+```rbs
 123                         # Integer
 "hello world"               # A string
 :to_s                       # A symbol
@@ -102,7 +102,7 @@ true                        # true or false
 
 Union type denotes _a type of one of the given types_.
 
-```
+```rbs
 Integer | String           # Integer or String
 Array[Integer | String]    # Array of Integer or String
 ```
@@ -111,7 +111,7 @@ Array[Integer | String]    # Array of Integer or String
 
 Intersection type denotes _a type of all of the given types_.
 
-```
+```rbs
 _Reader & _Writer           # _Reader and _Writer
 ```
 
@@ -121,7 +121,7 @@ Note that `&` has higher precedence than `|` that `A & B | C` is `(A & B) | C`.
 
 Optional type denotes _a type of value or nil_.
 
-```
+```rbs
 Integer?
 Array[Integer?]
 ```
@@ -130,7 +130,7 @@ Array[Integer?]
 
 Records are `Hash` objects, fixed set of keys, and heterogeneous.
 
-```
+```rbs
 { id: Integer, name: String }     # Hash object like `{ id: 31, name: String }`
 ```
 
@@ -138,7 +138,7 @@ Records are `Hash` objects, fixed set of keys, and heterogeneous.
 
 Tuples are `Array` objects, fixed size and heterogeneous.
 
-```
+```rbs
 [ ]                               # Empty like `[]`
 [String]                          # Single string like `["hi"]`
 [Integer, Integer]                # Pair of integers like `[1, 2]`
@@ -149,7 +149,7 @@ Tuples are `Array` objects, fixed size and heterogeneous.
 
 ### Type variable
 
-```
+```rbs
 U
 T
 S
@@ -159,7 +159,7 @@ Elem
 Type variables cannot be distinguished from _class instance types_.
 They are scoped in _class/module/interface/alias declaration_ or _generic method types_.
 
-```
+```rbs
 class Ref[T]              # Object is scoped in the class declaration.
   @value: T               # Type variable `T`
   def map: [X] { (T) -> X } -> Ref[X]   # X is a type variable scoped in the method type.
@@ -193,7 +193,7 @@ It is an alias of `top` type, and you can use `boolish` if we want to allow any
 
 We can see an example at the definition of `Enumerable#find`:
 
-```
+```rbs
 module Enumerable[Elem, Return]
   def find: () { (Elem) -> boolish } -> Elem?
 end
@@ -201,7 +201,7 @@ end
 
 We want to write something like:
 
-```
+```ruby
 array.find {|x| x && x.some_test? }               # The block will return (bool | nil)
 ```
 
@@ -218,7 +218,7 @@ They are all equivalent for the type system; they are all _top type_.
 
 Proc type denotes type of procedures, `Proc` instances.
 
-```
+```rbs
 ^(Integer) -> String                  # A procedure with an `Integer` parameter and returns `String`
 ^(?String, size: Integer) -> bool     # A procedure with `String` optional parameter, `size` keyword of `Integer`, and returns `bool`
 ```
@@ -266,7 +266,7 @@ Variable name can be used for documentation.
 
 #### Examples
 
-```
+```rbs
 # Two required positional `Integer` parameters, and returns `String`
 (Integer, Integer) -> String
 
@@ -359,7 +359,7 @@ _method-name_ ::= ...
 
 An instance variable definition consists of the name of an instance variable and its type.
 
-```
+```rbs
 @name: String
 @value: Hash[Symbol, Key]
 ```
@@ -370,7 +370,7 @@ Method definition has several syntax variations.
 
 You can write `self.` or `self?.` before the name of the method to specify the kind of method: instance, singleton, or module function.
 
-```
+```rbs
 def to_s: () -> String                        # Defines a instance method
 def self.new: () -> AnObject                  # Defines singleton method
 def self?.sqrt: (Numeric) -> Numeric          # self? is for `module_function`s
@@ -380,7 +380,7 @@ def self?.sqrt: (Numeric) -> Numeric          # self? is for `module_function`s
 
 The method type can be connected with `|`s to define an overloaded method.
 
-```
+```rbs
 def +: (Float) -> Float
      | (Integer) -> Integer
      | (Numeric) -> Numeric
@@ -388,7 +388,7 @@ def +: (Float) -> Float
 
 Overloaded method can have `...` to overload an existing method. It is useful for monkey-patching.
 
-```
+```rbs
 def +: (Float) -> Float
 def +: (BigDecimal) -> BigDecimal
      | ...
@@ -396,14 +396,14 @@ def +: (BigDecimal) -> BigDecimal
 
 You need extra parentheses on return type to avoid ambiguity.
 
-```
+```rbs
 def +: (Float | Integer) -> (Float | Integer)
      | (Numeric) -> Numeric
 ```
 
 Adding `public` and `private` modifier changes the visibility of the method.
 
-```
+```rbs
 private def puts: (*untyped) -> void       # Defines private instance method
 
 public def self.puts: (*untyped) -> void   # Defines public singleton method
@@ -417,7 +417,7 @@ Attribute definitions help to define methods and instance variables based on the
 
 You can specify the name of instance variable using `(@some_name)` syntax and also omit the instance variable definition by specifying `()`.
 
-```
+```rbs
 # Defines `id` method and `@id` instance variable.
 attr_reader id: Integer
 # @id: Integer
@@ -436,7 +436,7 @@ attr_accessor people (): Array[Person]
 
 Attribute definitions can have the `public` and `private` modifiers like method definitions:
 
-```
+```rbs
 private attr_accessor id: Integer
 
 private attr_reader self.name: String
@@ -446,7 +446,7 @@ private attr_reader self.name: String
 
 You can define mixins between class and modules.
 
-```
+```rbs
 include Kernel
 include Enumerable[String, void]
 extend ActiveSupport::Concern
@@ -454,7 +454,7 @@ extend ActiveSupport::Concern
 
 You can also `include` or `extend` an interface.
 
-```
+```rbs
 include _Hashing
 extend _LikeString
 ```
@@ -465,7 +465,7 @@ This allows importing `def`s from the interface to help developer implementing a
 
 You can define an alias between methods.
 
-```
+```rbs
 def map: [X] () { (String) -> X } -> Array[X]
 alias collect map                                   # `#collect` has the same type with `map`
 ```
@@ -548,7 +548,7 @@ Class declaration can have type parameters and superclass. When you omit supercl
 
 Module declaration takes optional _self type_ parameter, which defines a constraint about a class when the module is mixed.
 
-```
+```rbs
 interface _Each[A, B]
   def each: { (A) -> void } -> B
 end
@@ -572,7 +572,7 @@ class Bar = Array
 
 The syntax defines a class and the definition is equivalent to the right-hand-side.
 
-```
+```rbs
 class Baz < Bar[String]    # Class alias can be inherited
   include Foo              # Module alias can be included
 end
@@ -590,7 +590,7 @@ end
 
 Interface declaration can have parameters but allows only a few of the members.
 
-```
+```rbs
 interface _Hashing
   def hash: () -> Integer
   def eql?: (untyped) -> bool
@@ -602,7 +602,7 @@ There are several limitations which are not described in the grammar.
 1. Interface cannot `include` modules
 2. Interface cannot have singleton method definitions
 
-```
+```rbs
 interface _Foo
   include Bar                  # Error: cannot include modules
   def self.new: () -> Foo      # Error: cannot include singleton method definitions
@@ -613,14 +613,14 @@ end
 
 You can declare an alias of types.
 
-```
+```rbs
 type subject = Attendee | Speaker
 type JSON::t = Integer | TrueClass | FalseClass | String | Hash[Symbol, t] | Array[t]
 ```
 
 Type alias can be generic like class, module, and interface.
 
-```
+```rbs
 type list[out T] = [T, list[T]] | nil
 ```
 
@@ -628,7 +628,7 @@ type list[out T] = [T, list[T]] | nil
 
 You can declare a constant.
 
-```
+```rbs
 Person::DefaultEmailAddress: String
 ```
 
@@ -636,13 +636,13 @@ Person::DefaultEmailAddress: String
 
 You can declare a global variable.
 
-```
+```rbs
 $LOAD_PATH: Array[String]
 ```
 
 ### Generics
 
-```md
+```markdown
 _module-type-parameter_ ::= _generics-unchecked_ _generics-variance_ _type-variable_ _generics-bound_
 
 _method-type-param_ ::= _type-variable_ _generics-bound_
@@ -677,7 +677,7 @@ For classes with type parameters, you may specify if they are "invariant" (defau
 
 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:
 
-```
+```rbs
 # The `T` type parameter is covariant.
 class Array[out T]
   # etc.
@@ -732,7 +732,7 @@ The upper bound must be one of a class instance type, interface type, or class s
 
 Directives are placed at the top of a file and provides per-file-basis features.
 
-```
+```markdown
 _use-directive_ ::= `use` _use-clauses_
 
 _use-clauses_ ::= _use-clause_ `,` ... `,` _use-clause_
@@ -745,7 +745,7 @@ _use-clause_ ::= _type-name_                           # Single use clause
 The *use directive* defines relative type names that is an alias of other type names.
 We can use the simple type names if it is declared with *use*.
 
-```
+```rbs
 use RBS::Namespace        # => Defines `Namespace`
 use RBS::TypeName as TN   # => Defines `TN`
 use RBS::AST::*           # => Defines modules under `::RBS::AST::` namespace
@@ -755,7 +755,7 @@ use RBS::AST::*           # => Defines modules under `::RBS::AST::` namespace
 
 You can write single line comments. Comments must be on their own line. Comments can lead with whitespace.
 
-```
+```rbs
 # This if interface Foo
 # Usage of Foo is bar
 interface _Foo