rbs 3.0.0.dev.2 → 3.0.0.dev.3

data/core/ruby_vm.rbs

@@ -51,3 +51,213 @@ RubyVM::OPTS: Array[String]
 #
 class RubyVM::InstructionSequence < Object
 end
+
+# <!-- rdoc-file=ast.rb -->
+# AbstractSyntaxTree provides methods to parse Ruby code into abstract syntax
+# trees. The nodes in the tree are instances of
+# RubyVM::AbstractSyntaxTree::Node.
+#
+# This module is MRI specific as it exposes implementation details of the MRI
+# abstract syntax tree.
+#
+# This module is experimental and its API is not stable, therefore it might
+# change without notice. As examples, the order of children nodes is not
+# guaranteed, the number of children nodes might change, there is no way to
+# access children nodes by name, etc.
+#
+# If you are looking for a stable API or an API working under multiple Ruby
+# implementations, consider using the *parser* gem or Ripper. If you would like
+# to make RubyVM::AbstractSyntaxTree stable, please join the discussion at
+# https://bugs.ruby-lang.org/issues/14844.
+#
+module RubyVM::AbstractSyntaxTree
+  # <!--
+  #   rdoc-file=ast.rb
+  #   - RubyVM::AbstractSyntaxTree.parse(string, keep_script_lines: false, error_tolerant: false, keep_tokens: false) -> RubyVM::AbstractSyntaxTree::Node
+  # -->
+  # Parses the given *string* into an abstract syntax tree, returning the root
+  # node of that tree.
+  #
+  #     RubyVM::AbstractSyntaxTree.parse("x = 1 + 2")
+  #     # => #<RubyVM::AbstractSyntaxTree::Node:SCOPE@1:0-1:9>
+  #
+  # If `keep_script_lines: true` option is provided, the text of the parsed source
+  # is associated with nodes and is available via Node#script_lines.
+  #
+  # If `keep_tokens: true` option is provided, Node#tokens are populated.
+  #
+  # SyntaxError is raised if the given *string* is invalid syntax. To overwrite
+  # this behavior, `error_tolerant: true` can be provided. In this case, the
+  # parser will produce a tree where expressions with syntax errors would be
+  # represented by Node with `type=:ERROR`.
+  #
+  #     root = RubyVM::AbstractSyntaxTree.parse("x = 1; p(x; y=2")
+  #     # <internal:ast>:33:in `parse': syntax error, unexpected ';', expecting ')' (SyntaxError)
+  #     # x = 1; p(x; y=2
+  #     #           ^
+  #
+  #     root = RubyVM::AbstractSyntaxTree.parse("x = 1; p(x; y=2", error_tolerant: true)
+  #     # (SCOPE@1:0-1:15
+  #     #  tbl: [:x, :y]
+  #     #  args: nil
+  #     #  body: (BLOCK@1:0-1:15 (LASGN@1:0-1:5 :x (LIT@1:4-1:5 1)) (ERROR@1:7-1:11) (LASGN@1:12-1:15 :y (LIT@1:14-1:15 2))))
+  #     root.children.last.children
+  #     # [(LASGN@1:0-1:5 :x (LIT@1:4-1:5 1)),
+  #     #  (ERROR@1:7-1:11),
+  #     #  (LASGN@1:12-1:15 :y (LIT@1:14-1:15 2))]
+  #
+  # Note that parsing continues even after the errored expresion.
+  #
+  def self.parse: (String string, ?keep_script_lines: bool, ?error_tolerant: bool, ?keep_tokens: bool) -> Node
+
+  # <!--
+  #   rdoc-file=ast.rb
+  #   - RubyVM::AbstractSyntaxTree.parse_file(pathname, keep_script_lines: false, error_tolerant: false, keep_tokens: false) -> RubyVM::AbstractSyntaxTree::Node
+  # -->
+  # Reads the file from *pathname*, then parses it like ::parse, returning the
+  # root node of the abstract syntax tree.
+  #
+  # SyntaxError is raised if *pathname*'s contents are not valid Ruby syntax.
+  #
+  #     RubyVM::AbstractSyntaxTree.parse_file("my-app/app.rb")
+  #     # => #<RubyVM::AbstractSyntaxTree::Node:SCOPE@1:0-31:3>
+  #
+  # See ::parse for explanation of keyword argument meaning and usage.
+  #
+  def self.parse_file: (String | ::_ToPath string, ?keep_script_lines: bool, ?error_tolerant: bool, ?keep_tokens: bool) -> Node
+
+  # <!--
+  #   rdoc-file=ast.rb
+  #   - RubyVM::AbstractSyntaxTree.of(proc, keep_script_lines: false, error_tolerant: false, keep_tokens: false)   -> RubyVM::AbstractSyntaxTree::Node
+  #   - RubyVM::AbstractSyntaxTree.of(method, keep_script_lines: false, error_tolerant: false, keep_tokens: false) -> RubyVM::AbstractSyntaxTree::Node
+  # -->
+  # Returns AST nodes of the given *proc* or *method*.
+  #
+  #     RubyVM::AbstractSyntaxTree.of(proc {1 + 2})
+  #     # => #<RubyVM::AbstractSyntaxTree::Node:SCOPE@1:35-1:42>
+  #
+  #     def hello
+  #       puts "hello, world"
+  #     end
+  #
+  #     RubyVM::AbstractSyntaxTree.of(method(:hello))
+  #     # => #<RubyVM::AbstractSyntaxTree::Node:SCOPE@1:0-3:3>
+  #
+  # See ::parse for explanation of keyword argument meaning and usage.
+  #
+  def self.of: (Proc | Method | UnboundMethod body, ?keep_script_lines: bool, ?error_tolerant: bool, ?keep_tokens: bool) -> Node?
+
+  # <!--
+  #   rdoc-file=ast.rb
+  #   - RubyVM::AbstractSyntaxTree.node_id_for_backtrace_location(backtrace_location)   -> integer
+  # -->
+  # Returns the node id for the given backtrace location.
+  #
+  #     begin
+  #       raise
+  #     rescue =>  e
+  #       loc = e.backtrace_locations.first
+  #       RubyVM::AbstractSyntaxTree.node_id_for_backtrace_location(loc)
+  #     end # => 0
+  #
+  def self.node_id_for_backtrace_location: (Thread::Backtrace::Location backtrace_location) -> Integer
+
+  # <!-- rdoc-file=ast.rb -->
+  # RubyVM::AbstractSyntaxTree::Node instances are created by parse methods in
+  # RubyVM::AbstractSyntaxTree.
+  #
+  # This class is MRI specific.
+  #
+  class Node
+    # <!--
+    #   rdoc-file=ast.rb
+    #   - node.type -> symbol
+    # -->
+    # Returns the type of this node as a symbol.
+    #
+    #     root = RubyVM::AbstractSyntaxTree.parse("x = 1 + 2")
+    #     root.type # => :SCOPE
+    #     lasgn = root.children[2]
+    #     lasgn.type # => :LASGN
+    #     call = lasgn.children[1]
+    #     call.type # => :OPCALL
+    #
+    def type: () -> Symbol
+
+    # <!--
+    #   rdoc-file=ast.rb
+    #   - node.first_lineno -> integer
+    # -->
+    # The line number in the source code where this AST's text began.
+    #
+    def first_lineno: () -> Integer
+
+    # <!--
+    #   rdoc-file=ast.rb
+    #   - node.first_column -> integer
+    # -->
+    # The column number in the source code where this AST's text began.
+    #
+    def first_column: () -> Integer
+
+    # <!--
+    #   rdoc-file=ast.rb
+    #   - node.last_lineno -> integer
+    # -->
+    # The line number in the source code where this AST's text ended.
+    #
+    def last_lineno: () -> Integer
+
+    # <!--
+    #   rdoc-file=ast.rb
+    #   - node.last_column -> integer
+    # -->
+    # The column number in the source code where this AST's text ended.
+    #
+    def last_column: () -> Integer
+
+    # <!--
+    #   rdoc-file=ast.rb
+    #   - node.tokens -> array
+    # -->
+    # Returns tokens corresponding to the location of the node. Returns `nil` if
+    # `keep_tokens` is not enabled when #parse method is called.
+    #
+    #     root = RubyVM::AbstractSyntaxTree.parse("x = 1 + 2", keep_tokens: true)
+    #     root.tokens # => [[0, :tIDENTIFIER, "x", [1, 0, 1, 1]], [1, :tSP, " ", [1, 1, 1, 2]], ...]
+    #     root.tokens.map{_1[2]}.join # => "x = 1 + 2"
+    #
+    # Token is an array of:
+    #
+    # *   id
+    # *   token type
+    # *   source code text
+    # *   location [ first_lineno, first_column, last_lineno, last_column ]
+    #
+    def tokens: () -> Array[[Integer, Symbol, String, [Integer, Integer, Integer, Integer]]]?
+
+    # <!--
+    #   rdoc-file=ast.rb
+    #   - node.all_tokens -> array
+    # -->
+    # Returns all tokens for the input script regardless the receiver node. Returns
+    # `nil` if `keep_tokens` is not enabled when #parse method is called.
+    #
+    #     root = RubyVM::AbstractSyntaxTree.parse("x = 1 + 2", keep_tokens: true)
+    #     root.all_tokens # => [[0, :tIDENTIFIER, "x", [1, 0, 1, 1]], [1, :tSP, " ", [1, 1, 1, 2]], ...]
+    #     root.children[-1].all_tokens # => [[0, :tIDENTIFIER, "x", [1, 0, 1, 1]], [1, :tSP, " ", [1, 1, 1, 2]], ...]
+    #
+    def all_tokens: () -> Array[[Integer, Symbol, String, [Integer, Integer, Integer, Integer]]]?
+
+    # <!--
+    #   rdoc-file=ast.rb
+    #   - node.children -> array
+    # -->
+    # Returns AST nodes under this one.  Each kind of node has different children,
+    # depending on what kind of node it is.
+    #
+    # The returned array may contain other nodes or `nil`.
+    #
+    def children: () -> Array[untyped]
+  end
+end

