module Prism (Ruby 4.0 リファレンスマニュアル)

要約

Ruby プログラムの構文解析・字句解析を行うためのモジュール関数を提供するモジュールです。文字列を直接解析する Prism?.parse や Prism?.lex の他、ファイルを指定して解析する Prism?.parse_file などが用意されています。

解析結果は多くの場合 Prism::ParseResult のインスタンスとして返されます。詳細は Prism::ParseResult を参照してください。

モジュール関数

dump(source, **options) -> StringRuby 3.3 から[permalink][rdoc][edit]

source を構文解析した結果を prism 独自のバイナリ形式にシリアライズし、その文字列を返します。この形式は主に、CRuby の拡張ライブラリを経由せずに、他言語(JavaScript、Rust、Java など)の実装から prism の構文木を読み込むために使われます。エンコーディングは常に ASCII-8BIT (BINARY) になります。オプションは Prism?.parse と同じです。

[PARAM] source:: 解析する Ruby プログラムの文字列を指定します。
[PARAM] options:: Prism?.parse を参照してください。

例

require "prism"

dumped = Prism.dump("1 + 2")
p dumped.class     # => String
p dumped.encoding  # => #<Encoding:BINARY (ASCII-8BIT)>

dump_file(filepath, **options) -> StringRuby 3.3 から[permalink][rdoc][edit]

filepath で指定したファイルを構文解析し、Prism?.dump と同様にシリアライズした文字列を返します。オプションは Prism?.parse と同じです。

[PARAM] filepath:: 解析する Ruby プログラムのファイルパスを指定します。
[PARAM] options:: Prism?.parse を参照してください。

例

require "prism"

File.write("sample.rb", "def foo(a, b) = a + b\n")

p Prism.dump_file("sample.rb").class # => String

[SEE_ALSO] Prism?.dump

lex(source, **options) -> Prism::LexResultRuby 3.3 から[permalink][rdoc][edit]

source を字句解析し、Prism::LexResult のインスタンスを返します。 value は [トークン, 直前からの字句解析器の状態(Integer)] という 2 要素配列の配列です。これは Ripper の Ripper.lex の戻り値の形式に近いものになっています。オプションは Prism?.parse と同じです。

[PARAM] source:: 解析する Ruby プログラムの文字列を指定します。
[PARAM] options:: Prism?.parse を参照してください。

例

require "prism"

result = Prism.lex("1 + 2")
p result.class   # => Prism::LexResult
result.value.each { |token, state| p [token.type, token.value, state] }
# => [:INTEGER, "1", 2]
# => [:PLUS, "+", 1]
# => [:INTEGER, "2", 2]
# => [:EOF, "", 2]

[SEE_ALSO] Prism?.parse, Ripper

lex_file(filepath, **options) -> Prism::LexResultRuby 3.3 から[permalink][rdoc][edit]

filepath で指定したファイルを字句解析します。戻り値の形式は Prism?.lex と同じです。オプションは Prism?.parse と同じです。

[PARAM] filepath:: 解析する Ruby プログラムのファイルパスを指定します。
[PARAM] options:: Prism?.parse を参照してください。

例

require "prism"

File.write("sample.rb", "def foo(a, b) = a + b\n")

result = Prism.lex_file("sample.rb")
p result.class
# => Prism::LexResult
p result.value.map { |token, _state| token.type }
# => [:KEYWORD_DEF, :IDENTIFIER, :PARENTHESIS_LEFT, :IDENTIFIER, :COMMA,
#     :IDENTIFIER, :PARENTHESIS_RIGHT, :EQUAL, :IDENTIFIER, :PLUS,
#     :IDENTIFIER, :NEWLINE, :EOF]

[SEE_ALSO] Prism?.lex

parse(source, **options) -> Prism::ParseResultRuby 3.3 から[permalink][rdoc][edit]

Ruby プログラムのソースコード文字列 source を構文解析し、結果を Prism::ParseResult として返します。

prism はエラー耐性のあるパーサなので、構文エラーがあっても可能な限り解析を継続し、部分的な構文木を Prism::ParseResult#value に格納します。エラーの有無は Prism::ParseResult#success? や Prism::ParseResult#errors で確認できます。

[PARAM] source:: 解析する Ruby プログラムの文字列を指定します。
[PARAM] options:: 解析オプションをキーワード引数で指定します。主なものは以下の通りです。

:filepath: ソースコードのファイルパスを指定します(エラーメッセージなどに使われます)。
:line: 解析を開始する行番号(1 始まり)を指定します。
:encoding: ソースコードのエンコーディングを指定します。
:scopes: ソースコードの周囲で定義済みのローカル変数を、シンボルの配列の配列で指定します。eval のように周囲のローカル変数を引き継いで解析したい場合に使います。
:version: 解析に使う Ruby の構文バージョンを文字列(例 "3.3.0")で指定します。省略時は最新の構文として解析します。

上記以外にも :command_line, :frozen_string_literal, :main_script, :partial_script などのオプションがあります。利用可能なオプションの完全な一覧は prism のバージョンによって多少異なるため、公式ドキュメントを参照してください。

例

require "prism"

result = Prism.parse("1 + 2")
p result.class          # => Prism::ParseResult
p result.value.class    # => Prism::ProgramNode
p result.success?       # => true

例: 構文エラーがあっても解析を継続する

require "prism"

