rbs 3.3.2 → 3.4.0

data/core/trace_point.rbs

@@ -1,6 +1,4 @@
 # <!-- rdoc-file=trace_point.rb -->
-# Document-class: TracePoint
-#
 # A class that provides the functionality of Kernel#set_trace_func in a nice
 # Object-Oriented API.
 #
@@ -207,9 +205,8 @@ class TracePoint < Object
   # -->
   # Return the generated binding object from event.
   #
-  # Note that for `c_call` and `c_return` events, the binding returned is the
-  # binding of the nearest Ruby method calling the C method, since C methods
-  # themselves do not have bindings.
+  # Note that for `c_call` and `c_return` events, the method will return `nil`,
+  # since C methods themselves do not have bindings.
   #
   def binding: () -> Binding?
 

data/core/true_class.rbs

@@ -1,66 +1,99 @@
 # <!-- rdoc-file=object.c -->
-# The global value `true` is the only instance of class TrueClass and represents
-# a logically true value in boolean expressions. The class provides operators
-# allowing `true` to be used in logical expressions.
+# The class of the singleton object `true`.
+#
+# Several of its methods act as operators:
+#
+# *   #&
+# *   #|
+# *   #===
+# *   #^
+#
+#
+# One other method:
+#
+# *   #to_s and its alias #inspect.
 #
 class TrueClass
   def !: () -> false
 
   # <!--
   #   rdoc-file=object.c
-  #   - true & obj    -> true or false
+  #   - true & object -> true or false
   # -->
-  # And---Returns `false` if *obj* is `nil` or `false`, `true` otherwise.
+  # Returns `false` if `object` is `false` or `nil`, `true` otherwise:
+  #
+  # true & Object.new # => true true & false      # => false true & nil        #
+  # => false
   #
   def &: (false | nil) -> false
        | (untyped obj) -> bool
 
   # <!--
   #   rdoc-file=object.c
-  #   - obj === other   -> true or false
+  #   - true === other -> true or false
+  #   - false === other -> true or false
+  #   - nil === other -> true or false
   # -->
-  # Case Equality -- For class Object, effectively the same as calling `#==`, but
-  # typically overridden by descendants to provide meaningful semantics in `case`
-  # statements.
+  # Returns `true` or `false`.
+  #
+  # Like Object#==, if `object` is an instance of Object (and not an instance of
+  # one of its many subclasses).
+  #
+  # This method is commonly overridden by those subclasses, to provide meaningful
+  # semantics in `case` statements.
   #
   def ===: (true) -> true
          | (untyped obj) -> bool
 
   # <!--
   #   rdoc-file=object.c
-  #   - true ^ obj   -> !obj
+  #   - true ^ object -> !object
   # -->
-  # Exclusive Or---Returns `true` if *obj* is `nil` or `false`, `false` otherwise.
+  # Returns `true` if `object` is `false` or `nil`, `false` otherwise:
+  #
+  #     true ^ Object.new # => false
+  #     true ^ false      # => true
+  #     true ^ nil        # => true
   #
   def ^: (false | nil) -> true
        | (untyped obj) -> bool
 
   # <!-- rdoc-file=object.c -->
-  # The string representation of `true` is "true".
+  # Returns string `'true'`:
+  #
+  #     true.to_s # => "true"
+  #
+  # TrueClass#inspect is an alias for TrueClass#to_s.
   #
   alias inspect to_s
 
   # <!--
   #   rdoc-file=object.c
-  #   - true.to_s   ->  "true"
+  #   - true.to_s -> 'true'
   # -->
-  # The string representation of `true` is "true".
+  # Returns string `'true'`:
+  #
+  #     true.to_s # => "true"
+  #
+  # TrueClass#inspect is an alias for TrueClass#to_s.
   #
   def to_s: () -> "true"
 
   # <!--
   #   rdoc-file=object.c
-  #   - true | obj   -> true
+  #   - true | object -> true
   # -->
-  # Or---Returns `true`. As *obj* is an argument to a method call, it is always
-  # evaluated; there is no short-circuit evaluation in this case.
+  # Returns `true`:
   #