data/{stdlib/set/0 → core}/set.rbs

@@ -40,12 +40,8 @@
 #
 # ## What's Here
 # First, what's elsewhere. Class Set:
-# *   Inherits from [class
-#     Object](https://docs.ruby-lang.org/en/master/Object.html#class-Object-labe
-#     l-What-27s+Here).
-# *   Includes [module
-#      which provides dozens of additional
-#     g/en/master/Enumerable.html#module-Enumerable-label-What-27s+Here),
+# *   Inherits from [class Object](rdoc-ref:Object@What-27s+Here).
+# *   Includes [module Enumerable](rdoc-ref:Enumerable@What-27s+Here),
 #      which provides dozens of additional methods.
 #
 # In particular, class Set does not have many methods of its own
@@ -63,126 +59,126 @@
 # *   [And more....](#class-Set-label-Other+Methods)
 #
 # ### Methods for Creating a Set
-# *   ::[] -
+# *   ::[]:
 #  Returns a new set containing the given objects.
-# *   ::new -
+# *   ::new:
 #      Returns a new set containing either the given objects
 #      (if no block given) or the return values from the called block
 #      (if a block given).
 #
 # ### Methods for Set Operations
-# *   [|](#method-i-7C) (aliased as #union and #+) -
+# *   [|](#method-i-7C) (aliased as #union and #+):
 #      Returns a new set containing all elements from `self`
 #      and all elements from a given enumerable (no duplicates).
