ruby/ast.rb

191 строка
5.8 KiB
Ruby
Исходник Обычный вид История

2019-11-08 03:30:11 +03:00
# for ast.c
2021-06-06 17:02:06 +03:00
# 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
2019-11-08 03:30:11 +03:00
2021-06-06 17:02:06 +03:00
# call-seq:
# RubyVM::AbstractSyntaxTree.parse(string) -> RubyVM::AbstractSyntaxTree::Node
2019-11-08 03:30:11 +03:00
#
2021-06-06 17:02:06 +03:00
# Parses the given _string_ into an abstract syntax tree,
# returning the root node of that tree.
2019-11-08 03:30:11 +03:00
#
2021-06-06 17:02:06 +03:00
# SyntaxError is raised if the given _string_ is invalid syntax.
#
2021-06-06 17:02:06 +03:00
# RubyVM::AbstractSyntaxTree.parse("x = 1 + 2")
# # => #<RubyVM::AbstractSyntaxTree::Node:SCOPE@1:0-1:9>
def self.parse string, save_script_lines: false
Primitive.ast_s_parse string, save_script_lines
2021-06-06 17:02:06 +03:00
end
# call-seq:
# RubyVM::AbstractSyntaxTree.parse_file(pathname) -> RubyVM::AbstractSyntaxTree::Node
#
# Reads the file from _pathname_, then parses it like ::parse,
# returning the root node of the abstract syntax tree.
#
2021-06-06 17:02:06 +03:00
# 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>
def self.parse_file pathname, save_script_lines: false
Primitive.ast_s_parse_file pathname, save_script_lines
2021-06-06 17:02:06 +03:00
end
# call-seq:
# RubyVM::AbstractSyntaxTree.of(proc) -> RubyVM::AbstractSyntaxTree::Node
# RubyVM::AbstractSyntaxTree.of(method) -> 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>
def self.of body, save_script_lines: false
Primitive.ast_s_of body, save_script_lines
2021-06-06 17:02:06 +03:00
end
# RubyVM::AbstractSyntaxTree::Node instances are created by parse methods in
# RubyVM::AbstractSyntaxTree.
#
# This class is MRI specific.
#
class Node
2019-11-08 03:30:11 +03:00
# call-seq:
2021-06-06 17:02:06 +03:00
# node.type -> symbol
2019-11-08 03:30:11 +03:00
#
2021-06-06 17:02:06 +03:00
# Returns the type of this node as a symbol.
2019-11-08 03:30:11 +03:00
#
2021-06-06 17:02:06 +03:00
# 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
Primitive.ast_node_type
2019-11-08 03:30:11 +03:00
end
# call-seq:
2021-06-06 17:02:06 +03:00
# node.first_lineno -> integer
2019-11-08 03:30:11 +03:00
#
2021-06-06 17:02:06 +03:00
# The line number in the source code where this AST's text began.
def first_lineno
Primitive.ast_node_first_lineno
2019-11-08 03:30:11 +03:00
end
# call-seq:
2021-06-06 17:02:06 +03:00
# node.first_column -> integer
2019-11-08 03:30:11 +03:00
#
2021-06-06 17:02:06 +03:00
# The column number in the source code where this AST's text began.
def first_column
Primitive.ast_node_first_column
end
# call-seq:
# node.last_lineno -> integer
2019-11-08 03:30:11 +03:00
#
2021-06-06 17:02:06 +03:00
# The line number in the source code where this AST's text ended.
def last_lineno
Primitive.ast_node_last_lineno
end
# call-seq:
# node.last_column -> integer
2019-11-08 03:30:11 +03:00
#
2021-06-06 17:02:06 +03:00
# The column number in the source code where this AST's text ended.
def last_column
Primitive.ast_node_last_column
2019-11-08 03:30:11 +03:00
end
2021-06-06 17:02:06 +03:00
# call-seq:
# node.children -> array
2019-11-08 03:30:11 +03:00
#
2021-06-06 17:02:06 +03:00
# Returns AST nodes under this one. Each kind of node
# has different children, depending on what kind of node it is.
2019-11-08 03:30:11 +03:00
#
2021-06-06 17:02:06 +03:00
# The returned array may contain other nodes or <code>nil</code>.
def children
Primitive.ast_node_children
end
2019-11-08 03:30:11 +03:00
2021-06-06 17:02:06 +03:00
# call-seq:
# node.inspect -> string
#
# Returns debugging information about this node as a string.
def inspect
Primitive.ast_node_inspect
2019-11-08 03:30:11 +03:00
end
# call-seq:
# node.node_id -> integer
#
# Returns an internal node_id number.
# Note that this is an API for ruby internal use, debugging,
# and research. Do not use this for any other purpose.
# The compatibility is not guaranteed.
def node_id
Primitive.ast_node_node_id
end
# call-seq:
# node.script_lines -> array
#
# Returns the original source code as an array of lines.
#
# Note that this is an API for ruby internal use, debugging,
# and research. Do not use this for any other purpose.
# The compatibility is not guaranteed.
def script_lines
Primitive.ast_node_script_lines
end
# call-seq:
# node.source -> string
#
# Returns the code fragment that corresponds to this AST.
#
# Note that this is an API for ruby internal use, debugging,
# and research. Do not use this for any other purpose.
# The compatibility is not guaranteed.
#
# Also note that this API may return an incomplete code fragment
# that does not parse; for example, a here document following
# an expression may be dropped.
def source
lines = script_lines
if lines
lines = lines[first_lineno - 1 .. last_lineno - 1]
lines[-1] = lines[-1][0...last_column]
lines[0] = lines[0][first_column..-1]
lines.join
else
nil
end
end
2019-11-08 03:30:11 +03:00
end
end