module RubyVM::AbstractSyntaxTree
AbstractSyntaxTree provides methods to parse Ruby code into abstract syntax trees. The nodes in the tree are instances ofRubyVM::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 theprism gem, which is the official Ruby API to parse Ruby code.
Public Class Methods
Source
# File ast.rb, line 110defself.node_id_for_backtrace_locationbacktrace_locationPrimitive.node_id_for_backtrace_locationbacktrace_locationend
Returns the node id for the given backtrace location.
beginraiserescue=>eloc =e.backtrace_locations.firstRubyVM::AbstractSyntaxTree.node_id_for_backtrace_location(loc)end# => 0
Source
# File ast.rb, line 95defself.ofbody,keep_script_lines:RubyVM.keep_script_lines,error_tolerant:false,keep_tokens:falsePrimitive.ast_s_ofbody,keep_script_lines,error_tolerant,keep_tokensend
Returns AST nodes of the givenproc ormethod.
RubyVM::AbstractSyntaxTree.of(proc {1+2})# => #<RubyVM::AbstractSyntaxTree::Node:SCOPE@1:35-1:42>defhelloputs"hello, world"endRubyVM::AbstractSyntaxTree.of(method(:hello))# => #<RubyVM::AbstractSyntaxTree::Node:SCOPE@1:0-3:3>
See::parse for explanation of keyword argument meaning and usage.
Source
# File ast.rb, line 57defself.parsestring,keep_script_lines:RubyVM.keep_script_lines,error_tolerant:false,keep_tokens:falsePrimitive.ast_s_parsestring,keep_script_lines,error_tolerant,keep_tokensend
Parses the givenstring 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>
Ifkeep_script_lines: true option is provided, the text of the parsed source is associated with nodes and is available viaNode#script_lines.
Ifkeep_tokens: true option is provided,Node#tokens are populated.
SyntaxError is raised if the givenstring 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 byNode withtype=: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 expression.
Source
# File ast.rb, line 74defself.parse_filepathname,keep_script_lines:RubyVM.keep_script_lines,error_tolerant:false,keep_tokens:falsePrimitive.ast_s_parse_filepathname,keep_script_lines,error_tolerant,keep_tokensend
Reads the file frompathname, then parses it like::parse, returning the root node of the abstract syntax tree.
SyntaxError is raised ifpathname’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.