rbs 4.0.3 → 4.1.0.pre.2

data/stdlib/strscan/0/string_scanner.rbs

@@ -498,7 +498,7 @@ class StringScanner
   # scanner[0]           # => nil
   # scanner[1]           # => nil
   #
-  def []: (Integer) -> String?
+  def []: (Integer | String | Symbol) -> String?
 
   # <!--
   #   rdoc-file=ext/strscan/strscan.c
@@ -625,7 +625,7 @@ class StringScanner
   #     scanner.check(/nope/)          # => nil
   # match_values_cleared?(scanner) # => true
   #
-  def check: (Regexp) -> String?
+  def check: (Regexp | String) -> String?
 
   # <!--
   #   rdoc-file=ext/strscan/strscan.c
@@ -673,15 +673,7 @@ class StringScanner
   #     scanner.check_until(/nope/)    # => nil
   # match_values_cleared?(scanner) # => true
   #
-  def check_until: (Regexp) -> String
-
-  # <!--
-  #   rdoc-file=ext/strscan/strscan.c
-  #   - clear()
-  # -->
-  # Equivalent to #terminate. This method is obsolete; use #terminate instead.
-  #
-  def clear: () -> void
+  def check_until: (Regexp | String) -> String?
 
   # <!--
   #   rdoc-file=ext/strscan/strscan.c
@@ -706,14 +698,6 @@ class StringScanner
   #
   alias concat <<
 
-  # <!--
-  #   rdoc-file=ext/strscan/strscan.c
-  #   - empty?()
-  # -->
-  # Equivalent to #eos?. This method is obsolete, use #eos? instead.
-  #
-  def empty?: () -> bool
-
   # <!--
   #   rdoc-file=ext/strscan/strscan.c
   #   - eos? -> true or false
@@ -776,7 +760,7 @@ class StringScanner
   #     scanner.exist?(/nope/)         # => nil
   # match_values_cleared?(scanner) # => true
   #
-  def exist?: (Regexp) -> Integer?
+  def exist?: (Regexp | String) -> Integer?
 
   # <!--
   #   rdoc-file=ext/strscan/strscan.c
@@ -818,14 +802,6 @@ class StringScanner
   #
   def get_byte: () -> String?
 
-  # <!--
-  #   rdoc-file=ext/strscan/strscan.c
-  #   - getbyte()
-  # -->
-  # Equivalent to #get_byte. This method is obsolete; use #get_byte instead.
-  #
-  def getbyte: () -> String?
-
   # <!--
   #   rdoc-file=ext/strscan/strscan.c
   #   - getch()
@@ -937,7 +913,7 @@ class StringScanner
   #     scanner.match?(/nope/)         # => nil
   # match_values_cleared?(scanner) # => true
   #
-  def match?: (Regexp) -> Integer?
+  def match?: (Regexp | String) -> Integer?
 
   # <!--
   #   rdoc-file=ext/strscan/strscan.c
@@ -997,6 +973,29 @@ class StringScanner
   #
   def matched_size: () -> Integer?
 
+  # <!--
+  #   rdoc-file=ext/strscan/strscan.c
+  #   - named_captures -> hash
+  # -->
+  # Returns the array of captured match values at indexes (1..)
+  # if the most recent match attempt succeeded, or nil otherwise;
+  # see [Captured Match Values](rdoc-ref:StringScanner@Captured+Match+Values):
+  #     scanner = StringScanner.new('Fri Dec 12 1975 14:39')
+  # scanner.named_captures # => {}
+  #
+  # pattern = /(?<wday>\w+) (?<month>\w+) (?<day>\d+) /
+  # scanner.match?(pattern)
+  # scanner.named_captures # => {"wday"=>"Fri", "month"=>"Dec", "day"=>"12"}
+  #
+  # scanner.string = 'nope'
+  # scanner.match?(pattern)
+  # scanner.named_captures # => {"wday"=>nil, "month"=>nil, "day"=>nil}
+  #
+  # scanner.match?(/nosuch/)
+  # scanner.named_captures # => {}
+  #
+  def named_captures: () -> Hash[String, String?]
+
   # <!--
   #   rdoc-file=ext/strscan/strscan.c
   #   - peek(length) -> substring
