rbs 3.9.4 → 4.2.0

data/stdlib/uri/0/rfc2396_parser.rbs

@@ -17,14 +17,14 @@ module URI
     # <!-- rdoc-file=lib/uri/rfc2396_parser.rb -->
     # The Hash of patterns.
     #
-    # See also URI::Parser.initialize_pattern.
+    # See also #initialize_pattern.
     #
     attr_reader pattern: Hash[Symbol, String]
 
     # <!-- rdoc-file=lib/uri/rfc2396_parser.rb -->
     # The Hash of Regexp.
     #
-    # See also URI::Parser.initialize_regexp.
+    # See also #initialize_regexp.
     #
     attr_reader regexp: Hash[Symbol, Regexp]
 
@@ -34,7 +34,7 @@ module URI
     # -->
     # ## Synopsis
     #
-    #     URI::Parser.new([opts])
+    #     URI::RFC2396_Parser.new([opts])
     #
     # ## Args
     #
@@ -52,7 +52,7 @@ module URI
     #
     # ## Examples
     #
-    #     p = URI::Parser.new(:ESCAPED => "(?:%[a-fA-F0-9]{2}|%u[a-fA-F0-9]{4})")
+    #     p = URI::RFC2396_Parser.new(:ESCAPED => "(?:%[a-fA-F0-9]{2}|%u[a-fA-F0-9]{4})")
     #     u = p.parse("http://example.jp/%uABCD") #=> #<URI::HTTP http://example.jp/%uABCD>
     #     URI.parse(u.to_s) #=> raises URI::InvalidURIError
     #
@@ -75,7 +75,7 @@ module URI
     # :   String to make safe
     #
     # `unsafe`
-    # :   Regexp to apply. Defaults to `self.regexp[:UNSAFE]`
+    # :   Regexp to apply. Defaults to <code>self.regexp[:UNSAFE]</code>
     #
     #
     # ## Description
@@ -105,7 +105,7 @@ module URI
     # Attempts to parse and merge a set of URIs. If no `block` given, then returns
     # the result, else it calls `block` for each element in result.
     #
-    # See also URI::Parser.make_regexp.
+    # See also #make_regexp.
     #
     def extract: (String str, ?Array[String] schemes) -> Array[String]
                | (String str, ?Array[String] schemes) { (String) -> untyped } -> nil
@@ -130,8 +130,9 @@ module URI
     #   rdoc-file=lib/uri/rfc2396_parser.rb
     #   - make_regexp(schemes = nil)
     # -->
-    # Returns Regexp that is default `self.regexp[:ABS_URI_REF]`, unless `schemes`
-    # is provided. Then it is a Regexp.union with `self.pattern[:X_ABS_URI]`.
+    # Returns Regexp that is default <code>self.regexp[:ABS_URI_REF]</code>, unless
+    # `schemes` is provided. Then it is a Regexp.union with
+    # <code>self.pattern[:X_ABS_URI]</code>.
     #
     def make_regexp: (?Array[String] schemes) -> Regexp
 
@@ -152,8 +153,7 @@ module URI
     #
     # ## Usage
     #
-    #     p = URI::Parser.new
-    #     p.parse("ldap://ldap.example.com/dc=example?user=john")
+    #     URI::RFC2396_PARSER.parse("ldap://ldap.example.com/dc=example?user=john")
     #     #=> #<URI::LDAP ldap://ldap.example.com/dc=example?user=john>
     #
     def parse: (String uri) -> URI::Generic
@@ -162,7 +162,7 @@ module URI
     #   rdoc-file=lib/uri/rfc2396_parser.rb
     #   - split(uri)
     # -->
-    # Returns a split URI against `regexp[:ABS_URI]`.
+    # Returns a split URI against <code>regexp[:ABS_URI]</code>.
     #
     def split: (String uri) -> [ String?, String?, String?, String?, String?, String?, String?, String?, String? ]
 
@@ -177,7 +177,7 @@ module URI
     # :   String to remove escapes from
     #
     # `escaped`
-    # :   Regexp to apply. Defaults to `self.regexp[:ESCAPED]`
+    # :   Regexp to apply. Defaults to <code>self.regexp[:ESCAPED]</code>
     #
     #
     # ## Description

data/stdlib/zlib/0/deflate.rbs

@@ -78,9 +78,10 @@ module Zlib
     #   - flush(flush = Zlib::SYNC_FLUSH)                 -> String
     #   - flush(flush = Zlib::SYNC_FLUSH) { |chunk| ... } -> nil
     # -->
-    # This method is equivalent to `deflate('', flush)`. This method is just
-    # provided to improve the readability of your Ruby program.  If a block is given
-    # chunks of deflate output are yielded to the block until the buffer is flushed.
+    # This method is equivalent to <code>deflate('', flush)</code>. This method is
+    # just provided to improve the readability of your Ruby program.  If a block is
+    # given chunks of deflate output are yielded to the block until the buffer is
+    # flushed.
     #
     # See Zlib::Deflate#deflate for detail on the `flush` constants NO_FLUSH,
     # SYNC_FLUSH, FULL_FLUSH and FINISH.

