rbs 4.1.0-java

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
+```

data/docs/stdlib.md

@@ -0,0 +1,147 @@
+# Testing Core API and Standard Library Types
+
+This is a guide for testing core/stdlib types.
+
+## Add Tests
+
+We support writing tests for core/stdlib signatures.
+
+### Writing tests
+
+First, execute `generate:stdlib_test` rake task with a class name that you want to test.
+
+```console
+$ bundle exec rake 'generate:stdlib_test[String]'
+Created: test/stdlib/String_test.rb
+```
+
+It generates `test/stdlib/[class_name]_test.rb`.
+The test scripts would look like the following:
+
+```rb
+class StringSingletonTest < Test::Unit::TestCase
+  include TypeAssertions
+
+  testing "singleton(::String)"
+
+  def test_initialize
+    assert_send_type "() -> String",
+                     String, :new
+    assert_send_type "(String) -> String",
+                     String, :new, ""
+    assert_send_type "(String, encoding: Encoding) -> String",
+                     String, :new, "", encoding: Encoding::ASCII_8BIT
+    assert_send_type "(String, encoding: Encoding, capacity: Integer) -> String",
+                     String, :new, "", encoding: Encoding::ASCII_8BIT, capacity: 123
+    assert_send_type "(encoding: Encoding, capacity: Integer) -> String",
+                     String, :new, encoding: Encoding::ASCII_8BIT, capacity: 123
+    assert_send_type "(ToStr) -> String",
+                     String, :new, ToStr.new("")
+    assert_send_type "(encoding: ToStr) -> String",
+                     String, :new, encoding: ToStr.new('Shift_JIS')
+    assert_send_type "(capacity: ToInt) -> String",
+                     String, :new, capacity: ToInt.new(123)
+  end
+end
+
+class StringTest < Test::Unit::TestCase
+  include TypeAssertions
+
+  testing "::String"
+
+  def test_gsub
+    assert_send_type "(Regexp, String) -> String",
+                     "string", :gsub, /./, ""
+    assert_send_type "(String, String) -> String",
+                     "string", :gsub, "a", "b"
+    assert_send_type "(Regexp) { (String) -> String } -> String",
+                     "string", :gsub, /./ do |x| "" end
+    assert_send_type "(Regexp) { (String) -> ToS } -> String",
+                     "string", :gsub, /./ do |x| ToS.new("") end
+    assert_send_type "(Regexp, Hash[String, String]) -> String",
+                     "string", :gsub, /./, {"foo" => "bar"}
+    assert_send_type "(Regexp) -> Enumerator[String, self]",
+                     "string", :gsub, /./
+    assert_send_type "(String) -> Enumerator[String, self]",
+                     "string", :gsub, ""
+    assert_send_type "(ToStr, ToStr) -> String",
+                     "string", :gsub, ToStr.new("a"), ToStr.new("b")
+  end
+end
+```
+
+You need include `TypeAssertions` which provide useful methods for you.
+`testing` method call tells which class is the subject of the class.
+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
+```