rbs 0.2.0

data/docs/stdlib.md

@@ -0,0 +1,152 @@
+# Stdlib Signatures Guide
+
+This is a guide for contributing to `ruby-signature` by writing/revising stdlib signatures.
+
+The typical steps of writing signatures will be like the following:
+
+1. Generate a prototype
+2. Import RDoc document
+3. Give correct types to the prototype
+4. Add tests
+
+## Signatures
+
+Signatures for standard libraries are located in `stdlib` directory. `stdlib/builtin` is for builtin libraries. Other libraries have directories like `stdlib/set` or `stdlib/pathname`.
+
+To write signatures see [syntax guide](syntax.md).
+
+## Generating prototypes
+
+`ruby-signature` provides a tool to generate a prototype of signatures, `rbs prototype`.
+It provides several options, `rbi` from Sorbet RBI files, `rb` from Ruby code, and `runtime` from runtime API.
+`runtime` should be the best option for standard libraries because they may be implemented in C, no Ruby source code.
+
+The tool `require`s all of the libraries specified with `-r` option, and then use introspection APIs like `instance_methods` to know the structure of the class.
+The commandline receives the name of classes you want to prototype, exact class name (like `Pathname`) or pattern with `*` (like `IO::*`).
+
+```
+$ bundle exec rbs prototype runtime --require pathname Pathname
+class Pathname
+  def self.getwd: () -> untyped
+
+  def self.glob: (*untyped) -> untyped
+
+  def self.pwd: () -> untyped
+
+  def +: (untyped other) -> untyped
+
+  alias / +
+
+  def <=>: (untyped) -> untyped
+
+  # snip
+end
+
+# snip
+```
+
+The prototype includes:
+
+* Instance method definitions,
+* Singleton method definitions,
+* Includes, and
+* Constants
+
+It generate a simple prototype in the sense that all of the types included are `untyped`.
+But it will help you to have an overview of the signatures you are trying to write.
+
+### What to do with existing RBS files
+
+Generating prototypes will override everything, so the problem is if there is a RBS files already.
+You can try to find missing parts, or you can start from the scratch.
+
+One non-trivial but absolutely better solution is to make a tool:
+
+1. To load type definitions from existing RBS file, and
+2. Generate prototypes only for missing methods.
+
+## Import RDoc document
+
+The next step should be importing RDoc documents.
+
+```
+$ bin/annotate-with-rdoc stdlib/pathname/pathname.rbs
+Loading store from /Users/soutaro/.rbenv/versions/2.7.0-dev/share/ri/2.7.0/system...
+Loading store from /Users/soutaro/.rbenv/versions/2.7.0-dev/share/ri/2.7.0/site...
+Opening stdlib/pathname/pathname.rbs...
+  Importing documentation for Pathname...
+    Processing glob...
+    Processing +...
+    # snip
+Writing stdlib/pathname/pathname.rbs...
+```
+
+The `annotate-with-rdoc` command adds annotations to RBS files.
+
+1. Query RDoc documents to annotate classes, modules, methods, and constants,
+2. Put annotations on RBS AST, and
+3. Update the given .RBS files
+
+We recommend using the command to annotate the RBS files.
+
+## Writing types
+
+The next step is to replace `untyped` types in the prototype.
+See [syntax guide](syntax.md) for the detail of the syntax.
+
+We can show some of the guides for writing types.
+
+1. Use `bool` for truth values, truthy or falsey. More specific types like `TrueClass | FalseClass` may be too strict.
+2. Use `void` if the return value is useless.
+3. Use `nil` instead of `NilClass`.
+4. The most strict types may not be the best types. Use `untyped` if you cannot find the best one.
+
+## Add Tests
+
+We support writing tests for stdlib signatures.
+
+### Writing tests
+
+First, execute `generate:stdlib_test` rake task with a class name that you want to test.
+
+```bash
+$ 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 StringTest < StdlibTest
+  target String
+  using hook.refinement
+
+  def test_gsub
+    s = "string"
+    s.gsub(/./, "")
+    s.gsub("a", "b")
+    s.gsub(/./) {|x| "" }
+    s.gsub(/./, {"foo" => "bar"})
+    s.gsub(/./)
+    s.gsub("")
+  end
+end
+```
+
+You need two method calls, `target` and `using`.
+`target` method call tells which class is the subject of the class.
+`using hook.refinement` installs a special instrumentation for stdlib, based on refinements.
+And you write the sample programs which calls all of the patterns of overloads.
+
+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.
+
+### Running tests
+
+You can run the test with:
+
+```
+$ bundle exec ruby bin/test_runner.rb         # Run all tests
+$ bundle exec ruby test/stdlib/String_test.rb # Run specific tests
+```