data/stdlib/zlib/0/gzip_file.rbs

@@ -143,7 +143,7 @@ module Zlib
     # `flush` method.  While `sync` mode is `true`, the compression ratio decreases
     # sharply.
     #
-    def sync=: (boolish) -> untyped
+    def sync=: (boolish) -> boolish
 
     # <!--
     #   rdoc-file=ext/zlib/zlib.c

data/stdlib/zlib/0/gzip_reader.rbs

@@ -35,8 +35,8 @@ module Zlib
   # Be careful of the footer of the gzip file. A gzip file has the checksum of
   # pre-compressed data in its footer. GzipReader checks all uncompressed data
   # against that checksum at the following cases, and if it fails, raises
-  # `Zlib::GzipFile::NoFooter`, `Zlib::GzipFile::CRCError`, or
-  # `Zlib::GzipFile::LengthError` exception.
+  # <code>Zlib::GzipFile::NoFooter</code>, <code>Zlib::GzipFile::CRCError</code>,
+  # or <code>Zlib::GzipFile::LengthError</code> exception.
   #
   # *   When an reading request is received beyond the end of file (the end of
   #     compressed data). That is, when Zlib::GzipReader#read,
@@ -62,8 +62,8 @@ module Zlib
     # GzipReader object associated with that file.  Further details of this method
     # are in Zlib::GzipReader.new and ZLib::GzipFile.wrap.
     #
-    def self.open: (String | _ToPath filename) -> instance
-                 | (String | _ToPath filename) { (instance gz) -> void } -> void
+    def self.open: (path filename) -> instance
+                 | (path filename) { (instance gz) -> void } -> void
 
     # <!--
     #   rdoc-file=ext/zlib/zlib.c
@@ -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
@@ -282,8 +282,8 @@ module Zlib
     # `read` method that behaves same as the IO#read.
     #
     # The `options` hash may be used to set the encoding of the data.
-    # `:external_encoding`, `:internal_encoding` and `:encoding` may be set as in
-    # IO::new.
+    # <code>:external_encoding</code>, <code>:internal_encoding</code> and
+    # <code>:encoding</code> may be set as in IO::new.
     #
     # If the gzip file header is incorrect, raises an Zlib::GzipFile::Error
     # exception.

data/stdlib/zlib/0/gzip_writer.rbs

@@ -38,7 +38,8 @@ module Zlib
     # returns a GzipWriter object associated with that file.  Further details of
     # this method are found in Zlib::GzipWriter.new and Zlib::GzipFile.wrap.
     #
-    def self.open: (String filename) { (instance gz) -> void } -> instance
+    def self.open: (String filename, ?Integer level, ?Integer strategy, **untyped opts) -> instance
+                 | (String filename, ?Integer level, ?Integer strategy, **untyped opts) { (instance gz) -> void } -> nil
 
     # <!--
     #   rdoc-file=ext/zlib/zlib.c
@@ -61,10 +62,11 @@ module Zlib
     #   - flush(flush=nil)
     # -->
     # Flushes all the internal buffers of the GzipWriter object.  The meaning of
-    # `flush` is same as in Zlib::Deflate#deflate.  `Zlib::SYNC_FLUSH` is used if
-    # `flush` is omitted.  It is no use giving flush `Zlib::NO_FLUSH`.
+    # `flush` is same as in Zlib::Deflate#deflate.  <code>Zlib::SYNC_FLUSH</code> is
+    # used if `flush` is omitted.  It is no use giving flush
+    # <code>Zlib::NO_FLUSH</code>.
     #
-    def flush: (?Integer flush) -> String
+    def flush: (?Integer flush) -> self
 
     # <!--
     #   rdoc-file=ext/zlib/zlib.c
@@ -74,16 +76,16 @@ module Zlib
     #
     # Setting the mtime in the gzip header does not effect the mtime of the file
     # generated. Different utilities that expand the gzipped files may use the mtime
-    # header. For example the gunzip utility can use the `-N` flag which will set
-    # the resultant file's mtime to the value in the header. By default many tools
-    # will set the mtime of the expanded file to the mtime of the gzipped file, not
-    # the mtime in the header.
+    # header. For example the gunzip utility can use the <code>-N</code> flag which
+    # will set the resultant file's mtime to the value in the header. By default
+    # many tools will set the mtime of the expanded file to the mtime of the gzipped
+    # file, not the mtime in the header.
     #
     # If you do not set an mtime, the default value will be the time when
     # compression started. Setting a value of 0 indicates no time stamp is
     # available.
     #
