1berry/ruby
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

[DOC] Document AST.parse's keyword arguments

Browse Source
This commit is contained in:
zverok 2022-12-22 23:29:44 +02:00 committed by Nobuyoshi Nakada
parent c3c116f6a6
commit 640dca9ae7
Notes: git 2022-12-24 01:52:47 +00:00 
Merged: https://github.com/ruby/ruby/pull/6996
1 changed files with 36 additions and 6 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

42
ast.rb
View File

@ -20,21 +20,47 @@
module RubyVM::AbstractSyntaxTree
# call-seq:
# RubyVM::AbstractSyntaxTree.parse(string) -> RubyVM::AbstractSyntaxTree::Node
# 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.
#
# SyntaxError is raised if the given _string_ is invalid syntax.
#
# RubyVM::AbstractSyntaxTree.parse("x = 1 + 2")
# # => #<RubyVM::AbstractSyntaxTree::Node:SCOPE@1:0-1:9>
#
# If <tt>keep_script_lines: true</tt> option is provided, the text of the parsed
# source is associated with nodes and is available via Node#script_lines.
#
# If <tt>keep_tokens: true</tt> option is provided, Node#tokens are populated.
#
# SyntaxError is raised if the given _string_ is invalid syntax. To overwrite this
# behavior, <tt>error_tolerant: true</tt> can be provided. In this case, the parser
# will produce a tree where expressions with syntax errors would be represented by
# Node with <tt>type=:ERROR</tt>.
#
# 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, keep_script_lines: false, error_tolerant: false, keep_tokens: false
Primitive.ast_s_parse string, keep_script_lines, error_tolerant, keep_tokens
end
# call-seq:
# RubyVM::AbstractSyntaxTree.parse_file(pathname) -> RubyVM::AbstractSyntaxTree::Node
# 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.
@ -44,13 +70,15 @@ module RubyVM::AbstractSyntaxTree
#
# 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 pathname, keep_script_lines: false, error_tolerant: false, keep_tokens: false
Primitive.ast_s_parse_file pathname, keep_script_lines, error_tolerant, keep_tokens
end
# call-seq:
# RubyVM::AbstractSyntaxTree.of(proc) -> RubyVM::AbstractSyntaxTree::Node
# RubyVM::AbstractSyntaxTree.of(method) -> RubyVM::AbstractSyntaxTree::Node
# 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_.
#
@ -63,6 +91,8 @@ module RubyVM::AbstractSyntaxTree
#
# 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 body, keep_script_lines: false, error_tolerant: false, keep_tokens: false
Primitive.ast_s_of body, keep_script_lines, error_tolerant, keep_tokens
end