-# *   [&](#method-i-26) (aliased as #intersection) -
+# *   [&](#method-i-26) (aliased as #intersection):
 #      Returns a new set containing all elements common to `self`
 #      and a given enumerable.
-# *   [-](#method-i-2D) (aliased as #difference) -
+# *   [-](#method-i-2D) (aliased as #difference):
 #      Returns a copy of `self` with all elements
 #      in a given enumerable removed.
-# *   [\^](#method-i-5E) -
+# *   [\^](#method-i-5E):
 #      Returns a new set containing all elements from `self`
 #      and a given enumerable except those common to both.
 #
 # ### Methods for Comparing
-# *   [<=>](#method-i-3C-3D-3E) -
+# *   [<=>](#method-i-3C-3D-3E):
 #      Returns -1, 0, or 1 as `self` is less than, equal to,
 #      or greater than a given object.
-# *   [==](#method-i-3D-3D) -
+# *   [==](#method-i-3D-3D):
 #      Returns whether `self` and a given enumerable are equal,
 #      as determined by Object#eql?.
-# *   #compare_by_identity? -
+# *   #compare_by_identity?:
 #      Returns whether the set considers only identity
 #  when comparing elements.
 #
 # ### Methods for Querying
-# *   #length (aliased as #size) -
+# *   #length (aliased as #size):
 #  Returns the count of elements.
-# *   #empty? -
+# *   #empty?:
 #  Returns whether the set has no elements.