result = Prism.parse('"unterminated')
p result.success?              # => false
p result.errors.size           # => 1
p result.errors.first.message  # => "unterminated string meets end of file"
p result.value.class           # => Prism::ProgramNode (エラーがあっても構文木は返る)

[SEE_ALSO] Prism::ParseResult

parse_comments(source, **options) -> ArrayRuby 3.3 から[permalink][rdoc][edit]

source を構文解析し、見つかったコメントを表すオブジェクトの配列を返します。配列の要素は Prism::InlineComment(# ... 形式のコメント)または Prism::EmbDocComment(=begin/=end 形式のコメント)のインスタンスです。オプションは Prism?.parse と同じです。

[PARAM] source:: 解析する Ruby プログラムの文字列を指定します。
[PARAM] options:: Prism?.parse を参照してください。

例

require "prism"

comments = Prism.parse_comments("# hello\n1 + 1")
p comments.size                  # => 1
p comments.first.class           # => Prism::InlineComment
p comments.first.location.slice  # => "# hello"

[SEE_ALSO] Prism::ParseResult#comments

parse_failure?(source, **options) -> boolRuby 3.3 から[permalink][rdoc][edit]

Prism?.parse_success? の否定です。source の構文解析にエラーがあった場合に true を返します。オプションは Prism?.parse と同じです。

[PARAM] source:: 解析する Ruby プログラムの文字列を指定します。
[PARAM] options:: Prism?.parse を参照してください。

例

require "prism"

p Prism.parse_failure?("1 + 1") # => false
p Prism.parse_failure?("1 +")   # => true

[SEE_ALSO] Prism?.parse_success?, Prism::ParseResult#failure?

parse_file(filepath, **options) -> Prism::ParseResultRuby 3.3 から[permalink][rdoc][edit]

filepath で指定したファイルを読み込んで構文解析します。オプションは Prism?.parse と同じです。

[PARAM] filepath:: 解析する Ruby プログラムのファイルパスを指定します。
[PARAM] options:: Prism?.parse を参照してください。

例

require "prism"

File.write("sample.rb", "def foo(a, b) = a + b\n")

result = Prism.parse_file("sample.rb")
p result.class         # => Prism::ParseResult
p result.value.class   # => Prism::ProgramNode
p result.success?      # => true

[SEE_ALSO] Prism?.parse

parse_file_comments(filepath, **options) -> ArrayRuby 3.3 から[permalink][rdoc][edit]

filepath で指定したファイルを構文解析し、Prism?.parse_comments と同様にコメントを表すオブジェクトの配列を返します。オプションは Prism?.parse と同じです。

[PARAM] filepath:: 解析する Ruby プログラムのファイルパスを指定します。
[PARAM] options:: Prism?.parse を参照してください。

例

require "prism"

File.write("sample2.rb", "# comment here\nputs 1\n")

comments = Prism.parse_file_comments("sample2.rb")
p comments.size         # => 1
p comments.first.class  # => Prism::InlineComment

[SEE_ALSO] Prism?.parse_comments

parse_lex(source, **options) -> Prism::ParseLexResultRuby 3.3 から[permalink][rdoc][edit]

source に対して構文解析と字句解析の両方を行い、 Prism::ParseLexResult のインスタンスを返します。value は [構文木, トークンの配列] という 2 要素配列です。

構文木とトークン列の両方が必要な場合、Prism?.parse と Prism?.lex を個別に呼び出すよりも効率的です。片方だけが必要な場合はそれぞれ Prism?.parse または Prism?.lex を使ってください。オプションは Prism?.parse と同じです。

[PARAM] source:: 解析する Ruby プログラムの文字列を指定します。
[PARAM] options:: Prism?.parse を参照してください。

例

require "prism"

result = Prism.parse_lex("1 + 2")
p result.class # => Prism::ParseLexResult

ast, tokens = result.value
p ast.class    # => Prism::ProgramNode
p tokens.size  # => 4

[SEE_ALSO] Prism?.parse, Prism?.lex

parse_lex_file(filepath, **options) -> Prism::ParseLexResultRuby 3.3 から[permalink][rdoc][edit]

filepath で指定したファイルに対して構文解析と字句解析の両方を行います。戻り値の形式は Prism?.parse_lex と同じです。オプションは Prism?.parse と同じです。

[PARAM] filepath:: 解析する Ruby プログラムのファイルパスを指定します。
[PARAM] options:: Prism?.parse を参照してください。

例

require "prism"

File.write("sample.rb", "1 + 2\n")

ast, tokens = Prism.parse_lex_file("sample.rb").value
p ast.class # => Prism::ProgramNode
p tokens.map { |token, _state| token.type }
# => [:INTEGER, :PLUS, :INTEGER, :NEWLINE, :EOF]

[SEE_ALSO] Prism?.parse_lex

parse_success?(source, **options) -> boolRuby 3.3 から[permalink][rdoc][edit]

source を構文解析し、エラーなく解析できた場合に true を返します。 Prism?.parse を呼び出して .success? を確認するのとほぼ同じ結果になりますが、構文木を Ruby オブジェクトとして構築しないぶん高速です。オプションは Prism?.parse と同じです。

[PARAM] source:: 解析する Ruby プログラムの文字列を指定します。
[PARAM] options:: Prism?.parse を参照してください。

例

require "prism"

p Prism.parse_success?("1 + 1") # => true
p Prism.parse_success?("1 +")   # => false

[SEE_ALSO] Prism?.parse_failure?, Prism::ParseResult#success?

要約

目次

モジュール関数