@@ -1014,11 +1013,14 @@ class StringScanner
 
   # <!--
   #   rdoc-file=ext/strscan/strscan.c
-  #   - peep(p1)
+  #   - peek_byte()
   # -->
-  # Equivalent to #peek. This method is obsolete; use #peek instead.
+  # Peeks at the current byte and returns it as an integer.
+  #
+  #     s = StringScanner.new('ab')
+  #     s.peek_byte         # => 97
   #
-  def peep: (Integer) -> String
+  def peek_byte: () -> Integer?
 
   # <!-- rdoc-file=ext/strscan/strscan.c -->
   # call-seq:
@@ -1124,7 +1126,7 @@ class StringScanner
   # scanner.match?(/nope/) # => nil
   # scanner.post_match     # => nil
   #
-  def post_match: () -> String
+  def post_match: () -> String?
 
   # <!--
   #   rdoc-file=ext/strscan/strscan.c
@@ -1144,7 +1146,7 @@ class StringScanner
   # scanner.exist?(/nope/) # => nil
   # scanner.pre_match      # => nil
   #
-  def pre_match: () -> String
+  def pre_match: () -> String?
 
   # <!--
   #   rdoc-file=ext/strscan/strscan.c
@@ -1166,7 +1168,7 @@ class StringScanner
   # # => nil
   # match_values_cleared?(scanner) # => true
   #
-  def reset: () -> void
+  def reset: () -> self
 
   # <!--
   #   rdoc-file=ext/strscan/strscan.c
@@ -1217,15 +1219,6 @@ class StringScanner
   #
   def rest_size: () -> Integer
 
-  # <!--
-  #   rdoc-file=ext/strscan/strscan.c
-  #   - restsize()
-  # -->
-  # `s.restsize` is equivalent to `s.rest_size`. This method is obsolete; use
-  # #rest_size instead.
-  #
-  def restsize: () -> Integer
-
   # <!--
   #   rdoc-file=ext/strscan/strscan.c
   #   - scan(p1)
@@ -1276,7 +1269,16 @@ class StringScanner
   #     scanner.scan(/nope/)           # => nil
   # match_values_cleared?(scanner) # => true
   #
-  def scan: (Regexp) -> String?
+  def scan: (Regexp | String) -> String?
+
+  # <!--
+  #   rdoc-file=ext/strscan/strscan.c
+  #   - scan_byte -> integer_byte
+  # -->
+  # Scans one byte and returns it as an integer. This method is not multibyte
+  # character sensitive. See also: #getch.
+  #
+  def scan_byte: () -> Integer?
 
   # <!--
   #   rdoc-file=ext/strscan/strscan.c
@@ -1288,7 +1290,23 @@ class StringScanner
   #
   # "full" means "#scan with full parameters".
   #
-  def scan_full: (Regexp pattern, bool advance_pointer_p, bool return_string_p) -> untyped
+  def scan_full: (Regexp | String pattern, bool advance_pointer_p, true return_string_p) -> String?
+               | (Regexp | String pattern, bool advance_pointer_p, false return_string_p) -> Integer?
+
+  # <!--
+  #   rdoc-file=ext/strscan/lib/strscan/strscan.rb
+  #   - scan_integer(base: 10)
+  # -->
+  # If `base` isn't provided or is `10`, then it is equivalent to calling
+  # <code>#scan</code> with a `[+-]?d+` pattern, and returns an Integer or nil.
+  #
+  # If `base` is `16`, then it is equivalent to calling <code>#scan</code> with a
+  # `[+-]?(0x)?[0-9a-fA-F]+` pattern, and returns an Integer or nil.
+  #
+  # The scanned string must be encoded with an ASCII compatible encoding,
+  # otherwise Encoding::CompatibilityError will be raised.
+  #
+  def scan_integer: (?base: Integer) -> Integer?
 
   # <!--
   #   rdoc-file=ext/strscan/strscan.c
