rbs 4.0.0.dev.4 → 4.0.0

data/docs/inline.md

@@ -0,0 +1,576 @@
+# Inline RBS Type Declaration
+
+Inline RBS type declarations allow you to write type annotations directly in your Ruby source files using comments. Instead of maintaining separate `.rbs` files, you can keep your type information alongside your Ruby code, making it easier to keep types and implementation in sync.
+
+The following example defines `Calculator` class and `add` instance method. The `@rbs` comment gives the type of the `add` method with the RBS method type syntax.
+
+```ruby
+class Calculator
+  # @rbs (Integer, Integer) -> Integer
+  def add(a, b)
+    a + b
+  end
+end
+```
+
+## Classes
+
+Inline RBS supports class definitions from your Ruby code. When you define a class in Ruby, the library recognizes it and the corresponding class definition is generated in RBS.
+
+```ruby
+class App
+end
+```
+
+The `::App` class is defined in RBS and you can use it as a type.
+
+### Non-constant class paths
+
+Only classes with constant names are imported. Dynamic or non-constant class definitions are ignored:
+
+```ruby
+# This class is imported
+class MyClass
+end
+
+# This is ignored - dynamic class definition
+MyClass = Class.new do
+end
+
+# This is also ignored - non-constant class name
+object = Object
+class object::MyClass
+end
+```
+
+### Class Nesting
+
+Nested classes work as expected:
+
+```ruby
+class Client
+  class Error
+  end
+end
+```
+
+This creates the types `::Client` and `::Client::Error`.
+
+### Inheritance
+
+Class declarations can have a super class.
+
+```ruby
+class UsersController < ApplicationController
+end
+```
+
+The super class specification must be a constant.
+
+The super class specification allows type applications.
+
+```ruby
+class StringArray < Array #[String]
+end
+```
+
+### Current Limitations
+
+- Generic class definitions are not supported
+
+## Modules
+
+Inline RBS supports module definitions from your Ruby code. When you define a module in Ruby, the library recognizes it and the corresponding module definition is generated in RBS.
+
+```ruby
+module Helper
+end
+```
+
+The `::Helper` module is defined in RBS and you can use it as a type.
+
+### Non-constant module paths
+
+Only modules with constant names are imported. Dynamic or non-constant module definitions are ignored:
+
+```ruby
+# This module is imported
+module MyModule
+end
+
+# This is ignored - dynamic module definition
+MyModule = Module.new do
+end
+
+# This is also ignored - non-constant module name
+object = Object
+module object::MyModule
+end
+```
+
+### Module Nesting
+
+Nested modules work as expected:
+
+```ruby
+module API
+  module V1
+    module Resources
+    end
+  end
+end
+```
+
+This creates the types `::API`, `::API::V1`, and `::API::V1::Resources`.
+
+### Current Limitations
+
+- Generic module definitions are not supported
+- Module self-type constraints are not supported
+
+## Method Definitions
+
+Inline RBS supports methods defined using the `def` syntax in Ruby.
+
+```ruby
+class Calculator
+  def add(x, y) = x+y
+end
+```
+
+It detects method definitions and allows you to add annotation comments to describe their types.
+
+### Unannotated method definition
+
+Methods defined with `def` syntax are detected, but their inferred type depends on whether a super method exists.
+
+If there is no super method, the inferred type is `(?) -> untyped` -- it accepts any arguments without type checking and returns an `untyped` object.
+
+```ruby
+class Calculator
+  def add(x, y) = x+y
+end
+```
+
+The type of `Calculator#add` is `(?) -> untyped`.
+
+If the super class (or an included module) defines a method with the same name, the unannotated method inherits that type.
+
+```ruby
+class Calculator
+  # @rbs (Integer, Integer) -> Integer
+  def add(x, y) = x + y
+end
+
+class ScientificCalculator < Calculator
+  def add(x, y) = x + y   # No annotation
+end
+```
+
+The type of `ScientificCalculator#add` is `(Integer, Integer) -> Integer`, inherited from `Calculator#add`.
+
+### Method type annotation syntax
+
+You can define the type of the method using `@rbs` and `:` syntax.
+
+```ruby
+class Calculator
+  # @rbs (Integer, Integer) -> Integer
+  def add(x, y) = x + y
+
+  #: (Integer, Integer) -> Integer
+  def subtract(x, y) = x - y
+end
+```
+
+The type of both methods is `(Integer, Integer) -> Integer` -- they take two `Integer` objects and return an `Integer` object.
+
+Both syntaxes support method overloading:
+
+```ruby
+class Calculator
+  # @rbs (Integer, Integer) -> Integer
+  #    | (Float, Float) -> Float
+  def add(x, y) = x + y
+
+  #: (Integer, Integer) -> Integer
+  #: (Float, Float) -> Float
+  def subtract(x, y) = x - y
+end
+```
+
+The type of both methods is `(Integer, Integer) -> Integer | (Float, Float) -> Float`.
+
+> [!NOTE]
+> The `@rbs METHOD-TYPE` syntax allows overloads with the `|` operator, just like in RBS files.
+> Multiple `: METHOD-TYPE` declarations are required for overloads.
+
+The `@rbs METHOD-TYPE` syntax allows having `...` at the last part.
+
+```ruby
+class Calculator2 < Calculator
+  # @rbs (Float, Float) -> Float | ...
+  def add(x, y) = x + y
+
+  # @rbs ...
+  def subtract(x, y) = super
+end
+```
+
+#### Doc-style syntax
+
+The doc-style syntax allows annotating individual method parameters and the return type using `@rbs NAME: TYPE` comments.
+
+The `@rbs PARAM_NAME: T` syntax declares the type of a parameter:
+
+```ruby
+class Calculator
+  # @rbs x: Integer
+  # @rbs y: Integer
+  # @rbs a: String
+  # @rbs b: bool
+  def add(x, y = 1, a:, b: false)
+    pp(x:, y:, a:, b:)
+  end
+end
+```
+
+You can add a description after `--`:
+
+```ruby
+class Calculator
+  # @rbs x: Integer -- required positional argument
+  # @rbs y: Integer -- optional positional argument
+  # @rbs a: String -- required keyword argument
+  # @rbs b: bool -- optional keyword argument
+  def add(x, y = 1, a:, b: false)
+    pp(x:, y:, a:, b:)
+  end
+end
+```
+
+Types of splat (`*a`) and double-splat (`**b`) parameters can be declared too.
+
+```ruby
+class Foo
+  # @rbs *a: String -- The type of `a` is `Array[String]`
+  # @rbs **b: bool -- The type of `b` is `Hash[Symbol, bool]`
+  def foo(*a, **b)
+  end
+
+  # @rbs *: String -- Parameter name is optional
+  # @rbs **: bool -- Parameter name can be omitted in Ruby too
+  def bar(*a, **)
+  end
+end
+```
+
+Types of block parameter (`&block`) can be declared.
+
+```ruby
+class Foo
+  # @rbs &block: () -> void
+  def foo(&block)
+  end
+
+  # @rbs &: () -> void -- The parameter name can be omitted
+  def bar(&)
+  end
+
+  # @rbs &block: ? () -> untyped -- The `?` prefix is for optional block
+  def baz(&block)
+  end
+end
+```
+
+The `@rbs return: T` syntax declares the return type of a method:
+
+```ruby
+class Calculator
+  # @rbs return: String -- a human-readable representation
+  def to_s
+    "Calculator"
+  end
+end
+```
+
+Both can be combined:
+
+```ruby
+class Calculator
+  # @rbs x: Integer -- the first operand
+  # @rbs y: Integer -- the second operand
+  # @rbs return: Integer
+  def add(x, y:)
+    x + y
+  end
+end
+```
+
+### Current Limitations
+
+- Class methods and singleton methods are not supported
+- Only positional and keyword parameters are supported. Splat parameters (`*x`, `**y`) and block parameter (`&block`) are not supported yet.
+- Method visibility declaration is not supported yet
+
+## Attributes
+
+Inline RBS supports Ruby's attribute methods: `attr_reader`, `attr_writer`, and `attr_accessor`.
+
+```ruby
+class Person
+  attr_reader :name #: String
+  attr_writer :age #: Integer
+  attr_accessor :email #: String?
+end
+```
+
+It detects these attribute declarations and generates the corresponding getter and setter methods.
+
+The accessor methods and instance variables are defined.
+
+### Unannotated attributes
+
+Attributes defined without type annotations are treated as `untyped`:
+
+```ruby
+class Person
+  attr_reader :name
+  attr_writer :age
+  attr_accessor :email
+end
+```
+
+### Type annotations for attributes
+
+You can add type annotations to attributes using the `#:` syntax in trailing comments:
+
+```ruby
+class Person
+  attr_reader :name #: String
+  attr_writer :age #: Integer
+  attr_accessor :email #: String?
+end
+```
+
+This generates the following typed methods:
+- `name: () -> String`
+- `age=: (Integer) -> Integer`
+- `email: () -> String?` and `email=: (String?) -> String?`
+
+### Multiple attributes
+
+When declaring multiple attributes in one line, the type annotation applies to all attributes:
+
+```ruby
+class Person
+  attr_reader :first_name, :last_name #: String
+  attr_accessor :age, :height #: Integer
+end
+```
+
+All attributes in each declaration share the same type.
+
+### Non-symbol attribute names
+
+Attribute names must be symbol literals.
+
+```ruby
+class Person
+  attr_reader "name" #: String
+
+  age = :age
+  attr_writer age #: Integer
+end
+```
+
+The attribute definitions are ignored because the names are given by string literals and local variables.
+
+### Current Limitations
+
+- Attribute visibility is not supported yet. All attributes are _public_
+
+## Mixin
+
+Inline RBS supports Ruby's mixin methods: `include`, `extend`, and `prepend`.
+
+```ruby
+module Printable
+  # @rbs () -> String
+  def to_print
+    to_s
+  end
+end
+
+class Document
+  include Printable
+  extend Enumerable #[String]
+  prepend Trackable
+end
+```
+
+It detects these mixin declarations and adds them to the class or module definition.
+
+### Basic mixin usage
+
+Mixins work just like in regular RBS files:
+
+```ruby
+module Helper
+end
+
+class MyClass
+  include Helper
+  extend Helper
+  prepend Helper
+end
+```
+
+### Type arguments for generic modules
+
+You can specify type arguments for generic modules using the `#[...]` syntax:
+
+```ruby
+class TodoList
+  include Enumerable #[String]
+
+  # @rbs () { (String) -> void } -> void
+  def each(&block)
+    @items.each(&block)
+  end
+end
+```
+
+### Module name requirements
+
+Only constant module names are supported. Dynamic module references are not allowed:
+
+```ruby
+class MyClass
+  include Helper         # ✓ Works - constant name
+
+  mod = Helper
+  include mod           # ✗ Ignored - non-constant module reference
+
+  include Helper.new    # ✗ Ignored - not a simple constant
+end
+```
+
+### Module name resolution
+
+The module name resolution is based on the nesting of the class/module definitions, unlike Ruby.
+
+Modules accessible through ancestors (super-class/included modules) are not supported.
+
+### Current Limitations
+
+- Only single module arguments are supported (no `include A, B` syntax)
+- Module names must be constants
+
+## Instance Variables
+
+Inline RBS declaration allows defining instance variables.
+
+```ruby
+class Person
+  # @rbs @name: String
+  # @rbs @age: Integer? --
+  #   how old is the person?
+  #   `nil` means it's unspecified.
+
+  # @rbs (String name, Integer? age) -> void
+  def initialize(name, age)
+    @name = name
+    @age = age
+  end
+end
+```
+
+The `@rbs @VAR-NAME: TYPE` syntax enclosed in `class`/`module` syntax declares instance variables.
+You can add the documentation of the variable followed by two hyphones (`--`).
+
+Instance variable declarations must be under the `class`/`module` syntax, and they are ignored if written inside method definitions.
+
+### Current Limitations
+
+- Only instance variables of class/module instances are allowed
+
+## Constants
+
+Constants are supported by inline RBS declaration.
+
+```ruby
+Foo = 123
+
+module Bar
+  Baz = [1, ""] #: [Integer, String]
+end
+
+# Version of the library
+#
+VERSION = "1.2.3".freeze #: String
+```
+
+### Type Inference for Literal Constants
+
+The types of constants may be automatically inferred when the right-hand side consists of literals:
+
+- **Integers**: `COUNT = 42` → `Integer`
+- **Floats**: `RATE = 3.14` → `Float`
+- **Booleans**: `ENABLED = true` → `bool`
+- **Strings**: `NAME = "test"` → `String`
+- **Symbols**: `STATUS = :ready` → `:ready`
+
+```ruby
+MAX_SIZE = 100           # Inferred as Integer
+PI = 3.14159            # Inferred as Float
+DEBUG = false           # Inferred as bool
+APP_NAME = "MyApp"      # Inferred as String
+DEFAULT_MODE = :strict  # Inferred as :strict
+```
+
+### Explicit Type Annotations
+
+For more complex types or when you want to override inference, use the `#:` syntax:
+
+```ruby
+ITEMS = [1, "hello"] #: [Integer, String]
+CONFIG = { name: "app", version: 1 } #: { name: String, version: Integer }
+CALLBACK = -> { puts "done" } #: ^() -> void
+```
+
+### Documentation Comments
+
+Comments above constant declarations become part of the constant's documentation:
+
+```ruby
+# The maximum number of retries allowed
+# before giving up on the operation
+MAX_RETRIES = 3
+
+# Application configuration loaded from environment
+#
+# This hash contains all the runtime configuration
+# settings for the application.
+CONFIG = load_config() #: Hash[String, untyped]
+```
+
+## Class/module Aliases
+
+Class and module aliases can be defined by assigning existing classes or modules to constants using the `#: class-alias` or `#: module-alias` syntax.
+
+```ruby
+MyObject = Object #: class-alias
+
+MyKernel = Kernel #: module-alias
+```
+
+This creates new type names that refer to the same class or module as the original.
+
+The annotations can have optional type name to specify the class/module name, for the case it cannot be infered through the right-hand-side of the constant declaration.
+
+```ruby
+MyObject = object #: class-alias Object
+
+MyKernel = kernel #: module-alias Kernel
+```

