rbs 3.4.4 → 3.5.1

data/core/time.rbs

@@ -389,6 +389,26 @@
 # You can define this method per subclasses, or on the toplevel Time class.
 #
 class Time < Object
+  # A type that's used for timeouts.
+  #
+  # All numeric types implement this, but custom classes can also implement it if desired.
+  #
+  # Usage of `Time::_Timeout` is fairly common throughout the stdlib, such as in `Kernel#sleep`,
+  # `IO#timeout=`, and `TCPSocket#new`'s `connet_timeout` field.
+  interface _Timeout
+    # Returns `[seconds, nanoseconds]`.
+    #
+    # The `seconds` should be a whole number of seconds, whereas the `nanoseconds` should be smaller
+    # than one. For example, `3.125.divmod(1)` would yield `[3, 0.125]`
+    def divmod: (1) -> [int, _TimeoutNSecs]
+  end
+
+  # The nanoseconds part of `Time::_Timeout`'s return value. See it for details
+  interface _TimeoutNSecs
+    # Convert `self` into a whole number of seconds.
+    def *: (1_000_000_000) -> int
+  end
+
   include Comparable
 
   # <!--
@@ -1083,8 +1103,8 @@ class Time < Object
   #     More digits will be truncated, as other operations of `Time`. Ignored
   #     unless the first argument is a string.
   #
-  def initialize: (?Integer? year, ?Integer? month, ?Integer? day, ?Integer? hour, ?Integer? min, ?Numeric? sec, ?String | Integer | nil) -> void
-                | (?Integer? year, ?Integer? month, ?Integer? day, ?Integer? hour, ?Integer? min, ?Numeric? sec, in: String | Integer | nil) -> void
+  def initialize: (?Integer year, ?Integer? month, ?Integer? day, ?Integer? hour, ?Integer? min, ?Numeric? sec, ?String | Integer | nil) -> void
+                | (?Integer year, ?Integer? month, ?Integer? day, ?Integer? hour, ?Integer? min, ?Numeric? sec, in: String | Integer | nil) -> void
                 | (String, ?in: string | int | nil, ?precision: int) -> void
 
   # <!--
@@ -1333,7 +1353,7 @@ class Time < Object
   # The returned array is suitable for use as an argument to Time.utc or
   # Time.local to create a new `Time` object.
   #
-  def to_a: () -> [ Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer, bool, String ]
+  def to_a: () -> [ Integer, Integer, Integer, Integer, Integer, Integer, Integer, Integer, bool, String? ]
 
   # <!--
   #   rdoc-file=time.c
@@ -1564,7 +1584,7 @@ class Time < Object
   #     Time.utc(2000, 1, 1).zone # => "UTC"
   #     Time.new(2000, 1, 1).zone # => "Central Standard Time"
   #
-  def zone: () -> String
+  def zone: () -> String?
 
   # <!-- rdoc-file=time.c -->
   # Like Time.utc, except that the returned `Time` object has the local timezone,

data/docs/architecture.md

@@ -0,0 +1,110 @@
+# Architecture
+
+This guide describes the outline of the architecture of RBS library. It helps you to understand the structure and key features of the library to start contributing to the library.
+
+## Bird's Eye View
+
+The goal of the library is simple: Read RBS files and generate the structure of Ruby programs.
+
+```
+RBS files
+  ↓         -- RBS::Parser
+Syntax tree
+  ↓
+Environment
+  ↓        -- Definition builder
+Definition
+```
+
+The input is RBS files. The gem ships with RBS type definitions of Ruby core library and some of the standard libraries. You write RBS files for your applications or gems.
+
+Syntax tree is the next representation. `RBS::Parser` transforms the sequence of characters in RBS files into syntax trees.
+
+Syntax tree objects are loaded to `RBS::Environment`. It collects loaded RBS objects, organizes the definitions, and provides some utilities, like resolving type names and finding the declarations.
+
+`RBS::Definition` is the goal of the transformation steps. It is associated with a class singleton, a class object, or an interface. You can find the list of available methods and their types, instance variables, and class hierarchies.
+
+## Core classes
+
+### Types
+
+Types are defined under `RBS::Types`, like `RBS::Types::ClassInstance` or `RBS::Types::Union`. You will find the definition of each type supported in RBS.
+
+### Parsing RBS files
+
+The RBS source code is loaded into `RBS::Buffer`, and `RBS::Parser` is the parser. The parser is implemented in C extension.
+
+`RBS::Parser` provides three entrypoints.
+
+- `RBS::Parser.parse_method_type` parsers a *method type*. (`[T] (String) { (IO) -> T } -> Array[T]`)
+- `RBS::Parser.parse_type` parses a *type*. (`Hash[Symbol, untyped]`)
+- `RBS::Parser.parse_signature` parses the whole RBS file.
+
+### Environment
+
+RBS AST is loaded to `RBS::Environment` by `RBS::EnvironmentLoader`. `Environment` gives *absolute names* to the declarations, and provides an index from the *absolute name* to their declarations.
+
+Assume we have the following nested RBS declarations:
+
+```rbs
+module Hello
+  class World
+  end
+end
+
+class Hello::World
+end
+```
+
+And the environment organizes the definitions as follows:
+
+- There are two classes `::Hello` and `::Hello::World`
+- It provides a mapping from `::Hello` to it's `module` declaration and `::Hello::World` to it's two `class` declarations
+
+### Definition and DefinitionBuilder
+
+`RBS::Definition` tells you:
+
+- The set of available methods in a class/module/interface
+- The set of instance variables in a class/module
+- The ancestors in a class/module
+
+Definition is constructed for:
+
+- A singleton class of a class/module -- `singleton(String)`, `singleton(Array)`,
+- An instance of a class -- `String`, `Array[T]`, or
+- An interface -- `_ToS`
+
+Note that generic class instances/interfaces are kept generic. We don't have a definition of `Array[String]` but of `Array[T]`.
+
+`DefinitionBuilder` constructs `Definition` of given type names.
+
+- `DefinitionBuilder#build_singleton` returns a definition of singleton classes of given class/module.
+- `DefinitionBuilder#build_instance` returns a definition of instances of given class/module.
+- `DefinitionBuilder#build_interface` returns a definition of interfaces.
+
+It uses `AncestorBuilder` to construct ancestor chains of the type. `MethodBuilder` constructs sets of available methods based on the ancestor chains.
+
+The `#build_singleton` calculates the type of `.new` methods based on the definition of `#initialize` method. This is different from Ruby's implementation -- it reused `Class#new` method but we need the custom implementation to give precise `.new` method type of each class.
+
+#### Working with type aliases
+
+`DefinitionBuilder#expand_alias` and its variants provide one step *unfold* operation of type aliases.
+
+```ruby
+builder.expand_alias2(TypeName("::int"), []) # => returns `::Integer | ::_ToInt`
+```
+
+We don't have *normalize* operation for type aliases, because RBS allows recursive type alias definition, which cannot be *fully* unfolded.
+
+### Other utilities
+
+`RBS::Validator` provides validation of RBS type declaration. It validates that all of the type name references can be resolved, all type applications have correct arity, and so on.
+
+`RBS::Test` provides runtime type checking, which confirms if a Ruby object can have an RBS type. It also provides an integration to existing Ruby code so that we run Ruby code, assuming unit tests, with runtime type checking.
+
+`RBS::UnitTest` provides utilities to help write unit tests for RBS type definitions. Use the tool to make sure your RBS type definition is consistent with implementation.
+
+`RBS::Prototype` is the core of `rbs prototype` feature. It scans Ruby source code or uses reflection features, and it generates the prototype of RBS files.
+
+`RBS::Collection` includes `rbs collection` features.