@@ -1341,7 +1359,7 @@ class StringScanner
   #     scanner.scan_until(/nope/)     # => nil
   # match_values_cleared?(scanner) # => true
   #
-  def scan_until: (Regexp) -> String?
+  def scan_until: (Regexp | String) -> String?
 
   # <!--
   #   rdoc-file=ext/strscan/strscan.c
@@ -1352,7 +1370,8 @@ class StringScanner
   # `return_string_p` is true, otherwise returns the number of bytes advanced.
   # This method does affect the match register.
   #
-  def search_full: (Regexp pattern, bool advance_pointer_p, bool return_string_p) -> untyped
+  def search_full: (Regexp | String pattern, bool advance_pointer_p, true return_string_p) -> String?
+                 | (Regexp | String pattern, bool advance_pointer_p, false return_string_p) -> Integer?
 
   # <!--
   #   rdoc-file=ext/strscan/strscan.c
@@ -1372,7 +1391,7 @@ class StringScanner
   # scanner.match?(/nope/)              # => nil
   # scanner.size                        # => nil
   #
-  def size: () -> Integer
+  def size: () -> Integer?
 
   # <!--
   #   rdoc-file=ext/strscan/strscan.c
@@ -1420,7 +1439,7 @@ class StringScanner
   # scanner.skip(/nope/)            # => nil
   # match_values_cleared?(scanner)  # => true
   #
-  def skip: (Regexp) -> Integer?
+  def skip: (Regexp | String) -> Integer?
 
   # <!--
   #   rdoc-file=ext/strscan/strscan.c
@@ -1468,7 +1487,7 @@ class StringScanner
   #     scanner.skip_until(/nope/)     # => nil
   # match_values_cleared?(scanner) # => true
   #
-  def skip_until: (Regexp) -> Integer?
+  def skip_until: (Regexp | String) -> Integer?
 
   # <!--
   #   rdoc-file=ext/strscan/strscan.c
@@ -1542,7 +1561,7 @@ class StringScanner
   # #   rest_size: 0
   # match_values_cleared?(scanner) # => true
   #
-  def terminate: () -> void
+  def terminate: () -> self
 
   # <!--
   #   rdoc-file=ext/strscan/strscan.c
@@ -1573,7 +1592,7 @@ class StringScanner
   # match_values_cleared?(scanner) # => true
   # scanner.unscan                 # Raises StringScanner::Error.
   #
-  def unscan: () -> void
+  def unscan: () -> self
 
   # <!--
   #   rdoc-file=ext/strscan/strscan.c
@@ -1588,7 +1607,7 @@ class StringScanner
   # scanner.values_at(*0..3)               # => ["Fri Dec 12 ", "Fri", "Dec", "12"]
   # scanner.values_at(*%i[wday month day]) # => ["Fri", "Dec", "12"]
   #
-  def values_at: (*Integer) -> Array[String]?
+  def values_at: (*Integer | String | Symbol) -> Array[String]?
 
   private
 
@@ -1611,7 +1630,7 @@ class StringScanner
   # #   rest:      "foobarbaz"
   # #   rest_size: 9
   #
-  def initialize: (String, ?bool dup, ?fixed_anchor: bool) -> untyped
+  def initialize: (String, ?fixed_anchor: bool) -> void
 
   # <!--
   #   rdoc-file=ext/strscan/strscan.c

data/stdlib/tsort/0/cyclic.rbs

@@ -1,5 +1,5 @@
 %a{annotate:rdoc:skip}
-module TSort[Node]
+module TSort[N]
   # <!-- rdoc-file=lib/tsort.rb -->
   # Exception class to be raised when a cycle is found.
   #

data/stdlib/tsort/0/interfaces.rbs

@@ -1,20 +1,20 @@
 %a{annotate:rdoc:skip}
-module TSort[Node]
-  interface _Sortable[Node]
+module TSort[N]
+  interface _Sortable[N]
     # #tsort_each_node is used to iterate for all nodes over a graph.
     #
