rbs-relaxed 3.9.0.1

data/stdlib/pty/0/pty.rbs

@@ -0,0 +1,237 @@
+# <!-- rdoc-file=ext/pty/pty.c -->
+# Creates and manages pseudo terminals (PTYs).  See also
+# https://en.wikipedia.org/wiki/Pseudo_terminal
+#
+# PTY allows you to allocate new terminals using ::open or ::spawn a new
+# terminal with a specific command.
+#
+# ## Example
+#
+# In this example we will change the buffering type in the `factor` command,
+# assuming that factor uses stdio for stdout buffering.
+#
+# If IO.pipe is used instead of PTY.open, this code deadlocks because factor's
+# stdout is fully buffered.
+#
+#     # start by requiring the standard library PTY
+#     require 'pty'
+#
+#     master, slave = PTY.open
+#     read, write = IO.pipe
+#     pid = spawn("factor", :in=>read, :out=>slave)
+#     read.close     # we dont need the read
+#     slave.close    # or the slave
+#
+#     # pipe "42" to the factor command
+#     write.puts "42"
+#     # output the response from factor
+#     p master.gets #=> "42: 2 3 7\n"
+#
+#     # pipe "144" to factor and print out the response
+#     write.puts "144"
+#     p master.gets #=> "144: 2 2 2 2 3 3\n"
+#     write.close # close the pipe
+#
+#     # The result of read operation when pty slave is closed is platform
+#     # dependent.
+#     ret = begin
+#             master.gets     # FreeBSD returns nil.
+#           rescue Errno::EIO # GNU/Linux raises EIO.
+#             nil
+#           end
+#     p ret #=> nil
+#
+# ## License
+#
+# (c) Copyright 1998 by Akinori Ito.
+#
+# This software may be redistributed freely for this purpose, in full or in
+# part, provided that this entire copyright notice is included on any copies of
+# this software and applications and derivations thereof.
+#
+# This software is provided on an "as is" basis, without warranty of any kind,
+# either expressed or implied, as to any matter including, but not limited to
+# warranty of fitness of purpose, or merchantability, or results obtained from
+# use of this software.
+#
+module PTY
+  # <!--
+  #   rdoc-file=ext/pty/pty.c
+  #   - PTY.check(pid, raise = false) => Process::Status or nil
+  #   - PTY.check(pid, true)          => nil or raises PTY::ChildExited
+  # -->
+  # Checks the status of the child process specified by `pid`. Returns `nil` if
+  # the process is still alive.
+  #
+  # If the process is not alive, and `raise` was true, a PTY::ChildExited
+  # exception will be raised. Otherwise it will return a Process::Status instance.
+  #
+  # `pid`
+  # :   The process id of the process to check
+  #
+  # `raise`
+  # :   If `true` and the process identified by `pid` is no longer alive a
+  #     PTY::ChildExited is raised.
+  #
+  def self.check: (Integer pid, ?boolish raise) -> Process::Status?
+
+  # <!-- rdoc-file=ext/pty/pty.c -->
+  # Spawns the specified command on a newly allocated pty. You can also use the
+  # alias ::getpty.
+  #
+  # The command's controlling tty is set to the slave device of the pty and its
+  # standard input/output/error is redirected to the slave device.
+  #
+  # `env` is an optional hash that provides additional environment variables to
+  # the spawned pty.
+  #
+  #     # sets FOO to "bar"
+  #     PTY.spawn({"FOO"=>"bar"}, "printenv", "FOO") do |r, w, pid|
+  #       p r.read #=> "bar\r\n"
+  #     ensure
+  #       r.close; w.close; Process.wait(pid)
+  #     end
+  #     # unsets FOO
+  #     PTY.spawn({"FOO"=>nil}, "printenv", "FOO") do |r, w, pid|
+  #       p r.read #=> ""
+  #     ensure
+  #       r.close; w.close; Process.wait(pid)
+  #     end
+  #
+  # `command` and `command_line` are the full commands to run, given a String. Any
+  # additional `arguments` will be passed to the command.
+  #
+  # ### Return values
+  #
+  # In the non-block form this returns an array of size three, `[r, w, pid]`.
+  #
+  # In the block form these same values will be yielded to the block:
+  #
+  # `r`
+  # :   A readable IO that contains the command's standard output and standard
+  #     error
+  #
+  # `w`
+  # :   A writable IO that is the command's standard input
+  #
+  # `pid`
+  # :   The process identifier for the command.
+  #
+  #
+  # ### Clean up
+  #
+  # This method does not clean up like closing IOs or waiting for child process,
+  # except that the process is detached in the block form to prevent it from
+  # becoming a zombie (see Process.detach).  Any other cleanup is the
+  # responsibility of the caller.  If waiting for `pid`, be sure to close both `r`
+  # and `w` before doing so; doing it in the reverse order may cause deadlock on
+  # some OSes.
+  #
+  alias self.getpty self.spawn
+
+  # <!--
+  #   rdoc-file=ext/pty/pty.c
+  #   - PTY.open => [master_io, slave_file]
+  #   - PTY.open {|(master_io, slave_file)| ... } => block value
+  # -->
+  # Allocates a pty (pseudo-terminal).
+  #
+  # In the block form, yields an array of two elements (`master_io, slave_file`)
+  # and the value of the block is returned from `open`.
+  #
+  # The IO and File are both closed after the block completes if they haven't been
+  # already closed.
+  #
+  #     PTY.open {|master, slave|
+  #       p master      #=> #<IO:masterpty:/dev/pts/1>
+  #       p slave      #=> #<File:/dev/pts/1>
+  #       p slave.path #=> "/dev/pts/1"
+  #     }
+  #
+  # In the non-block form, returns a two element array, `[master_io, slave_file]`.
+  #
+  #     master, slave = PTY.open
+  #     # do something with master for IO, or the slave file
+  #
+  # The arguments in both forms are:
+  #
+  # `master_io`
+  # :   the master of the pty, as an IO.
+  #
+  # `slave_file`
+  # :   the slave of the pty, as a File.  The path to the terminal device is
+  #     available via `slave_file.path`
+  #
+  #
+  # IO#raw! is usable to disable newline conversions:
+  #
+  #     require 'io/console'
+  #     PTY.open {|m, s|
+  #       s.raw!
+  #       # ...
+  #     }
+  #
+  def self.open: () -> [ IO, File ]
+               | [A] () { ([ IO, File ]) -> A } -> A
+
+  # <!--
+  #   rdoc-file=ext/pty/pty.c
+  #   - PTY.spawn([env,] command_line)  { |r, w, pid| ... }
+  #   - PTY.spawn([env,] command_line)  => [r, w, pid]
+  #   - PTY.spawn([env,] command, arguments, ...)  { |r, w, pid| ... }
+  #   - PTY.spawn([env,] command, arguments, ...)  => [r, w, pid]
+  # -->
+  # Spawns the specified command on a newly allocated pty. You can also use the
+  # alias ::getpty.
+  #
+  # The command's controlling tty is set to the slave device of the pty and its
+  # standard input/output/error is redirected to the slave device.
+  #
+  # `env` is an optional hash that provides additional environment variables to
+  # the spawned pty.
+  #
+  #     # sets FOO to "bar"
+  #     PTY.spawn({"FOO"=>"bar"}, "printenv", "FOO") do |r, w, pid|
+  #       p r.read #=> "bar\r\n"
+  #     ensure
+  #       r.close; w.close; Process.wait(pid)
+  #     end
+  #     # unsets FOO
+  #     PTY.spawn({"FOO"=>nil}, "printenv", "FOO") do |r, w, pid|
+  #       p r.read #=> ""
+  #     ensure
+  #       r.close; w.close; Process.wait(pid)
+  #     end
+  #
+  # `command` and `command_line` are the full commands to run, given a String. Any
+  # additional `arguments` will be passed to the command.
+  #
+  # ### Return values
+  #
+  # In the non-block form this returns an array of size three, `[r, w, pid]`.
+  #
+  # In the block form these same values will be yielded to the block:
+  #
+  # `r`
+  # :   A readable IO that contains the command's standard output and standard
+  #     error
+  #
+  # `w`
+  # :   A writable IO that is the command's standard input
+  #
+  # `pid`
+  # :   The process identifier for the command.
+  #
+  #
+  # ### Clean up
+  #
+  # This method does not clean up like closing IOs or waiting for child process,
+  # except that the process is detached in the block form to prevent it from
+  # becoming a zombie (see Process.detach).  Any other cleanup is the
+  # responsibility of the caller.  If waiting for `pid`, be sure to close both `r`
+  # and `w` before doing so; doing it in the reverse order may cause deadlock on
+  # some OSes.
+  #
+  def self.spawn: (*String command) -> [ IO, IO, Integer ]
+                | (*String command) { ([ IO, IO, Integer ]) -> void } -> void
+end

