rbs 4.1.0.pre.2-java

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[E]
+  def *: (String) -> String
+       | (Integer) -> Array[E]
+end
+```
+
+`Array`'s `*` method, when given a `String` returns a `String`. When given an
+`Integer`, it returns an `Array` of the same contained type `E` (in our example case, `E` 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[E]
+  def first: () -> E?
+           | (Integer) -> Array[E]
+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 `E`, 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 `(E | 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[E]
+  def filter: () { (E) -> boolish } -> ::Array[E]
+            | () -> ::Enumerator[E, ::Array[E]]
+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[E]
+  def collect: [U] () { (E) -> U } -> Array[U]
+             | () -> Enumerator[E, 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 `E`, 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[E]
+  def partition: () { (E) -> boolish } -> [Array[E], Array[E]]
+               | () -> ::Enumerator[E, [Array[E], Array[E] ]]
+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[E]
+  def to_h: () -> ::Hash[untyped, untyped]
+          | [T, U] () { (E) -> [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/repo.md

@@ -0,0 +1,125 @@
+# Third-party RBS Repository
+
+This is the spec of the directory structure for RBS files of gems without RBS files. It allows distributing RBS type definitions of gems separately from the `.gemspec` files so that the Ruby developers can type check their Ruby programs even if the dependent gems don't ship with their type definitions.
+
+The spec includes:
+
+* The directory structure, and
+* The RBS file lookup rules given _repository root_, gem name, and version.
+
+## Motivating Example
+
+Assume there is a rubygem called `bug-free-doodle` and our application depends on the library. We are trying to type check our application and we need RBS files of `bug-free-doodle`. The problem is that the `bug-free-doodle` gem doesn't ship with RBS files. The type checkers cannot resolve the type of constant `Bug::Free::Doodle` and its methods.
+
+One workaround is to add type definitions of the library in the application signatures.
+
+```rbs
+# sig/polyfill/bug-free-doodle.rbs
+
+module Bug
+  module Free
+    class Doodle
+      attr_reader name: Symbol
+      attr_reader strokes: Array[Stroke]
+
+      def initialize: (name: Symbol) -> void
+    end
+  end
+end
+```
+
+You may want to distribute the RBS file to anyone who needs it. Which version do we support? Testing it? How to load the RBS files? This is the spec you need!
+
+### Third-party RBS repository
+
+Make a directory (or you may want to `git init`) to put your _third party RBSs_.
+
+```sh
+$ make my-rbs      # Or you may want a git repository: git init my-rbs
+$ cd my-rbs
+$ mkdir gems
+```
+
+We call the `my-rbs/gems` directory _repository root_. Note that it is different from the root of the git repository. The RBS repository root is the directory that contains directories of gem names.
+
+Make a directory for the gem and the version.
+
+```sh
+$ mkdir gems/bug-free-doodle
+$ mkdir gems/bug-free-doodle/1.2.3
+```
+
+And copy the RBS file in it.
+
+```sh
+$ cp your-app/sig/polyfill/bug-free-doodle.rbs gems/bug-free-doodle/1.2.3
+```
+
+### Reading Third-party RBS
+
+`rbs` command accepts `--repo` option which points to a _repository root_. You can specify `-r` option to let the command know which gems you want to load.
+
+In this case, the _repository root_ is `./gems` and we are trying to load `bug-free-doodle` gem.
+
+```sh
+$ rbs --repo=gems -r bug-free-doodle paths
+```
+
+The `-r` option also accepts gem name with version.
+
+```sh
+$ rbs --repo=gems -r bug-free-doodle:1.2.3 paths
+```
+
+Note that the version resolution is not compatible with semantic versioning. It is optimistic. It resolves to some version unless no version for the gem is available.
+
+## Directory Structure
+
+There are directories for each gem under _repository root_. We also have directories for each version of each gem.
+
+- $REPO_ROOT/bug-free-doodle/0.2.0
+- $REPO_ROOT/bug-free-doodle/1.0
+- $REPO_ROOT/bug-free-doodle/1.2.3
+- $REPO_ROOT/bug-free-doodle/2.0
+
+Note that we assume that we have git repositories for each RBS repository, and we have a directory at the root of the git repository for _repository root_.
+
+So the git repository structure would be something like the following:
+
+- /Gemfile
+- /Gemfile.lock
+- /README.md
+- /LICENSE
+- /gems/bug-free-doodle/1.2.3/bug-free-doodle.rbs
+
+You should have `Gemfile` and `Gemfile.lock` to manage dependencies, `README.md` and `LICENSE` to documentation, and `gems` directory as _repository root_.
+
+(We call _repository root_ `gems` in this doc, but the name can be anything you like.)
+
+## Version Resolution
+
+The version resolution in RBS is optimistic. We don't block loading RBS files for _incompatible_ version in terms of semantic versioning.
+
+It tries to resolve version _n_ as follows:
+
+1. It resolves to _m_ such that _m_ is the latest version available and _m_ <= _n_ holds.
+2. It resolves to the oldest version when rule 1 cannot find version _m_.
+
+If two versions, `0.4.0`, `1.0.0` are available for a gem:
+
+| Requested version | Resolved version |
+|-------------------|------------------|
+| `0.3.0`           | `0.4.0` (Rule 2) |
+| `0.4.0`           | `0.4.0`          |
+| `0.5.0`           | `0.4.0`          |
+| `1.0.0`           | `1.0.0`          |
+| `2.0.0`           | `1.0.0`          |
+
+This is not compatible with the concept of semantic versioning. We don't want to block users to load RBS even for incompatible versions of gems.
+
+We believe this makes more sense because:
+
+* Using (potentially) incompatible type definitions are better than no type definition.
+* Users can stop loading RBS if incompatibility causes an issue and falling back to hand-written polyfills.
+
+

data/docs/rust.md

@@ -0,0 +1,96 @@
+# Rust Crates
+
+RBS provides two Rust crates:
+
+- **`ruby-rbs-sys`** -- Low-level FFI bindings to the RBS C parser
+- **`ruby-rbs`** -- High-level safe Rust API for parsing RBS signatures
+
+Both crates are published to [crates.io](https://crates.io/) and are developed within the `rust/` directory of this repository.
+
+## Vendored RBS Source
+
+The Rust crates depend on the RBS C parser source code (`include/`, `src/`) and configuration (`config.yml`) from this repository. These files are vendored into each crate's `vendor/rbs/` directory, which is managed by Rake tasks and not tracked by git.
+
+The file `rust/rbs_version` records which version of RBS the Rust crates are pinned to.
+
+## Setup
+
+After cloning the repository, set up the vendored source before building the Rust crates:
+
+```bash
+rake rust:rbs:sync       # Uses the pinned version from rust/rbs_version
+```
+
+Then build and test:
+
+```bash
+cd rust
+cargo test
+```
+
+## Rake Tasks
+
+### `rake rust:rbs:sync`
+
+Copies the source files from the pinned version into each crate's `vendor/rbs/`. The copied files are made read-only to prevent accidental edits.
+
+### `rake rust:rbs:pin[VERSION]`
+
+Records a git tag in `rust/rbs_version`. For example:
+
+```bash
+rake rust:rbs:pin[v4.0.3]
+```
+
+### `rake rust:publish:ruby-rbs-sys` / `rake rust:publish:ruby-rbs`
+
+Publishes each crate to crates.io individually. Each task:
+
+1. Verifies `rust/rbs_version` is set
+2. Verifies vendor directories contain real files (not symlinks)
+3. Verifies the git working tree is clean
+4. Creates a release branch and commits the vendor files
+5. Runs a dry-run to check packaging
+6. Publishes the crate
+
+Set `RBS_RUST_PUBLISH_DRY_RUN=1` to only run the dry-run step and skip the actual publish to crates.io. This is used in CI to verify that the crates can be packaged correctly.
+
+### `rake rust:rbs:symlink`
+
+If your development needs unreleased version of RBS source code, use `rake rust:rbs:symlink` to set up symlinks in vendor directories to refer the worktree source code. Changes to the C parser source are immediately reflected in Rust builds.
+
+## Publishing Workflow
+
+1. Pin the RBS version to release against:
+
+   ```bash
+   rake rust:rbs:pin[v4.0.3]
+   ```
+
+2. Sync the vendored source:
+
+   ```bash
+   rake rust:rbs:sync
+   ```
+
+3. Update crate versions in `rust/ruby-rbs-sys/Cargo.toml` and `rust/ruby-rbs/Cargo.toml`.
+
+4. Build and test:
+
+   ```bash
+   cd rust && cargo test
+   ```
+
+5. Commit the version changes and `rust/rbs_version`:
+
+   ```bash
+   git add rust/rbs_version rust/ruby-rbs-sys/Cargo.toml rust/ruby-rbs/Cargo.toml
+   git commit -m "Bump Rust crate versions"
+   ```
+
+6. Publish each crate:
+
+   ```bash
+   rake rust:publish:ruby-rbs-sys
+   rake rust:publish:ruby-rbs
+   ```

data/docs/sigs.md

@@ -0,0 +1,167 @@
+# Writing Signatures Guide
+
+You can write the signature of your applications and libraries.
+Signature of your Ruby program would help:
+
+1. Understanding the code structure
+2. Finding APIs
+
+And if you ship your gem with signature, the gem users can type check their applications!
+
+## Writing signatures
+
+You first need to write your program's signature.
+See [syntax guide](syntax.md).
+
+## Testing signatures
+
+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
+```
+
+The test installs instrumentations to spy the method calls and check if arguments/return values are correct with respect to the type of the method in signature.
+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 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
+
+If the test detects type errors, it will print error messages.
+
+### ArgumentTypeError, BlockArgumentTypeError
+
+The message means there is an unexpected type of argument or block argument.
+
+```
+ERROR -- : [Kaigi::Speaker.new] ArgumentTypeError: expected `::String` (email) but given `:"matsumoto@soutaro.com"`
+```
+
+### ArgumentError, BlockArgumentError
+
+The message means there is an unexpected argument or missing argument.
+
+```
+[Kaigi::Speaker.new] ArgumentError: expected method type (size: ::Symbol, email: ::String, name: ::String) -> ::Kaigi::Speaker
+```
+
+### ReturnTypeError, BlockReturnTypeError
+
+The message means the return value from method or block is incorrect.
+
+```
+ERROR -- : [Kaigi::Conference#each_speaker] ReturnTypeError: expected `self` but returns `[#<Kaigi::Speaker:0x00007fb2b249e5a0 @name="Soutaro Matsumoto", @email=:"matsumoto@soutaro.com">]`
+```
+
+### UnexpectedBlockError, MissingBlockError
+
+The errors are reported when required block is not given or unused block is given.
+
+```
+ERROR -- : [Kaigi::Conference#speakers] UnexpectedBlockError: unexpected block is given for `() -> ::Array[::Kaigi::Speaker]`
+```
+
+### UnresolvedOverloadingError
+
+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:
+
+```rbs
+# 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:
+
+1. Loading the testing library
+2. Setting up the test through environment variables
+
+### Loading the library
+
+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
+```
+
+### Environment variables
+
+You need to specify `RBS_TEST_TARGET` to run the test, and you can customize the test with the following environment variables.
+
+- `RBS_TEST_SKIP` (optional)
+- `RBS_TEST_OPT` (optional)
+- `RBS_TEST_LOGLEVEL` (optional)
+- `RBS_TEST_RAISE` (optional)
+
+`RBS_TEST_TARGET` is to specify the classes you want to test. `RBS_TEST_TARGET` can contain comma-separated class name pattern, which is one of an exact class name or with wildcard `*`.
+
+- `RBS_TEST_TARGET=Foo::Bar,Foo::Baz` comma separated exact class names
+- `RBS_TEST_TARGET=Foo::*` using wildcard
+
+`RBS_TEST_SKIP` is to skip some of the classes which matches with `RBS_TEST_TARGET`.
+
+`RBS_TEST_OPT` is to pass the options for rbs handling.
+You may need to specify `-r` or `-I` to load signatures.
+The default is `-I sig`.
+
+```shell
+RBS_TEST_OPT='-r logger -I sig'
+```
+
+Replacing `logger` 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.
+If the environment variable is set, it raises an exception when a type error is detected.
+You can see the backtrace how the type error is caused and debug your program or signature.
+
+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' \
+  RBS_TEST_OPT='-rlogger -Isig -Iprivate' \
+  RBS_TEST_RAISE=true \
+  RUBYOPT='-rbundler/setup -rrbs/test/setup' \
+  bundle exec rake test
+```
+
+## Testing tips
+
+### Skipping a method
+
+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
+```