-    def tsort_each_node: () { (Node) -> void } -> void
+    def tsort_each_node: () { (N) -> void } -> void
 
     # #tsort_each_child is used to iterate for child nodes of node.
     #
-    def tsort_each_child: (Node) { (Node) -> void } -> void
+    def tsort_each_child: (N) { (N) -> void } -> void
   end
 
-  interface _EachNode[Node]
-    def call: () { (Node) -> void } -> void
+  interface _EachNode[N]
+    def call: () { (N) -> void } -> void
   end
 
-  interface _EachChild[Node]
-    def call: (Node) { (Node) -> void } -> void
+  interface _EachChild[N]
+    def call: (N) { (N) -> void } -> void
   end
 end

data/stdlib/tsort/0/tsort.rbs

@@ -113,7 +113,7 @@
 #     1.  Tarjan, "Depth First Search and Linear Graph Algorithms",
 # *SIAM Journal on Computing*, Vol. 1, No. 2, pp. 146-160, June 1972.
 #
-module TSort[Node] : TSort::_Sortable[Node]
+module TSort[N] : TSort::_Sortable[N]
   # <!--
   #   rdoc-file=lib/tsort.rb
   #   - each_strongly_connected_component(each_node, each_child) { |nodes| ... }
@@ -290,8 +290,8 @@ module TSort[Node] : TSort::_Sortable[Node]
   #     #   [2, 3]
   #     #   [1]
   #
-  def each_strongly_connected_component: () { (Array[Node]) -> void } -> void
-                                       | () -> Enumerator[Array[Node], void]
+  def each_strongly_connected_component: () { (Array[N]) -> void } -> void
+                                       | () -> Enumerator[Array[N], void]
 
   # <!--
   #   rdoc-file=lib/tsort.rb
@@ -323,8 +323,8 @@ module TSort[Node] : TSort::_Sortable[Node]
   #     #=> [4]
   #     #   [2, 3]
   #
-  def each_strongly_connected_component_from: (Node, ?untyped id_map, ?untyped stack) { (Array[Node]) -> void } -> void
-                                            | (Node, ?untyped id_map, ?untyped stack) -> Enumerator[Array[Node], void]
+  def each_strongly_connected_component_from: (N, ?untyped id_map, ?untyped stack) { (Array[N]) -> void } -> void
+                                            | (N, ?untyped id_map, ?untyped stack) -> Enumerator[Array[N], void]
 
   # <!--
   #   rdoc-file=lib/tsort.rb
@@ -349,7 +349,7 @@ module TSort[Node] : TSort::_Sortable[Node]
   #     graph = G.new({1=>[2], 2=>[3, 4], 3=>[2], 4=>[]})
   #     p graph.strongly_connected_components #=> [[4], [2, 3], [1]]
   #
-  def strongly_connected_components: () -> Array[Array[Node]]
+  def strongly_connected_components: () -> Array[Array[N]]
 
   # <!--
   #   rdoc-file=lib/tsort.rb
@@ -376,7 +376,7 @@ module TSort[Node] : TSort::_Sortable[Node]
   #     graph = G.new({1=>[2], 2=>[3, 4], 3=>[2], 4=>[]})
   #     p graph.tsort # raises TSort::Cyclic
   #
-  def tsort: () -> Array[Node]
+  def tsort: () -> Array[N]
 
   # <!--
   #   rdoc-file=lib/tsort.rb
@@ -405,6 +405,6 @@ module TSort[Node] : TSort::_Sortable[Node]
   #     #   3
   #     #   1
   #
-  def tsort_each: () { (Node) -> void } -> void
-                | () -> Enumerator[Node, void]
+  def tsort_each: () { (N) -> void } -> void
+                | () -> Enumerator[N, void]
 end

data/stdlib/zlib/0/gzip_reader.rbs

@@ -187,7 +187,7 @@ module Zlib
     # -->
     # See Zlib::GzipReader documentation for a description.
     #