data/stdlib/rdoc/0/code_object.rbs

@@ -0,0 +1,51 @@
+%a{annotate:rdoc:skip}
+module RDoc
+  # <!-- rdoc-file=lib/rdoc/code_object.rb -->
+  # Base class for the RDoc code tree.
+  #
+  # We contain the common stuff for contexts (which are containers) and other
+  # elements (methods, attributes and so on)
+  #
+  # Here's the tree of the CodeObject subclasses:
+  #
+  # *   RDoc::Context
+  #     *   RDoc::TopLevel
+  #     *   RDoc::ClassModule
+  #         *   RDoc::AnonClass (never used so far)
+  #         *   RDoc::NormalClass
+  #         *   RDoc::NormalModule
+  #         *   RDoc::SingleClass
+  # *   RDoc::MethodAttr
+  #     *   RDoc::Attr
+  #     *   RDoc::AnyMethod
+  #         *   RDoc::GhostMethod
+  #         *   RDoc::MetaMethod
+  # *   RDoc::Alias
+  # *   RDoc::Constant
+  # *   RDoc::Mixin
+  #     *   RDoc::Require
+  #     *   RDoc::Include
+  #
+  class CodeObject
+    # <!-- rdoc-file=lib/rdoc/code_object.rb -->
+    # Our comment
+    #
+    attr_reader comment: Markup::Document | Comment | String
+
+    # <!--
+    #   rdoc-file=lib/rdoc/code_object.rb
+    #   - new()
+    # -->
+    # Creates a new CodeObject that will document itself and its children
+    #
+    def initialize: () -> void
+
+    # <!--
+    #   rdoc-file=lib/rdoc/code_object.rb
+    #   - comment=(comment)
+    # -->
+    # Replaces our comment with `comment`, unless it is empty.
+    #
+    def comment=: (Markup::Document | Comment | String | nil) -> (Markup::Document | Comment | String)
+  end
+end