data/docs/gem.md

@@ -31,7 +31,6 @@ Assume you have three RBS files in your gem package:
 
 ```yaml
 dependencies:
-  - name: abbrev
   - name: json
   - name: logger
   - name: optparse

data/docs/syntax.md

@@ -45,6 +45,7 @@ _literal_ ::= _string-literal_
             | `false`
 
 _proc_ ::= `^` _parameters?_ _self-type-binding?_ _block?_ `->` _type_
+         | `^` `(` `?` `)` `->` _type_                                   # Proc type with untyped parameter
 ```
 
 ### Class instance type
@@ -310,6 +311,7 @@ end
 
 ```markdown
 _method-type_ ::= _parameters?_ _block?_ `->` _type_                # Method type
+                | `(` `?` `)` `->` _type_                           # Method type with untyped parameters
 
 _parameters?_ ::=                   (Empty)
                 | _parameters_      (Parameters)
@@ -333,9 +335,11 @@ _var-name_ ::= /[a-z]\w*/
 _self-type-binding?_ =                              (Empty)
                      | `[` `self` `:` _type_ `]`    (Self type binding)
 
-_block?_ =                                                           (No block)
+_block?_ =                                                            (No block)
          | `{` _parameters_ _self-type-binding?_ `->` _type_ `}`      (Block)
+         | `{` `(` `?` `)` `->` _type_ `}`                            (Block with untyped parameters)
          | `?` `{` _parameters_ _self-type-binding?_ `->` _type_ `}`  (Optional block)
+         | `?` `{` `(` `?` `)` `->` _type_ `}`                        (Optional block with untyped parameters)
 ```
 
 ### Parameters

data/ext/rbs_extension/constants.c

@@ -61,6 +61,7 @@ VALUE RBS_Types_ClassInstance;
 VALUE RBS_Types_ClassSingleton;
 VALUE RBS_Types_Function_Param;
 VALUE RBS_Types_Function;
+VALUE RBS_Types_UntypedFunction;
 VALUE RBS_Types_Interface;
 VALUE RBS_Types_Intersection;
 VALUE RBS_Types_Literal;
@@ -138,6 +139,7 @@ void rbs__init_constants(void) {
   IMPORT_CONSTANT(RBS_Types_ClassInstance, RBS_Types, "ClassInstance");
   IMPORT_CONSTANT(RBS_Types_ClassSingleton, RBS_Types, "ClassSingleton");
   IMPORT_CONSTANT(RBS_Types_Function, RBS_Types, "Function");
+  IMPORT_CONSTANT(RBS_Types_UntypedFunction, RBS_Types, "UntypedFunction");
   IMPORT_CONSTANT(RBS_Types_Function_Param, RBS_Types_Function, "Param");
   IMPORT_CONSTANT(RBS_Types_Interface, RBS_Types, "Interface");
   IMPORT_CONSTANT(RBS_Types_Intersection, RBS_Types, "Intersection");

data/ext/rbs_extension/constants.h

@@ -64,6 +64,7 @@ extern VALUE RBS_Types_ClassInstance;
 extern VALUE RBS_Types_ClassSingleton;
 extern VALUE RBS_Types_Function_Param;
 extern VALUE RBS_Types_Function;
+extern VALUE RBS_Types_UntypedFunction;
 extern VALUE RBS_Types_Interface;
 extern VALUE RBS_Types_Intersection;
 extern VALUE RBS_Types_Literal;