rbs-relaxed 3.9.0.1

data/docs/collection.md

@@ -0,0 +1,192 @@
+# RBS Collection manager
+
+`rbs collection` sub command manages third party gems' RBS. In short, it is `bundler` for RBS.
+
+## Requirements
+
+* `git(1)`
+* `Gemfile.lock`
+
+## Usage
+
+### Setup
+
+First, generate the configuration file, `rbs_collection.yaml`, with `rbs collection init`.
+
+```console
+$ rbs collection init
+created: rbs_collection.yaml
+
+$ cat rbs_collection.yaml
+# Download sources
+sources:
+  - name: ruby/gem_rbs_collection
+    remote: https://github.com/ruby/gem_rbs_collection.git
+    revision: main
+    repo_dir: gems
+
+# A directory to install the downloaded RBSs
+path: .gem_rbs_collection
+
+# gems:
+#   # If you want to avoid installing rbs files for gems, you can specify them here.
+#   - name: GEM_NAME
+#     ignore: true
+```
+
+I also recommend updating `.gitignore`.
+
+```console
+$ echo /.gem_rbs_collection/ >> .gitignore
+```
+
+### Install dependencies
+
+Then, install gems' RBS with `rbs collection install`! It copies RBS from [the gem RBS repository](https://github.com/ruby/gem_rbs_collection) to `.gem_rbs_collection/` directory by default.
+I recommend to ignore `.gem_rbs_collection/` from version control system, such as Git.
+
+```console
+$ rbs collection install
+Installing ast:2.4 (ruby/gem_rbs_collection@4b1a2a2f64c)
+...
+It's done! 42 gems's RBSs now installed.
+```
+
+Finally the third party RBSs are available! `rbs` commands, such as `rbs validate`, automatically load the third party RBSs.
+
+### Other commands
+
+`rbs collection` has two more commands.
+
+* `rbs collection update` updates `rbs_collection.lock.yaml`.
+* `rbs collection clean` removes unnecessary rbs from `.gem_rbs_collection` directory.
+
+## 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:
+  - name: ruby/gem_rbs_collection
+    remote: https://github.com/ruby/gem_rbs_collection.git
+    revision: main
+    repo_dir: gems
+
+  # You can also add a local path as a collection source optionally.
+  - type: local
+    path: path/to/local/dir
+
+# A directory to install the downloaded RBSs
+path: .gem_rbs_collection
+
+gems:
+  # If the Gemfile.lock doesn't contain csv gem but you use csv gem,
+  # you can write the gem name explicitly to install RBS of the gem.
+  - name: csv
+
+  # If the Gemfile.lock contains nokogiri gem but you don't want to use the RBS,
+  # you can ignore the gem.
+  # `rbs collection` avoids to install nokogiri gem's RBS by this change.
+  # It is useful if the nokogiri RBS has a problem, such as compatibility issue with other RBS.
+  - name: nokogiri
+    ignore: true
+```
+
+### Avoid installing RBS
+
+There are two ways to avoid RBS installation.
+
+#### `require: false` in `Gemfile`
+
+First, you can specify `require: false` in `Gemfile`. It is the recommended way to avoid installing RBS.
+For example:
+
+```ruby
+# Gemfile
+
+gem 'GEM_NAME', require: false
+```
+
+In this case, `rbs collection` doesn't install the RBS of `GEM_NAME`.
+We recommend to specify `require: false` for `rbs` gem itself because `rbs` gem's RBS file is not necessary in most cases.
+
+#### `ignore: true` in `rbs_collection.yaml`
+
+Second, you can write `ignore: true` in `rbs_collection.yaml`. It is useful if you want to avoid installing RBS but you need to require the gem.
+
+```yaml
+# rbs_collection.yaml
+
+gems:
+  - name: GEM_NAME
+    ignore: true
+```
+
+#### Load RBS specified `require: false`
+
+You can also use `ignore: false` if you want to install RBS for a gem which you specify `require: false` in `Gemfile`.
+For example:
+
+```ruby
+# Gemfile
+
+gem 'GEM_NAME', require: false
+```
+
+```yaml
+# rbs_collection.yaml
+
+gems:
+  - name: GEM_NAME
+    ignore: false
+```
+
+In this case, `rbs collection` installs the RBS of `GEM_NAME`.
+
+### `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`
+  * The configuration file.
+  * You need to edit it if:
+    * You don't want to ignore gem's RBS.
+    * You want to add gem's RBS explicitly.
+  * You can change the file path with `--collection` option. e.g. `rbs --collection another_conf.yaml collection install`.
+* `rbs_collection.lock.yaml`
+  * RBS installs and loads RBS files with this file.
+  * It is auto-generated file. Do not edit this file.
+  * I recommend to manage it with VCS such as git.
+* `.gem_rbs_collection/`
+  * RBS installs third party RBS files to the directory.
+  * I recommend to ignore it from VCS.
+  * You can change the path with `path` option of `rbs_collection.yaml` file.
+
+
+## How it works
+
+`rbs collection` is integrated with Bundler.
+`rbs collection install` command generates `gem_rbs_collection.lock.yaml` from `gem_rbs_collection.yaml` and `Gemfile.lock`. It uses `Gemfile.lock` to detects dependencies.

data/docs/data_and_struct.md

@@ -0,0 +1,86 @@
+# Using `Data` and `Struct`
+
+`Data` and `Struct` are commonly used utilities to define simple *value* objects. The objects have attributes, and the equality between the two objects are defined by equality of the attributes. (Note that we can define additional methods and overwrite the equality definitions when we want.)
+
+```ruby
+# Defines `Measure` class with `#amount` and `#unit` attributes
+Measure = Data.define(:amount, :unit)
+```
+
+Unfortunately, supporting `Data` and `Struct` in RBS is not straightforward. You have to write down the attribute definitions and initializers in RBS.
+
+```rbs
+class Measure
+  # `attr_accessor amount: Integer` in the case of Struct
+  attr_reader amount: Integer
+  
+  # `attr_accessor unit: String` in the case of Struct
+  attr_reader unit: String
+  
+  def initialize: (Integer amount, String unit) -> void
+                | (amount: Integer, unit: String) -> void             
+end
+```
+
+This is simplified definition of the `Measure` class, for the case you only use the attributes and initializers. You can add more method definitions or inherit from `Data` class to make the definition more complete.
+
+However, it's common that you don't need all of the `Data` and `Struct` methods, like `.members` and `.[]`. When you are using those utility classes just for the attributes methods, you can simply ignore other methods or skip specifying a super class.
+
+> You may want to implement a generator that understands `Data.define` and `Struct.new`. But even with the generator, you need to edit the generated RBS files so that the attribute definitions have correct types.
+
+## Type checking class definitions using `Data` and `Struct`
+
+If you use Steep, you may need additional annotation in Ruby implementation.
+
+```ruby
+# Type error because return type of `Data.define(...)` is not `singleton(Measure)`
+Measure = Data.define(:amount, :unit)
+```
+
+You can please the type checker by adding a cast (`_`) or define the class inheriting from `Data.define(...)`.
+
+```ruby
+# Skip type checking by assigning to `_`
+Measure = _ = Data.define(:amount, :unit)
+
+# Super class is not type checked by Steep
+class Measure < Data.define(:amount, :unit)
+end
+```
+
+@soutaro has prefered inheriting from `Data.define`, but you may find an extra annonymous class in `.ancestors` [^1].
+
+```ruby
+Measure.ancestors #=> [Measure, #<Class:0xOOF>, Data, ...]
+```
+
+[^1]: [Shannon Skipper](https://github.com/havenwood) told me it in Discord
+
+## Generate prototype for `Data` and `Struct`
+
+RBS prototypes for classes using `Data` and `Struct` can be generated by `rbs prototype runtime`.
+
+```rb
+# t.rb
+class Measure < Data.define(:amount, :unit)
+end
+```
+
+```
+$ bundle exec rbs prototype runtime -R t.rb Measure
+class Measure < ::Data
+  def self.new: (untyped amount, untyped unit) -> instance
+              | (amount: untyped, unit: untyped) -> instance
+
+  def self.[]: (untyped amount, untyped unit) -> instance
+             | (amount: untyped, unit: untyped) -> instance
+
+  def self.members: () -> [ :amount, :unit ]
+
+  def members: () -> [ :amount, :unit ]
+
+  attr_reader amount: untyped
+
+  attr_reader unit: untyped
+end
+```

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

@@ -0,0 +1,309 @@
+# 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
+
+In each example, the first snippet is for *Ruby* and the second one is for *RBS*.
+
+### Zero argument methods
+
+**Example:** `String#empty?`
+
+```ruby
+"".empty?
+# => true
+"hello".empty?
+# => false
+```
+
+```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
+"homeowner".include?("house")
+# => false
+"homeowner".include?("meow")
+# => true
+```
+
+```rbs
+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
+"hello?".end_with?("!")
+# => false
+"hello?".end_with?("?")
+# => true
+"hello?".end_with?("?", "!")
+# => true
+"hello?".end_with?(".", "!")
+# => false
+```
+
+```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
+"hello".ljust(4)
+#=> "hello"
+"hello".ljust(20)
+#=> "hello               "
+"hello".ljust(20, '1234')
+#=> "hello123412341234123"
+```
+
+```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
+[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.
+
+```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
+a = "hello "
+a << "world"
+#=> "hello world"
+a << 33
+#=> "hello world!"
+```
+
+```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
+[1, 2, 3].first
+# => 1
+[].first
+# => nil
+[1, 2, 3].first(2)
+# => [1, 2]
+[].first(2)
+# => []
+```
+
+```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 would be `(Elem | nil)`.
+
+### Keyword Arguments
+
+**Example**: `String#lines`
+
+```ruby
+"hello\nworld\n".lines
+# => ["hello\n", "world\n"]
+"hello  world".lines(' ')
+# => ["hello ", " ", "world"]
+"hello\nworld\n".lines(chomp: true)
+# => ["hello", "world"]
+```
+
+```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
+Time.now
+# => 2009-06-24 12:39:54 +0900
+```
+
+```rbs
+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
+[1,2,3,4,5].filter {|num| num.even? }
+# => [2, 4]
+%w[ a b c d e f ].filter {|v| v =~ /[aeiou]/ }
+# => ["a", "e"]
+[1,2,3,4,5].filter
+```
+
+```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"]
+```
+
+```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
+a = [ "a", "b", "c", "d" ]
+a.collect {|x| x + "!"}
+# => ["a!", "b!", "c!", "d!"]
+a.collect.with_index {|x, i| x * i}
+# => ["", "b", "cc", "ddd"]
+```
+
+```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]]
+```
+
+```rbs
+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}
+```
+
+```rbs
+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.