data/stdlib/rdoc/0/comment.rbs

@@ -0,0 +1,59 @@
+%a{annotate:rdoc:skip}
+module RDoc
+  # <!-- rdoc-file=lib/rdoc/comment.rb -->
+  # A comment holds the text comment for a RDoc::CodeObject and provides a unified
+  # way of cleaning it up and parsing it into an RDoc::Markup::Document.
+  #
+  # Each comment may have a different markup format set by #format=.  By default
+  # 'rdoc' is used.  The :markup: directive tells RDoc which format to use.
+  #
+  # See RDoc::MarkupReference@Directive+for+Specifying+RDoc+Source+Format.
+  #
+  class Comment
+    # <!-- rdoc-file=lib/rdoc/comment.rb -->
+    # The format of this comment.  Defaults to RDoc::Markup
+    #
+    attr_reader format: String
+
+    # <!-- rdoc-file=lib/rdoc/comment.rb -->
+    # The RDoc::TopLevel this comment was found in
+    #
+    attr_accessor location: String
+
+    # <!--
+    #   rdoc-file=lib/rdoc/comment.rb
+    #   - new(text = nil, location = nil, language = nil)
+    # -->
+    # Creates a new comment with `text` that is found in the RDoc::TopLevel
+    # `location`.
+    #
+    def initialize: (?String? text, ?RDoc::Context? location, ?String? language) -> void
+
+    # <!--
+    #   rdoc-file=lib/rdoc/comment.rb
+    #   - format=(format)
+    # -->
+    # Sets the format of this comment and resets any parsed document
+    #
+    def format=: (String format) -> void
+
+    def normalized?: () -> bool
+
+    # <!--
+    #   rdoc-file=lib/rdoc/comment.rb
+    #   - normalize()
+    # -->
+    # Normalizes the text.  See RDoc::Text#normalize_comment for details
+    #
+    def normalize: () -> self
+
+    # <!--
+    #   rdoc-file=lib/rdoc/comment.rb
+    #   - parse()
+    # -->
+    # Parses the comment into an RDoc::Markup::Document.  The parsed document is
+    # cached until the text is changed.
+    #
+    def parse: () -> Markup::Document
+  end
+end