-  #     true |  puts("or")
-  #     true || puts("logical or")
+  #     true | Object.new # => true
+  #     true | false      # => true
+  #     true | nil        # => true
   #
-  # *produces:*
+  # Argument `object` is evaluated. This is different from `true` with the
+  # short-circuit operator, whose operand is evaluated only if necessary:
   #
-  #     or
+  #     true | raise # => Raises RuntimeError.
+  #     true || raise # => true
   #
   def |: (untyped obj) -> true
 end

data/core/warning.rbs

@@ -5,11 +5,11 @@
 #
 # Changing the behavior of Warning.warn is useful to customize how warnings are
 # handled by Ruby, for instance by filtering some warnings, and/or outputting
-# warnings somewhere other than $stderr.
+# warnings somewhere other than `$stderr`.
 #
 # If you want to change the behavior of Warning.warn you should use
-# +Warning.extend(MyNewModuleWithWarnMethod)+ and you can use `super` to get the
-# default behavior of printing the warning to $stderr.
+# `Warning.extend(MyNewModuleWithWarnMethod)` and you can use `super` to get the
+# default behavior of printing the warning to `$stderr`.
 #
 # Example:
 #     module MyWarningFilter
@@ -26,12 +26,13 @@
 # You should never redefine Warning#warn (the instance method), as that will
 # then no longer provide a way to use the default behavior.
 #
-# The `warning` gem provides convenient ways to customize Warning.warn.
+# The [warning](https://rubygems.org/gems/warning) gem provides convenient ways
+# to customize Warning.warn.
 #
 module Warning
   # The types of categories the `Warning` module understands.
   #
-  type category = :deprecated | :experimental
+  type category = :deprecated | :experimental | :performance
 
   # <!--
   #   rdoc-file=error.c
@@ -42,17 +43,19 @@ module Warning
   #
   # `:deprecated`
   # :   deprecation warnings
+  #     *   assignment of non-nil value to `$,` and `$;`
+  #     *   keyword arguments
   #
-  # *   assignment of non-nil value to `$,` and `$;`
-  # *   keyword arguments
-  # *   proc/lambda without block
-  #
-  # etc.
+  #     etc.
   #
   # `:experimental`
   # :   experimental features
+  #     *   Pattern matching
+  #
   #
-  # *   Pattern matching
+  # `:performance`
+  # :   performance hints
+  #     *   Shape variation limit
   #
   def self.[]: (category) -> bool
 

data/docs/data_and_struct.md

@@ -55,3 +55,32 @@ 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,58 @@
+# 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: abbrev
+  - 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/syntax.md

@@ -44,7 +44,7 @@ _literal_ ::= _string-literal_
             | `true`
             | `false`
 
-_proc_ ::= _parameters?_ _self-type-binding?_ _block?_ `->` _type_
+_proc_ ::= `^` _parameters?_ _self-type-binding?_ _block?_ `->` _type_
 ```
 
 ### Class instance type
@@ -311,8 +311,6 @@ end
 ```markdown
 _method-type_ ::= _parameters?_ _block?_ `->` _type_                # Method type
 
-_proc_ ::= `^` _parameters?_ _self-type-binding?_ _block?_ `->` _type_  # Proc type
-
 _parameters?_ ::=                   (Empty)
                 | _parameters_      (Parameters)
 
@@ -435,8 +433,8 @@ _visibility-member_ ::= _visibility_
 
 _ivar-name_ ::= /@\w+/
 _cvar-name_ ::= /@@\w+/
-_method-name_ ::= ...
-                | /`[^`]+`/
+_method-name_ ::= _most of the possible ruby method names_
+                | /`[^`]+`/                   # Quoted method names
 ```
 
 ### Ivar definition

data/docs/tools.md

@@ -14,3 +14,4 @@ This documentation describes major tools related to RBS. They are listed alphabe
 * Sublime Text: [sublime-rbs-plugin](https://github.com/soutaro/sublime-rbs-plugin)
 * Vim: [rbs.vim](https://github.com/pocke/rbs.vim)
 * Visual Studio Code: [vscode-rbs-syntax](https://github.com/soutaro/vscode-rbs-syntax)
+* NeoVim: [tree-sitter-rbs](https://github.com/joker1007/tree-sitter-rbs)