data/docs/sigs.md

@@ -131,10 +131,10 @@ You may need to specify `-r` or `-I` to load signatures.
 The default is `-I sig`.
 
 ```shell
-RBS_TEST_OPT='-r pathname -I sig'
+RBS_TEST_OPT='-r logger -I sig'
 ```
 
-Replacing `pathname` 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'`
+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`.
 
@@ -148,7 +148,7 @@ So, a typical command line to start the test would look like the following:
 $ RBS_TEST_LOGLEVEL=error \
   RBS_TEST_TARGET='Kaigi::*' \
   RBS_TEST_SKIP='Kaigi::MonkeyPatch' \
-  RBS_TEST_OPT='-rset -rpathname -Isig -Iprivate' \
+  RBS_TEST_OPT='-rlogger -Isig -Iprivate' \
   RBS_TEST_RAISE=true \
   RUBYOPT='-rbundler/setup -rrbs/test/setup' \
   bundle exec rake test

data/docs/syntax.md

@@ -3,17 +3,17 @@
 ## Types
 
 ```markdown
-_type_ ::= _class-name_ _type-arguments_                 (Class instance type)
-         | _interface-name_ _type-arguments_             (Interface type)
-         | _alias-name_ _type-arguments_                 (Alias type)
-         | `singleton(` _class-name_ `)`                 (Class singleton type)
-         | _literal_                                     (Literal type)
-         | _type_ `|` _type_                             (Union type)
-         | _type_ `&` _type_                             (Intersection type)
-         | _type_ `?`                                    (Optional type)
-         | `{` _record-name_ `:` _type_ `,` etc. `}`     (Record type)
-         | `[]` | `[` _type_ `,` etc. `]`                (Tuples)
-         | _type-variable_                               (Type variables)
+_type_ ::= _class-name_ _type-arguments_                     (Class instance type)
+         | _interface-name_ _type-arguments_                 (Interface type)
+         | _alias-name_ _type-arguments_                     (Alias type)
+         | `singleton(` _class-name_ `)` _type-arguments_    (Class singleton type)
+         | _literal_                                         (Literal type)
+         | _type_ `|` _type_                                 (Union type)
+         | _type_ `&` _type_                                 (Intersection type)
+         | _type_ `?`                                        (Optional type)
+         | `{` _record-name_ `:` _type_ `,` etc. `}`         (Record type)
+         | `[]` | `[` _type_ `,` etc. `]`                    (Tuples)
+         | _type-variable_                                   (Type variables)
          | `self`
          | `instance`
          | `class`