data/stdlib/rdoc/0/context.rbs

@@ -0,0 +1,153 @@
+%a{annotate:rdoc:skip}
+module RDoc
+  # <!-- rdoc-file=lib/rdoc/context.rb -->
+  # A Context is something that can hold modules, classes, methods, attributes,
+  # aliases, requires, and includes. Classes, modules, and files are all Contexts.
+  #
+  class Context < CodeObject
+    include Comparable
+
+    # <!-- rdoc-file=lib/rdoc/context.rb -->
+    # Types of methods
+    #
+    TYPES: ::Array["class" | "instance"]
+
+    TOMDOC_TITLES: ::Array[nil | "Public" | "Internal" | "Deprecated"]
+
+    type class_types = singleton(RDoc::NormalClass) | singleton(RDoc::SingleClass)
+
+    # <!--
+    #   rdoc-file=lib/rdoc/context.rb
+    #   - new()
+    # -->
+    # Creates an unnamed empty context with public current visibility
+    #
+    def initialize: () -> void
+
+    # <!--
+    #   rdoc-file=lib/rdoc/context.rb
+    #   - add_alias(an_alias)
+    # -->
+    # Adds `an_alias` that is automatically resolved
+    #
+    def add_alias: (RDoc::Alias an_alias) -> RDoc::Alias
+
+    # <!--
+    #   rdoc-file=lib/rdoc/context.rb
+    #   - add_attribute(attribute)
+    # -->
+    # Adds `attribute` if not already there. If it is (as method(s) or attribute),
+    # updates the comment if it was empty.
+    #
+    # The attribute is registered only if it defines a new method. For instance,
+    # `attr_reader :foo` will not be registered if method `foo` exists, but
+    # `attr_accessor :foo` will be registered if method `foo` exists, but `foo=`
+    # does not.
+    #
+    def add_attribute: (RDoc::Attr attribute) -> RDoc::Attr
+
+    # <!--
+    #   rdoc-file=lib/rdoc/context.rb
+    #   - add_class(class_type, given_name, superclass = '::Object')
+    # -->
+    # Adds a class named `given_name` with `superclass`.
+    #
+    # Both `given_name` and `superclass` may contain '::', and are interpreted
+    # relative to the `self` context. This allows handling correctly examples like
+    # these:
+    #     class RDoc::Gauntlet < Gauntlet
+    #     module Mod
+    #       class Object   # implies < ::Object
+    #       class SubObject < Object  # this is _not_ ::Object
+    #
+    # Given `class Container::Item` RDoc assumes `Container` is a module unless it
+    # later sees `class Container`.  `add_class` automatically upgrades `given_name`
+    # to a class in this case.
+    #
+    def add_class: (class_types class_type, ::String given_name, ?::String superclass) -> (RDoc::NormalClass | RDoc::SingleClass)
+
+    # <!--
+    #   rdoc-file=lib/rdoc/context.rb
+    #   - add_constant(constant)
+    # -->
+    # Adds `constant` if not already there. If it is, updates the comment, value
+    # and/or is_alias_for of the known constant if they were empty/nil.
+    #
+    def add_constant: (RDoc::Constant constant) -> RDoc::Constant
+
+    # <!--
+    #   rdoc-file=lib/rdoc/context.rb
+    #   - add_include(include)
+    # -->
+    # Adds included module `include` which should be an RDoc::Include
+    #
+    def add_include: (RDoc::Include `include`) -> RDoc::Include
+
+    # <!--
+    #   rdoc-file=lib/rdoc/context.rb
+    #   - add_extend(ext)
+    # -->
+    # Adds extension module `ext` which should be an RDoc::Extend
+    #
+    def add_extend: (RDoc::Extend ext) -> RDoc::Extend
+
+    # <!--
+    #   rdoc-file=lib/rdoc/context.rb
+    #   - add_method(method)
+    # -->
+    # Adds `method` if not already there. If it is (as method or attribute), updates
+    # the comment if it was empty.
+    #
+    def add_method: (RDoc::AnyMethod method) -> RDoc::AnyMethod
+
+    # <!--
+    #   rdoc-file=lib/rdoc/context.rb
+    #   - add_module(class_type, name)
+    # -->
+    # Adds a module named `name`.  If RDoc already knows `name` is a class then that
+    # class is returned instead.  See also #add_class.
+    #
+    def add_module: (singleton(RDoc::NormalModule) class_type, String name) -> RDoc::NormalModule
+
+    # <!-- rdoc-file=lib/rdoc/context.rb -->
+    # All attr* methods
+    #
+    def attributes: () -> Array[Attr]
+
+    # <!-- rdoc-file=lib/rdoc/context.rb -->
+    # Constants defined
+    #
+    def constants: () -> Array[Constant]
+
+    # <!--
+    #   rdoc-file=lib/rdoc/context.rb
+    #   - find_module_named(name)
+    # -->
+    # Find a module with `name` using ruby's scoping rules
+    #
+    def find_module_named: (untyped name) -> (untyped | self)
+
+    # <!--
+    #   rdoc-file=lib/rdoc/context.rb
+    #   - full_name()
+    # -->
+    # The full name for this context.  This method is overridden by subclasses.
+    #
+    def full_name: () -> "(unknown)"
+
+    # <!-- rdoc-file=lib/rdoc/context.rb -->
+    # Methods defined in this context
+    #
+    def method_list: () -> Array[AnyMethod]
+
+    def to_s: () -> ::String
+
+    # <!--
+    #   rdoc-file=lib/rdoc/context.rb
+    #   - top_level()
+    # -->
+    # Return the TopLevel that owns us
+    #
+    def top_level: () -> RDoc::TopLevel
+  end
+end