-    def read: (?int? length, ?string outbuf) -> String?
+    def read: (?int? length, ?string? outbuf) -> String?
 
     # <!--
     #   rdoc-file=ext/zlib/zlib.c
@@ -230,7 +230,7 @@ module Zlib
     # argument is present, it must reference a String, which will receive the data.
     # It raises `EOFError` on end of file.
     #
-    def readpartial: (int maxlen, ?string outbuf) -> String
+    def readpartial: (int maxlen, ?string? outbuf) -> String
 
     # <!--
     #   rdoc-file=ext/zlib/zlib.c

data/wasm/README.md

@@ -0,0 +1,59 @@
+# RBS parser as WebAssembly
+
+The parser under [`src/`](../src) is plain, self-contained C with no dependency
+on the Ruby C API, so it can be compiled to WebAssembly as-is. This directory
+holds the small entry-point shim ([`rbs_wasm.c`](rbs_wasm.c)) that exposes a
+stable ABI to a WebAssembly host.
+
+This is how RBS runs on Ruby implementations that cannot load the MRI C
+extension (notably JRuby): the host loads `rbs_parser.wasm`, runs the parser over
+a source buffer, and reads the serialized AST back out. The Ruby side then
+rebuilds `RBS::AST` objects with `RBS::WASM::Deserializer` — no native build per
+platform required. See [`lib/rbs/wasm`](../lib/rbs/wasm) and
+[`docs/wasm_serialization.md`](../docs/wasm_serialization.md).
+
+## Building
+
+The build needs the [WASI SDK](https://github.com/WebAssembly/wasi-sdk/releases)
+(for `clang`, the wasi-libc sysroot, and the wasm32 compiler-rt builtins):
+
+```console
+$ export WASI_SDK_PATH=/path/to/wasi-sdk
+$ rake wasm:build       # compile rbs_parser.wasm
+$ rake wasm:check       # also smoke-test it (needs wasmtime)
+$ rake wasm:jruby_setup # assemble lib/rbs/wasm/ for JRuby (wasm + Chicory jars)
+```
+
+The compiled `rbs_parser.wasm` is a build artifact and is not checked in.
+
+## Exported functions
+
+The module is built as a "reactor": it has no `main`, and the host calls
+`_initialize` once before invoking any export.
+
+Memory management and results:
+
+| Export | Signature | Description |
+| --- | --- | --- |
+| `rbs_wasm_alloc` | `(i32) -> i32` | Allocate N bytes in linear memory, return the offset. |
+| `rbs_wasm_free` | `(i32) -> ()` | Free a region from `rbs_wasm_alloc`. |
+| `rbs_wasm_result_ptr` | `() -> i32` | Offset of the most recent result. |
+| `rbs_wasm_result_len` | `() -> i32` | Length of the most recent result. |
+
+Parsing — each takes the whole buffer (`ptr`/`len`), its Ruby encoding name
+(`enc`/`enc_len`, e.g. `"UTF-8"` or `"EUC-JP"`; falls back to UTF-8 when empty or
+unknown), and the character range to parse (`start`/`end`). Each returns `1` on
+success or `0` on a parse error. On success the result is the serialized AST; on
+error it is an error blob (start/end positions, syntax flag, token type,
+message). Type/method-type parsing also takes a buffer of newline-separated
+type-variable names (`vars`/`vars_len`, with `vars_len < 0` meaning "none"):
+
+| Export | Signature |
+| --- | --- |
+| `rbs_wasm_parse_signature` | `(ptr, len, enc, enc_len, start, end) -> i32` |
+| `rbs_wasm_parse_type` | `(ptr, len, enc, enc_len, start, end, vars, vars_len, require_eof, void_allowed, self_allowed, classish_allowed) -> i32` |
+| `rbs_wasm_parse_method_type` | `(ptr, len, enc, enc_len, start, end, vars, vars_len, require_eof) -> i32` |
+| `rbs_wasm_selftest` | `() -> i32` (parses a fixed sample; `1` on success) |
+
+For type and method-type parsing, a successful result of length 0 means the input
+was empty (`nil`).