-    def mtime=: (string | _ToPath | IO file_name) -> Time
+    def mtime=: (Time | Integer) -> void
 
     # <!--
     #   rdoc-file=ext/zlib/zlib.c
@@ -123,7 +125,8 @@ module Zlib
     # -->
     # Same as IO.
     #
-    def putc: (Numeric | String arg0) -> untyped
+    def putc: (real) -> real
+            | (String) -> String
 
     # <!--
     #   rdoc-file=ext/zlib/zlib.c
@@ -158,9 +161,9 @@ module Zlib
     # that behaves the same as IO#write.
     #
     # The `options` hash may be used to set the encoding of the data.
-    # `:external_encoding`, `:internal_encoding` and `:encoding` may be set as in
-    # IO::new.
+    # <code>:external_encoding</code>, <code>:internal_encoding</code> and
+    # <code>:encoding</code> may be set as in IO::new.
     #
-    def initialize: (_Writer io, Integer level, Integer strategy, **untyped opts) -> void
+    def initialize: (_Writer io, ?Integer? level, ?Integer? strategy, **untyped opts) -> void
   end
 end

data/stdlib/zlib/0/inflate.rbs

@@ -123,7 +123,7 @@ module Zlib
     #
     #     What is this?
     #
-    # `:)`
+    # <code>:)</code>
     #
     def sync_point?: () -> bool
 

data/stdlib/zlib/0/need_dict.rbs

@@ -6,7 +6,7 @@ module Zlib
   # When zlib returns a Z_NEED_DICT if a preset dictionary is needed at this
   # point.
   #
-  # Used by Zlib::Inflate.inflate and `Zlib.inflate`
+  # Used by Zlib::Inflate.inflate and <code>Zlib.inflate</code>
   #
   class NeedDict < Zlib::Error
   end

data/wasm/README.md

@@ -0,0 +1,109 @@
+# 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  # copy rbs_parser.wasm into lib/rbs/wasm/ for JRuby
+$ rake wasm:install_jars # download the Chicory/ASM jars into ~/.m2 (run on JRuby)
+```
+
+The compiled `rbs_parser.wasm` is a build artifact and is not checked in.
+
+Like the MRI extension, the module is compiled with `-DNDEBUG`, which removes the
+`RBS_ASSERT` checks — they sit in the lexer and the constant pool, so leaving them
+in costs around 20% of parse time. `DEBUG=1 rake wasm:build` keeps them, which is
+what you want when debugging the parser itself through the module.
+
+The WASI SDK is needed for the *build*, not for running the result — the host clang already
+knows the `wasm32` target, but there is no wasm32 libc on a normal machine, so it picks up the
+host headers and fails on the first `#include`. That is what the SDK supplies, along with the
+builtins the link step needs.
+
+## Running the suite on JRuby
+
+[`Dockerfile.jruby`](../Dockerfile.jruby) builds an image that has everything this needs, so no
+JRuby, JDK or WASI SDK has to be installed to work on the JRuby side:
+
+```console
+$ docker build -f Dockerfile.jruby -t rbs-jruby .
+$ docker run --rm rbs-jruby                                  # run the test suite
+$ docker run --rm -e RBS_PLATFORM=java rbs-jruby \
+    gem build rbs.gemspec                                    # build the -java gem
+```
+
+Two things in it are not obvious:
+
+- `build-essential` is for prism, which builds `libprism.so` and loads it through FFI on JRuby
+  rather than as an MRI C extension. It needs `cc` and `make`.
+- Bundler is skipped. The development `Gemfile` pulls in CRuby-only C extensions (bigdecimal,
+  stackprof, …) that cannot build on JRuby, so the few gems the suite needs are installed
+  directly, in the same set as [`jruby.yml`](../.github/workflows/jruby.yml).
+
+The image compiles `rbs_parser.wasm` itself, which is why it carries the WASI SDK. That is not
+the only arrangement: the build needs the SDK but not JRuby, and running the suite needs JRuby
+but not the SDK, so `jruby.yml` splits them instead — it compiles the module on CRuby and then
+switches engines to test against the result.
+
+`rake wasm:install_jars` is the step that has to be on JRuby either way: it resolves the `jar`
+requirements from `rbs.gemspec` through the JVM.
+
+## 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:
+
+| Status | Meaning | Result |
+| --- | --- | --- |
+| `1` | Parsed. | The serialized AST. |
+| `0` | Parse error. | An error blob (start/end positions, syntax flag, token type, message). |
+| `-1` | Negative or reversed range. | Empty. |
+| `-2` | `start` is a byte position no character starts at — inside a character, or past the end of the buffer. | Empty. |
+
+An `end` past the end of the buffer is not an error: it is clamped to the
+buffer, which is where lexing stops anyway. The two negative statuses are about
+the range the caller asked for rather than the source text, and `RBS::Parser`
+turns both into an `ArgumentError`, as the C extension does.
+
+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`).