data/stdlib/rdoc/0/markup.rbs

@@ -0,0 +1,117 @@
+%a{annotate:rdoc:skip}
+module RDoc
+  # <!-- rdoc-file=lib/rdoc/markup.rb -->
+  # RDoc::Markup parses plain text documents and attempts to decompose them into
+  # their constituent parts.  Some of these parts are high-level: paragraphs,
+  # chunks of verbatim text, list entries and the like.  Other parts happen at the
+  # character level: a piece of bold text, a word in code font.  This markup is
+  # similar in spirit to that used on WikiWiki webs, where folks create web pages
+  # using a simple set of formatting rules.
+  #
+  # RDoc::Markup and other markup formats do no output formatting, this is handled
+  # by the RDoc::Markup::Formatter subclasses.
+  #
+  # # Markup Formats
+  #
+  # `RDoc` supports these markup formats:
+  #
+  # *   `rdoc`: the `RDoc` markup format; see RDoc::MarkupReference.
+  # *   `markdown`: The `markdown` markup format as described in the [Markdown
+  #     Guide](https://www.markdownguide.org); see RDoc::Markdown.
+  # *   `rd`: the `rd` markup format format; see RDoc::RD.
+  # *   `tomdoc`: the TomDoc format as described in [TomDoc for
+  #     Ruby](http://tomdoc.org); see RDoc::TomDoc.
+  #
+  # You can choose a markup format using the following methods:
+  #
+  # per project
+  # :   If you build your documentation with rake use RDoc::Task#markup.
+  #
+  #     If you build your documentation by hand run:
+  #
+  #         rdoc --markup your_favorite_format --write-options
+  #
+  #     and commit `.rdoc_options` and ship it with your packaged gem.
+  #
+  # per file
+  # :   At the top of the file use the `:markup:` directive to set the default
+  #     format for the rest of the file.
+  #
+  # per comment
+  # :   Use the `:markup:` directive at the top of a comment you want to write in
+  #     a different format.
+  #
+  #
+  # # RDoc::Markup
+  #
+  # RDoc::Markup is extensible at runtime: you can add new markup elements to be
+  # recognized in the documents that RDoc::Markup parses.
+  #
+  # RDoc::Markup is intended to be the basis for a family of tools which share the
+  # common requirement that simple, plain-text should be rendered in a variety of
+  # different output formats and media.  It is envisaged that RDoc::Markup could
+  # be the basis for formatting RDoc style comment blocks, Wiki entries, and
+  # online FAQs.
+  #
+  # ## Synopsis
+  #
+  # This code converts `input_string` to HTML.  The conversion takes place in the
+  # `convert` method, so you can use the same RDoc::Markup converter to convert
+  # multiple input strings.
+  #
+  #     require 'rdoc'
+  #
+  #     h = RDoc::Markup::ToHtml.new(RDoc::Options.new)
+  #
+  #     puts h.convert(input_string)
+  #
+  # You can extend the RDoc::Markup parser to recognize new markup sequences, and
+  # to add regexp handling. Here we make WikiWords significant to the parser, and
+  # also make the sequences {word} and <no>text...</no> signify strike-through
+  # text.  We then subclass the HTML output class to deal with these:
+  #
+  #     require 'rdoc'
+  #
+  #     class WikiHtml < RDoc::Markup::ToHtml
+  #       def handle_regexp_WIKIWORD(target)
+  #         "<font color=red>" + target.text + "</font>"
+  #       end
+  #     end
+  #
+  #     markup = RDoc::Markup.new
+  #     markup.add_word_pair("{", "}", :STRIKE)
+  #     markup.add_html("no", :STRIKE)
+  #
+  #     markup.add_regexp_handling(/\b([A-Z][a-z]+[A-Z]\w+)/, :WIKIWORD)
+  #
+  #     wh = WikiHtml.new RDoc::Options.new, markup
+  #     wh.add_tag(:STRIKE, "<strike>", "</strike>")
+  #
+  #     puts "<body>#{wh.convert ARGF.read}</body>"
+  #
+  # ## Encoding
+  #
+  # Where Encoding support is available, RDoc will automatically convert all
+  # documents to the same output encoding.  The output encoding can be set via
+  # RDoc::Options#encoding and defaults to Encoding.default_external.
+  #
+  # # RDoc Markup Reference
+  #
+  # See RDoc::MarkupReference.
+  #
+  class Markup
+    class Document
+      include Enumerable[Document]
+
+      def each: () { (Document) -> void } -> void
+              | () -> Enumerator[Document, void]
+
+      def file: () -> String?
+
+      def accept: (untyped) -> String
+    end
+
+    class ToMarkdown
+    end
+  end
+end