@@ -85,7 +85,8 @@ Class singleton type denotes _the type of a singleton object of a class_.
 
 ```rbs
 singleton(String)
-singleton(::Hash)            # Class singleton type cannot be parametrized.
+singleton(::Hash)            # Class singleton type
+singleton(Array)[String]     # Class singleton type with type application
 ```
 
 ### Literal type
@@ -650,7 +651,7 @@ _module-type-parameters_ ::=                                                  #
 
 Class declaration can have type parameters and superclass. When you omit superclass, `::Object` is assumed.
 
-* Super class arguments and generic class upperbounds are not *classish-context* nor *self-context*
+* Super class arguments and generic class bounds are not *classish-context* nor *self-context*
 
 ### Module declaration
 
@@ -668,7 +669,7 @@ end
 
 The `Enumerable` module above requires `each` method for enumerating objects.
 
-* Self type arguments and generic class upperbounds are not *classish-context* nor *self-context*
+* Self type arguments and generic class bounds are not *classish-context* nor *self-context*
 
 ### Class/module alias declaration
 
@@ -764,7 +765,8 @@ _module-type-parameter_ ::= _generics-unchecked_ _generics-variance_ _type-varia
 _method-type-param_ ::= _type-variable_ _generics-bound_
 
 _generics-bound_ ::=                 (No type bound)