data/docs/syntax.md

@@ -0,0 +1,528 @@
+# Syntax
+
+## Types
+
+```markdown
+_type_ ::= _class-name_ _type-arguments_                (Class instance type)
+         | _interface-name_ _type-arguments_            (Interface type)
+         | `singleton(` _class-name_ `)`                (Class singleton type)
+         | _alias-name_                                 (Alias type)
+         | _literal_                                    (Literal type)
+         | _type_ `|` _type_                            (Union type)
+         | _type_ `&` _type_                            (Intersection type)
+         | _type_ `?`                                   (Optional type)
+         | `{` _record-name_ `:` _type_ `,` ... `}`     (Record type)
+         | `[]` | `[` _type_ `,` ... `]`                (Tuples)
+         | _type-variable_                              (Type variables)
+         | `^(` _parameters_ `) ->` _type_              (Proc type)
+         | `self`
+         | `instance`
+         | `class`
+         | `bool`
+         | `untyped`
+         | `nil`
+         | `top`
+         | `bot`
+         | `void`
+
+_class-name_ ::= _namespace_ /[A-Z]\w*/
+_interface-name_ ::= _namespace_ /_[A-Z]\w*/
+_alias-name_ ::= _namespace_ /[a-z]\w*/
+
+_type-variable_ ::= /[A-Z]\w*/
+
+_namespace_ ::=                                         (Empty namespace)
+              | `::`                                    (Root)
+              | _namespace_ /[A-Z]\w*/ `::`             (Namespace)
+
+_type-arguments_ ::=                                    (No application)
+                   | `[` _type_ `,` ... `]`             (Type application)
+
+_literal_ ::= _string-literal_
+            | _symbol-literal_
+            | _integer-literal_
+            | `true`
+            | `false`
+```
+
+### Class instance type
+
+Class instance type denotes _an instance of a class_.
+
+```
+Integer                      # Instance of Integer class
+::Integer                    # Instance of ::Integer class
+Hash[Symbol, String]         # Instance of Hash class with type application of Symbol and String
+```
+
+### Interface type
+
+Interface type denotes _type of a value which can be a subtype of the interface_.
+
+```
+_ToS                          # _ToS interface
+::MyApp::_Each[String]        # Interface name with namespace and type application
+```
+
+### Class singleton type
+
+Class singleton type denotes _the type of a singleton object of a class_.
+
+```
+singleton(String)
+singleton(::Hash)            # Class singleton type cannot be parametrized.
+```
+
+### Alias type
+
+Alias type denotes an alias declared with _alias declaration_.
+
+The name of type aliases starts with lowercase `[a-z]`.
+
+
+```
+name
+::JSON::t                    # Alias name with namespace
+```
+
+### Literal type
+
+Literal type denotes _a type with only one value of the literal_.
+
+```
+123                         # Integer
+"hello world"               # A string
+:to_s                       # A symbol
+true                        # true or false
+```
+
+### Union type
+
+Union type denotes _a type of one of the given types_.
+
+```
+Integer | String           # Integer or String
+Array[Integer | String]    # Array of Integer or String
+```
+
+### Intersection type
+
+Intersection type denotes _a type of all of the given types_.
+
+```
+Integer & String           # Integer and String
+```
+
+Note that `&` has higher precedence than `|` that `Integer & String | Symbol` is `(Integer & String) | Symbol`.
+
+### Optional type
+
+Optional type denotes _a type of value or nil_.
+
+```
+Integer?
+Array[Integer?]
+```
+
+### Record type
+
+Records are `Hash` objects, fixed set of keys, and heterogeneous.
+
+```
+{ id: Integer, name: String }     # Hash object like `{ id: 31, name: String }`
+```
+
+### Tuple type
+
+Tuples are `Array` objects, fixed size and heterogeneous.
+
+```
+[ ]                               # Empty like `[]`
+[String]                          # Single string like `["hi"]`
+[Integer, Integer]                # Pair of integers like `[1, 2]`
+[Symbol, Integer, Integer]        # Tuple of Symbol, Integer, and Integer like `[:pair, 30, 22]`
+```
+
+*Empty tuple* or *1-tuple* sound strange, but RBS allows these types.
+
+### Type variable
+
+```
+U
+T
+S
+Elem
+```
+
+Type variables cannot be distinguished from _class instance types_.
+They are scoped in _class/module/interface declaration_ or _generic method types_.
+
+```
+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.
+end
+```
+
+### Proc type
+
+Proc type denots type of procedures, `Proc` instances.
+
+```
+^(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`
+```
+
+### Base types
+
+`self` denotes the type of receiver. The type is used to model the open recursion via `self`.
+
+`instance` denotes the type of instance of the class. `class` is the singleton of the class.
+
+`bool` is an abstract type for truth value.
+
+`untyped` is for _a type without type checking_. It is `?` in gradual typing, _dynamic_ in some languages like C#, and _any_ in TypeScript. It is both subtype _and_ supertype of all of the types. (The type was `any` but renamed to `untyped`.)
+
+`nil` is for _nil_.
+
+`top` is a supertype of all of the types. `bot` is a subtype of all of the types.
+
+`void` is a supertype of all of the types.
+
+#### `nil` or `NilClass`?
+
+We recommend using `nil`.
+
+#### `bool` or `TrueClass | FalseClass`
+
+We recommend using `bool` because it is more close to Ruby's semantics. If the type of a parameter of a method is `bool`, we usually pass `true` and `false`, and also `nil` or any other values. `TrueClass | FalseClass` rejects other values than `true` and `false`.
+
+#### `void`, `bool`, or `top`?
+
+They are all equivalent for the type system; they are all _top type_.
+
+`void` tells developers a hint that _the value should not be used_. `bool` implies the value is used as a truth value. `top` is anything else.
+
+## Method Types
+
+```markdown
+_method-type_ ::= `(` _parameters_ `) ->` _type_                                       # Method without block
+                | `(` _parameters_ `) { (` _parameters_ `) -> ` _type_ `} ->` _type_   # Method with required block
+                | `(` _parameters_ `) ?{ (` _parameters_ `) -> ` _type_ `} ->` _type_  # Method with optional block
+
+_parameters_ ::= _required-positionals_ _optional-positionals_ _rest-positional_ _trailing-positionals_ _keywords_
+
+_paramater_ ::= _type_ _var-name_                                  # Parameter with var name
+              | _type_                                             # Parameter without var name
+_required-positionals_ ::= _parameter_ `,` ...
+_optional-positionals_ ::= `?` _parameter_ `,` ...
+_rest-positional_ ::=                                              # Empty
+                    | `*` _parameter_
+_trailing-positionals_ ::= _parameter_ `,` ...
+_keywords_ ::=                                                     # Empty
+             | `**` _parameter_                                    # Rest keyword
+             | _keyword_ `:` _parameter_ `,` _keywords_            # Required keyword
+             | `?` _keyword_ `:` _parameter_ `,` _keywords_        # Optional keyword
+
+_var-name_ ::= /[a-z]\w*/
+```
+
+### Parameters
+
+A parameter can be a type or a pair of type and variable name.
+Variable name can be used for documentation.
+
+### Examples
+
+```
+# Two required positional `Integer` parameters, and returns `String`
+(Integer, Integer) -> String
+
+# Two optional parameters `size` and `name`.
+# `name` is a optional parameter with optional type so that developer can omit, pass a string, or pass `nil`.
+(?Integer size, ?String? name) -> String
+
+# Method type with a rest parameter
+(*Integer, Integer) -> void
+
+# `size` is a required keyword, with variable name of `sz`.
+# `name` is a optional keyword.
+# `created_at` is a optional keyword, and the value can be `nil`.
+(size: Integer sz, ?name: String, ?created_at: Time?) -> void
+```
+
+## Members
+
+```markdown
+_member_ ::= _ivar-member_                # Ivar definition
+           | _method-member_              # Method definition
+           | _attribute-member_           # Attribute definition
+           | _include-member_             # Mixin (include)
+           | _extend-member_              # Mixin (extend)
+           | _prepend-member_             # Mixin (prepend)
+           | _alias-member_               # Alias
+           | `public`                     # Public
+           | `private`                    # Private
+
+_ivar-member_ ::= _ivar-name_ `:` _type_
+
+_method-member_ ::= `def` _method-name_ `:` _method-types_            # Instance method
+                  | `def self.` _method-name_ `:` _method-types_      # Singleton method
+                  | `def self?.` _method-name_ `:` _method-types_     # Singleton and instance method
+
+_method-types_ ::=                                                       # Empty
+                 | `super`                                               # `super` overloading
+                 | _type-parameters_ _method-type_ `|` _method-types_    # Overloading types
+
+_type-parameters_ ::=                                                 # Empty
+                    | `[` _type-variable_ `,` ... `]`
+
+_attribute-member_ ::= _attribute-type_ _method-name_ `:` _type_                     # Attribute
+                     | _attribute-type_ _method-name_ `(` _ivar-name_ `) :` _type_   # Attribute with variable name specification
+                     | _attribute-type_ _method-name_ `() :` _type_                  # Attribute without variable
+
+_attribute-type_ ::= `attr_reader` | `attr_writer` | `attr_accessor`
+
+_include-member_ ::= `include` _class-name_ _type-arguments_
+                   | `include` _interface-name_ _type-arguments_
+_extend-member_ ::= `extend` _class-name_ _type-arguments_
+                  | `extend` _interface-name_ _type-arguments_
+_prepend-member_ ::= `prepend` _class-name_ _type-arguments_
+
+_alias-member_ ::= `alias` _method-name_ _method-name_
+                 | `alias self.` _method-name_ `self.` _method-name_
+
+_ivar-name_ ::= /@\w+/
+_method-name_ ::= ...
+                | /`[^`]+`/
+```
+
+### Ivar definition
+
+An instance variable definition consists of the name of an instance variable and its type.
+
+```
+@name: String
+@value: Hash[Symbol, Key]
+```
+
+### Method definition
+
+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 both instance and singleton.
+
+```
+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
+```
+
+The method type can be connected with `|`s to define an overloaded method.
+
+```
+def +: (Float) -> Float
+     | (Integer) -> Integer
+     | (Numeric) -> Numeric
+```
+
+You need extra parentheses on return type to avoid ambiguity.
+
+```
+def +: (Float | Integer) -> (Float | Integer)
+     | (Numeric) -> Numeric
+```
+
+Method types can end with `super` which means the methods from existing definitions.
+This is useful to define an _extension_, which adds a new variation to the existing method preserving the original behavior.
+
+### Attribute definition
+
+Attribute definitions help to define methods and instance variables based on the convention of `attr_reader`, `attr_writer` and `attr_accessor` methods in Ruby.
+
+You can specify the name of instance variable using `(@some_name)` syntax and also omit the instance variable definition by specifying `()`.
+
+```
+# Defines `id` method and `@id` instance variable.
+attr_reader id: Integer
+# @id: Integer
+# def id: () -> Integer
+
+# Defines `name=` method and `raw_name` instance variable.
+attr_writer name (@raw_name) : String
+# @raw_name: String
+# def name=: (String) -> String
+
+# Defines `people` and `people=` methods, but no instance variable.
+attr_accessor people (): Array[Person]
+# def people: () -> Array[Person]
+# def people=: (Array[Person]) -> Array[Person]
+```
+
+### Mixin (include), Mixin (extend), Mixin (prepend)
+
+You can define mixins between class and modules.
+
+```
+include Kernel
+include Enumerable[String, void]
+extend ActiveSupport::Concern
+```
+
+You can also `include` or `extend` an interface.
+
+```
+include _Hashing
+extend _LikeString
+```
+
+This allows importing `def`s from the interface to help developer implementing a set of methods.
+
+### Alias
+
+You can define an alias between methods.
+
+```
+def map: [X] () { (String) -> X } -> Array[X]
+alias collect map                                   # `#collect` has the same type with `map`
+```
+
+### `public`, `private`
+
+`public` and `private` allows specifying the visibility of methods.
+
+These work only as _statements_, not per-method specifier.
+
+## Declarations
+
+```markdown
+_decl_ ::= _class-decl_                         # Class declaration
+         | _module-decl_                        # Module declaration
+         | _interface-decl_                     # Interface declaration
+         | _extension-decl_                     # Extension declaration
+         | _type-alias-decl_                    # Type alias declaration
+         | _const-decl_                         # Constant declaration
+         | _global-decl_                        # Global declaration
+
+_class-decl_ ::= `class` _class-name_ _module-type-parameters_ _members_ `end`
+               | `class` _class-name_ _module-type-parameters_ `<` _class-name_ _type-arguments_ _members_ `end`
+
+_module-decl_ ::= `module` _module-name_ _module-type-parameters_ _members_ `end`
+                | `module` _module-name_ _module-type-parameters_ `:` _class-name_ _type-arguments_ _members_ `end`
+
+_interface-decl_ ::= `interface` _interface-name_ _module-type-parameters_ _interface-members_ `end`
+
+_interface-members_ ::= _method-member_              # Method
+                      | _include-member_             # Mixin (include)
+                      | _alias-member_               # Alias
+
+_extension-decl_ ::= `extension` _class-name_ _type-parameters_ `(` _extension-name_ `)` _members_ `end`
+
+_type-alias-decl_ ::= `type` _alias-name_ `=` _type_
+
+_const-decl_ ::= _const-name_ `:` _type_
+
+_global-decl_ ::= _global-name_ `:` _type_
+
+_const-name_ ::= _namespace_ /[A-Z]\w*/
+_global-name_ ::= /$[a-zA-Z]\w+/ | ...
+
+_module-type-parameters_ ::=                                                  # Empty
+                           | `[` _module-type-parameter_ `,` ... `]`
+
+_module-type-parameter_ ::= _variance_ _type-variable_
+_variance_ ::= `out` | `in`
+```
+
+### Class declaration
+
+Class declaration can have type parameters and superclass. When you omit superclass, `::Object` is assumed.
+
+```
+class Ref[A] < Object
+  attr_reader value: A
+  def initialize: (value: A) -> void
+end
+```
+
+### Module declaration
+
+Module declaration takes optional _self type_ parameter, which defines a constraint about a class when the module is mixed.
+
+```
+interface _Each[A, B]
+  def each: { (A) -> void } -> B
+end
+
+module Enumerable[A, B] : _Each[A, B]
+  def count: () -> Integer
+end
+```
+
+The `Enumerable` module above requires `each` method for enumerating objects.
+
+### Interface declaration
+
+Interface declaration can have parameters but allows only a few of the members.
+
+```
+interface _Hashing
+  def hash: () -> Integer
+  def eql?: (any) -> bool
+end
+```
+
+There are several limitations which are not described in the grammar.
+
+1. Interface cannot `include` modules
+2. Interface cannot have singleton method definitions
+
+```
+interface _Foo
+  include Bar                  # Error: cannot include modules
+  def self.new: () -> Foo      # Error: cannot include singleton method definitions
+end
+```
+
+### Extension declaration
+
+Extension is to model _open class_.
+
+```
+extension Kernel (Pathname)
+  def Pathname: (String) -> Pathname
+end
+
+extension Array[A] (ActiveSupport)
+  def to: (Integer) -> Array[A]
+  def from: (Integer) -> Array[A]
+  def second: () -> A?
+  def third: () -> A?
+end
+```
+
+### Type alias declaration
+
+You can declare an alias of types.
+
+```
+type subject = Attendee | Speaker
+type JSON::t = Integer | TrueClass | FalseClass | String | Hash[Symbol, t] | Array[t]
+```
+
+### Constant type declaration
+
+You can declare a constant.
+
+```
+Person::DefaultEmailAddress: String
+```
+
+### Global type declaration
+
+You can declare a global variable.
+
+```
+$LOAD_PATH: Array[String]
+```
+