data/stdlib/rdoc/0/parser.rbs

@@ -0,0 +1,56 @@
+%a{annotate:rdoc:skip}
+module RDoc
+  # <!-- rdoc-file=lib/rdoc/parser.rb -->
+  # A parser is simple a class that subclasses RDoc::Parser and implements #scan
+  # to fill in an RDoc::TopLevel with parsed data.
+  #
+  # The initialize method takes an RDoc::TopLevel to fill with parsed content, the
+  # name of the file to be parsed, the content of the file, an RDoc::Options
+  # object and an RDoc::Stats object to inform the user of parsed items.  The scan
+  # method is then called to parse the file and must return the RDoc::TopLevel
+  # object.  By calling super these items will be set for you.
+  #
+  # In order to be used by RDoc the parser needs to register the file extensions
+  # it can parse.  Use ::parse_files_matching to register extensions.
+  #
+  #     require 'rdoc'
+  #
+  #     class RDoc::Parser::Xyz < RDoc::Parser
+  #       parse_files_matching /\.xyz$/
+  #
+  #       def initialize top_level, file_name, content, options, stats
+  #         super
+  #
+  #         # extra initialization if needed
+  #       end
+  #
+  #       def scan
+  #         # parse file and fill in @top_level
+  #       end
+  #     end
+  #
+  class Parser
+    # <!--
+    #   rdoc-file=lib/rdoc/parser.rb
+    #   - parse_files_matching(regexp)
+    # -->
+    # Record which file types this parser can understand.
+    #
+    # It is ok to call this multiple times.
+    #
+    def self?.parse_files_matching: (Regexp path) -> void
+
+    # <!--
+    #   rdoc-file=lib/rdoc/parser.rb
+    #   - new(top_level, file_name, content, options, stats)
+    # -->
+    # Creates a new Parser storing `top_level`, `file_name`, `content`, `options`
+    # and `stats` in instance variables.  In +@preprocess+ an
+    # RDoc::Markup::PreProcess object is created which allows processing of
+    # directives.
+    #
+    def initialize: (RDoc::TopLevel top_level, String filename, String content, Hash[untyped, untyped] options, RDoc::Stats stats) -> void
+
+    def scan: () -> RDoc::TopLevel
+  end
+end