-# *   #include? (aliased as #member? and #===) -
+# *   #include? (aliased as #member? and #===):
 #      Returns whether a given object is an element in the set.
-# *   #subset? (aliased as [<=](#method-i-3C-3D)) -
+# *   #subset? (aliased as [<=](#method-i-3C-3D)):
 #      Returns whether a given object is a subset of the set.
-# *   #proper_subset? (aliased as [<](#method-i-3C)) -
+# *   #proper_subset? (aliased as [<](#method-i-3C)):
 #      Returns whether a given enumerable is a proper subset of the set.
-# *   #superset? (aliased as [<=](#method-i-3E-3D)]) -
+# *   #superset? (aliased as [>=](#method-i-3E-3D)]):
 #      Returns whether a given enumerable is a superset of the set.
-# *   #proper_superset? (aliased as [>](#method-i-3E)) -
+# *   #proper_superset? (aliased as [>](#method-i-3E)):
 #      Returns whether a given enumerable is a proper superset of the set.
-# *   #disjoint? -
+# *   #disjoint?:
 #      Returns `true` if the set and a given enumerable
 #      have no common elements, `false` otherwise.
-# *   #intersect? -
-#      Returns `true` if the set and a given enumerable -
+# *   #intersect?:
+#      Returns `true` if the set and a given enumerable:
 #      have any common elements, `false` otherwise.
-# *   #compare_by_identity? -
+# *   #compare_by_identity?:
 #      Returns whether the set considers only identity
 #  when comparing elements.
 #
 # ### Methods for Assigning
-# *   #add (aliased as #<<) -
+# *   #add (aliased as #<<):
 #  Adds a given object to the set; returns `self`.
-# *   #add? -
+# *   #add?:
 #      If the given object is not an element in the set,
 #      adds it and returns `self`; otherwise, returns `nil`.
-# *   #merge -
+# *   #merge:
 #  Adds each given object to the set; returns `self`.
-# *   #replace -
+# *   #replace:
 #      Replaces the contents of the set with the contents
 #      of a given enumerable.
 #
 # ### Methods for Deleting
-# *   #clear -
+# *   #clear:
 #  Removes all elements in the set; returns `self`.
-# *   #delete -
+# *   #delete:
 #  Removes a given object from the set; returns `self`.
-# *   #delete? -
+# *   #delete?:
 #      If the given object is an element in the set,
 #      removes it and returns `self`; otherwise, returns `nil`.
-# *   #subtract -
+# *   #subtract:
 #  Removes each given object from the set; returns `self`.
 # *   #delete_if - Removes elements specified by a given block.
-# *   #select! (aliased as #filter!) -
+# *   #select! (aliased as #filter!):
 #      Removes elements not specified by a given block.
-# *   #keep_if -
+# *   #keep_if:
 #  Removes elements not specified by a given block.
 # *   #reject!
 #  Removes elements specified by a given block.
 #
 # ### Methods for Converting
-# *   #classify -
+# *   #classify:
 #      Returns a hash that classifies the elements,
 #      as determined by the given block.
-# *   #collect! (aliased as #map!) -
+# *   #collect! (aliased as #map!):
 #      Replaces each element with a block return-value.
-# *   #divide -
+# *   #divide:
 #      Returns a hash that classifies the elements,
 #      as determined by the given block;
 #      differs from #classify in that the block may accept
 #      either one or two arguments.
-# *   #flatten -
+# *   #flatten:
 #      Returns a new set that is a recursive flattening of `self`.
-#      #flatten! -
+#      #flatten!:
 #      Replaces each nested set in `self` with the elements from that set.
-# *   #inspect (aliased as #to_s) -
+# *   #inspect (aliased as #to_s):
 #  Returns a string displaying the elements.
-# *   #join -
+# *   #join:
 #      Returns a string containing all elements, converted to strings
 #      as needed, and joined by the given record separator.
-# *   #to_a -
+# *   #to_a:
 #  Returns an array containing all set elements.
-# *   #to_set -
+# *   #to_set:
 #      Returns `self` if given no arguments and no block;
 #      with a block given, returns a new set consisting of block
 #  return values.
 #
 # ### Methods for Iterating
-# *   #each -
+# *   #each:
 #  Calls the block with each successive element; returns `self`.
 #
 # ### Other Methods
-# *   #reset -
+# *   #reset:
 #      Resets the internal state; useful if an object
 #      has been modified while an element in the set.
 #