diff --git a/refm/api/src/_builtin.rd b/refm/api/src/_builtin.rd index bd4fcff121..468fdd7150 100644 --- a/refm/api/src/_builtin.rd +++ b/refm/api/src/_builtin.rd @@ -102,6 +102,8 @@ require を書かなくても使うことができます。 #@include(_builtin/RubyVM__InstructionSequence) #@since 2.6.0 #@include(_builtin/RubyVM__MJIT) +#@include(_builtin/RubyVM__AbstractSyntaxTree) +#@include(_builtin/RubyVM__AbstractSyntaxTree__Node) #@end #@include(_builtin/RuntimeError) #@include(_builtin/ScriptError) diff --git a/refm/api/src/_builtin/RubyVM__AbstractSyntaxTree b/refm/api/src/_builtin/RubyVM__AbstractSyntaxTree new file mode 100644 index 0000000000..83ea95c71a --- /dev/null +++ b/refm/api/src/_builtin/RubyVM__AbstractSyntaxTree @@ -0,0 +1,100 @@ += module RubyVM::AbstractSyntaxTree + +Ruby のコードをパースして得られる抽象構文木を扱うモジュールです。 + +抽象構文木は[[c:RubyVM::AbstractSyntaxTree::Node]]クラスのインスタンスとして表されます。 + + +このモジュールはMRIの抽象構文木の実装の詳細を表します。 + +このモジュールは実験的であり、安定したAPIではないため、 +予告なしに変更される可能性があります。 +例えば、子要素の順序は保証されておらず、 +子要素の数は変更される可能性があります。 +また子要素に名前でアクセスする方法は提供されていません。 + +もし安定したAPIやMRI以外の実装で抽象構文木を扱いたい場合、 +parser gem ([[url:https://github.com/whitequark/parser]])や +[[c:Ripper]]の使用を検討してください。 +もし RubyVM::AbstractSyntaxTree のAPIを安定にしたい場合、[[feature:14844]] での議論に参加してください。 + +== Singleton Methods + +--- of(proc) -> RubyVM::AbstractSyntaxTree::Node + +引数 proc に渡したProcやメソッドオブジェクトの抽象構文木を返します。 + +このメソッドはProcやメソッドが定義されたファイルを読み込む必要があるため、 +irbのようなファイルを介さない対話的環境では動作しません。 + +@param proc Procもしくはメソッドオブジェクトを指定します。 + +#@samplecode +pp RubyVM::AbstractSyntaxTree.of(proc {1 + 2}) +# => (SCOPE@2:38-2:45 +# tbl: [] +# args: nil +# body: +# (OPCALL@2:39-2:44 (LIT@2:39-2:40 1) :+ +# (LIST@2:43-2:44 (LIT@2:43-2:44 2) nil))) + +def hello + puts "hello, world" +end + +pp RubyVM::AbstractSyntaxTree.of(method(:hello)) +# => (SCOPE@5:0-7:3 +# tbl: [] +# args: +# (ARGS@5:9-5:9 +# pre_num: 0 +# pre_init: nil +# opt: nil +# first_post: nil +# post_num: 0 +# post_init: nil +# rest: nil +# kw: nil +# kwrest: nil +# block: nil) +# body: +# (FCALL@6:2-6:21 :puts (LIST@6:7-6:21 (STR@6:7-6:21 "hello, world") nil))) +#@end + + +--- parse(string) -> RubyVM::AbstractSyntaxTree::Node + +文字列を抽象構文木にパースし、その木の根ノードを返します。 + +@param string パースする対象の Ruby のコードを文字列で指定します。 +@raise SyntaxError string が Ruby のコードとして正しくない場合に発生します。 + +#@samplecode +pp RubyVM::AbstractSyntaxTree.parse("x = 1 + 2") +# => (SCOPE@1:0-1:9 +# tbl: [:x] +# args: nil +# body: +# (LASGN@1:0-1:9 :x +# (OPCALL@1:4-1:9 (LIT@1:4-1:5 1) :+ (LIST@1:8-1:9 (LIT@1:8-1:9 2) nil)))) +#@end + +--- parse_file(pathname) -> RubyVM::AbstractSyntaxTree::Node + +pathname のファイルを読み込み、その内容を抽象構文木にパースし、その木の根ノードを返します。 + +@param pathname パースする対象のファイルパスを指定します +@raise SyntaxError string が Ruby のコードとして正しくない場合に発生します。 + +#@samplecode +pp RubyVM::AbstractSyntaxTree.parse_file(__FILE__) +# => (SCOPE@1:0-1:50 +# tbl: [] +# args: nil +# body: +# (FCALL@1:0-1:50 :pp +# (LIST@1:3-1:50 +# (CALL@1:3-1:50 +# (COLON2@1:3-1:29 (CONST@1:3-1:9 :RubyVM) :AbstractSyntaxTree) +# :parse_file (LIST@1:41-1:49 (STR@1:41-1:49 "") nil)) nil))) +#@end diff --git a/refm/api/src/_builtin/RubyVM__AbstractSyntaxTree__Node b/refm/api/src/_builtin/RubyVM__AbstractSyntaxTree__Node new file mode 100644 index 0000000000..5a122616c3 --- /dev/null +++ b/refm/api/src/_builtin/RubyVM__AbstractSyntaxTree__Node @@ -0,0 +1,84 @@ += class RubyVM::AbstractSyntaxTree::Node + +[[m:RubyVM::AbstractSyntaxTree.parse]] によって作られる抽象構文木を表すクラスです。 + +このクラスは MRI の実装の詳細を表します。 + +== Instance Methods + +--- children -> Array + +self の子ノードを配列で返します。 + +どのような子ノードが返ってくるかは、そのノードの type によって異なります。 + +戻り値は、ほかの RubyVM::AbstractSyntaxTree::Node のインスタンスや nil を含みます。 + +#@samplecode +node = RubyVM::AbstractSyntaxTree.parse('1 + 2') +p node.children +# => [[], nil, #] +#@end + +--- first_column -> Integer + +ソースコード中で、self を表すテキストが最初に現れる列番号を返します。 + +列番号は0-originで、バイト単位で表されます。 + +#@samplecode +node = RubyVM::AbstractSyntaxTree.parse('1 + 2') +p node.first_column # => 0 +#@end + +--- first_lineno -> Integer + +ソースコード中で、self を表すテキストが最初に現れる行番号を返します。 + +行番号は1-originです。 + +#@samplecode +node = RubyVM::AbstractSyntaxTree.parse('1 + 2') +p node.first_lineno # => 1 +#@end + +--- inspect -> String + +self のデバッグ用の情報を含んだ文字列を返します。 + +#@samplecode +node = RubyVM::AbstractSyntaxTree.parse('1 + 1') +puts node.inspect +# => # +#@end + +--- last_column -> Integer + +ソースコード中で、self を表すテキストが最後に現れる列番号を返します。 + +列番号は0-originで、バイト単位で表されます。 + +#@samplecode +node = RubyVM::AbstractSyntaxTree.parse('1 + 1') +p node.last_column # => 5 +#@end + +--- last_lineno -> Integer + +ソースコード中で、self を表すテキストが最後に現れる行番号を返します。 + +行番号は1-originです。 + +#@samplecode +node = RubyVM::AbstractSyntaxTree.parse('1 + 1') +p node.last_lineno # => 1 +#@end + +--- type -> Symbol + +self の種類を Symbol で返します。 + +#@samplecode +node = RubyVM::AbstractSyntaxTree.parse('1 + 1') +p node.type # => :SCOPE +#@end