sorbet/rbi/gems/ast@2.4.2.rbi
# typed: true
# DO NOT EDIT MANUALLY
# This is an autogenerated file for types exported from the `ast` gem.
# Please instead update this file by running `bin/tapioca gem ast`.
# {AST} is a library for manipulating abstract syntax trees.
#
# It embraces immutability; each AST node is inherently frozen at
# creation, and updating a child node requires recreating that node
# and its every parent, recursively.
# This is a design choice. It does create some pressure on
# garbage collector, but completely eliminates all concurrency
# and aliasing problems.
#
# See also {AST::Node}, {AST::Processor::Mixin} and {AST::Sexp} for
# additional recommendations and design patterns.
#
# source://ast//lib/ast.rb#13
module AST; end
# Node is an immutable class, instances of which represent abstract
# syntax tree nodes. It combines semantic information (i.e. anything
# that affects the algorithmic properties of a program) with
# meta-information (line numbers or compiler intermediates).
#
# Notes on inheritance
# ====================
#
# The distinction between semantics and metadata is important. Complete
# semantic information should be contained within just the {#type} and
# {#children} of a Node instance; in other words, if an AST was to be
# stripped of all meta-information, it should remain a valid AST which
# could be successfully processed to yield a result with the same
# algorithmic properties.
#
# Thus, Node should never be inherited in order to define methods which
# affect or return semantic information, such as getters for `class_name`,
# `superclass` and `body` in the case of a hypothetical `ClassNode`. The
# correct solution is to use a generic Node with a {#type} of `:class`
# and three children. See also {Processor} for tips on working with such
# ASTs.
#
# On the other hand, Node can and should be inherited to define
# application-specific metadata (see also {#initialize}) or customize the
# printing format. It is expected that an application would have one or two
# such classes and use them across the entire codebase.
#
# The rationale for this pattern is extensibility and maintainability.
# Unlike static ones, dynamic languages do not require the presence of a
# predefined, rigid structure, nor does it improve dispatch efficiency,
# and while such a structure can certainly be defined, it does not add
# any value but incurs a maintaining cost.
# For example, extending the AST even with a transformation-local
# temporary node type requires making globally visible changes to
# the codebase.
#
# source://ast//lib/ast/node.rb#40
class AST::Node
# Constructs a new instance of Node.
#
# The arguments `type` and `children` are converted with `to_sym` and
# `to_a` respectively. Additionally, the result of converting `children`
# is frozen. While mutating the arguments is generally considered harmful,
# the most common case is to pass an array literal to the constructor. If
# your code does not expect the argument to be frozen, use `#dup`.
#
# The `properties` hash is passed to {#assign_properties}.
#
# @return [Node] a new instance of Node
#
# source://ast//lib/ast/node.rb#72
def initialize(type, children = T.unsafe(nil), properties = T.unsafe(nil)); end
# Concatenates `array` with `children` and returns the resulting node.
#
# @return [AST::Node]
#
# source://ast//lib/ast/node.rb#168
def +(array); end
# Appends `element` to `children` and returns the resulting node.
#
# @return [AST::Node]
#
# source://ast//lib/ast/node.rb#177
def <<(element); end
# Compares `self` to `other`, possibly converting with `to_ast`. Only
# `type` and `children` are compared; metadata is deliberately ignored.
#
# @return [Boolean]
#
# source://ast//lib/ast/node.rb#153
def ==(other); end
# Appends `element` to `children` and returns the resulting node.
#
# @return [AST::Node]
#
# source://ast//lib/ast/node.rb#177
def append(element); end
# Returns the children of this node.
# The returned value is frozen.
# The to_a alias is useful for decomposing nodes concisely.
# For example:
#
# node = s(:gasgn, :$foo, s(:integer, 1))
# var_name, value = *node
# p var_name # => :$foo
# p value # => (integer 1)
#
# @return [Array]
#
# source://ast//lib/ast/node.rb#56
def children; end
# Nodes are already frozen, so there is no harm in returning the
# current node as opposed to initializing from scratch and freezing
# another one.
#
# @return self
#
# source://ast//lib/ast/node.rb#115
def clone; end
# Concatenates `array` with `children` and returns the resulting node.
#
# @return [AST::Node]
#
# source://ast//lib/ast/node.rb#168
def concat(array); end
# Enables matching for Node, where type is the first element
# and the children are remaining items.
#
# @return [Array]
#
# source://ast//lib/ast/node.rb#253
def deconstruct; end
# Nodes are already frozen, so there is no harm in returning the
# current node as opposed to initializing from scratch and freezing
# another one.
#
# @return self
#
# source://ast//lib/ast/node.rb#115
def dup; end
# Test if other object is equal to
#
# @param other [Object]
# @return [Boolean]
#
# source://ast//lib/ast/node.rb#85
def eql?(other); end
# Returns the precomputed hash value for this node
#
# @return [Fixnum]
#
# source://ast//lib/ast/node.rb#61
def hash; end
# Converts `self` to a s-expression ruby string.
# The code return will recreate the node, using the sexp module s()
#
# @param indent [Integer] Base indentation level.
# @return [String]
#
# source://ast//lib/ast/node.rb#211
def inspect(indent = T.unsafe(nil)); end
# Returns the children of this node.
# The returned value is frozen.
# The to_a alias is useful for decomposing nodes concisely.
# For example:
#
# node = s(:gasgn, :$foo, s(:integer, 1))
# var_name, value = *node
# p var_name # => :$foo
# p value # => (integer 1)
#
# @return [Array]
#
# source://ast//lib/ast/node.rb#56
def to_a; end
# @return [AST::Node] self
#
# source://ast//lib/ast/node.rb#229
def to_ast; end
# Converts `self` to a pretty-printed s-expression.
#
# @param indent [Integer] Base indentation level.
# @return [String]
#
# source://ast//lib/ast/node.rb#187
def to_s(indent = T.unsafe(nil)); end
# Converts `self` to a pretty-printed s-expression.
#
# @param indent [Integer] Base indentation level.
# @return [String]
#
# source://ast//lib/ast/node.rb#187
def to_sexp(indent = T.unsafe(nil)); end
# Converts `self` to an Array where the first element is the type as a Symbol,
# and subsequent elements are the same representation of its children.
#
# @return [Array<Symbol, [...Array]>]
#
# source://ast//lib/ast/node.rb#237
def to_sexp_array; end
# Returns the type of this node.
#
# @return [Symbol]
#
# source://ast//lib/ast/node.rb#43
def type; end
# Returns a new instance of Node where non-nil arguments replace the
# corresponding fields of `self`.
#
# For example, `Node.new(:foo, [ 1, 2 ]).updated(:bar)` would yield
# `(bar 1 2)`, and `Node.new(:foo, [ 1, 2 ]).updated(nil, [])` would
# yield `(foo)`.
#
# If the resulting node would be identical to `self`, does nothing.
#
# @param type [Symbol, nil]
# @param children [Array, nil]
# @param properties [Hash, nil]
# @return [AST::Node]
#
# source://ast//lib/ast/node.rb#133
def updated(type = T.unsafe(nil), children = T.unsafe(nil), properties = T.unsafe(nil)); end
protected
# By default, each entry in the `properties` hash is assigned to
# an instance variable in this instance of Node. A subclass should define
# attribute readers for such variables. The values passed in the hash
# are not frozen or whitelisted; such behavior can also be implemented
# by subclassing Node and overriding this method.
#
# @return [nil]
#
# source://ast//lib/ast/node.rb#98
def assign_properties(properties); end
# Returns `@type` with all underscores replaced by dashes. This allows
# to write symbol literals without quotes in Ruby sources and yet have
# nicely looking s-expressions.
#
# @return [String]
#
# source://ast//lib/ast/node.rb#264
def fancy_type; end
private
def original_dup; end
end
# This class includes {AST::Processor::Mixin}; however, it is
# deprecated, since the module defines all of the behaviors that
# the processor includes. Any new libraries should use
# {AST::Processor::Mixin} instead of subclassing this.
#
# @deprecated Use {AST::Processor::Mixin} instead.
#
# source://ast//lib/ast/processor.rb#8
class AST::Processor
include ::AST::Processor::Mixin
end
# The processor module is a module which helps transforming one
# AST into another. In a nutshell, the {#process} method accepts
# a {Node} and dispatches it to a handler corresponding to its
# type, and returns a (possibly) updated variant of the node.
#
# The processor module has a set of associated design patterns.
# They are best explained with a concrete example. Let's define a
# simple arithmetic language and an AST format for it:
#
# Terminals (AST nodes which do not have other AST nodes inside):
#
# * `(integer <int-literal>)`,
#
# Nonterminals (AST nodes with other nodes as children):
#
# * `(add <node> <node>)`,
# * `(multiply <node> <node>)`,
# * `(divide <node> <node>)`,
# * `(negate <node>)`,
# * `(store <node> <string-literal>)`: stores value of `<node>`
# into a variable named `<string-literal>`,
# * `(load <string-literal>)`: loads value of a variable named
# `<string-literal>`,
# * `(each <node> ...)`: computes each of the `<node>`s and
# prints the result.
#
# All AST nodes have the same Ruby class, and therefore they don't
# know how to traverse themselves. (A solution which dynamically
# checks the type of children is possible, but is slow and
# error-prone.) So, a class including the module which knows how
# to traverse the entire tree should be defined. Such classes
# have a handler for each nonterminal node which recursively
# processes children nodes:
#
# require 'ast'
#
# class ArithmeticsProcessor
# include AST::Processor::Mixin
# # This method traverses any binary operators such as (add)
# # or (multiply).
# def process_binary_op(node)
# # Children aren't decomposed automatically; it is
# # suggested to use Ruby multiple assignment expansion,
# # as it is very convenient here.
# left_expr, right_expr = *node
#
# # AST::Node#updated won't change node type if nil is
# # passed as a first argument, which allows to reuse the
# # same handler for multiple node types using `alias'
# # (below).
# node.updated(nil, [
# process(left_expr),
# process(right_expr)
# ])
# end
# alias_method :on_add, :process_binary_op
# alias_method :on_multiply, :process_binary_op
# alias_method :on_divide, :process_binary_op
#
# def on_negate(node)
# # It is also possible to use #process_all for more
# # compact code if every child is a Node.
# node.updated(nil, process_all(node))
# end
#
# def on_store(node)
# expr, variable_name = *node
#
# # Note that variable_name is not a Node and thus isn't
# # passed to #process.
# node.updated(nil, [
# process(expr),
# variable_name
# ])
# end
#
# # (load) is effectively a terminal node, and so it does
# # not need an explicit handler, as the following is the
# # default behavior. Essentially, for any nodes that don't
# # have a defined handler, the node remains unchanged.
# def on_load(node)
# nil
# end
#
# def on_each(node)
# node.updated(nil, process_all(node))
# end
# end
#
# Let's test our ArithmeticsProcessor:
#
# include AST::Sexp
# expr = s(:add, s(:integer, 2), s(:integer, 2))
#
# p ArithmeticsProcessor.new.process(expr) == expr # => true
#
# As expected, it does not change anything at all. This isn't
# actually very useful, so let's now define a Calculator, which
# will compute the expression values:
#
# # This Processor folds nonterminal nodes and returns an
# # (integer) terminal node.
# class ArithmeticsCalculator < ArithmeticsProcessor
# def compute_op(node)
# # First, node children are processed and then unpacked
# # to local variables.
# nodes = process_all(node)
#
# if nodes.all? { |node| node.type == :integer }
# # If each of those nodes represents a literal, we can
# # fold this node!
# values = nodes.map { |node| node.children.first }
# AST::Node.new(:integer, [
# yield(values)
# ])
# else
# # Otherwise, we can just leave the current node in the
# # tree and only update it with processed children
# # nodes, which can be partially folded.
# node.updated(nil, nodes)
# end
# end
#
# def on_add(node)
# compute_op(node) { |left, right| left + right }
# end
#
# def on_multiply(node)
# compute_op(node) { |left, right| left * right }
# end
# end
#
# Let's check:
#
# p ArithmeticsCalculator.new.process(expr) # => (integer 4)
#
# Excellent, the calculator works! Now, a careful reader could
# notice that the ArithmeticsCalculator does not know how to
# divide numbers. What if we pass an expression with division to
# it?
#
# expr_with_division = \
# s(:add,
# s(:integer, 1),
# s(:divide,
# s(:add, s(:integer, 8), s(:integer, 4)),
# s(:integer, 3))) # 1 + (8 + 4) / 3
#
# folded_expr_with_division = ArithmeticsCalculator.new.process(expr_with_division)
# p folded_expr_with_division
# # => (add
# # (integer 1)
# # (divide
# # (integer 12)
# # (integer 3)))
#
# As you can see, the expression was folded _partially_: the inner
# `(add)` node which could be computed was folded to
# `(integer 12)`, the `(divide)` node is left as-is because there
# is no computing handler for it, and the root `(add)` node was
# also left as it is because some of its children were not
# literals.
#
# Note that this partial folding is only possible because the
# _data_ format, i.e. the format in which the computed values of
# the nodes are represented, is the same as the AST itself.
#
# Let's extend our ArithmeticsCalculator class further.
#
# class ArithmeticsCalculator
# def on_divide(node)
# compute_op(node) { |left, right| left / right }
# end
#
# def on_negate(node)
# # Note how #compute_op works regardless of the operator
# # arity.
# compute_op(node) { |value| -value }
# end
# end
#
# Now, let's apply our renewed ArithmeticsCalculator to a partial
# result of previous evaluation:
#
# p ArithmeticsCalculator.new.process(expr_with_division) # => (integer 5)
#
# Five! Excellent. This is also pretty much how CRuby 1.8 executed
# its programs.
#
# Now, let's do some automated bug searching. Division by zero is
# an error, right? So if we could detect that someone has divided
# by zero before the program is even run, that could save some
# debugging time.
#
# class DivisionByZeroVerifier < ArithmeticsProcessor
# class VerificationFailure < Exception; end
#
# def on_divide(node)
# # You need to process the children to handle nested divisions
# # such as:
# # (divide
# # (integer 1)
# # (divide (integer 1) (integer 0))
# left, right = process_all(node)
#
# if right.type == :integer &&
# right.children.first == 0
# raise VerificationFailure, "Ouch! This code divides by zero."
# end
# end
#
# def divides_by_zero?(ast)
# process(ast)
# false
# rescue VerificationFailure
# true
# end
# end
#
# nice_expr = \
# s(:divide,
# s(:add, s(:integer, 10), s(:integer, 2)),
# s(:integer, 4))
#
# p DivisionByZeroVerifier.new.divides_by_zero?(nice_expr)
# # => false. Good.
#
# bad_expr = \
# s(:add, s(:integer, 10),
# s(:divide, s(:integer, 1), s(:integer, 0)))
#
# p DivisionByZeroVerifier.new.divides_by_zero?(bad_expr)
# # => true. WHOOPS. DO NOT RUN THIS.
#
# Of course, this won't detect more complex cases... unless you
# use some partial evaluation before! The possibilites are
# endless. Have fun.
#
# source://ast//lib/ast/processor/mixin.rb#240
module AST::Processor::Mixin
# Default handler. Does nothing.
#
# @param node [AST::Node]
# @return [AST::Node, nil]
#
# source://ast//lib/ast/processor/mixin.rb#284
def handler_missing(node); end
# Dispatches `node`. If a node has type `:foo`, then a handler
# named `on_foo` is invoked with one argument, the `node`; if
# there isn't such a handler, {#handler_missing} is invoked
# with the same argument.
#
# If the handler returns `nil`, `node` is returned; otherwise,
# the return value of the handler is passed along.
#
# @param node [AST::Node, nil]
# @return [AST::Node, nil]
#
# source://ast//lib/ast/processor/mixin.rb#251
def process(node); end
# {#process}es each node from `nodes` and returns an array of
# results.
#
# @param nodes [Array<AST::Node>]
# @return [Array<AST::Node>]
#
# source://ast//lib/ast/processor/mixin.rb#274
def process_all(nodes); end
end
# This simple module is very useful in the cases where one needs
# to define deeply nested ASTs from Ruby code, for example, in
# tests. It should be used like this:
#
# describe YourLanguage::AST do
# include Sexp
#
# it "should correctly parse expressions" do
# YourLanguage.parse("1 + 2 * 3").should ==
# s(:add,
# s(:integer, 1),
# s(:multiply,
# s(:integer, 2),
# s(:integer, 3)))
# end
# end
#
# This way the amount of boilerplate code is greatly reduced.
#
# source://ast//lib/ast/sexp.rb#20
module AST::Sexp
# Creates a {Node} with type `type` and children `children`.
# Note that the resulting node is of the type AST::Node and not a
# subclass.
# This would not pose a problem with comparisons, as {Node#==}
# ignores metadata.
#
# source://ast//lib/ast/sexp.rb#26
def s(type, *children); end
end