-                   | `<` _type_      (The generics parameter is bounded)
+                   | `<` _type_      (The generics parameter has an upper bound)
+                   | '>' _type_      (The generics parameter has a lower bound)
 
 _default-type_ ::=                    (No default type)
                  | `=` _type_         (The generics parameter has default type)
@@ -777,6 +779,9 @@ _generics-unchecked_ ::=              (Empty)
                        | `unchecked`  (Skips variance annotation validation)
 ```
 
+A type parameter can have both upper and lower bounds, which can be specified in either order:
+`[T < UpperBound > LowerBound]` or `[T > LowerBound < UpperBound]`.
+
 RBS allows class/module/interface/type alias definitions and methods to be generic.
 
 ```rbs
@@ -834,13 +839,38 @@ class PrettyPrint[T < _Output]
 end
 ```
 
-If a type parameter has an upper bound, the type parameter must be instantiated with types that is a subtype of the upper bound.
+If a type parameter has an upper bound, the type parameter must be instantiated with types that are a subtype of the upper bound.
 
 ```rbs
 type str_printer = PrettyPrint[String]    # OK
 type int_printer = PrettyPrint[Integer]   # Type error
 ```
 
+If a type parameter has a lower bound, the type parameter must be instantiated with types that are a supertype of the lower bound.
+
+```rbs
+class PrettyPrint[T > Numeric]
+end
+
+type obj_printer = PrettyPrint[Object]    # OK
+type int_printer = PrettyPrint[Integer]   # Type error
+```
+
+A type parameter can have both an upper and a lower bound, and these bounds can be specified in any order.
+
+```rbs
+class FlexibleProcessor[T > Integer < Numeric]
+  # This class processes types T that are supertypes of Integer but also subtypes of Numeric.
+  # This includes Integer, Rational, Complex, Float, and Numeric itself.
+  def calculate: (T) -> T
+end
+
+type int_processor = FlexibleProcessor[Integer]   # OK (Integer > Integer and Integer < Numeric)
+type num_processor = FlexibleProcessor[Numeric]   # OK (Numeric > Integer and Numeric < Numeric)
+type obj_processor = FlexibleProcessor[Object]    # Type error (Object is not < Numeric)
+type str_processor = FlexibleProcessor[String]    # Type error (String is not > Integer)
+```
+
 The generics type parameter of modules, classes, interfaces, or type aliases can have a default type.
 
 ```rbs